Disclaimer: ChatGPT generated document.
An architecture decision (AD) is a significant design choice about a software system’s architecture. An architecture decision record (ADR) is the document that captures that decision, its context, and why it was made.
An architecture decision is a choice that has a meaningful impact on the structure, qualities, constraints, or evolution of a system.
Examples include:
- “We will use PostgreSQL as the primary transactional database.”
- “Services will communicate asynchronously through Kafka for domain events.”
- “The frontend will be a React single-page application.”
- “Authentication will be handled by an external identity provider using OIDC.”
- “We will use a modular monolith rather than microservices.”
Not every technical choice deserves to be called an architecture decision. Choosing a local variable name obviously isn't one. A useful rule is:
If changing the decision later would be expensive, risky, or affect multiple parts of the system, it is probably architectural.
Architecture decisions can concern technology, system structure, integration patterns, security, deployment, data ownership, scalability, reliability, and other important system qualities.
An ADR is a short, durable record of an architecture decision.
It answers not only “What did we decide?”, but more importantly “Why did we decide it?”
A typical ADR might contain:
| Section | Purpose |
|---|---|
| Title | The decision, e.g. “Use PostgreSQL for transactional storage” |
| Status | Proposed, accepted, rejected, deprecated, superseded, etc. |
| Context | The problem, requirements, constraints, and forces involved |
| Decision | What was actually decided |
| Alternatives | Other approaches that were considered |
| Rationale | Why this option was chosen |
| Consequences | Positive and negative implications of the decision |
For example, imagine a team is deciding between synchronous REST calls and asynchronous messaging.
An ADR could say:
ADR-017: Use asynchronous events for order fulfillment
Context: Order creation currently calls inventory, payment, and fulfillment synchronously. This creates tight coupling and causes order creation to fail when downstream systems are temporarily unavailable.
Decision: Order creation will publish an OrderCreated event. Inventory and fulfillment services will consume the event asynchronously.
Alternatives considered: Continue synchronous REST communication; introduce a central workflow/orchestration service.
Consequences: Services become more loosely coupled and tolerate temporary downstream outages better. However, the system becomes eventually consistent and requires message retry, idempotency, monitoring, and dead-letter handling.
That last part is especially important: ADRs should capture trade-offs, not merely announce technology choices.
The distinction is simple:
AD = the decision itself. ADR = the historical record of that decision.
You can think of it as:
Problem → Options → Architecture Decision → ADR
Over time, a project accumulates ADRs into an architecture decision log:
docs/architecture/decisions/
001-use-postgresql.md
002-adopt-modular-monolith.md
003-use-oidc-for-authentication.md
004-use-kafka-for-domain-events.md
005-deploy-on-kubernetes.md
An important property of ADRs is that they generally form a historical record rather than documentation that is silently rewritten. If ADR-004 is later reconsidered, you might create ADR-012 saying that ADR-004 has been superseded and explaining why. This preserves the reasoning that led the architecture from one state to another.
That makes ADRs particularly valuable when someone joins a project months or years later and asks, “Why on earth did we build it this way?” The code tells them what the architecture is; ADRs can tell them why.
The ideas are older than the terminology, but “architectural decision” and especially “Architecture Decision Record (ADR)” emerged from software-architecture research and practice in the 2000s.
A useful way to trace the lineage is through three developments.
Software architects had long made consequential design choices, but during the 1990s and early 2000s researchers increasingly argued that architecture shouldn't be understood only as boxes, components, and connectors. It should also include the decisions that produced that structure.
A major influence was Philippe Kruchten. In his 2004 IEEE Software article “An Ontology of Architectural Design Decisions in Software Intensive Systems,” Kruchten argued for treating architectural design decisions as first-class architectural knowledge.
Around the same period, researchers including Anton Jansen, Jan Bosch, Paris Avgeriou, and others developed the field of architectural knowledge management: recording not just an architecture, but the decisions, alternatives, rationale, assumptions, and consequences behind it.
So the concept of an architectural decision (AD) largely comes out of this broader research movement.
The specific term Architecture Decision Record (ADR) is strongly associated with software architect and author Michael Nygard.
In 2011, Nygard published a short article called “Documenting Architecture Decisions.” His proposal was deliberately lightweight: instead of producing large architecture documents that quickly become obsolete, record each significant architectural decision separately.
His original ADR structure was essentially:
Title
Status
Context
Decision
Consequences
The idea was that each important decision gets its own small record, numbered sequentially:
ADR 1: Use PostgreSQL
ADR 2: Use REST for the public API
ADR 3: Adopt asynchronous messaging
...
This is the direct ancestor of the ADR files commonly found in software repositories today.
The idea spread because it fit well with Git-based development: ADRs could simply be Markdown files committed alongside the source code.
People subsequently extended Nygard's format. For example, ADR templates may explicitly record:
Context
Decision drivers
Considered options
Decision
Pros and cons
Consequences
This led to related terminology such as ADRs, architecture decision logs, decision logs, and architecture knowledge.
One influential later resource is the ADR work associated with Nat Pryce and Steve Freeman and the broader ADR community, while tools and templates such as MADR (Markdown Architectural Decision Records) formalized richer ADR structures.
So historically, I would distinguish the terms this way:
Architectural decision / architectural design decision → arose from the broader software-architecture research literature concerned with design rationale and architectural knowledge.
Architecture Decision Record (ADR) → the lightweight, one-record-per-decision practice popularized by Michael Nygard in 2011.
There is an interesting intellectual shift underneath the terminology: architecture stops being merely “the structure of the system” and becomes partly “the important decisions that explain why the system has that structure.” ADRs are essentially the mechanism for preserving that reasoning.