sims-hq/README.md

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 177 tests pass. Current state and run-vs-pending detail live in STATUS.md; the go-live runbook (server, HTTPS, backups, Gmail/AWS/import wiring, the Postgres switch) is in 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	The console spec: shape, data model, features, delivery sequence (D15)
docs/11-ADMIN-SUPPORT-CONSOLE.md	The vendor-side HQ / support console this app implements
docs/07-DB-AND-CONFIG.md	Everything-in-DB design (messages, plans, settings) and the local DB engine analysis
docs/06-DECISIONS.md	Founder decisions, including D15 (build HQ early) and the Postgres call
docs/16-PROJECT-RULES.md	The hard rules a PR must satisfy to merge
docs/DEPLOY-HQ.md	Go-live runbook for the console

Run

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

# Backend — HQ server (builds the server bundle, then runs it on :5182)
cd apps/hq && npm start
# First boot creates data/hq.db and prints a one-time owner password — capture it.
# Log in as admin@tecnostac.com with that password, 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.