Architecture & structure · Documentation template
arc42
Document architecture through a coherent set of questions about context, structure, behavior, quality, and risk.
What it helps you do
Keep the information needed to understand and evaluate an architecture in a predictable, maintainable structure.
Starting knowledge: No specialist knowledge is required.
- State goals, quality priorities, and constraints before explaining a solution.
- Connect context, building blocks, runtime, and deployment views.
- Record decisions, risks, and a shared glossary rather than hiding them behind diagrams.
The problem it came from
Gernot Starke and Peter Hruschka developed arc42 as a pragmatic architecture-documentation template. The official overview describes twelve sections and notes use since 2005.
Its organization brings several architectural views and decisions together. It does not require a particular diagramming product or a large document for every system.
Work through an example
Goals: new readers can trace document access.
Constraint: work offline during a network outage.
Building blocks: local cache and synchronization service.
Runtime: read locally, then reconcile changes.
Decision: conflict handling follows an explicit rule.
Risk: concurrent edits need further validation.- Quality claims become questions that require evidence.
- The runtime view adds behavior to the structure.
- The unresolved risk remains visible.
Where it helps. Where it stops.
Use it when
- A maintained system needs a usable architecture reference.
- Several diagrams exist but their rationale, assumptions, and quality goals are scattered.
Potential benefits
- A shared structure can reveal missing information.
- Linking decisions and risks helps explain why the architecture has its current shape.
Limits and common mistakes
- Filling every heading with generic prose creates documentation without insight.
- A completed template does not establish that quality goals are met.
The prompt below asks for this structure. It does not guarantee accuracy, complete coverage, better learning, or conformance to a standard. Treat those outcomes as separate checks.
Practise the judgment
Try a choice, inspect a boundary, then explain a case yourself. Hints and answers are available whenever you need them.
Where should “must work during a network outage” first influence the document?
Hint
Architecture follows constraints.
Explained answer
Best answer for this case: Goals and constraints
The requirement should shape the solution and its quality scenarios, not appear as a decorative claim afterward.
Does filling all twelve sections establish a good architecture?
Hint
A template is a structure for inquiry.
Explained answer
Best answer for this case: No; the content and supporting evidence still matter
Coverage of headings is different from adequacy of the design or its evidence.
Turn “fast enough” into a quality scenario without inventing numbers.
Hint
Which missing parameter prevents a meaningful check?
Explained answer & self-review rubric
Identify the user action, operating conditions, measurable response, and agreed limit. Leave the limit unresolved until stakeholders supply or approve it, then test under the stated load.
- Name action and conditions
- Specify a measurable response
- Do not invent acceptance thresholds
Take it into your own work
Manual template
Use this structure yourself, with a colleague, or in your preferred writing tool.
# Architecture brief
Goals and quality priorities:
Constraints:
Context and scope:
Solution strategy:
Building blocks:
Runtime scenarios:
Deployment:
Cross-cutting concepts:
Decisions:
Quality scenarios:
Risks and technical debt:
Glossary:
Review the result
- Do the views describe the same system?
- Can a reader trace a quality goal to a scenario?
- Are consequential decisions and risks recorded?
Use this approach with your own AI tool
Help me apply arc42 to the material below.
Reader and existing knowledge: [describe]
Task and desired outcome: [describe]
Use these principles: State goals, quality priorities, and constraints before explaining a solution.; Connect context, building blocks, runtime, and deployment views.; Record decisions, risks, and a shared glossary rather than hiding them behind diagrams..
Preserve source facts, identifiers, quantities, conditions, exceptions, and uncertainty.
Separate supplied facts from assumptions. Ask for missing information instead of inventing it.
Explain your representation choices and provide a review checklist. Do not claim formal compliance or correctness from formatting alone.
Material: [paste only information you are permitted to share]Go to the source
History and the underlying approach are grounded in these references. Examples, prompts, and practice cases here are original educational adaptations. Edition-specific details should be checked against the referenced publication.
Last editorial review: 2026-10-24. An overview is not certification, and this guide is not a reproduction of a standard.