You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
84 lines
4.9 KiB
Markdown
84 lines
4.9 KiB
Markdown
# 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).
|
|
|
|
## Build state (start here)
|
|
|
|
Working codebase, not a plan. `npm install` + typecheck are clean and **270 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, Pipeline, Clients,
|
|
ClientDetail, Modules, Reports, NewDocument, DocumentView, Employees (owner-only),
|
|
DocumentTemplate (owner-only).
|
|
- **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`.
|