PushBackLog

Architecture Decision Records (ADRs)

Soft enforcement Complete by PushBackLog team
Topic: architecture Topic: documentation Topic: process Skillset: backend Skillset: fullstack Skillset: devops Technology: generic Stage: planning Stage: review

Architecture Decision Records (ADRs)

Status: Complete
Category: Architecture
Default enforcement: Soft
Author: PushBackLog team

Tags

  • Topic: architecture, documentation, process
  • Skillset: backend, fullstack, devops
  • Technology: generic
  • Stage: planning, review

Summary

An Architecture Decision Record (ADR) is a short document that captures a significant architectural decision — the context that prompted it, the options considered, the decision made, and the consequences. ADRs create a durable, searchable record of not just what was decided but why, giving future engineers the context they need to understand constraints before they work around them or ignore them. They are stored in the repository alongside the code they govern.

Rationale

Code tells you what; ADRs tell you why

Source code, comments, and diagrams can describe what a system does. They rarely capture why a particular design was chosen from among alternatives — why this database and not that one, why this pattern and not a simpler one, why this trade-off was acceptable. Over time, the team that made a decision turns over and the reasoning disappears. Decisions that originally had good justification appear arbitrary to newcomers, who may revisit them at significant cost or work around them in ways that undermine the original intent.

ADRs are the lowest-overhead mechanism for preserving architectural reasoning. A one-page document written when the decision is fresh saves hours of reverse-engineering later.

Decisions without ADRs tend to become tribal knowledge

When architectural decisions live in Slack threads, meeting notes, or nowhere at all, that knowledge is accessible only to the people who were present at the time. New team members, contractors, and future engineers inherit the architecture without the context. This leads to systems that accumulate accretion — workarounds layered on decisions nobody understands — rather than systems that evolve deliberately.

Guidance

ADR format

ADRs are intentionally lightweight. The goal is a document that takes 15–30 minutes to write, not a lengthy design specification. The standard Nygard format:

# ADR-0023: Use PostgreSQL as the primary database

**Status**: Accepted  
**Date**: 2026-01-14  
**Deciders**: Dayle Anderson, Marlene Sanchez, Marcus Okonkwo

## Context

We need a primary relational store for user, subscription, and billing data. We 
evaluated PostgreSQL, MySQL, and DynamoDB. Our data model is relational with complex 
queries; we need strong consistency and ACID transactions for financial records.

## Decision

Use PostgreSQL 16 managed via AWS RDS. We will not use DynamoDB for the primary store 
because the billing and subscription domain has complex relational queries that are 
awkward to model in a single-table design without significant over-engineering.

MySQL was not selected because our team has stronger operational experience with 
PostgreSQL and the feature gap (JSON support, window functions, CTEs) favours PostgreSQL 
for our query patterns.

## Consequences

- Strong consistency and ACID transactions for billing
- RDS managed service reduces operational overhead
- Horizontal write scaling requires additional design work (read replicas for reads only)
- Engineers should avoid MySQL-specific query syntax in migrations
- Review point: if write throughput exceeds 10,000 TPS, evaluate sharding or CQRS

ADR statuses

StatusMeaning
ProposedUnder discussion, not yet accepted
AcceptedDecision made and in effect
DeprecatedWas accepted; now superseded or no longer recommended
Superseded by ADR-NNNNReplaced by a newer decision

What warrants an ADR

Write an ADR when the decision:

  • Has long-term architectural implications that would be expensive to reverse
  • Involves a meaningful trade-off between competing valid options
  • Required discussion or research before reaching a conclusion
  • Would not be obvious to a future engineer reading the codebase
  • Involves external dependencies (libraries, services, protocols) that constrain future choices

Not every decision needs an ADR. Stick to genuinely architectural decisions — database choices, API protocols, authentication strategies, framework selections, deployment architecture, inter-service communication patterns.

Storage and discoverability

/
  docs/
    adr/
      0001-use-postgresql.md
      0002-use-event-driven-architecture.md
      0003-adopt-trunk-based-development.md
      README.md          # index of all ADRs with status and one-line summary

Store ADRs in the source repository so they are versioned alongside the code they govern, discoverable via search, and included in code review. Avoid storing them in wikis that are not code-reviewed — they tend to drift from reality.

ADR tooling

  • adr-tools (command-line) — scaffolds new ADRs and manages numbering
  • log4brains — generates a browsable ADR site from markdown files
  • Lightweight option: a script or PR template that creates the next numbered file

Reviewing ADRs in pull requests

A PR that introduces a significant architectural change should link to or include the ADR it implements. Reviewers should assess whether the ADR captures the reasoning accurately, not whether the reasoning is optimal — the discussion happened before the PR.