Skip to main content
Decisions · ADRs An architecture decision record captures a choice at the moment it was made, with the context that made it reasonable and the alternatives that were rejected. Read later, an ADR answers the question every codebase eventually raises: why on earth is it like this? The value is in the parts that are uncomfortable to write. A record listing only the benefits is marketing. Each of these states what the decision costs.

​
Accepted

0001 · Money as integer minor units

Every monetary value is a bigint count of minor units. No floats in monetary APIs, enforced by ESLint rather than convention.

0002 · Modular monolith over microservices

One deployable, six bounded contexts, and a boundary that fails the build rather than eroding.

0003 · Chain-agnostic driver

Settlement talks to an interface, not a chain SDK, with a seeded simulator so reorgs and stuck transactions are testable.

0004 · Saga over two-phase commit

Banks and blockchains do not enrol in distributed transactions, so every step carries a compensating action.

0005 · Idempotency keys

A retry returns the original response; the same key with a different body is a conflict, not a cache hit.

0006 · Transactional outbox

Events are staged in the same transaction as the state change, so delivery is at-least-once and handlers are idempotent.

0007 · Row-level tenancy

A tenant on every record, sandbox tenants by prefix, and environment-prefixed credentials.

0008 · Double-entry, enforced by the database

Balances derived from entries, entries append-only, and the balance rule enforced in Postgres as well as in code.

​
The format

Every record on this site uses the same four sections, and the order is deliberate:
1

Context

The forces in play before the decision. What made this a question at all? An ADR whose context does not explain why the obvious answer was insufficient is not describing a decision.
2

Decision

What was chosen, stated plainly and in the present tense. One paragraph, not a design document.
3

Consequences

Both directions. What this makes easy, and what it makes hard or impossible. The costs section is the one that earns the record its place.
4

Alternatives

What else was considered and specifically why it was rejected. Not strawmen: the version of each alternative its advocate would recognise.
ADRs are immutable once accepted. A decision that changes gets a new record that supersedes the old one, and the old one stays in place marked as superseded.Editing an accepted ADR destroys the only thing it was for: the record of what was known and believed at the time. The same reasoning as the ledger’s append-only entries: the record of what happened stays separate from the record of what was later thought better.