Architecture Decision Records
How many of you have gotten deep into debugging some production problem and said “Who wrote this crap?”? How often did it turn out that you yourself wrote it? At the moment in time that you designed the thing (system, database, algorithm), your choice probably made sense. But once customers got a hold of your software, realities set in that exposed a flaw in your design. It’s because when you made that design you were in the wide part of the Cone of Uncertainty. At this point, the question then morphs into “Why the hell did I do that?”. The solution to this problem is documentation.
In the software industry, there is a strong resistance to documentation.
“We’re Agile, we don’t need documentation!”. “The value is in the conversation.” “Documentation gets out of date quickly.”
The main problem is we, as engineers, tend to document the wrong things. Architecture diagrams and business rules are handy things to document, but they are only part of the whole picture. In my last article, I referenced the first law of software architecture: Everything is a trade-off. The second law of software architecture is this: the why is more important than the how. By keeping track of why a decision was made, you’re giving future developers (and future you) a look into the underlying assumptions used to build the software system. Knowing why a decision was made helps people better understand the context of the problem and avoid possible mistakes to refactoring to another solution that might cause problems.
One tool to help you track these whys is the Architecture Decision Record (ADR).. One of the early evangelists of the ADR was Michael Nygard. Making architecture decisions involves gathering enough relevant information, justifying the decision, documenting the decision, and communicating it to the stakeholders (which includes other developers). An ADR is generally a short text document (usually one or two pages long) that summarizes the problem, provides necessary context, states the decision made, and lists the consequences. You should write them as a simple text or markdown document stored in source control or some kind of internal knowledge base like a wiki or Confluence. They shouldn’t be distributed via email, but you can notify people of a new ADR via email.
Once a decision has been made, the ADR shouldn’t be changed or amended. It should be superseded by a new ADR referencing the old one. This way, future developers get a sense of why and how the system they are working on has changed.
The basic structure of an ADR consists of five main sections: Title, Status, Context, Decision, and Consequences. You can optionally add an Alternatives section to provide analysis of all the alternatives you investigated while making this decision. ADRs are typically numbered so they can be easily referred to.
Let’s say you want to migrate data from a relational database to a NoSQL database. Here’s an example of how that ADR might look:
ADR 1. Migrate trip data from SQL Server to MongoDb
Status
Accepted November 11, 2022
Context
MoneyMakerService currently stores its trip data in SQL Server in a normalized data structure. The company is looking to sign up two new customers that will triple the number of trips we receive on a daily basis. This increase in data will put significant stress on the database server and will necessitate the addition of several more hard drives. As the data volume increases, SELECT queries will begin to slow down even with the appropriate indexes in place, leading to issues in scalability.
Decision
We will migrate the data from a hosted SQL Server instance to MongoDb Atlas. The trip data isn’t relational, so a NoSQL implementation will suit our needs.
Consequences
We can easily add new clusters to our node to scale out.
MongoDb will handle sharding for us to improve scalability.
Moving to MongoDb Atlas will incur additional cost.
The effort will cause delays for new features being introduced as developers will be tied up writing the migration.
QA will need to be involved testing the migration and some form of customer communication will need to go out informing them of the cutover window.
This is an example of refactoring an existing application. For a new application, this section should list the tradeoffs you made while picking the decision you did. Example, if you chose a microservice architecture over a service-oriented architecture, which benefits of microservices did you think outweighed the benefits of SOA. It should also list any work that results from the decision.
The Architecture Decision Record isn’t a standard that you must rigidly follow. You are free to adapt it to fit your own company’s process and needs. What’s important is that you capture the decision you made and the rationale behind it. Future You will thank you for it.