Architectural Decision Record

ADR, or Architectural Decision Record, is a concise record of architectural decisions made during the software design process. These records capture the context in which the decision was made, the decision itself, and the consequences of the decision. ADRs should be written whenever a decision has been made that affects the system's architecture, its non-functional requirements, or its development processes. Note that not every change requires an ADR. The intent is to capture meaningful decisions that have a lasting impact on the project or system. If the decision would benefit from additional context or if future developers might wonder 'why was this done?', then it's worth capturing in an ADR. Also, keep in mind that ADRs aren't set in stone. As systems evolve and requirements change, previous architectural decisions might be revisited, and new ADRs can be created to document the evolution.

Case scenarios

• Significant architectural changes: whenever a decision is made that significantly changes the system's architecture, such as adopting a microservices architecture, choosing a specific database system, or introducing a new technology stack.
• New Requirements: when new business or technical requirements lead to architectural changes. For example, a requirement for multi-region support might necessitate decisions around data replication and latency.
• Trade-offs: anytime there are multiple options considered and trade-offs evaluated to make a decision. Documenting why certain options were rejected can be as valuable as documenting why one was chosen.
• Risk mitigation: when a decision is made to address risks, such as security vulnerabilities or potential bottlenecks in the system, it's beneficial to capture the decision and the context.
• Changes to established practices: if the development or deployment practices are changed, such as adopting a new branching strategy or incorporating new CI/CD tools.
• Overturning previous decisions: when an earlier decision is being revisited, modified, or reversed, an ADR can provide insight into what's changed in the interim, be it new information, shifting requirements, or the evolution of technology.
• Regulatory or compliance impacts: in industries where regulatory or compliance requirements are crucial, architectural decisions made to meet these requirements should be documented.
• Knowledge sharing: to ensure that team members, especially those who join later in the project, understand the context and rationale behind certain choices.
• Controversial decisions: when the team is divided on a particular decision or when it could have significant consequences (either positive or negative).

ADR structure

• Title: short present-tense phrase or sentence explaining the decision.
• Status: proposed, Accepted, Rejected, Superseded, etc.
• Date: date of last edition of document
• Participants: colleagues involved on creating the document.
• Context: describes the situation, constraints, or problem leading up to the decision.
• discussion: defines all the brainstorming that has been made to find a way to solve the problem.
• Decision: a concise description of the chosen solution or strategy.
• Consequences: describes the outcomes, changes, and impacts resulting from the decision.

Example ADR of starting to use Docker

Title

Adoption of docker for microservices deployment

Status

Accepted

Date

2022-08-27

Participants

• Jane Doe (Lead Architect)
• John Smith (DevOps Engineer)
• Emily Clark (Backend Developer)

Context

As our application grows in complexity, the team has been exploring ways to simplify deployment, improve scalability, and isolate service failures. We've identified that adopting a microservices architecture might address our concerns. However, deploying microservices can be complicated due to the management of multiple small services, each with its own dependencies.

Discussion

• Option 1: Traditional VMs
  • Pros: Well-understood, isolation at the OS level.
  • Cons: Resource-heavy, slower to start, managing multiple VM images can become tedious.
• Option 2: Docker containers
  • Pros: Lightweight, fast startup, isolation at the process level, consistent environments.
  • Cons: Requires new knowledge and tooling, potential security concerns if not configured properly.
• Option 3: Serverless functions
  • Pros: Fully managed, auto-scaling, pay-as-you-go.
  • Cons: Might not suit all types of microservices, cold starts, vendor lock-in.

The team leaned towards Docker due to its lightweight nature, the vast community and ecosystem, and its ability to ensure consistent environments across different stages of development and deployment.

Decision

Adopt Docker for deploying our microservices. We'll containerize each service with its dependencies, ensuring a consistent environment from development to production. Additionally, we'll invest in tooling (like Docker Compose for local development and Kubernetes for production) to manage these containers.

Consequences

• All microservices will be developed with Docker in mind, possibly requiring some refactoring of existing services.
• Team members will need training on Docker, and potentially Kubernetes, to understand best practices and security considerations.
• While initial setup might increase development time, we expect faster deployment cycles and increased system stability in the long run.
• We will need to monitor the system closely initially to ensure there are no unforeseen issues with container orchestration, especially under heavy loads.

The team will need training since Cassandra and NoSQL approaches differ from traditional RDBMS. We'll need to design our data models differently, considering denormalization and Cassandra's query-first design principle. Given Cassandra's eventual consistency model, we might experience some consistency-related challenges, but this is a trade-off we're willing to make for the scale and availability it offers.