ADRs (Architecture Decision Records) are essential to software development for several reasons, especially in complex, collaborative, or long-lived projects. An Architectural Decision Record(ADR) is a justified design choice that addresses a functional or non-functional requirement that is architecturally significant. ADR provides an accessible way to capture architectural knowledge, communicate decisions effectively with the teams, and support the long-term maintainability of your project.
In this article, I would like to provide an overview of the ADR and an ADR template that can be used for your project architecture decisions.
What is ADR?
An Architecture Decision Record (ADR) is a document or structured template that captures significant architectural decisions during software project development. It provides a clear, concise, and traceable record of why certain decisions were made, the context in which they were made, and the consequences of those decisions.
Purpose of ADR
- Documentation: To record why and how a decision was made.
- Knowledge Sharing: Assists existing/new team members in understanding the rationale behind architectural choices.
- Accountability: Serves as an auditable record of decisions.
Historical Context: Provides a timeline of architectural evolution in the project.
Facilitates Revisions: It makes revising decisions easier when the context or requirements change.
Structure of an ADR
An ADR is structured in a simple format. Here is a template that covers all the aspects.
- Title: A clear and descriptive title for the decision
- Status: This section describes the status of ADR such as proposed, approved, rejected, deprecated, superseded, etc.
- Author: This section denotes the Author of ADR. It can be a single person or a group.
- Context: This section provides the background context as to why we need to make this decision and the scope of the decision being made.
- Considered Options: This section describes the considered options and the unique/specific characteristics of each option along with pros and cons.
- Decision: The decision that we have agreed on from the proposed options.
- Rationale: Explanation of why this decision was made and why other proposed options were not chosen.
- Consequences/Trade-offs: Negative impact or consequences of the decision.
- Mitigation Strategy: Mitigation strategy of the consequences of the decision.
Why do we need ADRs?
ADRs (Architecture Decision Records) are crucial in software development for various reasons, especially in complex, collaborative, or long-lived projects.
- Preserve Decision-Making Context: Architectural decisions are often made based on specific business requirements, technical constraints, or team capabilities at a particular time. Without ADRs, this context is easily lost as teams change or time passes.
- Facilitate team Alignment: Decisions made in isolation can lead to misalignment and inefficiencies in the team. ADRs provide a shared understanding of architectural choices.
- Improve Knowledge Sharing and Onboarding: This helps new team members quickly understand why certain decisions were made and the context around them. ADRs act as a lightweight way to transfer this knowledge.
- Enable Better Decision Making: Having a record of past decisions, including the alternatives considered, helps avoid repeating discussions or making inconsistent decisions.
- Traceability and Accountability: Projects often need to justify their decisions to stakeholders, whether for audits, reviews, or just internal validation. ADRs provide a clear, written record of architectural choices.
- Manage Architectural Evolution: Software systems evolve, and decisions may need to be revisited. ADRs provide a baseline to determine when and why a decision should be updated.
- Avoid “Tribal Knowledge”: Key knowledge should not be limited to a few senior developers. ADRs ensure critical architectural insights are accessible to everyone on the team.
Below is a sample ADR for using Kafka as a messaging queue in Microservice Architecture.
# Title : Use Kafka for Messaging in Microservices Architecture
## Status
Accepted
## Author
Anjireddy Kata
## Context
We are building a microservices-based architecture where services need to exchange data asynchronously. The key requirements include:
- High throughput and low latency.
- Durable and replayable message storage.
- Scalability to handle growing traffic.
- Fault tolerance to ensure minimal downtime.
## Considered Options
Below are the evaluated several messaging systems
### Option 1: Kafka
Kafka is a distributed streaming platform.Kafka is designed for handling large volumes of data efficiently.
Kafka provides persistent message storage, allowing messages to be replayed.
#### Pros
- **Scalability**: Kafka can scale horizontally by adding more brokers and partitions.
- **High Throughput**: Designed for high-performance data ingestion and processing.
- **Durability**: Messages are stored on disk and can be replayed.
- **Fault Tolerance**: Partition replication ensures reliability in case of broker failures.
- **Ecosystem**: Kafka offers tools like Kafka Streams, Kafka Connect, and ksqlDB for advanced use cases.
- **Event Replay**: Enables reprocessing of historical data by re-consuming messages.
#### Cons
- **Operational Complexity**: Managing Kafka clusters requires expertise, especially in self-hosted setups.
- **Resource Intensive**: Kafka's brokers and topics require substantial CPU, memory, and disk resources.
- **Steep Learning Curve**: Developers and operators need to understand Kafka's architecture, APIs, and tooling.
- **Latency**: While low, it may not match real-time systems for ultra-low-latency requirements.
- **Limited Message Routing**: Kafka’s topic-partition model lacks advanced routing capabilities like RabbitMQ.
### Option 2: RabbitMQ
#### Pros
- Simple to set up
- supports complex routing patterns.
#### Cons
- Limited durability for large-scale data.
- Replaying messages is less straightforward.
### Option 3: AWS SQS
Fully managed message queue service from AWS.
#### Pros
- Fully managed
- No infrastructure to maintain.
#### Cons
- Higher latency compared to Kafka.
- Lacks advanced features like topic-based subscription.
## Decision
We decided to use **Kafka** as the messaging backbone for our microservices.
## Rationale
1. **High Throughput**: Kafka is designed for handling large volumes of data efficiently.
2. **Durability**: Kafka provides persistent message storage, allowing messages to be replayed.
3. **Scalability**: Kafka’s partitioning and replication features make it suitable for scaling with traffic.
4. **Event Streaming Support**: Kafka supports event-driven architectures, aligning with our long-term goals.
## Consequences
### Positive
- Ensures system scalability and fault tolerance.
- Provides the ability to replay and debug message streams.
- Aligns with our long-term event-driven architecture plans.
### Negative
- Increased operational complexity in managing Kafka clusters.
- Requires team members to learn Kafka's APIs and tooling.
## Related Decisions
- Use a Dead Letter Queue (DLQ) for message handling (See ADR: 0002-use-dead-letter-queue.md).
## References
- [Apache Kafka Documentation](https://kafka.apache.org/documentation/)
- [Microservices and Event Streaming with Kafka](https://www.confluent.io/)Each project member should have access to the collection of ADRs. I recommend that you store the ADRs in a central location and reference them on the main page of your project documentation. There are two popular options for storing ADRs:
- A Git repository, which makes it easier to version ADRs
- A wiki page, which makes the ADRs accessible to all team members
References:
