# Lanka ShopDesk High-fidelity Windows-style React desktop dashboard, POS billing, inventory, and reports UI for Sri Lankan retail counters using CDN-only React, HTM, Tailwind, hash routing, and local state. ## Masterplan - Deliver a standalone desktop-app-feeling retail counter interface, not a website: floating Windows-like shell, titlebar controls, sidebar navigation, rounded white/soft-blue surfaces, subtle shadows, and receipt-print support. - Serve Sri Lankan small-shop operators who need fast POS billing, searchable product lookup, low-stock visibility, inventory entry, and daily/weekly trading summaries. - Optimize for counter speed with large product tiles, readable LKR totals, one-click quantity changes, barcode/search affordance, print button, and minimal navigation depth. - Keep the app zero-build and easy to host: CDN-only React, HTM templates instead of JSX, Tailwind CDN utilities, and plain ES modules. - Preserve offline-friendly demo/session state in `localStorage` so products, cart, and theme survive reloads. ## Tech Stack & Architecture - `index.html` is the only host page. It loads: - Tailwind CDN: `https://cdn.tailwindcss.com` - App CSS: `styles/main.css` - ES module entry: `src/main.js` - React is imported directly from CDN: - `react@19.2.0` from `https://esm.sh/react@19.2.0` - `react-dom@19.2.0/client?deps=react@19.2.0` in `src/main.js` - No npm, bundler, JSX transform, TypeScript, server, database, or API exists. - HTM replaces JSX: - `src/jsx.js` binds `htm@3.1.1` to `React.createElement`. - Components return ``html`...` `` templates. - New component/page files must import `React` from `https://esm.sh/react@19.2.0` and `html` from the correct relative `jsx.js` path. - Icons use `lucide-react` from `https://esm.sh/lucide-react?deps=react@19.2.0`. - Keep `?deps=react@19.2.0`; removing it can create duplicate React instances. - Routing is hash-based in `src/App.js`: - `#/dashboard` - `#/inventory` - `#/billing` - `#/reports` - Empty hash redirects to `#/dashboard`. - Unknown routes render `Dashboard`, but `Layout` receives the unknown `route`, so no sidebar item is active. - State management lives in `src/mainProviders.js`: - React Context + `useReducer` - `useStore()` exposes `{ state, dispatch }` - Persistent key: `lanka-shopdesk-state` - `Providers` side effects: - Toggles `.dark` on `document.documentElement` when `state.theme === 'dark'`. - Saves the entire state to `localStorage` after every reducer change. - Forces loaded `session.branch` to `Mawanella` even if older saved state contains a different branch. - Current data is client-only/demo data. Products, cart, KPI values, reports, and weekly chart values are not fetched from a backend. - Printing: - `Billing.js` uses `window.print()` for receipts. - `styles/main.css` hides the app shell during print and shows `.receipt-print-area`. - Browser print dialog/receipt printer handles final output. ## File Structure ```text index.html Single HTML host; loads Tailwind CDN, styles/main.css, and src/main.js. styles/main.css Theme tokens, Windows shell, titlebar, chart animation, hover/focus states, responsive rules, receipt print CSS. src/main.js Creates React root and renders App inside Providers. src/jsx.js HTM binding; required because the project has no JSX/build step. src/mainProviders.js Store Context, seeded products/cart/session, reducer actions, localStorage persistence, dark-mode side effect. src/App.js Hash route listener and page selection. src/components/Layout.js Windows-style frame, titlebar, theme toggle, sidebar nav, branch/status card. src/components/StatCard.js Reusable KPI card for Dashboard and Reports. src/components/SalesChart.js Static animated SVG weekly sales line chart. src/pages/Dashboard.js KPI cards, dynamic low-stock count, critical stock list, sales chart. src/pages/Billing.js POS product search grid, billing cart, 8% tax, quantity controls, clear/pay/print behavior, receipt print markup. src/pages/Inventory.js Search/filter inventory table and validated Add Product form. src/pages/Reports.js Static weekly report cards and reused sales chart. CLAUDE.md Project/agent documentation target; keep synchronized with actual code. ``` ## Key Features ### Windows-style desktop shell Implemented in `src/components/Layout.js` and `styles/main.css`. Requirements: - App appears inside `.desktop-shell`, not full-page website chrome. - Titlebar shows Lanka_ShopDesk, “Offline-ready retail desktop”, theme toggle, and decorative window control icons. - Sidebar navigation uses four fixed pages: Dashboard, Inventory, Billing, Reports. - On small screens, sidebar becomes horizontal top navigation below the titlebar. Gotchas: - The titlebar uses `-webkit-app-region: drag`; harmless in browsers, useful if later wrapped in a desktop shell. - Window controls are decorative only. They do not minimize/maximize/close. ### Dashboard Implemented in `src/pages/Dashboard.js`. Requirements: - Show four summary cards via `src/components/StatCard.js`: - `Today's Sales`: fixed `LKR 286,450` - `Low Stock Alerts`: computed from `state.products.filter(p => p.stock <= 10).length` - `Total Orders`: fixed `147` - `New Customers`: fixed `23` - Show `SalesChart`. - Show Critical Stock list for products with `stock <= 10`. Data dependency: ```js Product.stock <= 10 means low/critical stock. ``` ### POS Billing Implemented in `src/pages/Billing.js`. Requirements: - Left side product grid: - Search by product `name` or `id`. - Barcode and search icons in search bar. - Product tile displays emoji, name, ID, stock, and LKR price. - Clicking a tile dispatches `ADD_TO_CART`. - Right side billing cart: - Cart items are derived from `state.cart` joined with `state.products`. - Missing products are filtered out, preventing crashes after stale saved state. - Quantity cannot go below 1 because reducer clamps with `Math.max(1, action.qty)`. - Remove item with `REMOVE_FROM_CART`. - Clear cart with `CLEAR_CART`. - Totals: - `subtotal = sum(product.price * qty)` - `tax = Math.round(subtotal * 0.08)` - `total = subtotal + tax` - Currency format: `LKR ${value.toLocaleString('en-LK')}` - Receipt: - Receipt number format: `LS-YYYYMMDD-####`, based on current date and cart/total. - Print button is disabled when cart is empty. - `window.print()` opens browser print flow. - Print CSS targets 80mm receipt paper and displays `.receipt-print-area`. Important limitation: - Adding to cart does not reduce inventory stock. This is currently a UI/session demo, not a real stock transaction system. ### Inventory Management Implemented in `src/pages/Inventory.js`. Product model: ```js { id: 'P-1001', name: 'Keells Samba Rice 5kg', category: 'Groceries', stock: 42, price: 2650, emoji: '🍚' } ``` Requirements: - Search by product `name` or `id`. - Filter by category; category list is generated from current products. - Add New Product form: - Fields: `name`, `category`, `stock`, `price`, `emoji`. - Category uses an `` so operators can reuse or type categories. - ID is generated by scanning existing `P-####` IDs and using max + 1. - New product is prepended to `state.products`. - Validation: - Product name and category required. - Stock must be an integer `>= 0`. - Price must be finite and `> 0`. - Price is rounded before saving. - Empty emoji defaults to `📦`. - Low-stock status threshold is `stock <= 10`. Gotchas: - `nextProductId()` only understands IDs shaped like `P-1001`. Nonconforming IDs are ignored when calculating max. - Product additions persist through `localStorage`; clear `lanka-shopdesk-state` to reset demo data. ### Reports Implemented in `src/pages/Reports.js`. Requirements: - Show static weekly report cards: - Gross Revenue: `LKR 1.92M` - Stock Accuracy: `98.4%` - Invoices Closed: `812` - Reuse `SalesChart` for weekly sales visualization. ### Sales Chart Implemented in `src/components/SalesChart.js`. Requirements: - Static weekly data: ```js [62000, 74500, 68800, 94200, 102500, 117900, 132400] ``` - Labels: `Mon` through `Sun`. - SVG line is animated with `.chart-line` in `styles/main.css`. - Uses theme CSS variables for stroke/fill/borders. ## Design Guidelines - Visual style: clean Windows desktop dashboard with soft blue/white cards, rounded corners, subdued borders, and subtle shadows. - Theme tokens are CSS variables in `styles/main.css`; use `hsl(var(--token))` or `hsla(var(--token), alpha)` in Tailwind arbitrary values. - Primary colors: - Light `--primary`: blue `210 92% 38%` - Light `--secondary`: soft blue `199 86% 92%` - Light `--card`: white - Dark theme overrides are defined under `.dark`. - Typography: - System stack: `Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` - Headings use heavy weights (`font-black`) for desktop/POS readability. - Layout: - Main shell: `height: calc(100vh - 24px); margin: 12px`. - Desktop navigation: left sidebar `md:w-64`. - Billing target window: uses `min-h-[720px]` and `lg:grid-cols-[1fr_420px]` for a 1000x800-style counter layout. - Responsive behavior: - Below `760px`, body scroll is enabled and shell height becomes auto. - Sidebar nav becomes horizontal before `md`. - Use existing utility classes: - `.card-hover` for clickable cards/tiles. - `.focus-ring` for inputs. - `.no-scrollbar` for internal scrolling panels. - Print design: - `@media print` switches to monochrome receipt styling. - Keep receipt-specific markup/classes compatible with `.receipt-print-area`, `.receipt-paper`, `.receipt-divider`, `.receipt-line`, and `.receipt-total`. ## App Flow 1. User opens `index.html`. 2. `src/main.js` renders ``. 3. `Providers` loads `localStorage["lanka-shopdesk-state"]` or seeds default products/cart. 4. `App` normalizes the hash route; no hash redirects to `#/dashboard`. 5. `Layout` wraps the selected page and provides persistent titlebar/sidebar. 6. Operator journeys: - Dashboard: review KPIs, weekly trend, and low-stock products. - Inventory: search/filter products, add new products, verify stock status. - Billing: search/scan product, add to cart, adjust quantities, view tax/total, print receipt, pay/clear cart. - Reports: review static weekly summary and sales chart. 7. Edge cases: - Empty product search shows a “No matching products” message. - Empty cart shows an instructional empty state. - Print with empty cart is blocked with a status message. - Corrupt `localStorage` falls back to `initialState`. - Unknown route displays Dashboard content with no active sidebar item. ## Conventions - Use ES modules only. Do not add build tooling unless intentionally migrating the whole app. - Use HTM syntax, not JSX: ```js return html`

${value}

`; ``` - Every React component file should import: ```js import React from 'https://esm.sh/react@19.2.0'; import { html } from '../jsx.js'; // adjust path ``` - For lucide icons, import with React dependency pinned: ```js import { IconName } from 'https://esm.sh/lucide-react?deps=react@19.2.0'; ``` - State changes must go through reducer actions in `src/mainProviders.js`. - Existing action types: `TOGGLE_THEME`, `ADD_TO_CART`, `SET_QTY`, `REMOVE_FROM_CART`, `CLEAR_CART`, `ADD_PRODUCT`. - Keep persistent state serializable; it is saved wholesale to `localStorage`. - Use product IDs as stable keys and cart references. Cart items store `{ id, qty }`, not full product objects. - Add a new page by: 1. Creating `src/pages/NewPage.js`. 2. Importing it in `src/App.js`. 3. Adding route selection for `route === 'newpage'`. 4. Adding a nav item in `src/components/Layout.js` with `href: '#/newpage'`. - Add a new reusable component under `src/components/`. - Prefer CSS variables from `styles/main.css` over hardcoded colors. - Keep Sri Lankan retail context: LKR formatting, local product examples, and branch/session wording. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.