Skip to content

Architecture Decision Records

What is an Architecture Decision?

An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. This might, for instance, be a technology choice (e.g., Java vs. JavaScript), a choice of the IDE (e.g., IntelliJ vs. Eclipse IDE), a choice between a library (e.g., SLF4J vs java.util.logging), or a decision on features (e.g., infinite undo vs. limited undo). Do not take the term “architecture” too seriously or interpret it too strongly. As the examples illustrate, any decisions that might have an impact on the architecture somehow are architectural decisions.

It should be as easy as possible to a) write down the decisions and b) to version the decisions.

source: Markdown Any Decision Records

Notes about ADRs

  • Every ADR should explain exactly one single decision.
  • Decision records should have a unique code (filename) and title
  • Example: ADR0001 - Use an SQS queue to manage outgoing emails

Lifecycle of an ADR

Decision records should start as a draft version, usually in 'proposed' status, then move to other states as decisions are made, such as 'accepted' or 'rejected'.

The document should be managed in an append-only manner. The only part of the document that should evolve is the STATUS paragraph.

When a decision becomes irrelevant it's status should be changed to deprecated, but if the context of the decision changes then a new ADR should be created and the old one's status moved to superseded.

You can cross-link ADRs. For example "Superseded by ADR0032" and when there is some kind of relation between two decisions like the second one is a consequence of the first one.

WHEN should an ADR be created?

  • When the decision will affect the work of the developers
  • When the decision will be hardly reversible
  • When the decision is not obvious to the entire team (but pay attention, the team will change, sooner or later)

ADR Templates

Basic Template Example

Markdown
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
# Title

## Date

## Status
What is the status, such as proposed, accepted, rejected, deprecated, superseded, etc.?

## Context
What is the issue that we're seeing that is motivating this decision or change?

## Decision
What is the change that we're proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because of this change?

## Tags
Context triggers or keywords, comma separated, that can be used to search for decision records.  These are usually terms that are coupled to some business context.

MADR Template Example

Markdown
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Use Plain JUnit5 for advanced test assertions

## Context and Problem Statement

How to write readable test assertions?
How to write readable test assertions for advanced tests?

## Considered Options

* Plain JUnit5
* Hamcrest
* AssertJ

## Decision Outcome

Chosen option: "Plain JUnit5", because it is a standard framework and the features of the other frameworks do not outweigh the drawbrack of adding a new dependency.

Resources about ADRs

:::note

Most of the Above was copied and pasted from another site, but I didn't copy the link. As soon as I find that resource again I'll post a link here.

:::