You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
93 lines
5.5 KiB
Markdown
93 lines
5.5 KiB
Markdown
# 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.
|