7.1 The arc42 Template

arc42 is the de-facto standard template for architecture documentation, recommended by iSAQB and widely used in Europe and beyond. It provides a proven structure of 12 sections that covers everything from goals to deployment to risks.

The beauty of arc42 is that you don't have to fill every section for every project. Use what's relevant. A small project might only need sections 1, 3, 5, and 8. A complex enterprise system might use all 12 in depth.

📐 arc42 Template 1 Introduction and Goals What are we building, for whom, and why? Quality goals, key stakeholders. 2 Architecture Constraints Technical, organizational, and political constraints we must respect. 3 System Scope and Context Business context + technical context. Who/what interacts with our system? 4 Solution Strategy Fundamental technology and architecture decisions. The "why" behind the approach. 5 Building Block View Static decomposition into levels. The backbone of the documentation. 6 Runtime View Key scenarios showing dynamic behavior. Sequence/activity diagrams. 7 Deployment View Infrastructure, nodes, network. How and where the system runs. 8 Cross-cutting Concepts Logging, security, error handling, persistence strategies, etc. 9 Architecture Decisions (ADRs) Significant decisions with context, reasoning, and consequences. 10 Quality Requirements Quality tree and quality scenarios — making quality goals concrete. 11 Risks and Technical Debt Known risks with probability and impact. Tracked technical debt. 12 Glossary
Know all 12 sections of arc42 and their purpose. The exam may ask "which section would you use to document X?"

7.2 Architecture Decision Records (ADRs)

An ADR captures a single architecturally significant decision — the context, the decision itself, and its consequences. ADRs are one of the most valuable documentation practices because they capture why a decision was made, not just what was decided.

Without ADRs, future team members (including future-you) will encounter code or architecture choices and wonder "why was this done this way?" — and may change it, breaking things that were working for good reasons.

SectionContent
TitleShort descriptive name: "ADR-007: Use PostgreSQL for the Order Service"
StatusProposed → Accepted → Deprecated → Superseded by ADR-XXX
ContextThe situation and forces at play. What problem needs solving? What constraints exist?
DecisionWhat was decided, stated clearly and concisely.
ConsequencesBoth positive and negative outcomes of this decision. Be honest about trade-offs.
AlternativesWhat other options were considered and why they were rejected.

7.3 Notations — UML and Beyond

The iSAQB curriculum emphasizes that UML is not mandatory. What matters is that your notation is consistent and includes a legend. That said, you should understand the most common UML diagram types.

Key UML Diagram Types

DiagramTypeShowsWhen to Use
ComponentStructuralComponents, interfaces, dependenciesBuilding block view
DeploymentStructuralNodes, artifacts, infrastructureDeployment view
SequenceBehavioralObject interactions over timeRuntime view — most common
ClassStructuralClasses, attributes, relationshipsDetailed design of critical components
ActivityBehavioralWorkflow / process flowComplex business processes
Use CaseBehavioralSystem features from user perspectiveRequirements overview

Key UML Relationships

A B Association (knows about) A B Dependency (uses / depends on) A B Generalization (A inherits B) A B Realization (A implements B) A B Composition (A owns B — B dies with A) A B Aggregation (A has B — B can exist alone) Multiplicity: 1 | 0..1 | * (0..*) | 1..*
The notation matters less than the content. A clear, informal box-and-arrow diagram with a legend is better than a technically perfect UML diagram that nobody understands. Consistency and clarity are what matter.

Documentation Anti-Patterns

  • "The Shelfware" — A 200-page Word document that was written once and never read. Nobody knows if it's still accurate.
  • "The Absence" — No documentation at all. Knowledge lives only in people's heads — and they leave.
  • "The Screenshot Graveyard" — Paste screenshots of code and call it documentation. Outdated the moment it's created.
  • "Over-documentation" — Documenting obvious things while ignoring important decisions. If the code already says it clearly, don't document it.

The sweet spot: Document decisions (why), constraints (what you can't change), interfaces (how things connect), and risks (what might go wrong). Skip obvious implementation details.

← Architecture Views Quality →