Architecture Decision Records

June 15, 2026 ยท View on GitHub

This directory holds the project's architecture decision records (ADRs).

An ADR records an architecturally significant decision, one that affects the project's structure, dependencies, interfaces, or qualities like performance, scalability, and security. CONTRIBUTING.md explains when an ADR is required, and the rule that it must reach Accepted before its implementation pull request can merge.

Starting a new ADR

  1. Copy 000-template.md.
  2. Number it in sequence. Take the highest existing number in this directory, add one, and pad with zeros to three digits.
  3. Name the file <number>-<title>.md with <title> in kebab-case.
  4. Fill in the header. Use today's date and the author's GitHub handle.

Status

  • Proposed while the decision is still under discussion.
  • Accepted once the stakeholders agree. Required before the implementation pull request can merge.
  • Rejected if the decision was discussed and turned down. Keep the file.
  • Deprecated or Superseded when a later ADR changes the decision. Link to the replacement.

Small ADRs that land together with their implementation can start as Accepted when the design is not contested.

Sections

Context

Describe the technical and operational pressures that motivate the decision. These pressures often pull in different directions, say so when they do. Keep the language factual, not opinionated. The recommendation belongs in Decision. When you compare real alternatives, add a ### Possible Solutions subsection. Give each option a sub-heading and list its pros and cons. ADR 001 is the canonical example.

Decision

State the response in active voice ("We will ..."). Name the chosen option when the Context listed alternatives. Say clearly what is in scope and what is not.

Consequences

Describe what changes once the decision is in place. Cover the good, the bad, and the neutral effects honestly.

Follow-up (optional)

When later work adds detail to an Accepted ADR without changing the decision, add a ## Follow-up (yyyy-mm-dd) section to the same file.

ADR 028 is an example. A follow-up is also the right place to revise a single aspect of a decision, for example narrowing the scope, adjusting a default, or replacing one of several listed alternatives, as long as the core decision still holds.

Write a new ADR only when the original decision as a whole no longer holds, for example when the chosen option is replaced, the problem is reframed, or the trade-offs that justified the decision have changed. Link the two with Superseded by and Supersedes. A partial revision that leaves the headline decision intact belongs in a Follow-up, not in a new ADR.

Writing style

  • Write as if speaking to a future contributor. Use full sentences in paragraphs. Bullets are fine for lists, but do not use them to hide fragments.
  • Use simple language at roughly CEFR B1 level. Many readers are not native English speakers. Prefer common words over jargon, short sentences over long ones, and explain acronyms on first use unless they are obvious in the domain (for example BOM, URL, VEX).
  • Stay at the architecture level. Refer to modules (apiserver, notification-publisher), subsystems, data stores, and external dependencies. Avoid class and method names unless the ADR is about a Java API.
  • Keep each sentence short, but do not leave out important context. An honest ADR is more useful than a brief one.
  • Keep punctuation simple. Em-dashes and semicolons usually stitch together clauses that read more clearly as two shorter sentences. Use a comma or a full stop instead.
  • Define links at the bottom as [Label]: url and reference them inline as [Label]. ADR 001 is the canonical example.
  • Link other ADRs by relative path, for example [ADR 007](./007-spec-first-rest-api-v2.md).
  • Draw diagrams in Mermaid using fenced ```mermaid blocks. GitHub renders them natively, so the source stays diffable and reviewable in pull requests. Avoid embedded images for anything a diagram can express.