# SiMS HQ — Internal Ops Console

The console for running our own software business. It manages our **~300 Classic clients**
end to end — and it replaces the internal Oracle APEX app. This repo is **internal only**;
it is **not** shipped to clients.

One place for the client book, what each client has bought, the money they owe, and every
document and conversation we've had with them.

## What it does

- **Client book** — the registry of ~300 clients: contacts, GSTIN, status, notes.
- **Modules + price book** — the sellable software modules with a **dated price book** (a
  price change is a new row, not a code release) and per-client subscriptions.
- **Documents** — quotations (QT), proforma invoices (PI), invoices (INV) and credit notes
  (CN), built on **editable letterhead templates**, rendered to **PDF** (headless Chromium),
  with **shareable public links** (one token-guarded, rate-limited, revocable read route).
- **Interactions** — call / visit / meeting tracking against each client.
- **AMC contracts** and **AWS cost recovery** — per-client cost attribution pulled monthly.
- **Payments + allocations**, **recurring plans**, and **reminders** sent via **Gmail** on
  the company mailbox, with **bounce handling** and a manual queue when the token dies.
- **Reports**, a **Dashboard**, an **append-only audit log** (every mutation), an **APEX
  importer** for the initial 300-client load, and a **scheduler** (runs on boot + every 6h:
  reminders, bounce polling, AWS cost pull).

## Build state (start here)

Working codebase, not a plan. `npm install` + typecheck are clean and **255 tests pass**.
Current state and run-vs-pending detail live in **[STATUS.md](STATUS.md)**; the go-live
runbook (server, HTTPS, backups, Gmail/AWS/import wiring, the Postgres switch) is in
**[docs/DEPLOY-HQ.md](docs/DEPLOY-HQ.md)**.

## Architecture

- **Backend — `apps/hq/src`**: an Express JSON API over **better-sqlite3**, behind portable
  repositories (`repos-*.ts`, one per domain: clients, modules, documents, payments, amc,
  aws, interactions, recurring, reminders, shares, reports, dashboard, email). SQLite is the
  dev/test engine; Postgres is the locked production engine (see DEPLOY-HQ.md). DB at
  **`data/hq.db`**; server on **:5182** (also serves the built web UI and the public
  `/share/:token` route).
- **Frontend — `apps/hq-web`**: React + Vite. Pages: Dashboard, Clients, ClientDetail,
  Documents, Modules, Reports.
- **Shared packages** (trimmed forks): `@sims/domain` (ids, money, business-day, doc-series,
  gstin, documents), `@sims/auth` (pin/scrypt), `@sims/billing-engine` (compute, tax — our
  invoices are GST documents, computed to the paisa), `@sims/ui` (design system).

## Planning docs

| Doc | What it covers |
|-----|----------------|
| [docs/14-SPEC-HQ-CONSOLE.md](docs/14-SPEC-HQ-CONSOLE.md) | The console spec: shape, data model, features, delivery sequence (D15) |
| [docs/11-ADMIN-SUPPORT-CONSOLE.md](docs/11-ADMIN-SUPPORT-CONSOLE.md) | The vendor-side HQ / support console this app implements |
| [docs/07-DB-AND-CONFIG.md](docs/07-DB-AND-CONFIG.md) | Everything-in-DB design (messages, plans, settings) and the local DB engine analysis |
| [docs/06-DECISIONS.md](docs/06-DECISIONS.md) | Founder decisions, including D15 (build HQ early) and the Postgres call |
| [docs/16-PROJECT-RULES.md](docs/16-PROJECT-RULES.md) | The hard rules a PR must satisfy to merge |
| [docs/DEPLOY-HQ.md](docs/DEPLOY-HQ.md) | Go-live runbook for the console |

## Run

```bash
npm install                     # from the repo root (workspaces: packages/*, apps/*)

# Backend — HQ server. Build the bundle, then run it FROM THE REPO ROOT: the DB
# path resolves to ./data/hq.db against the current working directory, so the
# server must be launched from the repo root (not from apps/hq, which would look
# in apps/hq/data and boot an empty database).
npm run build --workspace @sims/hq
node apps/hq/dist/server.cjs     # serves :5182 (API, built web UI, /share/:token)
# First boot on an empty data/ creates data/hq.db and prints a one-time owner
# password — capture it. Log in as admin@tecnostac.com, then change it.

# Frontend — hq-web dev server (Vite on :5183, proxies /api and /share to :5182)
cd apps/hq-web && npm run dev
```

Nothing in `apps/hq/.env` is required to boot; each var unlocks a capability (Gmail sending,
AWS cost pull, security peppers) — see `apps/hq/.env.example` and DEPLOY-HQ.md. Repo-wide
checks from the root: `npm run typecheck` and `npm test`.