Architecture Decision Records

Introduction

Architecture Decision Records (ADRs) capture significant decisions with context, alternatives, and consequences — lightweight documents that prevent future teams from relitigating settled trade-offs or repeating rejected failures. Amazon teams use ADRs to scale architectural governance without central bottleneck.

Real production story

An Amazon fulfillment team rewrote a shipment router "the right way" with a new event bus — unaware a 2021 ADR rejected that bus for latency reasons and mandated SQS fan-out with idempotent consumers. Six months of rework duplicated operational playbooks and rediscovered the same poison-message failure mode. After mandating ADR search in design review templates and indexing ADRs in the internal catalog, duplicate-architecture incidents dropped and onboarding architects cited ADRs as the fastest path to safe changes.

Business problem

Amazon loses velocity when architectural knowledge lives in departed engineers' heads. Without ADRs, teams repeat failed experiments and auditors cannot trace why systems look the way they do.

• Organizational memory: Turnover and reorgs erase rationale — ADRs persist.
• Compliance: SOX and PCI reviews ask "why this design?" — ADRs are evidence.
• Coordination: Cross-team dependencies need shared record of interface decisions.

Architecture overview

ADR format: Title, status, context, decision, consequences, alternatives rejected. Staff practice: supersede rather than edit history; link ADRs to services; require ADR for one-way doors.

• When to write: One-way doors, cross-team contracts, technology choices with ops impact.
• When to skip: Reversible two-way doors with obvious paved-road path — link to template instead.
• Lifecycle: Proposed → accepted → deprecated → superseded by ADR-NNNN.
• Discovery: Index by domain, service, and quality attribute tags.

Architecture motivation

ADRs scale governance: Lightweight, version-controlled, close to code — they complement diagrams and service catalogs without heavyweight ARB documents nobody reads.

• Force: Hundreds of teams make local decisions that compose globally.
• Constraint: ADRs must be cheap to write — one to two pages, not six-week documents.
• Outcome: Searchable decision history linked from service repos and PR templates.

Internal architecture

ADR ecosystem at Amazon scale — decisions wired into delivery flow:

• ADRs live in git beside code — same review flow, same search.
• Supersede links preserve chain of reasoning across generations.

Engineer opens design doc / PR
   ↓
ADR template (context · options · decision)
   ↓
Peer + staff review (async, 48h SLA)
   ↓
Merge ADR to /docs/adr/ in service repo
   ↓
Catalog indexer tags service + domain
   ↓
PR template requires ADR link for tier-2 changes
   ↓
Quarterly supersede review (deprecated tech)

Data flow

ADR-informed changes: Engineer searches catalog → reads constraints → implements within decision boundaries → PR cites ADR → reviewer verifies compliance → runtime fitness functions check where possible.

• Discovery: Search by service name, attribute tag, or technology keyword.
• Enforcement: CI checks PR body for ADR reference on labeled changes.
• Feedback: Incident postmortem may supersede ADR when decision proven wrong.

System design diagram

Two diagrams show the Architecture Decision Records topology and the primary request/event path used in production at scale.

Production code example

ADR CI lint — GitHub Action validating PR ADR references:

• Automate the cheap checks — humans review decision quality, CI enforces presence and format.
• Tier labels prevent ADR fatigue on low-risk changes.

# .github/workflows/adr-lint.yml
name: adr-lint
on:
  pull_request:
    types: [opened, synchronize, edited]

jobs:
  require-adr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check tier-2 label requires ADR link
        env:
          PR_BODY: ${{ github.event.pull_request.body }}
          LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }}
        run: |
          echo "$LABELS" | grep -q 'architecture/tier-2' || exit 0
          echo "$PR_BODY" | grep -Eq 'ADR-[0-9]+|docs/adr/[0-9]+' || {
            echo "Tier-2 changes must link an ADR (ADR-NNNN or docs/adr/NNNN)"
            exit 1
          }
      - name: Validate ADR file structure
        if: contains(github.event.pull_request.changed_files, 'docs/adr')
        run: node scripts/lint-adr.mjs docs/adr/*.md

Enterprise case study

Amazon fulfillment ADR program: Duplicate event-bus rewrite wasted six months before ADR discovery culture improved.

• Before: ADRs optional; 30% duplicate architecture attempts on new teams.
• Decision: Mandatory ADR for tier-2+, catalog index, PR template enforcement, search in design review.
• After: Duplicate attempts down 70%; audit prep time halved; onboarding architects productive in week two.

Trade-offs

• Process vs agility: Mandatory ADRs slow trivial work — tier the requirement by blast radius.
• Detail vs adoption: Long ADRs don't get written — enforce concise template.
• Central catalog vs federated repos: Federated in service repos with central index — avoid single repo bottleneck.
• Living doc vs immutable: Never rewrite accepted ADRs — supersede to preserve audit trail.

Security considerations

ADRs for security architecture: Document threat model choices, fail-open/closed decisions, and data classification — auditors read ADRs.

• Immutable audit: Git history on ADRs satisfies change traceability requirements.
• Access control: Security ADRs may be restricted — index metadata still searchable.
• Threat linkage: Reference STRIDE findings and accepted risks explicitly.

Scalability analysis

ADR programs scale with search, templates, and automation — not with more review meetings.

• Search: Full-text index across org; LLM-assisted "related ADRs" on design docs.
• Quality lint: CI validates required sections and revisit dates.
• Decay: Automated reminders when ADR references deprecated services.

Failure scenarios

ADR program failures: Shelfware ADRs nobody reads; ADRs written after decision; contradictory ADRs without supersede links.

• Template fatigue: Too many required ADRs → teams write garbage — tier requirements.
• Stale ADRs: Accepted ADR for monolith after extraction — quarterly ownership audit.
• Missing link: PR merges without ADR — CI gate on tier-2 label prevents.

Staff engineer insights

• An ADR nobody can find is worse than no ADR — invest in index and PR integration before mandating volume.
• Supersede, don't edit — auditors and future you need to see the original mistake.
• The best ADRs include "alternatives rejected" — that section saves the next team from heroically rediscovering failure.

Interview questions

Architecture review questions

• Does ADR include context, decision, consequences, and rejected alternatives?
• Is status lifecycle correct (proposed/accepted/superseded)?
• Is ADR linked from service catalog and owning repo README?
• Does tier-2+ PR cite ADR in description?
• Are revisit or supersede triggers documented?
• Can a new engineer find relevant ADRs via search in under five minutes?

Summary

Architecture Decision Records at Amazon scale turn tribal knowledge into durable, searchable decisions: concise ADRs in service repos, catalog indexing, PR enforcement, and supersede chains — so teams inherit context instead of repeating six-month mistakes.