Architecture Decision Records (ADR)
We will keep a collection of records for “architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques. -- Michael Naygard
To be more precise, the five main decision fields that should be documented and recorded are:
Structure: Agreement about the main architectural style like EDA, modular monolith, microservice and so on.
Non-functional Characteristics: Requirements and -ilities such as scalability, elasticity, data integrity and security that comes from customer needs and are a part of software feature which changing such decisions would be expensive in future.
Dependencies: Internal and/or external dependencies between software components that could be resulted to coupling in services.
Interfaces: Consists of software interfaces like API and user interfaces.
Construction Techniques: Includes programming languages, platforms, software development methodologies such as scrum and so on.
Each document has five sections that conveys all necessary information about decision, side-effects and consequences briefly. Regarding company policy and management decisions, we can add more sections to make it more informative, comprehensive and complete.
Title: As it is recognizable, it expresses the Architecture Decision in a nutshell. Normally, the documentation should be numbered in this section.
Status: The condition of decision that could be defined in 4 statuses..
Status | Description |
proposed | Initial status of each ADR, regardless of decision filed |
accepted | Approved or confirmed architecture decision. |
rejected | The dropped solutions because of any reasons. It is strongly suggested to kept them to have complete history of discussed solutions and decisions. |
superseded | It describes the revised decisions. The accepted ADR could be surpassed by them. |
Context: There is always a reason(s) that we are convinced or sometimes forced to take this decision and it has to be explained here.
Decision: It contains the affirmative description with non-passive sentences about the architectural decisions. Furthermore, this part of documentation should be written in details to simply prevent doubts and upcoming questions about the decision.
Consequence: The section that covers the advantages and disadvantages of decision and the services and components that would be affected with it should be mentioned here. Moreover, here is the right place to talk about trade-offs.
Compliance: How the architecture decision will be measured and governed from a compliance perspective.
Notes: This chunk is a metadata section that can have information such as author, approval date, approved by and so on.
The suggested format for ADR is Markdown or ASCII that should be written in maximum two pages. I have seen many companies and organizations prefer using wiki or confluence pages for this reason that are not suggested. The ADR Best Practice is to keep records in the repository with source code.
Case Study
Title | ADR01: Micro-Kernel architecture style to redesign Parameter-Regulator application |
Status | Accepted |
Context | Parameter-Regulator is a polyglot desktop application created using multiple programming languages. The following architectural characteristics (-ilities) should be considered in choosing application architecture:
Parameter-Regulator needs to offer reporting on its processes and results in various formats such as text or binary, depending on what the customer prefers. These reports can be saved locally on the system, stored in a database, or sent to the customer through external services. |
Decision | To redesign Parameter-Regulator application, regarding the mentioned requirements in context section, we choose micro-kernel architecture style. |
Consequence | This decision would lead to the following consequences:
|
Title | ADR02: Synchronous communication style for north/south and cross layer communication |
Status | Accepted |
Context | Parameter-Regulator should be able to integrate with various tools and services from third-party vendors, whether they are cloud-based (SaaS) or on-premises to fulfill the north/south communication. Another important aspect of Parameter-Regulator, which has modular architecture, is the core module's ability to communicate reliably with other components (Plugins). This includes interactions with plug-ins in the upper presentation layer and the database in the lower layer. |
Decision | We decided to implement synchronous messaging mechanism for both cases:
There two main reasons to decide for synchronous communication:
|
Consequence | Choosing a synchronous communication pattern has two major consequences:
|
Wrapping Up
Many companies and firms underestimate the importance of recording architectural decisions due to a misunderstanding of agile software development principles and the need for incremental or evolutionary architecture in their projects.
Architecture Decision Records (ADRs) are a best practice methodology that allows teams to document architectural decisions similarly to how they document source code. ADRs can be recorded in various formats, such as wiki pages, Markdown, or ASCII text files. Additionally, there are specialized tools available that can help manage and maintain these records effectively.
Furthermore, properly documenting architectural decisions through ADRs provides several key benefits as followings:
It creates a valuable knowledge base for current and future team members
ADR promotes consistency and clarity in decision-making
It helps to ensure that architectural choices are aligned with the project’s long-term goals
By incorporating ADRs into their development processes, organizations can enhance communication, facilitate better collaboration, and ultimately contribute to the success of their projects.
Share This Article