Skip to content
Software Architecture Guide

arc42 Architecture Documentation Template

Explanation

Section titled “Explanation”

arc42 is a template for documenting software architecture. It answers one question: where does each piece of architecture information belong? It does not prescribe how a team works. The method is process-agnostic, so it fits agile, lean or formal projects. It sets no fixed order of activities.

Twelve sections. The template has twelve sections. Each has a clear purpose, and teams can tailor them to their needs. The official documentation site follows the same twelve sections. It promotes lightweight documentation for agile environments.

The sections are:

  1. Introduction and Goals
  2. Architecture Constraints
  3. Context and Scope
  4. Solution Strategy
  5. Building Block View
  6. Runtime View
  7. Deployment View
  8. Cross-cutting Concepts
  9. Architecture Decisions
  10. Quality Requirements
  11. Risks and Technical Debts
  12. Glossary

Building block view. This section is a hierarchy of black boxes and white boxes. A black box shows what a part does without showing its inside. A white box opens it up. Level 1 is the white box of the whole system. The view abstracts the structure of the source code. Stakeholders can then discuss that structure without implementation details.

Runtime view. This section shows how building blocks do their job and communicate while the system runs. It uses scenarios. Authors choose scenarios for their architectural relevance. A large number is not needed.

Open source. arc42 is free, including for commercial use. A GitHub repository holds the AsciiDoc source of the template. Releases include all languages, styles and formats, plus a manifest of checksums. The founders maintain the English and German versions.

Relation to C4. The arc42 FAQ says the C4 model overlaps with some arc42 sections. It also omits parts such as quality requirements, crosscutting concepts and risks. See the article on the C4 Model.

Example

Section titled “Example”

A small team starts a new product. They create one document from the template. They describe the system as one white box with three black boxes inside. They add two runtime scenarios for the most important workflows. They tailor the template by leaving out what nobody needs. Later, a new colleague reads the document and finds each topic in the expected section.

Trade-offs

Section titled “Trade-offs”

The template says where information belongs, not how to work. Teams must decide on their own process and order of writing. The C4 model is not a full replacement. According to the FAQ, it omits parts that arc42 covers.

Checks

Section titled “Checks”
  • The architecture documentation is organized by the twelve arc42 sections, tailored to the project’s needs.
  • The building block view is a hierarchy of black boxes and white boxes, with level 1 as the white box of the whole system.
  • The runtime view uses scenarios chosen for architectural relevance, not a large number of scenarios.
Section titled “Related”

Sources

Section titled “Sources”