ADR-0001: Record architecture decisions
Status: accepted · Date: 2026-10-13 · Decision makers: James Hebden
Context and Problem Statement
Decisions for this project live in three places that don’t agree. The Go project’s docs/contributing/decisions.md was a table of nine alpha-era decisions, two of which were still marked “Proposed” although the behaviour they described had shipped. Its docs/design/registry-cache.md embedded twelve numbered “ADR” sections inside a design document. The Rust rewrite added many more choices that were only written down as porting notes in crates/*/PORT_NOTES.md. A reader can’t tell which record is current.
Decision Drivers
- Decisions should sit next to the code and be reviewed in the same merge requests
- Reversals need a visible trail, so a decision that changes should say what it replaces
- The threat model and the spec need stable identifiers to link to
- The existing decision log is a deliberate stopgap (“an intermediate approach to ADRs”), and its own text says to convert it
Considered Options
- Markdown ADRs in
book/src/project/adr/, MADR 4.0.0 format, numbered sequentially - Keep extending the decision log table
- Track decisions in an external wiki or issue tracker
Decision Outcome
Chosen option: “Markdown ADRs in book/src/project/adr/”, because they get reviewed with the change, carry full git history, and give the threat model and spec something stable to link to. Option 2 stays readable but has no per-decision rationale or alternatives, and the table is already out of date. Option 3 was rejected because the decision log’s own header notes that Slack threads and similar sources expire.
Consequences
Good:
- Each decision records its alternatives and trade-offs
- Cross-references from threats and requirements have a target that won’t be renumbered
Bad:
- Existing decisions had to be migrated. ADR-0011 through ADR-0016 carry over the alpha decision log and the registry-cache design; the one row not carried over is the GitLab-specific Postgres decision, which isn’t about Xianyun.
- Writing ADRs is a recurring cost on every significant change
Neutral:
- The old decision log is gone with the Go documentation (see ADR-0017); its upstream copy is at the pinned commit
More Information
- Retroactively documented on 2026-10-13.
- Still unmigrated: the decision to use locally rendered templates for edit mode (deferring CNG-as-single-source-of-truth), which is about GitLab’s container images and not yet reflected in Xianyun’s code.
- Related: threat model, spec.