Architecture decision records (ADR) in Microservices - System Design Guide

Problem Statement

When teams build microservices without documenting key architectural decisions, knowledge is lost over time. This leads to inconsistent implementations, repeated debates, and difficulty onboarding new members or maintaining the system.

Solution

Architecture decision records capture important decisions in a simple, structured document. They explain the context, options considered, the chosen solution, and its consequences. This creates a shared knowledge base that guides future development and maintenance.

Architecture

Developer 1

→ADR Repository

↓

Microservice A

This diagram shows developers writing and reading ADRs stored in a shared repository, which informs the design of multiple microservices.

Trade-offs

✓ Pros

→

Preserves architectural knowledge for current and future team members.

→

Improves consistency across microservices by documenting decisions and rationale.

→

Facilitates onboarding by providing clear explanations of past choices.

→

Supports better communication and reduces repeated debates.

✗ Cons

→

Requires discipline and time to write and maintain ADRs regularly.

→

May become outdated if not reviewed and updated with system changes.

→

Adds overhead that might feel unnecessary for very small or short-lived projects.

Use ADRs when working on medium to large microservices systems with multiple teams or long-term maintenance needs. Recommended when architectural decisions impact multiple services or require trade-offs.

Avoid ADRs for very small projects with a single developer or when the system is experimental and expected to change rapidly without stable decisions.

Real World Examples

Netflix

Netflix uses ADRs to document decisions about service communication protocols and data consistency models across their microservices ecosystem.

Uber

Uber maintains ADRs to track choices about service discovery and load balancing strategies to ensure consistent behavior across teams.

Amazon

Amazon documents architectural decisions for their microservices to help teams understand trade-offs in database selection and caching mechanisms.

Code Example

This example shows how before ADRs, decisions were implicit and scattered. After ADRs, decisions are clearly documented in a structured format that anyone can read and understand.

Microservices

### Before: No ADR, decisions scattered in code comments or meetings
# Service A uses REST, Service B uses gRPC without explanation

### After: ADR example in markdown format
"""
# ADR 001: Communication Protocol Choice

## Context
We need to decide how microservices communicate.

## Decision
We choose REST for external-facing services and gRPC for internal high-performance calls.

## Consequences
- REST is easier for third parties.
- gRPC improves performance internally.
"""

Alternatives

Wiki-based documentation

Uses unstructured pages that can be edited freely without a formal template or decision record format.

Use when: Choose when you need flexible, broad documentation beyond architectural decisions and have a culture of active documentation maintenance.

Issue tracking with decision tags

Records decisions as tagged issues or tickets rather than standalone documents.

Use when: Choose when decisions are closely tied to specific tasks or bugs and you want to link decisions directly to code changes.

Summary

Architecture decision records capture and preserve key design choices in microservices.

They improve team communication and consistency by documenting context, options, and consequences.

ADRs are best used in medium to large systems where decisions impact multiple services or teams.

Practice

1. What is the main purpose of an Architecture Decision Record (ADR) in microservices projects?

easy

A. To document important architecture decisions and their reasons

B. To write detailed code for each microservice

C. To track bugs and issues in the system

D. To monitor server performance metrics

Solution

1. Step 1: Understand the role of ADRs

   ADRs are used to record key architecture decisions and why they were made.

2. Step 2: Differentiate ADRs from other documents

   ADRs are not for code, bugs, or performance monitoring but for decision documentation.

3. Final Answer:

   To document important architecture decisions and their reasons -> Option A

4. Quick Check:

   Purpose of ADR = Document decisions [OK]

Hint: ADRs capture decisions, not code or bugs [OK]

Common Mistakes:

• Confusing ADRs with bug tracking
• Thinking ADRs are code documentation
• Assuming ADRs monitor system metrics

2. Which of the following is the correct basic structure of an ADR document?

easy

A. Title, Status, Context, Decision, Consequences

B. Title, Code, Tests, Deployment, Logs

C. Summary, Bugs, Fixes, Performance, Metrics

D. Introduction, User Stories, UI Design, API Endpoints

Solution

1. Step 1: Recall ADR standard sections

   ADRs typically include Title, Status, Context, Decision, and Consequences.

2. Step 2: Eliminate unrelated structures

   Options with code, bugs, or UI design are unrelated to ADR format.

3. Final Answer:

   Title, Status, Context, Decision, Consequences -> Option A

4. Quick Check:

   ADR structure = Title, Status, Context, Decision, Consequences [OK]

Hint: Look for Context and Consequences in ADR structure [OK]

Common Mistakes:

• Mixing ADR with test or deployment docs
• Confusing ADR with bug reports
• Including UI design in ADR

3. Given this ADR excerpt:

Title: Use REST for service communication
Status: Accepted
Context: Need simple, stateless communication
Decision: Use REST over HTTP
Consequences: Easier integration but higher latency

What is the main consequence documented here?

medium

A. REST requires stateful connections for speed

B. REST causes stateless communication to fail

C. REST reduces integration complexity and latency

D. REST leads to easier integration but higher latency

Solution

1. Step 1: Read the Consequences section carefully

   The consequence states "Easier integration but higher latency".

2. Step 2: Match the consequence with options

   REST leads to easier integration but higher latency matches exactly; others contradict the text.

3. Final Answer:

   REST leads to easier integration but higher latency -> Option D

4. Quick Check:

   Consequence = Easier integration, higher latency [OK]

Hint: Focus on Consequences section for effects [OK]

Common Mistakes:

• Ignoring the 'higher latency' part
• Assuming REST reduces latency
• Confusing stateless with stateful

4. You find an ADR with this status:

Status: Deprecated

What does this status indicate about the decision?

medium

A. The decision is newly proposed and under review

B. The decision is no longer recommended or used

C. The decision is currently active and enforced

D. The decision has been accepted but not implemented yet

Solution

1. Step 1: Understand ADR status meanings

   "Deprecated" means the decision is outdated and should not be used.

2. Step 2: Compare with other statuses

   New proposals are "Proposed", active ones "Accepted", so deprecated means no longer recommended.

3. Final Answer:

   The decision is no longer recommended or used -> Option B

4. Quick Check:

   Status 'Deprecated' = Not recommended [OK]

Hint: Deprecated means outdated, avoid using [OK]

Common Mistakes:

• Confusing deprecated with accepted
• Thinking deprecated means new proposal
• Assuming deprecated means pending

5. Your team must decide between using REST or gRPC for microservice communication. You want to document this choice clearly for future reference. Which is the best way to use an ADR in this situation?

hard

A. Write code samples for both REST and gRPC without explanation

B. Skip documentation and decide by majority vote only

C. Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice

D. Create a bug report to track this decision

Solution

1. Step 1: Identify ADR purpose for decision documentation

   ADRs should explain context, decision, and consequences clearly.

2. Step 2: Evaluate options for documenting architecture choices

   Only Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice uses ADR properly; others ignore documentation or misuse formats.

3. Final Answer:

   Write an ADR with Context explaining needs, Decision stating REST or gRPC, and Consequences of each choice -> Option C

4. Quick Check:

   Use ADR to document decision and consequences [OK]

Hint: Use ADR to record context, decision, and consequences [OK]

Common Mistakes:

• Skipping documentation
• Confusing ADR with bug reports
• Only writing code without explanation