Skip to content
Software Architecture Guide

Architectural Decision Record Example

Explanation

Section titled “Explanation”

An architectural decision record (ADR) is a short note about one decision. arc42 section 9 (see “arc42 Architecture Decisions”) defines a decision as picking one alternative against given criteria. It asks you to record decisions that are important, costly or risky, together with the reasons.

A good worked example has these parts:

  • The question. It states the problem and why it matters. An ADR should log how at least one architecturally significant requirement is resolved. That ties the problem to a quality goal (see “Architecturally Significant Requirement”).
  • All options, not only the winner. Every neglected option gets evaluated too. The pros and cons of the chosen option should be balanced. The record explains the trade-offs and states a judgment.
  • The outcome and its consequences. In the Nygard-style ADR that arc42 describes, consequences must cover more than the positive ones. The status can move from proposed to accepted, then to deprecated or superseded.
  • Factual rationale. The argument should be factual and traced back to requirements.

arc42 also wants rejected alternatives and decision criteria documented. Then stakeholders can retrace the decision later.

An integration-style example. One worked example asks how programs should exchange information. It lists four options: File Transfer, Shared Database, Remote Procedure Invocation (RPI) and Messaging. It picks Messaging. The reasons are loose coupling in time and the throttling behavior of messaging channels.

Messaging means applications connect to a common messaging system. They exchange data and trigger behavior through messages. Remote invocation is synchronous: the caller waits while the called procedure runs. That is a drawback compared with messaging. See “Messaging” and “Remote Procedure Call”.

Format. arc42 recommends ADRs for important decisions. It also allows a list, a table, or a separate section per decision. Small records are easier to maintain.

Example

Section titled “Example”

A team must decide how a booking system passes updates to a reporting tool.

  • Question: How should the two programs exchange information? The booking system must stay responsive when reporting is slow.
  • Quality goal: Reliability. A slow reporting tool must not block bookings.
  • Options: File transfer, shared database, direct remote call, messaging. Each gets pros and cons.
  • Decision: Messaging. Status: accepted.
  • Consequences: Bookings no longer wait for reporting. Reports may lag. The team must run and monitor a messaging system.

Trade-offs

Section titled “Trade-offs”

Writing a full record takes time. arc42 therefore limits it to important, costly or risky decisions. Small records are easier to read, create and maintain than one large document.

The main risk is listing only upsides. Zimmermann calls this the “Free Lunch Coupon” anti-pattern: no consequences, or only harmless-looking ones, are recorded. Every option has costs. In the messaging example, the caller no longer waits, but the choice rests on specific needs (loose coupling in time, throttling). Under other requirements the same reasoning may not hold. The rationale must stay tied to the context and requirements.

Checks

Section titled “Checks”
  • The record names the problem and links it to at least one quality goal or significant requirement.
  • Rejected options are listed and evaluated, not only the chosen one.
  • Pros, cons and trade-offs of the chosen option are balanced, with a stated judgment.
  • Consequences include negative ones, not only positive or harmless-looking ones.
  • The rationale is factual and traced back to requirements.
Section titled “Related”

Sources

Section titled “Sources”