This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Architecture Decision Records (ADRs)

1: 0. Emtpy ADR-template
2: 1. Use Markdown Architectural Decision Records
3: Architectural Significance

This section contains all Architecture Decision Records made within the Project. You can either create them manually, by copying another file and naming it accordingly or use this fork of adr-tools for hugo

1 - 0. Emtpy ADR-template

Status: proposed
Deciders: [list everyone involved in the decision]
Date: 2026-01-05

Technical Story: [description | ticket/issue URL]

Context and Problem Statement

[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]

Decision Drivers

[driver 1, e.g., a force, facing concern, …]
[driver 2, e.g., a force, facing concern, …]
…

Considered Options

[option 1]
[option 2]
[option 3]
…

Decision Outcome

Chosen option: “[option 1]”, because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].

Positive Consequences:

[e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
…

Negative consequences:

[e.g., compromising quality attribute, follow-up decisions required, …]
…

Pros and Cons of the Options

[option 1]

[example | description | pointer to more information | …]

Good, because [argument a]
Good, because [argument b]
Bad, because [argument c]
…

[option 2]

[example | description | pointer to more information | …]

Good, because [argument a]
Good, because [argument b]
Bad, because [argument c]
…

[option 3]

[example | description | pointer to more information | …]

Good, because [argument a]
Good, because [argument b]
Bad, because [argument c]
…

Additional Information

Here are some questions to maybe assess the architectural significance of the decision. Try to avoid defining every little thing as an ADR.

The requirement is directly associated with high business value (benefit vs. cost) or business risk.
The requirement is a concern of a particularly important stakeholder such as the project sponsor or an external compliance auditor.
The requirement includes runtime Quality-of-Service (QoS) characteristics (such as performance needs) that deviate from those already satisfied by the evolving architecture substantially.
The requirement causes new or deals with one or more existing external dependencies that might have unpredictable, unreliable and/or uncontrollable behavior.
The requirement has a cross-cutting nature and therefore affects multiple parts of the system and their interactions; it may even have system-wide impact, short term and/or in the long run (examples: security, monitoring).
The requirement has a First-of-a-Kind (FOAK) character: For instance, this team has never built a component or subsystem that satisfies this particular requirement before.
The requirement has been troublesome and caused critical situations, budget overruns or client dissatisfaction on a previous project in a similar context.

2 - 1. Use Markdown Architectural Decision Records

Status: proposed
Date: 2026-01-05

Context and Problem Statement

We want to record architectural decisions made in this project. Which format and structure should these records follow?

Decision Drivers

Low barrier of entry - since the act of documenting is always cumbersome, the format should not burden you any more than it needs to. E.g. we do not necessarily need an 11-Point Document for each and every decision.
Overview - an ADR should provide a list of considered options and why you chose one of them while discarding others.
Tool support - there is a strong need to integrate ADRs with our central (hugo based) documentation, as natively as possible. Previous projects have shown that scattering relevant documentation leads to a lot of confusion.

Considered Options

MADR 2.1.0 - The Markdown Architectural Decision Records
Michael Nygard’s template - The first incarnation of the term “ADR”
Sustainable Architectural Decisions - The Y-Statements
Other templates listed at https://github.com/joelparkerhenderson/architecture_decision_record
Formless - No conventions for file format and structure

Decision Outcome

Chosen option: “MADR 2.1.0”, because

Implicit assumptions should be made explicit. Design documentation is important to enable people understanding the decisions later on. See also A rational design process: How and why to fake it.
The MADR format is lean and fits our development style.
The MADR structure is comprehensible and facilitates usage & maintenance.
The MADR project is vivid.
Version 2.1.0 is the latest one available when starting to document ADRs.

Pros and Cons of the Options

MADR

(This whole Document is an Example)

Good, because a few mandatory concise fields
Good, because optional fields provide more information about reasoning and weighing different options
Good, allows for linking to different ADRs

Y-Statement

In the context of capturing architecture decisions, facing tedious verbosity, scattered documentation and knowledge drain from people leaving the project, we decided to implement ADRs using the MADR template and neglected other formats like Y-Statement, Nygard and similar to achieve a simple, lightweight and modular approach to capturing ADs, accepting the fewer guardrails but more verbosity than y-statement, because our decisions are not overly complex and decided within days-weeks instead of months but still need thorough consideration of multiple options in a structured manner.

Good, because it results in brief ADRs
Good, because it allows capturing existing decisions rather quickly
Bad, because options are not considered in depth
Bad, because condensing decisions this much requires more thought, not less
Bad, because it lacks information for future readers that are new to the project

NygardADR

Homepage

Bad, few fields for weighing options
Bad, ambiguous fields might lead to vastly different focal points when making decisions

Links

You can add links via the adr tool e.g.: adr link 1 Amends 0 "Amended by" or while creating a new one: adr new -l "0:Amends:Amended by" Use Markdown Architectural Decision Records.

The other option is to use manual linking like this: [ADR0001]({{< relref "docs/architecture/adr/0000-empty-adr-template.md" >}}) produces: ADR0001

Or use normal Markdown links (also supports relative linking): [\<Link Name\>]\(docs/architecture/adr/0000-empty-adr-template.md) - Produces: Link Name

3 - Architectural Significance

How do we decide on which decisions we need to capture in an Architectural Decision Record (ADR)? O. Zimmermann wrote an article proposing the following guiding principles:

The requirement is directly associated with high business value (benefit vs. cost) or business risk.
The requirement is a concern of a particularly important stakeholder such as the project sponsor or an external compliance auditor.
The requirement includes runtime Quality-of-Service (QoS) characteristics (such as performance needs) that deviate from those already satisfied by the evolving architecture substantially.
The requirement causes new or deals with one or more existing external dependencies that might have unpredictable, unreliable and/or uncontrollable behavior.
The requirement has a cross-cutting nature and therefore affects multiple parts of the system and their interactions; it may even have system-wide impact, short term and/or in the long run (examples: security, monitoring).
The requirement has a First-of-a-Kind (FOAK) character: For instance, this team has never built a component or subsystem that satisfies this particular requirement before.
The requirement has been troublesome and caused critical situations, budget overruns or client dissatisfaction on a previous project in a similar context.

Translating that to our case is a bit tricky but works for a lot of things:

The Decision is directly associated with goals relating to the projects success (student and professional workshops, demonstrators, development projects). E.g: How do we document and publish the API for our core services?
The particularly important stakeholder is only partly relevant
QoS Characteristics are also mostly arbitrary, but play an important role for the local dev env and when actually scaling out.
The Decision introduces or deals with external dependencies - these are mostly in the form of code Libraries and tooling. E.g. Which tools do we use to deploy our infrastructure? (Terraform, Ansible, Puppet, Chef, etc.) As in our case, external dependencies also mean knowledge that has to be acquired in order to maintain the system.
The Decision has a cross-cutting nature and therefore affects multiple parts of the system and their interactions; it may even have system-wide impact, short term and/or in the long run (examples: security, monitoring, event formats, tooling).
FOAK is quite common in our case, as a lot of this is new to some of us. Nevertheless, an important indicator.
The decision has been troublesome and caused intensive discussions before.