Creating an Architecture Module & Writing ADRs

Architecture documentation answers why the system is shaped the way it is: its system-level structure, the patterns it standardises on, and — through Architecture Decision Records (ADRs) — the individual decisions and trade-offs that got it there. It is the reference a lead reads before making a change that crosses subsystem boundaries.

1. When to use this type

Create an Architecture module when the system has cross-cutting structure and patterns worth stating once (integration style, security model, service patterns), and adopt ADRs as soon as decisions with long-term consequences start being made.

It IS architecture/ADR when… It is NOT when…

It describes system-level structure or a standard pattern

It describes one feature’s build → Design

It records why a decision was made and the alternatives

It records what must be true → Requirements

It will be referenced when changes cross boundaries

It is a transient implementation note

2. Standard structure

modules/architecture/
├── nav.adoc
└── pages/
    ├── index.adoc                 # Architecture overview + pattern catalogue
    ├── <pattern>.adoc             # A standardised pattern (e.g. service, integration)
    └── adr/
        ├── index.adoc             # ADR log (table of all decisions + status)
        ├── adr-0001-<slug>.adoc
        └── adr-0002-<slug>.adoc

ADRs are immutable once accepted — a superseded decision is not edited; a new ADR supersedes it and the old one is marked Superseded by ADR-NNNN.

3. ADR template

Use the lightweight ADR format. Copy templates/adr-template.adoc, or:

= ADR-NNNN: <Decision title>
:description: <one line — the decision>

[cols="1,3"]
|===
| Status | Proposed | Accepted | Superseded by ADR-NNNN
| Date | YYYY-MM-DD
| Deciders | <names/roles>
|===

== Context
<The forces at play — the problem, constraints, and what makes this a real decision.>

== Decision
<What we decided, stated plainly.>

== Consequences
<What becomes easier and what becomes harder. Include the costs you are accepting.>

== Alternatives considered
<The options not taken, and why — this is what makes the ADR valuable later.>

The Alternatives considered and the costs in Consequences are the parts a future reader needs most. An ADR that records only the chosen path, with no trade-offs, is a changelog, not a decision record.

4. Architecture pages vs ADRs

  • An architecture page describes a standing structure or pattern as it is now ("the service pattern", "the security model"). It is kept current.

  • An ADR is a point-in-time decision with its rationale. It is immutable and accumulates into a log. Architecture pages often cite the ADRs that produced them.

5. Flexibility

  • Small project: ADRs alone (an adr/ folder) may be enough — no separate pattern pages until a pattern is actually reused.

  • Platform / many services: a fuller Architecture module with pattern pages, plus the ADR log.

  • Strategic context: link ADRs to organisational strategy/roadmap where one exists.

6. Quality checklist

  • Each ADR records Context, Decision, Consequences (incl. costs), and Alternatives.

  • ADR status is current; superseded ADRs point to their replacement.

  • The ADR log/index lists every decision with status and date.

  • Architecture pages describe standing structure and cite the ADRs behind them.

  • Distinct from Design (how) and Requirements (what).

7. Common pitfalls

  • Editing an accepted ADR — supersede it with a new one instead; the history is the value.

  • ADR with no alternatives — without the roads not taken, the decision can’t be re-evaluated.

  • Architecture page that’s really a design — if it’s one feature’s build, it’s Design.

  • Decisions that never get recorded — capture them when made, not reconstructed months later.

8. Related