Joshua OosthuizenandClaude Sonnet 5
4acbc03b35
Root company app (src/, client/) — GL foundation, AR, and AP: - Segmented Chart of Accounts (Sage 300-style), double-entry PostingService with three-layer balance enforcement (app validation, CHECK constraints, deferred DB trigger), gap-free document numbering, RBAC with branch restrictions. - Accounts Receivable: Customers, Invoices, Credit Notes, Receipts with allocation, all posting through PostingService. - Accounts Payable: Suppliers, Supplier Invoices, Debit Notes, Payments with allocation, mirroring AR's posting pattern. - Tax Codes shared between AR and AP. - Company-app login is a token handoff from the Account Manager (RS256, single-use, company-scoped) rather than a local password. - Frontend reskinned to the approved mockup: navy sidebar, dashboard, tree-view Chart of Accounts, Customer/Supplier 360 pages. Account Manager (manager/, manager/client/) — central login gateway: - Password + TOTP 2FA + Google/Microsoft OAuth, company picker, and the RS256 handoff token issuance that the company app verifies. Covered by unit + integration tests against a real Postgres database (GL balance invariants, AR/AP posting correctness and allocation limits, the full handoff exchange including replay/cross-company/expiry/forgery rejection). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Tq2DbEvzHzs13jDFhLaX44
2.8 KiB
2.8 KiB
Setup — Phase 1 (Foundation)
Prerequisites
- Node.js 18+ (tested on v22)
- A reachable PostgreSQL 15+ database (this project does not use Docker)
Login
This app has no local login screen — see ../manager/. Sign-in happens once at the central
Account Manager (2FA, Google, Microsoft), which hands this app a short-lived signed token
(POST /api/auth/handoff) instead of a password. ../manager/keys/handoff-public.pem must be
copied into keys/handoff-public.pem here (see step 4) before that will work.
First-time setup
- Copy
.env.exampleto.envand fill in a realDATABASE_URL, two random JWT secrets (e.g.node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"), andCOMPANY_SLUG(must match theslugof this company'sCompanyrow in the Manager)..envis gitignored — never put real secrets in.env.example. npm installnpm run prisma:migrate— applies all migrations, including the hand-writtenprisma/migrations/*_add_journal_balance_trigger/migration.sql(the double-entry DB backstop; source copy also kept atprisma/manual-sql/add_journal_balance_trigger.sqlfor reference).mkdir keys && cp ../manager/keys/handoff-public.pem keys/(after runningnpm run generate-handoff-keysin../manager/at least once).npm run prisma:seed— creates the default 4-segment account structure, default Chart of Accounts across two example branches (HQ, AMA), the GJ general journal, the 2026 fiscal year, default roles/permissions, and an admin user (joosth2002@icloud.com, no local password — this email must match the ManagerPersonwho signs in).npm run dev— starts the API onhttp://localhost:4000(seePORTin.env).
Verifying it works
npm test— unit tests (no DB required; validates PostingService's pre-write balance checks).npm run test:integration— integration tests against the real DB: posts balanced/unbalanced entries through the full stack (including a direct raw-SQL attempt that proves the DB trigger backstop works even ifPostingServiceis bypassed), and exchanges real handoff tokens (minted with the Manager's real private key) to prove sign-in, replay protection, and cross-company rejection all work end-to-end.npm run smoke— seeds two sample balanced entries (HQ and AMA), confirms an unbalanced one is rejected, and prints a Main-level trial balance check.GET /health— basic liveness check.
Adding a new migration
Prisma's schema DSL can't express multi-row CHECK constraints or triggers, so any future raw-SQL addition (e.g. more constraints) follows the same pattern used for the balance trigger:
npx prisma migrate dev --create-only --name <description>- Hand-edit the generated
migration.sql npx prisma migrate devto apply it