Architecture Decision Records (ADRs)

The decision log for DemozPay's engineering choices.

Why ADRs?

Six months from now, someone — maybe you — will ask "wait, why did we pick PostgreSQL over MongoDB?" or "why is the ledger a separate service?" ADRs answer that, in writing, with the alternatives we considered. They are the difference between "we just did it" and "here's the reasoning."

When to write one

Write an ADR when you make a decision that:

• Affects more than one team or codebase area, OR
• Locks in a choice that is expensive to reverse, OR
• Will be questioned later by people who weren't in the room.

If a decision is reversible in an afternoon, you probably don't need an ADR. If it's a 3-month migration to undo, you do.

Template

# ADR-NNN: <title in present tense>

- **Status:** Proposed | Accepted | Superseded by ADR-XXX
- **Date:** YYYY-MM-DD
- **Deciders:** name(s) or role(s)

## Context
What problem are we solving? What constraints exist?

## Decision
What we decided to do. One paragraph, plain language.

## Alternatives considered
- **Option A** — why we didn't pick it
- **Option B** — why we didn't pick it

## Consequences
- Positive: what this gives us
- Negative: what this costs us
- Follow-ups: what we now need to do

How to add one

1. Copy the template above to ADR-NNN-<short-kebab-title>.md (next number in sequence).
2. Fill it in.
3. Open a PR. ADRs get reviewed like code.
4. Once merged, status becomes Accepted.
5. If a later decision supersedes this one, update the status to Superseded by ADR-XXX and leave the old file in place — never delete ADRs.

Index

#	Title	Status
001	Modular monolith + 3 satellite services from day 1	Accepted
002	packages/ over libs/; domain-first layout	Accepted
003	Domain package shape — domain / application / infrastructure / presentation	Accepted
004	Frontend apps use <audience>-web naming	Accepted
005	Money is NUMERIC(20, 0) in santim; floats forbidden	Accepted
006	The ledger is the sole source of money truth — no derived balance columns	Accepted
007	Idempotency-Key required on every money-moving POST	Accepted
008	Audit + outbox event live in the same DB transaction as the state change	Accepted
009	No DELETE on financial rows — reversals only	Accepted
010	Two-language ceiling — TypeScript and Go only	Accepted
011	Cross-domain communication is event-only — no direct imports between domain packages	Accepted
012	Ledger accounting model — double-entry, derived balances, DB-enforced invariants	Accepted
013	Tenant isolation via Postgres RLS, fail-closed by default	Accepted
014	DemozPay is a bank-to-bank orchestrator, not a custodian	Accepted (pending Legal counter-sign)
015	Adjustment-journal process for non-zero reconciliation drift	Proposed
016	Dispute workflow for contested money movements	Proposed
017	Postgres outbox + table-poller is the event-transport spine; no running broker	Accepted
018	Progressive service extraction behind stable contracts	Accepted
019	Database-per-service — per-context schemas at MVP, separate DBs on extraction	Accepted
020	Contract-first integration — packages/contracts is the law (buf + schema registry + CI gates)	Accepted
021	Lightweight saga orchestration at MVP; Temporal deferred	Accepted
022	Kafka topic naming, ownership, versioning, DLQ & replay (when activated)	Accepted
023	API Gateway + BFF; REST only at the edge	Accepted
024	Custody model — partner banks hold funds, the Ledger is the record, no internal wallet	Accepted (pending Legal counter-sign)
025	Bank Gateway adapter contract — bank-sandbox is a dev adapter; real FIs plug into the same port	Accepted
026	Typed event contracts + Kafka consumer rules	Accepted
027	Redis usage posture — cache & ephemeral state only, never a source of truth	Accepted
028	Unified compensation model	Accepted
029	DemozAuth — framework-agnostic auth platform	Accepted (Phase 2a)