The world of software development and product architecture has different meaning from beginning of 21st century by emerging Agile software development methodology.
We have heard about different types of documentations that used and benefited variety of them, based on requested information and their usage, such as source code (low-level) documentation, software requirement (high-level) documentation and end user instructions in our projects. But what about the architecture documentation? What kind of challenges do we have to record our daily architectural decisions regarding Agile Software Development Manifesto?
What is ADR?
The necessity of using evolutionary architecture and developing incremental software production procedure in today’s software development life-cycle obliges us to record our architectural decisions as we do it for other decisions like design and implementation.
We will keep a collection of records for “architecturally significant” decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques.
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.
ADR Document Sections
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.
Optional Sections
Neal Ford and Mark Richards in their book suggest two more optional section for ADR as complementary parts.
- 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
Redefining an architecture for a monolithic project, Parameter-Regulator, that has been developed during roughly 20 years and now is suffering from big ball of mud anti-pattern without any possibility to extend, modify and further development, and documenting our decisions are what we desire in this section.
Parameter-Regulator is a desktop application that has been developed to parametrize and program ICs from different commercial brands for variety of embedded devices in cars such as mirror, window lifter and so on.
1st Decision — Application Architecture Style
| 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: 1) Modularity: The application functionalities should be independent from each other as much as possible. 2) Deployability: Whenever we change or modify a module, we have to only deploy the altered/updated one, not whole application. 3) Testability: Creating and design this application that allows its features to be tested automatically. 4) Extensibility: We should add new features in a way that keeps costs low, regardless of adding new customer or fulfilling new requirements from current customers. 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: 1) The plugins should be designed to be standalone and independent from each other. 2) The plugins don’t have any understanding from each other and can not communicating directly. 3) The components will be controlled and orchestrated with core component. |
2nd Decision — North-South Communication Style
| 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: 1) Communication parameter-Regulator with the services provided by 3rd parties 2) Component orchestration and communication by Core module There two main reasons to decide for synchronous communication: 1) Feedback from recipient of message is necessary for the sender or service requester. 2) The development team can quickly learn the required skills due to their experience with this methodology. |
| Consequence | Choosing a synchronous communication pattern has two major consequences: 1) Architectural Consequences: This communication style can cause components and plugins to become tightly linked, making the system less flexible. Furthermore, using different communication methods, such as asynchronous communication, can make the overall system more complex. 2) Implementation and Documentation Consequences: The synchronous messaging brings latency issue by itself. That’s why, we have to find a way to mitigate it in our implementation. Additionally to taking advantage of synchronous communication, beside defining and implementing interfaces for components and plugins, we have to clearly document the messaging format, their status code and possible errors. 3) The components will be controlled and orchestrated with core component. |
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.
