Architecture Decision Records
1. Purpose
An Architecture Decision Record (ADR) captures one significant decision — what was decided, why, what alternatives were considered, and what the consequences are. ADRs exist so that someone asking "why did you do it this way?" or "why not the other way?" can find the original reasoning instead of re-litigating it.
Decisions that belong here:
-
Shape the system in ways that are expensive to reverse.
-
Trade one desirable property off against another (performance vs. simplicity, consistency vs. availability, strictness vs. tolerance).
-
Encode operational realities that are not obvious from reading the code.
Decisions that do not belong here — use the design journal for those:
-
In-progress exploration (ADRs are the output of the process, not the thinking).
-
Coding style, naming, or formatting preferences.
-
Decisions scoped to a single file or method.
2. Conventions
-
Filename:
adr-NNNN-short-kebab-title.adoc(zero-padded sequence). -
Status: one of
Proposed,Accepted,Deprecated,Superseded by ADR-NNNN. -
Once an ADR is Accepted and merged, it is immutable. Decisions that supersede it get a new ADR; the old one is updated to point forward.
-
Use the template at adr-template.adoc when adding a new ADR.
3. Catalogue
| ADR | Title | Status |
|---|---|---|
RaceNumber state transitions live in the service, not the callers |
Accepted |
|
Result import accepts IN_STOCK as implicit issuance |
Accepted |
|
Result import does not transition UNFIT_FOR_SERVICE |
Accepted |
|
|
Accepted |
|
Prefer eventual consistency over enforced process |
Accepted |
|
Auto-assign prefers latest-used only; UNFIT-latest forces manual assignment |
Accepted |