liveBook · Manning

Architecture decision record

As explained in Grokking Software Architecture

A document that records an architectural decision, its context, considered alternatives, and rationale.

Six months after a design meeting, someone asks, “Why didn’t we use the other option?” An architecture decision record (ADR) is the team’s receipt: a short document capturing a significant choice, its context, alternatives, and rationale. It preserves the reasoning for future teammates and helps prevent the same debate from starting over. section 2.3

An ADR focuses on one significant decision, rather than providing a broad blueprint for an entire feature like a design document or request for comments. Keep it short and store it in the repository as a historical record. section 2.7

A practical ADR can include:

  • A title, date, status, and participants. section 2.7.1
  • The problem context, options considered, and criteria used to compare them. section 2.7.1
  • The tradeoffs, chosen option, and reasons for the choice. section 2.7.1
  • Risks, mitigations, and a trigger for reviewing the decision. section 2.7.1

Choosing session storage

A web app needs sessions so users do not have to log in on every page. The team compares application memory, Redis, and a database table against availability, latency, deployment simplicity, and cost. Memory is fast and simple but loses sessions on restart and cannot share them across servers. Redis offers low latency and shared sessions but adds a service to maintain. The database is durable and operationally simple but adds latency and load. The team chooses Redis, records the risk that an outage could log users out, and plans to revisit the choice after a multi-region deployment or more than 10,000 concurrent sessions. section 2.7.1

Not every choice needs an ADR. Look for decisions that significantly affect the system or would be onerous to change; choosing between a loop and a map function does not need one. Before changing an existing design, check for an ADR: the original constraints may explain it, even if those constraints no longer apply. section 2.7 section 3.5.2

The record can also make an accepted business risk explicit. For example, if leadership chooses to bypass automated verification to meet a deadline, document the context, the decision, and the risk accepted. section 13.9.4

How Grokking Software Architecture covers it

How deep it goes
Provides a decision-worthiness test, a field-by-field example, and guidance on recording risks and review triggers.
Examples
Works through a session-storage choice and assigns a security audit with an ADR deliverable.
What you can do after
Practice writing a concise ADR that explains a choice, its alternatives, tradeoffs, and risks.
How it connects
Connects ADRs to quality attributes, constraints, tradeoffs, and design documents.

Also explained in

Compare how 7 books explain architecture decision record →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.