9. Architecture Decisions¶

Help: Important, expensive, large scale, or risky architecture decisions including rationale. With "decisions" we mean selecting one alternative based on given criteria.

Please use your judgment to decide whether an architectural decision should be documented here or whether it is better to document it in individual building blocks (Section 5). Avoid redundancy. Refer to Section 4 for the most general decisions that already have been captured there.

Motivation: Stakeholders of your system should be able to comprehend and retrace your decisions. You should be able to explain the reasoning behind your decisions to your stakeholders at any time.

Form: Various options: - Architecture Decision Records (ADRs) - recommended format - A decision log in tabular form - References to individual ADR documents (e.g., in a separate /decisions/ folder)

Keep the ADRs up to date, especially their status. A superseded or deprecated decision is valuable context for understanding the current architecture.

Decision Log¶

ADR-001: \<Decision Title>¶

Status¶

\<Proposed | Accepted | Deprecated | Superseded by ADR-XXX>

Date¶

\<YYYY-MM-DD>

Context¶

\<Describe the issue motivating this decision. What is the problem, what forces are at play, and what are the constraints?>

Decision¶

\<Describe the decision that was made. State the decision clearly and concisely.>

Considered Alternatives¶

Consequences¶

\<Describe the resulting context after applying the decision. What becomes easier or more difficult? What are the trade-offs?>

Positive: - \<Positive consequence 1> - \<Positive consequence 2>

Negative: - \<Negative consequence 1> - \<Negative consequence 2>

Risks: - \<Risk 1 and mitigation>

Compliance¶

\<How will adherence to this decision be verified? Automated checks, code review, architecture fitness functions?>

ADR-002: \<Decision Title>¶

Status¶

\<Proposed | Accepted | Deprecated | Superseded by ADR-XXX>

Date¶

\<YYYY-MM-DD>

Context¶

\<Describe the issue motivating this decision.>

Decision¶

\<Describe the decision that was made.>

Considered Alternatives¶

Consequences¶

\<Describe the resulting context after applying the decision.>

Positive: - \<Positive consequence 1>

Negative: - \<Negative consequence 1>

ADR Template (Copy for New Decisions)¶

## ADR-XXX: <Decision Title>

### Status
<Proposed | Accepted | Deprecated | Superseded by ADR-XXX>

### Date
YYYY-MM-DD

### Context
<What is the issue that we're seeing that motivates this decision?>

### Decision
<What is the change that we're proposing and/or doing?>

### Considered Alternatives
| Alternative | Pros | Cons |
|------------|------|------|
| Option A (chosen) | ... | ... |
| Option B | ... | ... |

### Consequences
<What becomes easier or more difficult to do because of this change?>

**Positive:**
- ...

**Negative:**
- ...

### Compliance
<How will this decision be enforced or verified?>

Based on the arc42 architecture template (https://arc42.org).
Created by Dr. Peter Hruschka and Dr. Gernot Starke.
Licensed under CC BY-SA 4.0.