Skip to content

Architectural Decision Records (ADRs)

This repository contains our team's Architectural Decision Records—documented decisions about the architecture, patterns, and technologies we use. ADRs help us understand why we made certain choices, what alternatives we considered, and what the consequences were.

Quick Start

Need to create an ADR?

  1. Check if your decision requires an ADR (see When an ADR Is Required)
  2. Copy the template from records/0001-template.md
  3. Create a new file in records/ following the naming convention: NNNN-short-descriptive-title.md
  4. Create a branch, draft your ADR, and open a pull request
  5. Follow the ADR Lifecycle process

Looking for an existing decision?

Table of Contents

What Are ADRs?

Architectural Decision Records document decisions that have lasting architectural significance. They capture:

  • Why we made a particular choice
  • What alternatives we considered
  • What the consequences are (both positive and negative)

ADRs are not for:

  • Routine implementation details
  • Decisions with isolated, low impact
  • Day-to-day coding choices

Think of ADRs as the "why" behind our architecture—they help future you (and your teammates) understand the reasoning behind important technical decisions.

When an ADR Is Required

Create an ADR when a decision meets one or more of these criteria:

  • Introduces or deprecates a technology, framework, or major dependency
  • Changes cross-cutting architectural patterns
  • Impacts multiple services, pipelines, environments, or teams
  • Affects reliability, security, compliance, or operational posture
  • Defines a new standard, convention, or process with long-term consequences
  • Resolves a recurring or contentious technical question

Not sure if you need an ADR? Ask the Principal Engineer—they'll help you decide.

If your decision doesn't meet these criteria, use your standard engineering judgment. No ADR needed.

Roles and Responsibilities

Principal Engineer

  • Determines whether an ADR is required
  • Serves as the sponsor for all ADRs
  • Ensures completeness, clarity, and architectural soundness
  • Facilitates technical discussion when necessary
  • Resolves disputes and makes the final decision when consensus isn't reached

ADR Author

  • Identifies a qualifying decision
  • Produces the initial ADR draft using the standard template
  • Incorporates feedback from reviewers
  • Updates the ADR throughout the review lifecycle

Engineering Team

  • Reviews proposed ADRs
  • Provides feedback, challenges assumptions, and identifies gaps
  • Highlights impacts relevant to their domain or responsibilities

ADR Lifecycle

The ADR process follows these steps:

flowchart TD
    A[Engineer identifies decision] --> B{Principal Engineer<br/>approves starting<br/>AD Process?}
    B -->|No| C[No AD Process needed]
    B -->|Yes| D[Engineer becomes<br/>ADR Author]
    D --> E[Author drafts ADR<br/>in dedicated branch]
    E --> F[Principal Engineer reviews<br/>ADR draft for completeness]
    F -->|Needs work| E
    F -->|Ready| G[Submit ADR<br/>as Pull Request]
    G --> H[Engineering team reviews<br/>ADR asynchronously]
    H --> I{Complex or<br/>high-impact?}
    I -->|Yes| J[Schedule discussion meeting]
    I -->|No| K[Principal Engineer<br/>determines ADR final status]
    J --> L[Principal Engineer facilitates<br/>structured discussion]
    L --> M{Additional<br/>modifications needed?}
    M -->|Yes| E
    M -->|No| K
    K --> N{Determine ADR status}
    N -->|Accepted| O[Update ADR status to Accepted]
    N -->|Rejected| P[Update ADR status to Rejected]
    N -->|Deferred| Q[Update ADR status to Deferred]
    N -->|Superseded| R[Update ADR status to Superseded]
    O --> S[Merge Pull Request<br/>to primary branch]
    P --> S
    Q --> S
    R --> S
    S --> T[ADR becomes<br/>authoritative reference]

    style A fill:#e1f5ff
    style T fill:#d4edda
    style C fill:#fff3cd
    style O fill:#d4edda
    style P fill:#f8d7da
    style Q fill:#fff3cd
    style R fill:#d1ecf1

1. Initiation

  • An engineer identifies a decision requiring architectural alignment
  • The Principal Engineer determines whether an ADR is appropriate
  • If approved, the engineer becomes the ADR Author

2. Drafting

  • The Author creates an ADR in a dedicated branch
  • Draft includes context, constraints, alternatives, decision proposal, and consequences
  • The Principal Engineer reviews the draft for structural and conceptual completeness

3. Team Review

  • The ADR is submitted as a pull request
  • Engineers review asynchronously and provide written feedback
  • Revisions are pushed to the same branch until the proposal is ready for discussion

4. Discussion (If Required)

  • Complex or high-impact ADRs may be placed on a scheduled technical review agenda
  • The Principal Engineer facilitates structured discussion
  • Additional modifications may be requested

5. Finalization

  • Once review concludes, the Principal Engineer determines the final status:
  • Accepted - Decision is approved and becomes policy
  • Rejected - Decision is not approved
  • Deferred - Decision is postponed for later consideration
  • Superseded - This ADR replaces an earlier ADR
  • The ADR's status is updated accordingly

6. Merge

  • The ADR PR is merged into the primary branch
  • The ADR becomes the authoritative reference for future decisions

Template and Format

All ADRs must contain the following sections:

  • Title - Clear, descriptive title
  • Status - Accepted, Rejected, Deferred, or Superseded
  • Date - When the decision was made
  • Context - What situation led to this decision?
  • Constraints and Forces - What limitations or requirements influenced the decision?
  • Decision - What did we decide?
  • Alternatives Considered - What other options did we evaluate?
  • Consequences - What are the positive and negative outcomes?
  • References (optional) - Links to related documents, discussions, or resources

📄 Template: See records/0001-template.md for the standard template.

Naming Convention: Use the format NNNN-short-descriptive-title.md (e.g., 0002-use-terraform-for-infrastructure.md)

Change Management

Once accepted, an ADR represents an official architectural decision.

  • Historical ADRs must remain unaltered except for status updates (e.g. changing from Accepted to Superseded)
  • To change an accepted ADR, create a new ADR that supersedes the original

This preserves the decision history and helps us understand how our architecture evolved.

Scope and Authority

Accepted ADRs guide engineering practice across the organization. They apply to:

  • New designs and implementations
  • Modifications to existing systems where applicable
  • Architectural reviews, RFCs, and technical planning efforts

When implementing work governed by an ADR:

  • Reference the ADR in code reviews
  • Include ADR references in documentation
  • Mention relevant ADRs in planning materials

Exceptions

Non-compliance with an accepted ADR requires explicit approval from the Principal Engineer.

Temporary exceptions must include:

  • A clear justification
  • A remediation plan, or
  • A follow-up ADR to address the exception

Record Location

All ADRs are stored in the records/ directory. Browse existing ADRs to understand past decisions and find relevant context for your work.