BuildLedger Construction ERP

#Overview

BuildLedger is a single-tenant construction ERP: a React SPA talking to a versioned REST API (/api/v1) backed by PostgreSQL. The backend is a modular monolith with 17 domain modules (projects, materials, labour, vendors, expenses, client payments, invoices, salary slips, fund transfers, documents, reports, users, audit, deletion requests and more), each split into the same layers:

routes → controller → service → repository → Prisma → PostgreSQL

• Routes attach auth, permission checks and Zod validation
• Controllers translate HTTP into service calls
• Services own business rules (who can void, how settlement works)
• Repositories are the only layer that touches Prisma

#System

React + TypeScript (Vercel)
  │  React Query cache · JWT access token · httpOnly refresh cookie
  ▼
Express API (Railway)
  │  helmet → request timing → pino logging → CORS → rate limits
  │  → auth → permissions → validation → module
  ├──► PostgreSQL (Prisma ORM, NUMERIC(14,2) money columns)
  └──► Cloudflare R2 (documents via presigned URLs)

#Key design decisions

Money is never a float. All money columns are NUMERIC(14,2), and invoice and payment math goes through a shared Decimal helper that rounds once, half-up, to 2 decimal places. Floating-point drift (0.1 + 0.2 ≠ 0.3) never reaches a printed invoice.

Inter-project transfers without double counting. When one project funds another, the money moves between projects; it isn't company income or expense. The financial engine nets every pair of projects into a single balance (A→B minus B→A), so each project sees a clear receivable (they owe us) or payable (we owe them). Internal transfers never inflate company-wide totals. Net position = available cash + receivables − payables.

Financial records are voided, not deleted. Transfers and entries are voided with a reason, who did it and when. Real deletions go through an approval workflow: a user requests, a reviewer approves or rejects, and a snapshot of the record is kept so it can be restored.

Everything is audited. A Prisma middleware records every write (old value, new value, who, when) in an audit log, using the request context so no module has to remember to do it.

Access is scoped per project. Admins and accountants see everything. Other roles see only projects granted to them, and that list is read from the database (cached for 60s), not from the JWT. Removing someone's access takes effect within a minute, not when their token expires.

Defense in depth on writes. Global rate limiting, plus a stricter limiter on financial write routes (payments, materials, labour, vendors, expenses, transfers).

#Quality

• Vitest + Supertest tests for money math, invoice totals, project scoping (including IDOR checks), auth, uploads, and race conditions in deletion review
• OpenAPI docs generated with Swagger
• Request timing and structured logs with request IDs for tracing slow calls