ADR: Deep Dive into Architecture Decision Records
A software design or architecture has continually been a complicated, arguable, and considerable concept to develop a project with numerous features, fix the bugs, or even write the tests. Although miscellaneous parameters, such as functional or non-functional requirements, constraints, technical know-how, etc., play a significant role in making an architectural decision, not all decisions will be carried out at once, nor will all of them be accomplished when the project launches.
Despite all these difficulties, consider that your team verbally discussed the cons and pros of separate approaches, spent lots of time and you finally made a decision. What happens if a new developer joins your team and tries to understand the motivations for your architectural decisions? Worse, what happens if you can’t remember the explicit reasons that impacted your decisions?
I believe you got the point. To comprehend the rationale or consequences, not to accept the decisions blindly or not to change those decisions haphazardly, documentation of the architectural decisions is an inevitable fact.
First, let’s look at the terminology, and then try to understand the benefits and how to record the architectural decisions with the best practices.
Terminology
- More specifically, an Architectural Decision (AD) is a software design preference that handles the functional or non-functional requirements, which are architecturally significant.
- An Architecture Decision Record (ADR) is a document that captures a crucial architectural decision made along with its boundary and outcomes. In other words, ADR apprehends the key options available, the major requirements that force a decision, and the design decisions themselves. We usually store ADRs as a short text file within the related code base for that decision. If someone needs to understand the motivation of a specific architectural decision, they may easily scan the ADR with the associated code.
- An Architecture Decision Log (ADL) is the collection of all ADRs generated and maintained for a particular project. All related ADRs are stored in the same collection.
- An Architecturally-Significant Requirement (ASR) is a requirement that has an observable impact on the architecture of a software system.
- All these terminologies are a part of Architecture Knowledge Management (AKM).
How to document Architecture Decisions?
There are a lot of ready-to-use templates from basic to more sophisticated for the documentation of the architecture decisions. (Check Templates) Primitively, there are 4 major sections we follow in the document, called Status, Context, Decision, and Consequences, respectively.
1. Discussion for Context
In this section, we explain the forces at play, including technological, political, social, and local projects. This part is the primary story describing the problem we are looking to resolve. You should be transparent and descriptive about your motivations for that decision or a change as much as possible. Discuss your ideas and the paths you follow with your teammates while defining the problem you face.
2. Decision for Solution
This section may be one of the most important parts of the document. Here, we describe the details of the decision for a specific problem we mentioned in the Context section. It is a kind of a response to the forces in the story. We present how to solve the problem with a given decision in detail. There is a correlation between decision and solution. Your decision affects the solution based on the approach you propose. That’s why readability and understandability have a huge impact from a technical perspective.
3. Observation of Consequences
This section refers to the results of the given decision for a specific problem mentioned in the story. We illustrate the long-term effects of the decision if any. All results should be documented here, not just the “positive” ones. A given decision may generate positive, negative, and neutral consequences, but all of them influence the team and project in the future. In addition, this part examines the questions as follows;
- Did the architecture decision work?
- Did the architecture decision not work?
- Was the architecture decision changed?
- Was the architecture decision upgraded?
4. Describe Status
This section primarily represents the status of an architecture decision to give information regarding which step AD currently is. A couple of examples are as follows;
- Accepted
- Rejected
- Proposed
- Deprecated
Best Practices for ADR
- Identify when the Architecture Decision was formed. Time is a significant factor to understand under which circumstances you made this decision.
- Explain the rationale for making the certain Architecture Decision. Be descriptive for clear explanations.
- The record must be immutable. The previously given decision in the ADR should not be modified.
- Be cohesive. Each ADR should be regarding a single AD.
- Create a new ADR, if the AD invalidates the previous one.
- Explain your organization’s position and business precedences.
API Gateway Decision Example
Time to make practice with a real scenerio! If you are interested with microservices, you probably heard API Gateways. Assume that your organization decided to migrate the current system to the microservices for various reasons (We don’t focus the reasons). As a first step, you need to choose the most suitable API Gateway in terms of your motivations such as performance, stateless architecture, open-source development, etc.
From the point of a story we mentioned above, the context is obviously a choice of API Gateway for your organization. While deciding an API Gateway, you have two major needs: open-source options, the know-how about the language of the source code. Besides the major needs, you have constraints, that affect your choice, like high-throughput, performance, open-source community, etc.
Suppose that, in line with this information, you have 4 positions or options, which are KrakenD, Kong, Ocelot, and Tyk. Based on these options, you made research and provide the arguments as summary. In addition, you expressed the details as implications of these API Gateways.
At the end, you combined the arguments with implications and you made a decision and chose KrakenD considering the motivations. Then, you proposed this decision to your organization and the status of the decision was accepted.
Check to see what the final version of API Gateway ADR looks like;
Conclusion
In this post, I tried to explain what the architecture decision and architecture decision record were, how to document it, and most importantly, emphasized the significance of the architecture decision documents in our organizations.
I am welcome to see your opinions or additional information. I hope you enjoy and find this post useful :)
