Files

T

Joshua OosthuizenandClaude Sonnet 5 4acbc03b35 Initial commit: multi-company financial management system

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

2026-09-03 13:27:19 +02:00

2.8 KiB

Raw Permalink Blame History

Setup — Phase 1 (Foundation)

Prerequisites

Node.js 18+ (tested on v22)
A reachable PostgreSQL 15+ database (this project does not use Docker)

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.example to .env and fill in a real DATABASE_URL, two random JWT secrets (e.g. node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"), and COMPANY_SLUG (must match the slug of this company's Company row in the Manager). .env is gitignored — never put real secrets in .env.example.
npm install
npm run prisma:migrate — applies all migrations, including the hand-written prisma/migrations/*_add_journal_balance_trigger/migration.sql (the double-entry DB backstop; source copy also kept at prisma/manual-sql/add_journal_balance_trigger.sql for reference).
mkdir keys && cp ../manager/keys/handoff-public.pem keys/ (after running npm run generate-handoff-keys in ../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 Manager Person who signs in).
npm run dev — starts the API on http://localhost:4000 (see PORT in .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 if PostingService is 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 dev to apply it

2.8 KiB Raw Permalink Blame History