Importance of ADRs in agile architecture

Maintaining clear and concise architecture documentation is essential for successful teams. In the past, waterfall-based approaches often struggled to keep pace with the rapid changes in software development; by finishing the main architecture plan, the decisions made might already be obsolete. This led to including Architecture Decision Records (ADRs), which served partly as rationale and partly in some cases as later-elaborated details, in the parts where the plan was (un)intentionally vague.

With the emergence of Agile methodologies, the focus was shifted towards having a working product with real value rather than an elaborate architecture plan before any implementation. [1] Coincidentally, over time (according to my experience), it also brought the renaissance of Architecture Decision Records (ADRs) as a form of documenting architecture. It is no longer just a tool (like previously). In this blog post, we will explore the concept of ADRs and their significance in modern software development.

ADR - Agile Infrastructure Documentation

Lately, I noticed that ADRs might soon be the only form of architectural documentation. Whereas the traditional waterfall project typically uses ADRs to update predefined architectural plans, in Agile teams, ADRs take on a more prominent role as they become the foundation of the architecture documentation itself.

The reasons are inherently clear: Agile infrastructure documentation embraces flexibility, adaptability, and iterative decision-making, allowing teams to navigate the evolving landscape of software development and the ever-changing requirements.

I would describe Agile infrastructure documentation as a tree: the Agile team has a base, high-level architecture documentation = the trunk, which is enriched by the roots = the initial motivation for setting up the team. These are concise and clear fundaments that rarely change and define a stable base. They never go into too many details; those are for ADRs.

On top of a strong trunk sit the branches, the ADRs. These branches might occasionally break in a storm (e.g., retiring components) and must be trimmed regularly to have a nice shape (e.g., refactoring). Branches with many other branches might eventually evolve into somewhat of a trunk themselves (e.g., a new component/team forming), providing stable fundaments, too. Branches also bring the fruit, aka. customer value.

Benefits of ADRs

ADRs bring numerous benefits for teams adopting them [2][5]:

Clarity and Transparency

ADRs provide a clear and concise record of the architectural decisions made throughout a project's lifecycle. This transparency promotes a shared understanding among team members, stakeholders, and future contributors, facilitating collaboration and reducing ambiguity.

Onboarding and handover

By documenting architectural decisions, ADRs serve as valuable materials that preserve knowledge. They enable new team members to understand the rationale behind past choices, preventing unnecessary reinvention and fueling knowledge transfer.

Decision Accountability

ADRs establish accountability for architectural decisions by documenting the context, alternatives considered, and the reasoning behind the chosen approach. This accountability promotes a culture of responsibility and facilitates discussions around decision-making processes.

Sections in an ADR

The following sections should be included in a well-defined ADR [2][3]:

• Title and Identification: a clear and descriptive title reflecting the decision's essence. A unique id should be assigned to facilitate referencing and tracking.
• Context: an overview of the situation or problem that led to the need for a decision. It includes background information, existing architecture, challenges, and relevant external factors.
• Decision: describes the concrete decision made, including alternatives considered and the rationale behind choosing a particular approach. It should address the trade-offs, risks, and benefits of the decision.
• Consequences: the expected implications of the decision, both positive and negative. This section helps stakeholders understand the impact on the system, potential risks, and any implications for future decisions.
• Status and Tracking: To ensure the ADR's relevance over time, it is essential to track its status. This can include the decision date, the decision-makers names, and any updates or modifications made.
• Moreover, one or two diagrams where they help guide the train of thought are essential.

Example ADR

Let's look at a practical example of an ADR:

Title
MYTEAM-001: Using AWS lambda as the backend runtime

Context
Our application currently relies on a monolithic architecture running on traditional virtual machines. This approach poses challenges in scalability, resource management, and operational efficiency. To address these issues, we have explored the benefits of adopting a serverless architecture using AWS Lambda.

Decision
Use AWS Lambda as the backend runtime. Lambda provides several advantages significant to our stakeholders, including automatic scaling, reduced operational overhead, and an optimal pricing model.
<< Ideally a diagram goes here >>

Rationale
1. Scalability: AWS Lambda allows us to scale our application seamlessly in response to varying workloads, almost infinitely. With the ability to automatically provision and manage resources based on demand, we can ensure optimal performance during peak usage periods while avoiding over-provisioning during periods of low activity.

2. Cost Efficiency: The pay-per-use model of AWS Lambda aligns with our goal of optimizing costs. We can significantly reduce infrastructure costs by eliminating the need for long-running servers and paying only for actual usage.

3. Operational Simplicity: AWS Lambda handles server management, automatic scaling, and resource allocation, freeing our team from infrastructure maintenance tasks. This enables us to focus more on application development and delivering user value.

Consequences
1. Vendor Lock-in

2. Cold Start Latency: AWS Lambda functions may experience a slight delay when invoked for the first time (cold start) due to the need to initialize the underlying infrastructure. We must optimize our application to mitigate any potential impact on user experience.

Status and Tracking
Decision made: 2023-06-12
Decision makers: John Smith, Jane Doe
ADR status: Active

Conclusion
We aim to enhance our application's scalability, cost-efficiency, and operational simplicity by adopting AWS Lambda as our serverless platform. This decision aligns with our organizational goals and paves the way for embracing a more agile and scalable architecture. As we progress, we will monitor the impact of this decision, continuously refine our implementation, and reassess our options to ensure the long-term success of our application.

Conclusion

Agile architecture documentation can be visualized as an evolving tree, where branches represent decisions made along the architectural journey, and the tree itself symbolizes the system's architecture. As branches grow from the trunk, ADRs branch out from existing decisions, forming connections and dependencies within the architecture.

In this blog post, we looked at ADRs historically, what they mean today, and what makes an ADR a good ADR with a practical example.

Sources
[1]: https://ieeexplore.ieee.org/document/9801811
[2]: https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html
[3]: https://adr.github.io
[4]: https://github.com/alphagov/govuk-aws/tree/master/doc/architecture/decisions
[5]: https://engineering.atspotify.com/2020/04/when-should-i-write-an-architecture-decision-record/