Treating Architecture Decisions as a Black Box: Why ADRs Matter

Why ADRs? The "Black Box" Analogy

Many teams encounter situations where new architects question past decisions, historical choices lack documented reasons, or discussions are repeatedly revisited. Architecture Decision Records (ADRs) address these problems by acting like an aircraft’s black box: they capture what decision was made, why it was made, and the context surrounding it.

What Is an ADR?

Definition

ADR stands for Architecture Decision Records. It is a document that records a single architectural decision.

Essence

Like a black box, an ADR records:

Why the aircraft (system) flew a certain way?

What were the weather (environment) and decisions at that time?

Why that particular choice was made?

Value

Knowledge accumulation : decision process does not depend on individuals.

Avoid duplication : prevents repeated discussions.

Context preservation : helps understand historical decisions.

Problem tracing : know the rationale when issues arise.

Onboarding : new members can quickly grasp the system.

ADR Formats

Simple (Title Only)

# ADR-001: Use JWT as Authentication Token

Applicable for simple or temporary decisions.

Standard (Michael Nygard) Format

# ADR-001: Use JWT as Authentication Token

## Status
Accepted, 2024-01-15

## Background
Mobile and web need a stateless authentication solution.

## Decision
Adopt JWT (JSON Web Token) as the authentication token.

## Options Comparison
| Option | Pros | Cons |
|-------|------|------|
| JWT   | Stateless, cross‑origin | Size limit, not revocable |
| Session | Controllable, revocable | Requires storage, stateful |

## Consequences
- Positive: good performance, strong scalability
- Negative: token expiration requires front‑end refresh handling

## Related Decisions
- ADR-002: Token expiration settings

Full Format (Extended Fields)

# ADR-001: Use JWT as Authentication Token

## Metadata
| Field | Content |
|-------|---------|
| ID    | ADR-001 |
| Title | Use JWT as Authentication Token |
| Date  | 2024-01-15 |
| Status| Accepted |
| Decider| Zhang San |
| Reviewer| Li Si, Wang Wu |

## Background & Problem
[Describe background]

## Decision
[Describe decision]

## Options
### Option A: JWT
- Pros: xxx
- Cons: xxx
### Option B: Session
- Pros: xxx
- Cons: xxx
### Option C: OAuth2.0
- Pros: xxx
- Cons: xxx

## Evaluation Criteria
| Criterion | JWT | Session | OAuth2.0 |
|-----------|-----|---------|----------|
| Performance | High | Medium | Low |
| Scalability | High | Low | High |
| Implementation Complexity | Low | Medium | High |

## Decision
Choose: JWT

## Rationale
1. System needs a stateless solution
2. Clear cross‑origin requirements
3. Team has prior experience with JWT

## Consequences
### Positive
- Stateless, good scalability
- Performance improvement
### Negative
- Token leakage risk
- Revocation difficulty

## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Token leakage | Medium | High | HTTPS transport, short‑lived tokens |
| Token expiration | Medium | Low | Front‑end refresh mechanism |

## Implementation Plan
1. 2024-01-20: Design JWT scheme
2. 2024-01-25: Prototype implementation
3. 2024-02-01: Test deployment
4. 2024-02-05: Full rollout

## Related Decisions
- ADR-002: Token expiration settings
- ADR-010: Unified authentication center

## References
- JWT official site: https://jwt.io
- RFC 7519: https://tools.ietf.org/html/rfc7519

ADR Lifecycle

Status Flow

Proposed → Accepted → Deprecated → Superseded
                         ↓
                     Implemented

Status Descriptions

Proposed (yellow): under discussion

Accepted (blue): decision adopted

Implemented (green): implementation completed

Deprecated (gray): no longer used

Superseded (red): replaced by a newer ADR

When to Create an ADR

Important technical selection decisions

Architecture changes

Introducing new technology

Major design changes

Decisions affecting multiple teams

Do not create an ADR for minor code changes, clear daily decisions, or decisions with well‑defined standards.

ADR Creation Process

1. Propose decision need
   ↓
2. Analyze options and impact
   ↓
3. Draft ADR
   ↓
4. Review ADR
   ↓
5. Record decision
   ↓
6. Track implementation

ADR Numbering

ADR-001
│     └── Incremental sequence number
└── Fixed ADR prefix

Managing ADRs

Storage Location

Place ADRs in the repository, for example:

project-root/
├── docs/
│   └── adr/
│       ├── ADR-001-use-jwt-auth.md
│       ├── ADR-002-token-expiration.md
│       └── README.md ← ADR index
└── ...

ADR Index

An index file lists all ADRs with their status, e.g.:

# ADR Index

## ADR List
- ADR-001 | Use JWT as Authentication Token | 2024-01-15 | Implemented
- ADR-002 | Token expiration settings | 2024-01-16 | Implemented
- ADR-003 | Use Redis for caching | 2024-01-20 | Accepted

## By Status
### Implemented
- ADR-001
- ADR-002
### Accepted
- ADR-003
### Deprecated
- ADR-010 (superseded by ADR-015)

Tool Support

adr-tools : CLI for creating and managing ADRs

adr-management : web platform for ADR governance

VSCode extension : manage ADRs inside the IDE

Example commands:

# Create a new ADR
adr new "Use JWT authentication"

# List all ADRs
adr list

# Show a specific ADR
adr show 001

Practical Advice

Keep It Simple

Record only key information

Avoid redundancy

Be clear and concise

Record Promptly

Document decisions immediately after they are made

Never postpone documentation

Use Simple Markdown and Version Control

Store ADRs as plain Markdown files

Commit them to the code repository

Case Study: Full ADR Example (Kafka Adoption)

# ADR-023: Adopt Kafka as Message Queue

## Status
Implemented, 2024-02-01

## Background
Order system needs asynchronous processing (stock deduction, points issuance, notifications). Current synchronous calls cause tight coupling and poor performance.

## Decision
Adopt Apache Kafka for asynchronous order event handling.

## Candidate Options
| Feature | Kafka | RabbitMQ | RocketMQ |
|---------|-------|----------|----------|
| Throughput | Millions/sec | Tens of thousands/sec | Hundreds of thousands/sec |
| Latency | Milliseconds | Milliseconds | Milliseconds |
| Ordered messages | Supported | Supported | Supported |
| Transactional messages | Not supported | Supported | Supported |
| Delayed messages | Not supported | Supported | Supported |

## Evaluation Criteria
- Throughput: high (millions/sec)
- Reliability: high
- Latency: <100 ms
- Operational complexity: medium
- Team familiarity: high

## Decision Rationale
1. Throughput meets requirements
2. Team already has Kafka experience
3. Rich ecosystem and tooling
4. No need for transactional or delayed messages

## Implementation Plan
- 2024-02-01: Deploy Kafka cluster
- 2024-02-05: Integrate order events
- 2024-02-10: Full traffic switch

## Consequences
### Positive
- System decoupling
- Performance boost
- Strong scalability
### Negative
- Added operational complexity
- Need to handle duplicate consumption
- Must monitor message latency

## Related ADRs
- ADR-024: Kafka cluster deployment plan
- ADR-025: Message idempotency handling

Summary

Architecture Decision Records (ADRs) are lightweight, version‑controlled Markdown documents that capture the what, why, and context of each significant architectural choice. They provide knowledge retention, avoid duplicated debates, preserve context, aid onboarding, and support systematic review. By following simple formats, clear lifecycle states, and using tools such as adr-tools, teams can create, store, and manage ADRs effectively, ensuring that every important decision is documented and revisitable.