# 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](https://arc.fuet.ch/concepts/documentation/arc42-solution-strategy.md)
- [Architectural Decision Record](https://arc.fuet.ch/concepts/forces-decisions/architectural-decision-record.md)
- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md)
- [Architectural Decision](https://arc.fuet.ch/concepts/forces-decisions/architectural-decision.md)
- [Architecture Decision Rationale](https://arc.fuet.ch/concepts/forces-decisions/architecture-decision-rationale.md)
- [Architecturally Significant Decision](https://arc.fuet.ch/concepts/forces-decisions/architecturally-significant-decision.md)
- [Markdown Architectural Decision Records](https://arc.fuet.ch/concepts/forces-decisions/markdown-architectural-decision-records-madr.md)
- [Documentation as Code](https://arc.fuet.ch/concepts/documentation/documentation-as-code.md)

## Sources

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