sims-hq/docs/superpowers/specs/2026-07-16-hq-store-split-design.md

# Split SiMS into two independent projects: HQ and Store

**Date:** 2026-07-16
**Status:** DELIVERED 2026-07-16 (executed directly, no separate implementation plan)

## Delivered — outcome

Both repos exist, are independently buildable/testable/runnable, and were red-teamed.

- **`C:/SiMS/hq`** — this repo. Inherited the full history. Apps `hq`, `hq-web`; trimmed
  forks of `@sims/domain`, `@sims/auth`, `@sims/billing-engine`, `@sims/ui`. Typecheck
  clean, **177 tests pass**. Server boots on :5182 against the real `data/hq.db` (225 KB)
  **when launched from the repo root** (the DB path resolves against cwd — see README).
- **`C:/SiMS/store`** — apps `pos`, `store-server`, `backoffice`; full package set.
  **Fresh single-commit history with zero HQ bytes** (rebuilt after an audit caught HQ
  material in the first init). Typecheck clean, **205 tests pass**. Server boots on :5181.
  Its copied dev DB is SQLCipher-encrypted — needs the correct `SIMS_DB_KEY` to open, else
  start fresh.
- **`C:/SiMS/Store Software`** — the pre-split combined repo. **Deleted 2026-07-16**: all
  contents removed; the empty folder shell could not be unlinked from within the session
  that is rooted in it, to be removed by the user after reopening elsewhere.

Decisions held: shared code forked (not shared) so each repo is self-contained and free to
diverge; the `@sims/*` scope and `SIMS_*` env prefix are deliberately kept in both — they
resolve per-repo/per-process and never collide, so renaming them was declined as pure churn.
Transfer completeness verified: all 273 original tracked files land in one repo or the other
(zero orphans); every shared source module is byte-identical across the two.

## Why

`C:/SiMS/Store Software` currently holds two products that are not one product.

**HQ** (`apps/hq`, `apps/hq-web`) is internal: our client book, their projects,
proforma-invoice billing, call tracking, AMC contracts, AWS cost recovery,
payments and reminders. It is the commercial record of the business.

**Store** (`apps/pos`, `apps/store-server`, `apps/backoffice`) is the product we
sell: GST retail management deployed on client premises.

They are independent projects and should be developed, deployed and released as
such:

- **Different audiences.** HQ is internal-only; Store ships to ~300 clients.
- **Different databases.** Two SQLite schemas with no conceptual overlap. HQ:
  `client`, `module`, `document`, `interaction`, `amc_contract`, `aws_usage`,
  `payment`, `reminder`, `staff_user`. Store: `item`, `batch`, `bill`,
  `purchase`, `stock_movement`, `party`, `counter`, `store`, `tenant`. Four
  names collide (`audit_log`, `doc_series`, `setting`, `tax_class`) but they are
  different definitions in different DBs — shared in appearance only.
- **Different cadences.** Of 75 commits, 60 touch HQ and 2 touch Store. The repo
  is already HQ wearing a Store name.
- **Confidentiality.** A single tree means every Store branch, contractor
  handout, or repo copy carries our client book and revenue data in its history.

## Decisions

| # | Decision | Choice |
|---|---|---|
| 1 | Split shape | Two separate git repos |
| 2 | Shared code | Fork into each repo, trimmed to what each uses |
| 3 | History | HQ inherits the existing 60 commits; Store starts fresh |
| 4 | Docs | Trim each side to only what that repo needs |
| 5 | Repo name | `C:/SiMS/hq` (keep — matches docs/14, DEPLOY-HQ.md, `@sims/hq`, 60 commits) |
| 6 | Project tracking | Out of scope — split first, build after |

Rejected: a third shared repo and a private npm registry. Both add versioning
overhead to solve a divergence risk the evidence says does not exist (see below).

## Target layout

```
C:/SiMS/
├── hq/                      ← current repo, 60 commits preserved
│   ├── apps/{hq, hq-web}
│   ├── packages/{domain, auth, billing-engine, ui}   ← trimmed, names kept
│   ├── docs/                ← HQ-only, renumbered
│   ├── DEPLOY-HQ.md
│   └── README.md, STATUS.md ← STATUS.md is new
└── store/                   ← fresh git init
    ├── apps/{pos, store-server, backoffice}
    ├── packages/{domain, billing-engine, auth, ui, config, scanning, search-core}
    ├── docs/                ← the remaining 15 docs
    └── README.md, STATUS.md, BUILDING.md
```

Each repo gets its own `package.json` (`sims-hq` / `sims-store`), `tsconfig`,
`vitest.config`, `.gitignore`, and `CLAUDE.md`. Neither references the other at
any point — no workspace links, no relative paths across roots, no doc citing a
file it does not contain.

## Shared code: fork, trimmed

HQ's dependency on shared packages is shallow and fully verified — utilities and
a design system, no shared schema or business logic.

**HQ keeps the package names** (`@sims/domain`, `@sims/auth`,
`@sims/billing-engine`, `@sims/ui`) and removes files underneath. Import
specifiers are unchanged, so **no import statement in HQ's app source changes** —
not one of `apps/hq`'s 75 files or `apps/hq-web`'s 14. What changes is narrow and
enumerable: the four `index.ts` barrels (drop the removed `export *` lines), and
`apps/hq-web`'s `package.json` + `vite.config.ts` (drop the dead `@sims/printing`
dependency and alias).

| Package | HQ keeps | HQ drops |
|---|---|---|
| `domain` | `ids`, `money`, `business-day`, `doc-series`, `gstin`, `documents` | `tenancy`, `masters`, `batch`, `outbox` |
| `auth` | `pin` | `lockout`, `permissions`, `session` |
| `billing-engine` | `compute`, `tax` | `returns`, `gst-returns` (588 lines) |
| `ui` | all 5 files | — |
| `printing` | — | whole package |

Store's `packages/` is untouched.

### Closure verification (done, 2026-07-16)

Every trim is a clean cut — verified by reading the imports, not by assumption:

- `compute.ts` imports `./tax` and four **types** from `@sims/domain`
  (`BillLine`, `BillTotals`, `Paise`, `IsoDate`) — all in files HQ keeps.
- `tax.ts` imports only `IsoDate`.
- `documents.ts` imports only from `money` and `business-day`.
- `pin.ts` imports only `node:crypto` — no `@sims` deps.
- `ui` has no `@sims` deps at all (`react` + its own `theme`).
- Nothing HQ retains imports `tenancy`, `masters`, `batch`, or `outbox`. The
  reverse edges (`batch → business-day`, `masters → money`) are one-way and
  drop cleanly.
- `@sims/printing` is declared in `apps/hq-web/package.json` and aliased in its
  `vite.config.ts`, but **imported by no source file** — a dead dependency.

### Why forking is safe

The divergence risk for forked code is GST computation. It does not apply:
**tax rates are dated DB rows, not code.** `tax_class` rows carry
`effective_from`/`effective_to` and resolve by the bill's business date, with
the Sept-2025 GST 2.0 slab change cited in `tax.ts` as the precedent. HQ reads
its own `tax_class` table; Store reads its own. A rate change is a row insert
per DB, never a code edit.

What remains in `compute.ts` is stable arithmetic — CGST/SGST/IGST split,
rounding. It has no reason to change often, and the two products are entitled to
diverge: HQ invoices software modules, Store bills retail goods.

## History

The current repo becomes `C:/SiMS/hq`: all 60 HQ commits preserved, then one
commit removing Store paths. No `filter-repo` surgery.

`C:/SiMS/store` gets `git init` and one clean initial commit. It loses only 2
commits (one titled `wip`) and gains a guarantee: **zero HQ bytes in its history,
permanently.** This is the confidentiality boundary, and it is only real if the
Store history starts empty.

## Docs

Trimmed per repo — each doc cut to what that side actually needs.

**HQ** (renumbered `00`–`04`):

| New | From | Treatment |
|---|---|---|
| `00-HQ-CONSOLE-SPEC.md` | `14-SPEC-HQ-CONSOLE.md` | As-is |
| `01-ADMIN-SUPPORT-CONSOLE.md` | `11-ADMIN-SUPPORT-CONSOLE.md` | As-is |
| `02-PROJECT-RULES.md` | `16-PROJECT-RULES.md` | Trimmed: keep money, config-over-code, document rules; drop counter/POS rules |
| `03-DECISIONS.md` | `06-DECISIONS.md` | Extract D15 + HQ-only calls |
| `04-DB-AND-CONFIG.md` | `07-DB-AND-CONFIG.md` | Trimmed: D12 portable-repo pattern, dated tax-class config |

Plus `DEPLOY-HQ.md` as-is, a rewritten `README.md`, and a **new `STATUS.md`**.

**Store**: the remaining 15 docs, with D15/HQ references pruned from
`06-DECISIONS.md` and the HQ rows removed from `README.md`'s doc table.

### HQ has no STATUS.md

The largest app in the repo (75 files, at go-live per `DEPLOY-HQ.md`) has no
build-state doc. `STATUS.md` covers only the Store product. HQ's current state
had to be reconstructed from source and `git log`. Write one during the split,
covering the built surface: clients, modules and price book, documents
(QT/PI/INV/CN) with templates/PDF/share links, interactions, AMC, AWS usage,
payments, recurring plans, reminders with Gmail send and bounce handling,
reports, dashboard, audit, APEX import, scheduler.

## Verification

The split is done when, for each repo independently:

1. `node_modules` removed and `npm install` run fresh
2. `npm run typecheck` passes
3. `npm test` passes
4. No path resolves outside its own root

Typecheck is the real proof of the fork closure — a missed dependency fails
immediately and loudly.

Additionally, confirm the confidentiality boundary holds rather than assuming it:
searching `C:/SiMS/store/.git` for client, AMC, and AWS-cost terms must return
nothing.

## Out of scope

- **Project tracking.** Listed as a core HQ concept but not built — no `project`
  table, no repo module, no UI. It is a feature to design and build, not code to
  move. Deferred so the split stays mechanical: pure move-and-verify, with no new
  feature to confuse a failure with.
- **Conversion reporting.** `client.status` (`lead`/`active`/`dormant`/`lost`)
  exists but has no lead-to-won reporting on it. Wanted alongside the existing
  conversation log (`interaction`), but after the split.
- **Oracle 12c adapter** (Store, pending Classic DDL) and the **46 wireframe
  back-office screens** (Store) are unaffected by this work.

## Risks

| Risk | Mitigation |
|---|---|
| A trimmed file is needed by something unread | Typecheck on a fresh install in each repo catches it immediately |
| Store history retains HQ data | Fresh `git init`, verified by searching `.git` |
| Docs cite files that no longer exist in their repo | Grep each repo's docs for cross-references to removed paths |
| HQ's dead `@sims/printing` alias breaks its Vite build when dropped | Remove from both `package.json` and `vite.config.ts` together; build verifies |