# 02 — Architecture: Offline vs Online, Sync, Stack

## 1. The offline/online question (the brainstorm you asked for)

### Option A — Pure offline (what Classic is)

**Benefits**
- Counter never depends on internet; zero latency; works in tier-3 towns with bad connectivity.
- No hosting cost; customer feels "my data is mine, in my shop."
- Simple mental model, simple debugging (one machine, one DB).

**Defects**
- No multi-store, no owner-away-from-shop visibility, no Purchase Inbox (needs cloud).
- Support requires reaching into the shop machine; updates are a door-to-door problem.
- Data loss when the shop PC dies and backups were "supposed to happen."
- Licensing/piracy enforcement is weak; subscriptions are hard to enforce.
- No telemetry: you learn about bugs from angry calls.

### Option B — Pure cloud (browser POS, server is truth)

**Benefits**
- One deployment, instant updates, central data, easy multi-store, easy licensing.
- Any device with a browser becomes a counter.

**Defects**
- **Internet dies → billing dies. Fatal in India.** This alone disqualifies pure cloud
  for the counter. Competitors who went cloud-first all retrofitted awkward offline modes.
- Every scan pays network latency; "fast counter" becomes a fight with physics.
- Browser hardware access (thermal printers, cash drawers, scales) is painful.
- Customer trust: "my sales data lives on your server?" is a real sales objection.

### Option C — Local-first hybrid (the answer)

**The rule: the counter reads and writes a local database, always. The cloud is a
sync target, a backup, a reporting brain, and a licensing authority — never a
dependency for billing.**

**Benefits**
- Billing works identically with or without internet — offline is not a "mode," it's
  the architecture. Sync happens in the background when connectivity exists.
- Gets everything cloud promises: multi-store, owner app, Purchase Inbox, central
  reporting, subscriptions, telemetry, auto-update, off-site backup.
- Latency at counter is local-DB latency (~0 ms network).

**Defects (and how we contain them)**
- *Sync is genuinely hard.* → Contain it with strict design rules (§3) and buy, don't
  build, where possible. Sync is the single biggest technical risk of this project —
  it gets a proof-of-concept before anything else (see roadmap Phase 0).
- *Conflicts.* → Design them away: transactional documents are append-only and
  counter-scoped (they cannot conflict); only master-data edits can conflict, and those
  get last-write-wins + full audit trail + rare-enough-to-review.
- *Version skew* (store app v2.3 talking to cloud v2.5). → Versioned sync protocol,
  additive-only schema changes between forced upgrades.
- *Harder debugging.* → Sync health dashboard per store, op logs, replayability.

**Decision: Option C.** Back office can lean online (it tolerates a spinner; the counter
cannot), owner app is online-first with cached reads, POS is local-first, period.

## 2. System topology

```
                         ┌──────────────────────────────────────────┐
                         │                 CLOUD                    │
                         │  Multi-tenant Postgres (RLS by tenant)   │
                         │  API + Sync service    Licensing/Plans   │
                         │  Purchase Inbox (email ⇢ AI parse)       │
                         │  Reporting/analytics   Backups           │
                         │  GSP bridge (e-Invoice / e-Way)          │
                         │  WhatsApp/SMS/UPI integrations           │
                         └─────────▲──────────────────▲─────────────┘
                                   │ sync (queued ops) │ https
              ┌────────────────────┴───┐          ┌────┴─────────────┐
              │      STORE (each)      │          │  Back-office Web │
              │  ┌──────────────────┐  │          │  (browser, admin │
              │  │ Store Hub (opt.) │  │          │   & reports)     │
              │  │ local sync fan-in│  │          └──────────────────┘
              │  └───▲────────▲─────┘  │          ┌──────────────────┐
              │  ┌───┴───┐ ┌──┴────┐   │          │  Owner Mobile    │
              │  │ POS 1 │ │ POS 2 │…  │          │  (online + cache)│
              │  │SQLite │ │SQLite │   │          └──────────────────┘
              │  └───────┘ └───────┘   │
              │  printers, scanner,    │
              │  scale, cash drawer,   │
              │  customer display      │
              └────────────────────────┘
```

- **POS client**: desktop app, embedded SQLite is the source of truth for that counter.
- **Store Hub** (optional, Standard+): one machine in the store acts as LAN relay so
  counters see each other's bills/stock instantly even when the internet is down;
  it also fan-ins sync to cloud. For single-counter Lite, the POS syncs direct to cloud.
- **Cloud**: multi-tenant; per-tenant row isolation; all cross-store logic lives here.

## 3. Sync design rules (write these on the wall)

1. **Client-generated IDs everywhere** (UUIDv7). No "wait for server to get an ID."
2. **Transactional documents are immutable events.** A bill, once closed, is an
   append-only fact. Corrections are new documents (credit note, amendment) referencing
   the original. This kills 90% of conflict scenarios and satisfies audit requirements
   in one stroke.
3. **Invoice numbering is per-counter series** — e.g. `ST1C2-000123` (GST allows multiple
   series; ≤16 chars, unique & consecutive within a series per FY). Counters can therefore
   number bills offline with zero coordination.
4. **Outbox/inbox pattern**: every local write that must reach the cloud goes into a local
   outbox table in the same SQLite transaction as the write itself; a background worker
   drains it with retries + idempotency keys. Downstream (cloud→store) is a cursor-based
   pull of changes since last sync.
5. **Master data flows down, transactions flow up.** Masters are edited in back office
   (cloud) and pushed to stores; store-side master edits (allowed on lower plans) sync up
   with last-write-wins + audit log.
6. **Stock is derived, never synced as a number.** Each store's stock = fold of its local
   events; cloud recomputes global views. Never ship "stock = 47" between nodes — ship the
   movements.
7. **Clocks lie.** Order by (lamport counter, device id), keep wall-clock only for display.
8. **Sync must be observable**: per-store last-sync time, pending-op count, error surface
   in both the POS status bar and a support dashboard.

**Build vs buy:** evaluate PowerSync and ElectricSQL (Postgres ⇄ SQLite sync engines)
against a hand-rolled outbox in the Phase-0 spike. Rule of thumb: buy the pipe if it fits,
but the *semantic* rules above stay ours either way.

## 4. Multi-tenancy & audit

- Single Postgres cluster, `tenant_id` on every row, enforced with Row-Level Security;
  the API sets tenant context from the auth token. (Schema-per-tenant only if a large
  Enterprise chain demands isolation — don't start there.)
- Tenant = the client business; stores, counters, users hang off it. All client-specific
  compliance settings (GST scheme, FY, invoice formats, rounding rules) are tenant config.
- **Audit**: append-only `audit_log` (who, what, before, after, when, where) written in the
  same transaction as the change, synced up, never deletable — this covers the MCA
  audit-trail requirement for company clients and your own support forensics.
- Backups: continuous cloud PITR + nightly encrypted per-tenant export; store-side SQLite
  snapshots shipped to cloud so a dead shop PC costs minutes, not the business.
- DPDP Act hygiene: customer phone numbers are personal data — encrypt at rest, purge on
  request, keep telemetry free of PII.

## 5. GST/compliance layer (data-driven, never hard-coded)

- GST rates, cess, and slab structures are **dated configuration**, not code — the
  Sept 2025 GST 2.0 slab overhaul is the proof that rates change under you.
- e-Invoice (IRN) and e-Way bill via a **GSP aggregator API** (ClearTax / Masters India /
  similar) rather than direct IRP integration — one decision in [06-DECISIONS.md](06-DECISIONS.md).
- Queue-and-forward: bills that need IRN but were made offline are queued and registered
  when online, within the reporting window; the POS shows pending-IRN status.

## 6. Tech stack — recommendation

**Primary recommendation: TypeScript end-to-end.** One language, the largest hiring pool
in India, one skill set across all four surfaces, and the web back office shares
components with the POS UI.

| Layer | Choice | Why |
|-------|--------|-----|
| POS desktop | **Electron + React + SQLite** | Mature hardware story on Windows (ESC/POS, serialport for scales/drawers/displays), offline SQLite, auto-update solved, huge ecosystem. Tauri is the leaner alternative — decide after the Phase-0 hardware spike. |
| Back office | **React SPA** (same design system as POS) | Browser-only, no install; admins tolerate online-only. |
| Owner app | **React Native** | Shares TS models/API client; Android-first (your market), iOS later. |
| API/backend | **Node.js + NestJS + PostgreSQL + Redis** | Structured enough for a long-lived product; trivially hireable. |
| Sync | PowerSync / ElectricSQL **or** custom outbox — Phase-0 spike decides | Biggest risk, prove it first. |
| AI (Purchase Inbox) | Claude API (vision + structured output) behind our own parsing service | PDF/photo invoice → structured draft purchase; item-matching memory in Postgres. |
| Infra | Managed Postgres + containers on an Indian region (data residency comfort) | Mumbai region; boring and reliable. |

> **Note (D12, decided 2026-07-09):** the store-tier DB remains the existing **Oracle 12c**
> for now — it is shared infrastructure running other systems. Counters keep their local
> SQLite buffer (offline bill queue + item cache); the Store Hub role is played by the
> Oracle box; sync is a custom outbox (D3 → build). Adapted topology, guardrails, and
> revisit triggers: [07-DB-AND-CONFIG.md](07-DB-AND-CONFIG.md) §3.
>
> **Staging (D14, 2026-07-09):** the cloud tier in the topology above is switched on
> *after* the local-only v1 ships. From the first build, all writes carry client UUIDs
> and dormant outbox rows so cloud enablement is a switch-on, not a migration.

**Considered alternatives** (kept honest in one line each):
- **Flutter everywhere**: one codebase POS-desktop + Android-POS + owner app; weaker
  Windows-desktop/hardware maturity and you'd still want a web back office. Strong option
  if Android POS terminals are a v1 target — see 06-DECISIONS.
- **.NET (WPF/WinUI + ASP.NET Core)**: best raw Windows hardware story; smaller shared-code
  story across web/mobile, second hiring pool. Solid, less leverage.

## 7. Hardware integration checklist (POS)

Barcode scanners (keyboard wedge — free), ESC/POS thermal printers 2"/3" (network/USB),
A4/A5 laser printing, cash drawers (printer-kick), weighing scales (RS-232/USB, and
label-scale EAN-13 `2x` barcodes), customer-facing display (second monitor or pole
display), UPS-friendly crash recovery (journaled SQLite, resume mid-bill after power cut).

## 8. Non-functional targets

| Metric | Target |
|--------|--------|
| Scan/type → line rendered | < 150 ms |
| Item search (50k SKUs) | < 150 ms |
| Bill close + print spool | < 1 s |
| POS cold start to billable | < 5 s |
| Offline duration tolerated | Unlimited (sync catches up) |
| Store→cloud sync lag when online | < 5 min p99 |
| POS crash data loss | Zero committed lines (journaled writes) |