Architecture Decision Records Example

Architecture Decision Records (ADR) is a technique of documenting decisions in the development process in a comprehensible and continuous way.

This article will give you a short example of an ADR based on an imaginary application that helps to find Easter eggs.

What are Architecture Decision Records?

In software development, there is a best practice for documenting architectural decisions in a structured and defined way: an Architecture Decision Record or short ADR.

ThoughtWorks grades this concept as “adopt” on their technology radar, which means that they recommend this technique.

At https://adr.github.io you can find an excellent overview of this technique. But roughly, the idea is to document the decision by writing down this information (according to the template from Michael Nygard):

Title

Give a meaningful name that quickly lets the reader understand what this ADR is all about.

Status

Note the status of this ADR. This depends on the individual process of your team or company. Usually, this section only holds a single word defining the status.

Examples are: proposed, accepted, rejected, deprecated, superseded

Context

This section explains the context, problem, or issue that causes the need for this decision. Some also call this section “motivation”.

Be precise and focus on facts.

Decision

Describe the proposed change. Stick to the facts and don’t try to sell the decision. Also, describe how and why you came to this decision. Point out alternatives that were looked at during the decision-finding process.

Consequences

Describes the effects of the change. What becomes easier? What will be more difficult?

The Egg Finder App

To explain the technique with a practical example (and because Easter is fast approaching) I thought about a useful app called “Egg Finder”.

In Austria, it’s tradition to hide colored eggs on Easter Sunday in the garden, flat or around the house. The kids look for them and get to keep all their finds.

Of course, this family tradition is great fun for everybody. But it can also be frustrating if you can’t locate any egg or be the last to find something.

We might solve this issue with technology. So, let’s design an Egg Finder mobile app that will allow us to take pictures of the surrounding area and tell us where to find the eggs.

So, let me show you how this is done by deciding which high-level architectural pattern we will use for our Egg Finder app.

Example: High-Level Architecture Pattern for Egg Finder app

Status

Proposed

Context

For our Egg Finder app, we need to choose a high-level architecture pattern that helps us go to market fast and gives us the flexibility to make future changes easily. A modular approach has proven to be a wise choice in that regard.

We can do AI-based image recognition on mobile phones. Still, our analysis shows that the capabilities of cloud providers can be leveraged quickly and might lead to good results. So, we need to split the system into a mobile app and a backend application. Communication should be done via an API.

The logical structure that we are aiming for is to split the backend application into the components: API, Photos (store photos), Egg Recognition (look for eggs on photos), and Push (send a notification to the mobile app when the backend found an egg).

Decision

Candidates for the high-level architecture pattern are a Modular Monolith or Microservices. These software architecture diagrams describe the patterns.

Both candidates have their advantages and disadvantages. To make a good decision, one must take many factors into account.

But there is a new concept that I developed that works best during the Easter season and leverages another Austrian Easter tradition: “Eierpecken”. Without thinking too much about the consequences, it will give you a decision in no time: “Software Architecture Decision Egg Fights“.

YouTube

By loading the video, you agree to YouTube’s privacy policy.
Learn more

Load video

  1. Draw the diagrams of the candidates on eggs
  2. Smash the upper and lower “ends” of the eggs together
  3. The last egg with at least one intact end wins and represents the decision

The Architectural Decision Egg Fights is a not too serious concept, it is fairly new and needs to prove its usefulness in a real-life scenario ;). To gather more data on the concept, please share your experiences. Happy Easter!

As you can see in the video, we “decided” to go with the Modular Monolith.

Consequences

A Modular Monolith allows us to move fast in the beginning because we don’t have to deal with the complexity that comes with Microservices. Splitting the design into modules gives us the flexibility to migrate to a Microservices architecture in the future easily.

Summary

Making decisions and communicating clearly and unambiguously are key elements in the life of a software architect.

ADRs are a great tool for both of these aspects. They are easy to do and once you have started doing them frequently, it will improve your way of decision-making. Having ADRs will also improve the documentation of your system because it will make it more lively and transparent.

There is also a lot of tooling available. I like to use this one: https://github.com/npryce/adr-tools.

Written by

Simon Lasselsberger

Founder Lasssim, Software Architecture and Development Expert

Written by

Simon Lasselsberger

Founder Lasssim, Software Architecture and Development Expert

Over the past ten years, I’ve worked with small startups as well as global companies like adidas, helped them implement their business ideas by creating technical plans and by guiding their development teams through projects. The proudest I am about the success we had with Runtastic. They got acquired by adidas in 2015 for €220 million.

How can I help you?

SIMON LASSELSBERGER
Software Architecture and Development Expert