# 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.
- **Quote-to-close funnel** — employee accounts (owner / manager / staff), a cross-client
  **pipeline chase-list** (stages derived, oldest-overdue on top), and **escalating quote
  follow-up** that nudges the owning employee and emails the client a share link on a dated
  schedule (`reminder_schedule`), stopping automatically on accept / lose / convert.
- **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).
- **A redesigned ops UI** — light/dark theme with accent + neutral palettes, grouped
  sidebar with a live reminder badge, a **Ctrl-K command palette** (clients, documents,
  tickets, pages, actions), and a **Client 360** with tabbed sections and a 12-month
  **relationship-pulse ribbon**; phone-usable drawer layout.
- **Support tickets** (aging/SLA/assignee workbench, bill-from-ticket), **onboarding**
  milestones, and **per-module operational fields** each module declares (config, not code) —
  surfaced per client on Client 360, across all clients in the **Module data** directory, and
  as a **Portals** quick-list of every stored login. For the **SMS** module those fields
  include a **live credit balance** pulled from the provider gateway (manual refresh + a daily
  pass), with low balances flagged for a one-click top-up quote.
- **Renewals** command center, an owner **MIS cockpit**, an **audit-log viewer**, and
  **database backups** (`npm run backup` → compressed, restorable `pg_dump`). Credentials are
  stored in the clear (no `HQ_SECRET_KEY`), so the DB and its backups are the security boundary.
- **Employees** with per-user logins (imported from the master; an "invited" flag until they
  change their default password), and a **login history** (every sign-in with IP + device).
- **Client classification** — each client is a **PACS** or **Store**, and carries a **society
  category** matching the Kerala co-op directory (Service Bank / Vanitha / Housing / Employees /
  …); both are filterable on the Clients screen.

## Build state (start here)

Working codebase, not a plan. `npm install` + typecheck are clean and **416 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: Home, Dashboard, Pipeline, Reminders,
  Tickets, Onboarding, Clients, ClientDetail, Documents, NewDocument, DocumentView, Renewals,
  SMS credits, Modules, Module data, Portals, Reports, MIS cockpit (owner), Employees (owner),
  Profile, APEX Import (owner), Audit log (owner), Login history (owner), Settings.
- **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/superpowers/specs/2026-07-17-quote-to-close-funnel-design.md](docs/superpowers/specs/2026-07-17-quote-to-close-funnel-design.md) | The delivered D16 funnel slice — employees, pipeline, escalating reminders, convert/supersede, module roster |
| [docs/superpowers/specs/2026-07-17-hq-console-redesign-design.md](docs/superpowers/specs/2026-07-17-hq-console-redesign-design.md) | The delivered warm ops-console UI redesign |
| [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@sims.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`.