sims-hq/docs/03-FRONTEND.md

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.