Architecture Decisions

Architecture Decision Records

Decision-Driven Documentation — Architecture Decision Records (ADRs) capture the why behind significant technical choices, ensuring institutional knowledge outlasts the individuals who held it.

What is an Architecture Decision Record?

An Architecture Decision Record (ADR) is a short document that captures an important architectural decision made in a project, along with its context and consequences. The concept was introduced by Michael Nygard in 2011 and has become a widely adopted practice in software engineering and infrastructure teams.

An ADR answers three fundamental questions:

  • What did we decide? — A clear, unambiguous statement of the decision made.
  • Why did we decide it? — The context, constraints, forces, and trade-offs that drove the decision.
  • What are the consequences? — Both positive outcomes and accepted drawbacks that result from the decision.

Crucially, an ADR is not a design document or a specification. It is a record of a decision that was made at a specific point in time, under specific constraints. The decision may later be superseded — and that's expected — but the historical record remains.

Why Document Architecture Decisions?

Knowledge Transfer & Onboarding

When a new engineer joins the team, they inevitably ask: "Why is the system built this way?" Without ADRs, the answer is either "ask Alice — she was here when that was decided" or, if Alice has left, a shrug. ADRs make institutional knowledge explicit and accessible to anyone who reads the repository. A new team member reading through 20 ADRs understands years of architectural evolution in an hour.

Avoid Repeating Mistakes and Revisited Debates

Without documented decisions, teams repeatedly revisit the same choices. Every few months someone proposes switching from Terraform to Pulumi, or from PostgreSQL to MongoDB, and the team relitigates the same arguments from memory — except key details are forgotten. An ADR short-circuits this by recording not just what was chosen, but what was rejected and why. The next person who raises the same alternative encounters a documented rationale for the rejection.

Audit Trail & Accountability

In regulated industries (financial services, healthcare, government), auditors and compliance officers may ask: "Why is customer data stored in this region? Who authorised the choice of this encryption standard?" ADRs provide a timestamped, version-controlled answer. They demonstrate that architectural choices were deliberate, considered, and approved — not accidental.

Design Review & Team Alignment

The act of writing an ADR forces clarity. An engineer who cannot clearly articulate the context and consequences of a decision in one page has not yet fully understood the problem. The PR-based review process for ADRs creates a structured forum for architectural debate, ensuring all stakeholders have visibility and input before a decision is locked in.

When to Write an ADR

Not every technical choice warrants an ADR. The signal that an ADR is appropriate is when the decision:

  • Involves adopting a new technology, framework, or platform for the first time
  • Represents a significant change to the system's structure, integration points, or data model
  • Involves a meaningful trade-off where reasonable engineers could disagree
  • Requires rejecting an alternative that others might later propose
  • Has consequences that will affect other teams or services
  • Is difficult or costly to reverse — a "one-way door" decision
What NOT to write an ADR for: Routine implementation details (naming a variable, choosing a specific library version patch), pure style preferences with no architectural consequence, and decisions that are trivially reversible without system-wide impact.

ADR Lifecycle

Every ADR moves through a defined set of statuses. The status is always recorded in the ADR header and updated in the same Git commit that changes the status.

Proposed
→
Accepted
→
Deprecated
Accepted
→
Superseded
Status Meaning Next State
Proposed The ADR has been written and submitted for review via pull request. The decision has not yet been approved. Accepted (PR merged) or Rejected (PR closed)
Accepted The decision has been reviewed, approved by required reviewers, and merged. The decision is in effect and the team is expected to follow it. Deprecated or Superseded
Deprecated The decision is no longer relevant or in force, but has not been replaced by a specific successor decision. The system may still reflect this decision, but no new work should follow it. Terminal (may eventually be Superseded if a replacement is written)
Superseded This decision has been replaced by a newer ADR. The superseding ADR number must be referenced in the header. The original ADR is retained for historical context. Terminal

MADR Format

This portfolio uses the MADR (Markdown Architectural Decision Records) format, developed by the MADR project at adr.github.io/madr. MADR is lightweight, human-readable, and well-suited to storage in Git alongside code.

# ADR-NNNN: [Short Title of Decision]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-NNNN]

## Date
YYYY-MM-DD

## Authors
- [Name] <email>

## Reviewers
- [Name] <email>

## Context and Problem Statement
[Describe the context and the architectural problem that necessitates this decision.
Include relevant background: team size, system scale, regulatory constraints, timeline.
Keep this to 2–4 paragraphs. The reader should understand WHY a decision was needed.]

## Decision Drivers
- [Primary constraint or requirement driving this decision]
- [Secondary driver: e.g., team expertise, cost, operational burden]
- [Non-functional requirement: performance, security, reliability]

## Considered Options
1. [Option A — preferred option]
2. [Option B]
3. [Option C]
4. Do nothing / status quo

## Decision Outcome
**Chosen option:** "[Option A]", because [summarise the primary reason in one sentence].

### Positive Consequences
- [Benefit 1]
- [Benefit 2]

### Negative Consequences / Accepted Trade-offs
- [Trade-off 1 that was accepted]
- [Limitation or risk that must be managed]

## Pros and Cons of the Options

### Option A — [Name]
**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]

### Option B — [Name]
**Pros:**
- [Pro 1]

**Cons:**
- [Con 1: the reason this was not chosen]

### Option C — [Name]
**Pros:**
- [Pro 1]

**Cons:**
- [Con 1: the reason this was not chosen]

## Links
- [Link to related ADR, RFC, Jira ticket, or design document]
- [Link to proof-of-concept or benchmark results if applicable]

ADR Numbering and Naming Convention

ADRs use a zero-padded four-digit sequential number followed by a lowercase hyphenated short title.

Format: ADR-NNNN-short-title.md

Examples:

  • ADR-0001-use-postgresql-as-primary-database.md
  • ADR-0002-use-terraform-for-infrastructure-provisioning.md
  • ADR-0015-migrate-from-jenkins-to-github-actions.md
  • ADR-0023-adopt-open-telemetry-for-observability.md

Rules: Numbers are sequential and never reused. If an ADR is rejected (PR closed), the number is still consumed — do not recycle numbers. Titles should be a short verb phrase (5–8 words) that reads as a decision statement, not a question.

Where to Store ADRs

Primary Location: docs/decisions/ in the Git Repository

ADRs must live in version control, ideally in the same repository as the code or infrastructure they govern. This ensures that:

  • ADRs are versioned and auditable alongside the changes they describe
  • Engineers reading code can reference decisions from the same repository
  • ADR reviews happen via the same PR workflow as code reviews
  • ADRs are never separated from the artefact they document

Co-location: Near the Code They Affect

For decisions that are scoped to a specific service or component, place the ADR in that component's own docs/decisions/ subdirectory rather than a top-level directory. This makes the ADR discoverable by engineers working on that component. Cross-cutting decisions (infrastructure, security, data architecture) should go in the top-level repository.

ADR Review Process

All ADRs must be reviewed and approved before they are merged with status Accepted. The review process mirrors the code review process: a pull request is opened, reviewers are assigned, feedback is addressed, and the PR is merged only when approval criteria are met.

Required Reviewers

  • Technical lead of the team owning the decision (mandatory)
  • Architect or senior engineer from an affected team (mandatory for cross-cutting decisions)
  • Security engineer for any decision involving data storage, authentication, encryption, or network architecture
  • At least one other team member for perspective and knowledge sharing

Acceptance Criteria

  • The problem statement clearly explains why the decision was needed
  • At least two alternatives were genuinely considered (not just listed as strawmen)
  • The rationale for the chosen option is specific — not just "it's better" but "it satisfies constraint X which options B and C do not"
  • Negative consequences are acknowledged honestly, not minimised
  • All required reviewers have approved
  • The ADR links to any relevant proof-of-concept, benchmark, or spike ticket

Tools

adr-tools CLI

The adr-tools CLI by Nat Pryce provides shell commands to create, list, and link ADRs from the command line. It automatically manages numbering and supports status transitions.

# Install (macOS)
brew install adr-tools

# Initialise ADR directory in current project
adr init docs/decisions

# Create a new ADR
adr new "Use PostgreSQL as primary relational database"

# List all ADRs
adr list

# Mark an ADR as superseded by a newer one
adr supersede 3 15

log4brains

log4brains is a static site generator for ADRs. It reads Markdown ADRs from your repository and generates a searchable, browsable web interface — similar to what you are reading now. Integrate it into your CI/CD pipeline to auto-publish ADR documentation on every merge to main.

# Install log4brains
npm install -g log4brains

# Initialise in project
log4brains init

# Preview ADR site locally
log4brains preview

# Build static site for deployment
log4brains build

Confluence Decision Log

For organisations using Atlassian Confluence, a Decision Log space (using the built-in Decision page template) provides a centralised, searchable view of ADRs with richer formatting and inline comments. The trade-off is that decisions live outside the code repository. The recommended approach is to maintain the canonical ADR in Git and sync a summary to Confluence for stakeholder visibility.

Getting Started: The best time to write your first ADR is immediately after a significant architectural decision has been made. Start with the most recent decision your team made that involved a meaningful trade-off. Use the MADR template above, fill it in from memory, and submit it as a pull request. The review process itself will surface gaps and improve the document.