arc42 Architecture Decisions

In short

Section 9 of arc42 records important, expensive, large-scale or risky architecture decisions with their reasons. It points back to section 4 for the most fundamental decisions instead of repeating them.

Explanation

Section 9 of the arc42 template (see the article “arc42 Architecture Documentation Template”) is the place for architecture decisions. An architecture decision is a choice that shapes how a system is built. You record the choice together with its rationale, meaning the reasons behind it.

Which decisions belong here

Section 9 covers decisions that are important, expensive, large in scale or risky. Small, easy-to-change choices do not need an entry.

Relation to section 4

Section 4, Solution Strategy (see the article “Solution Strategy”), already summarizes the fundamental decisions that shape the architecture. Section 9 does not repeat them. It refers back to section 4 instead.

Strategy decisions are cornerstones. Many more detailed decisions or implementation rules build on them. Section 9 can cover those follow-on decisions. Section 4 stays short, but each key decision there still carries its reasons.

Format

Section 9 can be a simple list or table of decisions. It can also hold one Architectural Decision Record (ADR) per decision. An ADR captures a single decision and its rationale. Michael Nygard’s 2011 blog post popularized the idea. See “Architectural Decision Record” for details.

Example

A team builds an online shop. Section 4 states the fundamental choice: one deployable application, kept simple for a small team, with short reasons.

Later the team makes a more detailed choice: use a managed payment provider instead of building payment handling. This is costly to reverse and risky. It does not appear in section 4, so section 9 records it. The entry gives the decision and the reasons. It also refers back to section 4 for the overall strategy.

Trade-offs

Recording a decision takes effort, so record only the important, expensive, large-scale or risky ones. Repeating section 4 content in section 9 creates duplication. Linking back to section 4 avoids it.

Checks

• Each entry in section 9 states the decision together with its rationale.
• Section 9 refers to section 4 instead of repeating the fundamental decisions.
• Decisions in section 4 are short but give reasons.
• Where ADRs are used, each ADR covers a single decision.

Related

• Solution Strategy
• Architectural Decision Record
• arc42 Architecture Documentation Template
• Architectural Decision
• Architecture Decision Rationale
• Architecturally Significant Decision
• Markdown Architectural Decision Records
• Documentation as Code

Sources

• 9 - Architecture decisions | arc42 Documentation — docs.arc42.org, accessed 2026-11-09
• 4 - Solution strategy | arc42 Documentation — docs.arc42.org, accessed 2026-11-09
• Architectural Decision Records (ADRs) | Architectural Decision Records — adr.github.io, accessed 2026-11-09