Architecture decisions
An architecture decision record (ADR) states one decision that shapes the system: the problem, the options that were on the table, the choice, and what it costs. This is section 11 of the system documentation.
Format
Section titled “Format”The records follow MADR (Markdown Architectural Decision Records). Every page has the same parts, in this order: status and date, “Context and problem statement”, “Decision drivers”, “Considered options”, “Decision outcome”, “Consequences” and “More information”. The status is “Proposed”, “Accepted” or “Superseded by ADR-NNNN”. “Considered options” lists only the options that were evaluated when the decision was made, or the common alternative in the market, marked as such. “More information” points to the code where the decision is applied and to the pages of this documentation that explain the concept.
A record is never rewritten to say something else. When a decision changes, a new record is written and the old one stays, with the status “Superseded by” and a link to its replacement.
Proposing a new record
Section titled “Proposing a new record”Run scripts/docs.sh new adr "<decision>" from the root of the repository. It creates a file in apps/docs/src/content/docs/system/adr/, named with the next free four-digit number and a slug of the title (for example 0029-short-title.md), in the format above, with the status “Proposed”, the date of today and sidebar.order set to the number, and adds the row to the table above. Replace every placeholder text the template marks, then open it for review together with the change it supports; scripts/docs.sh check fails while the record is out of the format or a number is missing. When the change is merged the status becomes “Accepted”. If the new record replaces an older one, change the status of the older record in the same commit.