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 allows us 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 finds 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“.
- Draw the diagrams of the candidates on eggs
- Smash the upper and lower “ends” of the eggs together
- 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.
If you have the feeling that you need support with your software architecture or your tech-lead role, contact me any time.
Written by
Founder Lasssim, Software Architecture and Development Expert
Written by
Founder Lasssim, Software Architecture and Development Expert
