Onboarding to DemozPay
Welcome. This folder is the front door for a developer who knows nothing about the codebase.
It is written with brutal honesty about what is built vs. what
is planned. If you read something here that says Live, it works
today. If it says Planned, it is a roadmap claim only — there is
no code for it yet. The legend lives in
docs/STATUS_LEGEND.md.
Read these in order
You can finish the whole suite in ~2 hours. Each file stands alone but they build on each other.
| # | File | What you'll learn | Time |
|---|---|---|---|
| 0 | This README | The map | 5 min |
| 1 | 01-what-is-demozpay.md | What the platform actually does in plain English, then how the code maps to it | 15 min |
| 2 | 02-running-locally.md | Clone, start Postgres, run migrations, boot the API, hit a real endpoint | 20 min hands-on |
| 3 | 03-the-codebase-tour.md | Every folder explained: why it exists, what's in it, what's stubbed | 20 min |
| 4 | 04-how-the-backend-works.md | NestJS modular monolith + Go ledger; request flow; money flow; event flow | 25 min |
| 5 | 05-the-frontend-apps.md | The five Next.js apps and what they show today (honest: all mocks) | 10 min |
| 6 | 06-status-matrix.md | One table: every capability × status × what blocks it from Live | 10 min |
| 7 | 07-rules-and-patterns.md | The seven non-negotiables and the patterns you must use | 15 min |
| 8 | 08-how-to-add-things.md | Recipes: a new endpoint, a new event, a new migration, a new domain | 20 min reference |
| 9 | 09-common-mistakes.md | What goes wrong and how to debug it | 10 min reference |
Different paths for different roles
If your time is limited, here are the minimum-viable reading paths:
| Role | Read at minimum |
|---|---|
| Backend engineer | 01, 02, 03, 04, 06, 07, 08, 09 |
| Frontend engineer | 01, 02, 05, 06, 08 |
| DevOps engineer | 01, 02, 03 (services/, infra/), 04 (operational flow), 06, 07, 09 |
| Product manager | 01, 05, 06 |
| Fintech auditor | 01, 04, 06, docs/adr/ADR-013, SECURITY_CONTROLS.md |
| Intern (June 2026 cohort) | All 10 + INTERN_PROGRAM.md |
The seven non-negotiable rules at a glance
These are enforced at code-review, lint, migration or runtime. Detail in 07-rules-and-patterns.md.
- Money is integer santim (
NUMERIC(20,0)). Never floats. (ADR-005) - Ledger is the sole source of money truth. No
balancecolumns on financial-tier tables. (ADR-006) Idempotency-Keyrequired on every money-moving POST. (ADR-007)- Audit + outbox event commit in the same DB transaction as the state change. (ADR-008)
- No
DELETEon financial rows. Reversals only. (ADR-009) - Tenant scoping mandatory — Postgres RLS, fail-closed. (ADR-013)
- Two-language ceiling. TypeScript + Go only. (ADR-010)
If you find yourself wanting to violate one of these, stop and write an ADR first. No exceptions.
Where else to read
After this suite:
../architecture/SYSTEM_TOPOLOGY.md— the operator-level picture: every container, every port, every API surface, every database, plus three end-to-end traces. Read this alongside 04-how-the-backend-works.md.../../CLAUDE.md— terse project context (also auto-loaded into AI sessions). Good cheat sheet.../../README.md— clone-and-run guide.../../PROJECT_STRUCTURE.md— folder guide (longer than 03-the-codebase-tour.md, less opinionated).../adr/— Architecture Decision Records. ADRs 001…013. The why behind every non-obvious choice.../../SECURITY_CONTROLS.md— partner-bank / auditor Q&A. Read with the status legend in mind.../../INTERN_PROGRAM.md— the 16-week intern programme starting 2026-06-01.
Tone of these docs
This suite is descriptive, not aspirational. When something isn't built, we say so. When something works only on the developer's laptop and not in production, we say so. This avoids the most common onboarding failure mode in fintech: a new engineer reads "the ledger guarantees X" and writes code that assumes X is live, when in fact only the schema for X is live and the Go server is compile-only.
If a doc here ever drifts from reality, fix the doc in the same PR as the code. The status tag is more important than the prose.