sims-hq/docs/04-ROADMAP.md

# 04 — Roadmap

Assumes a core team of ~4–6 (2–3 app devs, 1–2 backend, 1 QA/support who knows Classic).
Durations stretch/shrink with team size; the **sequence and exit criteria** are the point.
Dates below start from project kickoff.

> ## ⚡ Staging update (founder call, 2026-07-09 — see D14)
> **Build the local product first; add the cloud tier afterwards.** Phase 1 ships a
> fully working local-only system: POS counters (SQLite buffer) + the existing in-store
> Oracle 12c as store master (D12), offline licensing as Classic does today, local +
> exported backups. The cloud tier (Postgres, sync agent, licensing service, auto-update
> channel) is stood up as its own workstream and switched on per store afterwards.
>
> **The one non-negotiable that makes this safe:** even in local-only v1, every write
> uses client-generated UUIDs and also writes its outbox row (dormant, drained by
> nothing). Cloud enablement then = install sync agent + drain backlog — a switch-on,
> not a data migration. Skip this and "add cloud later" becomes a second migration project.
>
> **Deferred until the cloud tier exists** (moves with it, not with the phase numbers
> below): owner mobile app, Purchase Inbox, WhatsApp e-bills/reminders, UPI webhook
> auto-confirm, central backups, silent auto-update, HQ fleet dashboards (the HQ *ops*
> console starts earlier — see the HQ Ops workstream below), e-Invoice via
> GSP (can interim-run through a manual portal flow if needed before then).

## Phase 0 — Prove the risky bits (4–6 weeks)

Goal: kill the project-killers before writing product code.

- **Sync spike**: two POS clients + cloud; bills offline on both, kill the network, sync,
  verify stock & numbering correctness. Evaluate PowerSync/ElectricSQL vs custom outbox.
- **Hardware spike**: Electron app printing ESC/POS (2"/3"), cash-drawer kick, scanner
  input, one weighing scale. This decides Electron vs Tauri (vs Flutter).
- **Billing engine v0**: pure-TS pricing/GST/rounding engine with golden tests derived
  from real Classic bills (grab 100 real bills, new engine must reproduce them to the paisa).
- **Classic data audit**: map the Oracle schema; export 2–3 real customer datasets;
  identify the ugly bits (they exist).
- **UX prototype**: clickable billing screen; put it in front of 3 real cashiers; time them.
- Founder decisions locked: 06-DECISIONS items D1–D5.

**Exit criteria:** sync demo survives a pulled cable; printed bill from Electron; engine
reproduces Classic bills; stack decision written down.

## Phase 1 — MVP: one store bills on it all day (3–4 months)

Scope (all "M" items in [01-SCOPE.md](01-SCOPE.md)): masters + import, POS billing
offline with print, payments (cash/UPI-static/card/khata), returns, purchases (manual),
stock, day-end, party ledgers, GST invoice formats, core reports, users/roles/audit,
licensing skeleton, auto-update, cloud backup, **Classic migration tool alpha**.

**Pilot:** 3–5 friendly existing customers (one mini, one medium, one busy counter) run
Next **in parallel with Classic** for 2+ weeks, then cut over. Their cashiers' stopwatch
beats our opinions.

**Exit criteria:** a real store bills a full day with zero Classic fallback; migration
tool moves a real customer with verification report green; counter timing ≤ Classic.

## Phase 2 — Compliance depth + counter polish (2–3 months)

GSTR-1/3B exports, e-Invoice + e-Way via GSP, Tally export, schemes/offers, UPI dynamic
QR with auto-confirm, WhatsApp e-bills & khata reminders, multi-counter + Store Hub LAN
sync, weighing-scale barcodes, salesman tracking, accounting vouchers/day book,
multi-language UI (top 2 languages), onboarding wizard.

**Exit criteria:** a supermarket with 3+ counters runs through GST filing month entirely
on Next; dealer can onboard a new store without us on the call.

## Phase 3 — The differentiators (2–3 months)

**Purchase Inbox** (email/upload → AI parse → review queue → posted purchase, with
item-matching memory), GSTR-2B reconciliation, owner mobile app v1, stock-take mobile
scanning, dashboards & scheduled digests, loyalty, PO/GRN flow, expiry dashboards.

**Exit criteria:** ≥50% of pilot stores' purchase lines flow through the Inbox;
owner app DAU > 60% of owners.

## Phase 4 — Scale-out (ongoing)

Multi-store HO console, central pricing, inter-store transfers, consolidated reporting,
Enterprise onboarding for chains, API access, customer display/promo engine, offer
broadcasts, then evaluate: Android POS terminals, ONDC/e-commerce bridges, restaurant mode.

## Migration & go-to-market thread (runs across all phases)

1. Phase 1: migration tool + parallel-run playbook; migrate the 5 pilots.
2. Phase 2: dealer training kit, migration-week checklist, Classic price-lock offer;
   migrate the top 20% (largest/most engaged) of the base.
3. Phase 3: mass migration waves by region with dealer incentives; Classic enters
   maintenance-only mode (security/GST patches).
4. Phase 4: Classic sunset date announced — only after >80% of active base has moved
   and Next's support ticket rate is demonstrably lower.

## HQ Ops workstream — the internal console (parallel track)

New workstream (founder call, 2026-07-09 — **D15 ✅ RESOLVED**, [06-DECISIONS.md](06-DECISIONS.md)):
build `apps/hq` per [14-SPEC-HQ-CONSOLE.md](14-SPEC-HQ-CONSOLE.md) — the
[doc-11 HQ Console](11-ADMIN-SUPPORT-CONSOLE.md) **started early**, aimed at the
**current ~300 Classic clients** (quotations/proforma/invoices in minutes, recurring
billing + reminders, AMC, per-client AWS cost, interaction log), replacing the internal
Oracle APEX app entirely. Runs **in parallel with Phases 0–4**, staffed lightly (~1 dev),
reusing the tested foundation packages (billing-engine, domain, ui, auth patterns) — it
doesn't compete with the product track for people.

**Reconciling with the staging note above:** this does **not** change D14 — the store
product stays local. The HQ Console is *vendor-side* cloud, which doc 11 already
prescribes. The **fleet half** (fleet dashboards, migration tracker UI, remote support)
still waits for the cloud tier as deferred above — only the **ops/billing slice** starts
now, on the same client registry the fleet features will later share.

| Phase | Ships (condensed from spec §6) |
|---|---|
| **HQ-1** | Skeleton + auth/audit; client registry (APEX import + verification); module catalog + module_price_book; client_module tracking; **quotation/proforma/invoice + letterhead PDF + Gmail send + payment recording** |
| **HQ-2** | Recurring plans + reminder engine (auto + manual queue); AMC contracts; money dashboard + follow-ups; interaction/visit/call/training log |
| **HQ-3** | AWS usage & cost per client + margin view; reports (dues aging, module revenue, client profitability); Client 360° polish |
| **HQ-4** | Convergence with doc-11 fleet features once SiMS Next ships — migration tracker, fleet dashboards, support queue on the same registry, no rebuild |

## Standing risks to watch

| Risk | Mitigation |
|------|-----------|
| Sync correctness bugs erode trust fast | Phase-0 spike, property-based tests, sync health dashboard, replayable op logs |
| New POS feels slower than Classic to veteran cashiers | Keyboard-first + "Classic keys" preset; measure per-bill timings in pilots; don't ship until ≤ Classic |
| GST rule changes mid-build | Rates/thresholds as dated config; GSP handles portal churn |
| Migration data horror stories | Verification report (counts, balances, stock match) per migration; parallel-run period mandatory |
| Scope creep from Classic parity ("but it had X") | Parity backlog triaged against usage data from Classic telemetry/pilots, not memory |
| Team spread across 4 surfaces | Phase 1 ships POS + minimal back office only; owner app waits for Phase 3 |