# 03 — Frontend Plan

Four surfaces, one design system, one TypeScript codebase philosophy.

## Surfaces

| Surface | Tech | Mode | Users |
|---------|------|------|-------|
| **POS Counter** (desktop) | Electron + React | Local-first, offline always | Cashiers, supervisors |
| **Back Office** (web) | React SPA | Online (tolerates it) | Owner, manager, purchaser, accountant |
| **Owner App** (mobile) | React Native, Android-first | Online + cached | Owner on the move |
| **Customer Display** | Second window/screen from POS | Local | The person in the queue |

## The counter creed (UX principles for POS)

1. **Keyboard is king.** Every billing action reachable without a mouse. Classic users'
   muscle memory is the migration moat — publish the keymap, keep it configurable,
   offer a "Classic keys" preset that mirrors the old Oracle Forms bindings.
2. **The scan line is sacred.** Focus always returns to the scan/search box. No dialog,
   toast, or sync event may steal focus mid-bill. Ever.
3. **One screen, no navigation.** Billing is a single screen: item entry, bill lines,
   totals, payment. Payment is an overlay, not a page. Target: close a cash bill with
   **one keystroke** from the last scanned item.
4. **Errors never trap.** Unknown barcode → inline quick-add or skip, keep billing.
   Printer jam → bill saves, reprint later. Sync down → icon changes color, nothing else.
5. **Speed is visible.** Show per-bill timing internally (telemetry); we optimize what
   we measure. The queue is the enemy.
6. **Touch is secondary but real** — large hit targets on the right rail for
   touch-counter deployments; never at the cost of keyboard flow.
7. **Language switch per user** — cashier sees Hindi/regional, owner sees English,
   same install.
8. **Every state is recoverable** — power cut mid-bill → app reopens with the bill
   intact (journaled local writes).

## POS screen inventory

| Screen | Notes |
|--------|-------|
| Login / shift open | PIN-fast; denomination count on open |
| **Billing** (the screen) | Scan box, lines grid, totals, customer picker (phone), hold/resume tray, payment overlay (cash/UPI-QR/card/khata/split), quick-keys row for loose produce |
| Returns/exchange | Lookup by bill no / phone / scan of e-bill QR |
| Bill history & reprint | Day-scoped by default |
| Item quick-add | Minimal fields, flagged for back-office completion |
| Shift close / day-end | Cash count, variance, day report print |
| Supervisor overlay | PIN-gated: void, discount override, price change |
| Settings/diagnostics | Printers, scale, display, sync status, keymap |

## Back office screen inventory (by module)

- **Dashboard**: today across counters/stores, alerts (low stock, near expiry, khata due, sync health).
- **Catalog**: items list (bulk edit, import), item editor, categories, price lists, schemes, label printing queue.
- **Purchases**: purchase list, entry form, **Purchase Inbox review queue** (parsed draft ⇄ source PDF side-by-side, item-match confirmations), supplier ledger, GSTR-2B reconciliation.
- **Inventory**: stock view (filters: store/category/batch/expiry), adjustments, transfers, stock-take sessions.
- **Sales**: bill browser, returns, customer profiles, loyalty, khata & collections (WhatsApp reminder actions).
- **Accounting**: vouchers, ledgers, day book, P&L/BS, Tally export, GST returns (GSTR-1/3B), e-Invoice/e-Way queues.
- **HO console** (Enterprise): store comparison, central pricing pushes, consolidated GST.
- **Admin**: users/roles/permission matrix, audit log browser, stores & counters, subscription/plan, backup status.

## Owner app (v1 scope, deliberately small)

Today's sales (live), payments breakdown, top items, stock alerts, khata outstanding,
approval requests (big discounts/voids), daily digest notification. Read-mostly; one
write action: approve/deny.

## Design system

- **Tokens first** (color/spacing/type in one package) — POS, web, and mobile consume the
  same tokens; theme per surface (POS: high-contrast, dense; back office: comfortable).
- Dark and light from day one (night-shift counters love dark).
- Numerals: tabular figures everywhere money appears; ₹ formatting with Indian digit
  grouping (1,23,456.78) in one shared formatter.
- Grid/table component gets the most investment — half the back office is tables.
  Virtualized, keyboard-navigable, exportable.
- Print templates (thermal 2"/3", A4/A5 invoice, labels) as data-driven templates with a
  visual preview editor in settings — per-tenant customization without code. This was a
  Reports-era pain point; make it a strength.
- Component stack suggestion: Radix primitives + Tailwind + our tokens (or Mantine if
  speed beats control). Icon set: Lucide. Charts: lightweight (recharts) in back office only.

## Frontend engineering rules

- Local SQLite is the POS source of truth; UI reads via a thin repository layer —
  no component ever awaits the network on the billing path.
- State: keep it boring — TanStack Query for server state (back office), Zustand for
  POS session state; no global state kitchen-sink.
- Every screen testable headless: business logic in plain TS modules, UI is a shell.
  Billing engine (pricing, tax, rounding, schemes) is a **pure, versioned package** with
  golden-file tests — the same engine runs in POS, back office, and cloud so a bill
  computes identically everywhere.
- Feature flags evaluated client-side from the license token; locked features render
  as discoverable upsells, not hidden.
- i18n from the first commit (string files, no literals) — retrofitting is misery.