Architecture Decision Records

Decisions that would be expensive or impossible to reverse later, recorded with the alternatives that lost and the reason they lost.

ADR	Decision	Status
0001	Modular monolith with detached workers, not microservices	Accepted
0002	Point-in-time correctness enforced by API shape, not developer discipline	Accepted
0003	Deterministic calibrated aggregation; the LLM explains rather than scores	Accepted
0004	Compliance is a terminal gate, not a weighted signal	Accepted
0005	Untrusted content quarantined by capability removal, not by prompt instruction	Accepted
0006	Local-first inference with gateway-enforced redaction	Accepted
0007	No AI component may reach the broker	Accepted

When to write one

Write an ADR when a change alters a component boundary, a data contract, a compliance rule, or a security control — or when someone would reasonably ask "why is it done this way?" six months from now. Everything else is a normal commit.

Format

Context (the forces in tension) → Decision (what we chose) → Rationale (why, including what was rejected) → Consequences (positive, negative, and accepted risk).

State the negative consequences honestly. An ADR that lists only benefits is advocacy, and it is useless to the person who later has to decide whether the decision still holds.