Articles // arch

Architectural Decision Record

Sergey Grachev
published: ⏰ 6
article image

An Architecture Decision Record (ADR) is a documented process for making key architectural decisions on a project. It helps the team capture and communicate knowledge about why certain decisions were made, what alternatives were considered, and what the consequences of those decisions were.

Probably one of the most frequent problems that was found on projects with the “history” was that carriers Knowledge about the decisions made and the implemented functionality have already left the project. They went to a bright future, leaving the unknown and dark present to the descendants - without full-fledged documentation, without information why it was done just like that. To avoid such situations, the so-called registers of architectural solutions (ADR) can and should be used in the project.

The purpose of use ADR

The most important thing is that ADR reflect architecturally significant solutions, which can affect various aspects of the solution architecture (for example, performance, scalability, support, etc.), both from the point of view of the software part and the hardware.

The main goals of use by ADR include:

  • Documentation of architectural solutions.
  • justification of these decisions.
  • Preservation of knowledge about the decisions made.
  • Simplifying the understanding of the architecture of the project with new team members.
  • trackability of changes in architecture and their impact on the project.
  • ensuring consistency between developers and other team members.

When to use ADR?

ADR should be used when:

  • You make a decision that can significantly affect the architecture of the project.
  • The decision requires discussion and approval between several team members.
  • The solution has long -term consequences for the project.
  • The solution is not trivial or obvious.

More information can be found on the website Architectural Decision Record and in Repositories Architecture Decision Record (ADR).

Tools for working with ADR

There are several tools and libraries for working with ADR. Some of them:

Since ADR is the usual text files in the Markdown or AsciiDoc format, it is possible to use any text editor or version management systems supporting these formats.

Structure of ADR

Usually each ADR consists of the following sections:

  1. Number and Name – a unique number for each ADR and a brief description of the topic (in the files name).
  2. Date and Author – date of creation of ADR and the name of the author.
  3. Status – current status of a decision (for example, accepted, rejected).
  4. StakeHolders – who is participating and interested in solving this problem.
  5. Context – description of the current situation or the problem that ADR solves.
  6. Decision – description of the decision made and why it was chosen.
  7. Alternatives – description of alternative solutions and why they were rejected (rather useful information allowing you to understand the decision -making process).
  8. Consequences – description of the consequences of the adoption of this decision.

This is the minimum option. In this case, there are more detailed templates that may include additional Sections taking into account the specifics of the project or the subject area.

Below is an example of the template MADR in the Markdown format.

Markdown 
---
# These are optional metadata elements. Feel free to remove any of them.
status: "{proposed | rejected | accepted | deprecated | … | superseded by ADR-0123"
date: {YYYY-MM-DD when the decision was last updated}
decision-makers: {list everyone involved in the decision}
consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
---

# {short title, representative of solved problem and found solution}

## Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an
illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards
or issue management systems.}

<!-- This is an optional element. Feel free to remove. -->

## Decision Drivers

* {decision driver 1, e.g., a force, facing concern, …}
* {decision driver 2, e.g., a force, facing concern, …}
* … <!-- numbers of drivers can vary -->

## Considered Options

* {title of option 1}
* {title of option 2}
* {title of option 3}
* … <!-- numbers of options can vary -->

## Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision
driver | which resolves force {force} | … | comes out best (see below)}.

<!-- This is an optional element. Feel free to remove. -->

### Consequences

* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
* … <!-- numbers of consequences can vary -->

<!-- This is an optional element. Feel free to remove. -->

### Confirmation

{Describe how the implementation of/compliance with the ADR can/will be confirmed. Are the design that was decided for
and its implementation in line with the decision made? E.g., a design/code review or a test with a library such as
ArchUnit can help validate this. Not that although we classify this element as optional, it is included in many ADRs.}

<!-- This is an optional element. Feel free to remove. -->

## Pros and Cons of the Options

### {title of option 1}

<!-- This is an optional element. Feel free to remove. -->
{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}

<!-- use "neutral" if the given argument weights neither for good nor bad -->

* Neutral, because {argument c}
* Bad, because {argument d}
* … <!-- numbers of pros and cons can vary -->

### {title of other option}

{example | description | pointer to more information | …}

* Good, because {argument a}
* Good, because {argument b}
* Neutral, because {argument c}
* Bad, because {argument d}
* …

<!-- This is an optional element. Feel free to remove. -->

## More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team
agreement on the decision and/or define when/how this decision the decision should be realized and if/when it should be
re-visited. Links to other decisions and resources might appear here as well.}

Conclusion

The ADRs are a rather useful tool for documenting projects for the entire life cycle from the design stage to the maintenance stage. They allow you to effectively organize the decision-making process and provides access with the entire project team to information on what were adopted. And what is important – the registers of architectural solutions are not static and require regular updating in the development process.

Adr Documentation Essentials
Decision Records 1 of 2
Process Decision Record →