ADR

Introduction

An Architectural Decision (AD) is a justified design choice that addresses an architecturally significant functional or non-functional requirement.

An Architectural Decision Record (ADR) captures a single AD and its rationale; the collection of ADRs created and maintained in a project constitutes is decision log.

Criterias for an ASR

An Architecturally Significant Requirement (ASR) is a requirement that has a measurable effect on the architecture and quality of a software system. The seven criteria used to assess whether issues qualify as ASRs:

1. The requirement is directly associated with high business value (benefit vs. cost) or business risk.
2. The requirement is a concern of a particularly important stakeholder such as the project sponsor or an external compliance auditor.
3. The requirement includes runtime Quality-of-Service (QoS) characteristics, such as performance needs, that deviate from those already satisfied by the evolving architecture substantially.
4. The requirement causes new or deals with one or more existing external dependencies that might have unpredictable, unreliable, and/or uncontrollable behaviour.
5. The requirement has a cross-cutting nature and therefore affects multiple parts of the system and their interactions.
6. 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.
7. The requirement has been troublesome and caused critical situations, budget overruns or client dissatisfaction on a previous project in a similar context.

The list is ordered logically, from project goals and key players to analysis and design elements to organizational matters; this outside-in order does not imply that criterion 2 has less weight than criterion 1 or 3 (and so on). Criteria 1 to 5 are somewhat more objective and easier to agree upon and generalize than criteria 6 and 7, which are highly context-specific.

How to use an ADR

Reserve an ADR number

You will first need to reserve the number you wish to use for your ADR. This number should be the next available ADR number from looking at the current folder adr-<NN>-<TITLE>.md.

ADR Metadata and Status

At the start of every ADR document, we’d like to include a brief amount of metadata.

We keep track of three pieces of metadata:

1. status: Must be one of the status discussed below.
2. date: {YYYY-MM-DD} when the decision was last updated.
3. deciders: The decision owners of an ADR. They should be listed with their name and e-mail address.

An ADR can be in one of the following four status:

1. proposed
2. rejected
3. accepted
4. deprecated
5. superseded

ADR Format

Each ADR document should have the format:

1. Title: The title should be the appended to the filename.
2. Problem Statement: Articulate the problem in a form of a question or statement.
3. Context: Describe the forces at play in an objective manner; when the forces are opposing each other, they should be called out as such. The forces should include at least one ASR.
4. Decision Drivers: Desired qualities, assumptions, ASRs are identified here.
5. Considered Options: List of at least two options considered; ranked by recommended first.
6. Decision Outcome: This section describes our response to these forces, using "we" as a pronoun with an active voice.
7. Consequences: After applying the decision, all consequences should be listed here, include both positive and negative ones. The consequences of one ADR are very likely to become the context for subsequent ADRs.
8. More Information: Provide additional evidence for the decision outcome.

Example ADR

---
status: Accepted
date: 2022-11-22
deciders: ZIO
---

# AD: System Decomposition into Logical Layers

## Context and Problem Statement

Which concept is used to decompose the system under construction into logical building blocks?

## Decision Drivers

* Desire to divide the overall system into manageable parts to reduce complexity
* Ability to exchange system parts without affecting others

## Considered Options

1. Layers pattern
2. Pipes-and-filters
3. Workflow

## Decision Outcome

We decided to apply the Layers pattern and neglected other decomposition pattern such as pipes-and-filters or workflow because the system under construction and its capabilities do not suggest an organization by data flow or control flow. Technology is expected to be primary driver of change during system evolution.

### Consequences

* Good, because the Layers pattern provides high flexibility regarding technology selections within the layers (changeability) and enables teams to work on system parts in parallel.
* Bad, because there might be a performance penalty for each level of indirection and some undesired replication of implementation artifacts.

## More Information

* The three decomposition options come from the Cloud Computing Pattern [Distributed Application](https://www.cloudcomputingpatterns.org/distributed_application/).
* The Layers pattern is featured in POSA Volume 1, see <http://www.dre.vanderbilt.edu/~schmidt/POSA-tutorial.pdf>

A follow-on decision will be required to assign logical layers to physical tiers.

Definition of Done in ADR

The following is a checklist of when an ADR is considered done:

1. Evidence: Are we confident that this design will work?
2. Criteria: Have we decided between at least two options, and compared them systematically?
3. Agreement: Have we discussed with peers just enough and come to a common view?
4. Documentation: Have we captured the decision outcome and shared the decision record?
5. Realization and Review Plan: Do we know when to realize, review and possibly revise this decision?

If you answered yes five times, you are done with an AD.

Example of Done in ADR

(E) I had gained quite positive experience with Apache Freemarker on a previous (smaller) project, and our requirements were similar (for instance, Java was used on both projects, and the level of abstraction of the source and the target DSL were not too different). So I suggested this option to Stefan Kapferer, who was my master student at that time.

(E, C) Stefan got acquainted with Freemarker and also looked for alternatives (with criteria such as vitality of community, documentation, expressivity). We briefly considered Eclipse ecore/EMF coding as alternative because MDSL uses Xtext, which in turn depends on EMF and ecore. We identified flexibility/modifyablity and loose coupling as advantages of Freemarker; the main advantage of Eclipse ecore/EMF is full and instant validation of the target model. Downsides were an extra dependency (Freemarker) and development effort and complexity (ecore/EMF).

(A) In a meeting, we decided that templating is the way to go for this particular CML generator, and that Freemarker is an adequate, state of-the-art choice in Java land.

(D) The decision was documented in the final project report (a Y-statement for it is below).

(R) We agreed to reflect in an iteration review meeting. Later on, we revisited the decision when resuming work on Context Mapper this year. Due to the positive experience, we decided to stick to it and even use it further, for instance to generate JDL files from the tactic DDD models in Context Mapper (as input to the rapid application development framework/ecosystem JHipster).

Good Practices for an ADR

The following are examples of when an ADR is appropriate, these are intended to be broad:

• Select by priority and significance; an ADR should log the resolution of at least one ASR.
• Decide on a single template and stick to this format.
• Size the ADR adequately; present decision question (issue, problem in context), criteria (drivers) and options as well as decision outcome and consequences (good and bad) explicitly.
• Do not defer making and capturing an AD for too long.
• Prioritize meta-qualities such as observability and ability to react over presumed long-term goals such as scability to handle future workloads.
• Root and justify decision in actual requirements; be as objective as possible.
• Invest in editorial quality, having a limit on the ADR length.
• Split decisions into stages if no simple answer exist; revisit the AD at the end of each stage, effectively changing the ADR nature from letter of intent to action plan.
• Disclose your confidence level; be ready to revise an AD as the design work evolves.

When sticking to these guidelines, your ADRs do qualify as executive summaries, verdicts/scales and action plans.

Anti-Practices for an ADR

The following examples either dilute the ADR concept or result from unprofessional, unethical behaviour.

• Fairy tale or wishful thinking: a shallow justification is given with pros but no cons.
• Sales pitch using exaggerations.
• Free lunch or candy bar: no consequences are documented or hidden deliberately.
• Dummy alternative: a solution is made up and presented as an option, but does not work at all in the given context.
• Sprint or rush: only one option is considered and no long-term effects are discussed.
• Tunnel vision: only a local, isolated context is considered, where the consequences of operations and maintenance are not taken into account sufficiently.
• Maze: the ADR topic does not match its content.
• Blueprint or policy in disguise: the writing style is more like a commanding, or authoritative voice.
• Mega-ADR: too much detailed information and using ADRs as documentation.
• Novel and epic: even more extreme than Mega-ADR and Blueprint or Policy in Disguise.

Nature of ADR

A useful ADR should have the following characteristics:

• Executive Summary: ADRs should be brief and distill their content to the bare minimum of essential information required to understand what has been chosen - and why, including benefits and other consequences.
• Verdict or Scale: Selecting a concept, technology or product should bring benefits, but also comes at a price. Hence, the pros and cons of the chosen option should be balanced, tradeoffs explained and a judgment made. All neglected options should be evaluated as well.
• Letter of intent: To be able to initiate decision follow up, an assertive writing style is in order. The decision makers should be identified, which helps make them accountable for decision enforcement.
• Decisions must be executed to have any effect; they might have to be revisited. Hence, ADRs also have the nature of action plans.