More than a template

The arc42 method

arc42 is best known as a documentation template. It is also an opinionated method: six recurring, interrelated activities that keep your architecture, your code and your stakeholders in sync, in agile, lean or formal projects alike.

The template answers where architecture information belongs; the method answers how you work to produce it. And arc42 does take a position on the how: six core activities, with no fixed order and highly interrelated, so the results of any one refine the others in the next increment.

Along the way it takes clear stances: clarify the most important quality requirements before anything else, structure the system along its domain (domain-driven), and choose the crosscutting concepts that actually make those quality goals achievable (quality-driven architecture).

The arc42 method: six activities and their relations Six numbered activity boxes connected by double-headed arrows; each box links to its description below. One stakeholder group at the upper left exchanges with both clarify requirements and communicate and document. Design structures and design cross-cutting concepts overlap in the middle: structural decisions and concepts influence each other directly. Below: communicate and document, accompany the implementation, and analyze and evaluate, which feeds back into clarifying requirements. Clarify requirements 1 Design cross- cutting concepts 3 Design structures 2 Communicate and document 4 Accompany the implementation 5 Analyze and evaluate 6 Stakeholders
The six activities and how they feed each other. Structures and cross-cutting concepts overlap: neither can be designed without the other. Click an activity to jump to its description.

1 · Clarify requirements

Development teams need a robust foundation of goals, requirements and constraints to make targeted decisions. Software architects contribute decisively here: by questioning quality requirements, categorizing functional requirements, and identifying technical risks.

Back to the diagram

2 · Design structures

Building a system out of smaller parts is one of the fundamental tasks of architecture and development. arc42 calls these parts building blocks, deliberately technology-neutral. This task produces the static Building Block View, its dynamic counterpart, the Runtime View, and the interfaces that connect building blocks with each other and with the outside world.

Back to the diagram

3 · Design cross-cutting concepts

Some decisions affect single building blocks; others cut across the whole system: the choice of base technology and infrastructure, the frameworks and libraries in use, recurring architecture or design patterns, or the approach to build, deployment, test and release. arc42 calls these cross-cutting concepts. A small sample of questions such concepts answer:

  • How is the user interface structured and implemented, and with which libraries or patterns?
  • How and where is persistent data stored, distributed and read, and with which databases?
  • How are business, validation and plausibility rules implemented?
  • How do the system and its building blocks handle errors and exceptions?
  • How does the system handle logging and monitoring?

Back to the diagram

4 · Communicate and document

Coordinate architecture and design decisions with the relevant stakeholders, solicit their feedback, and incorporate it where appropriate. Communicate intensively in person, especially with and within the development team. Put decisions in writing as sparingly as possible, because written documentation creates maintenance effort for every future change. How much you write down depends on your industry, the type of system, its criticality and risk. The arc42 template supports both extremes: very sparse and very thorough documentation.

Back to the diagram

5 · Accompany the implementation

Good design discussions are not enough: deviations from agreed (or even documented) decisions can creep into the source code, on purpose or by accident. Work with your team to ensure the code implements the intended structures and concepts, which means actually looking into the source code (code reviews) and comparing the implementation against the target.

This works in both directions. Sometimes individual developers have better ideas than the original design: find these gold pieces and make them part of the architecture. In other cases, developers misunderstand a decision or concept; then coach, explain, or help with the implementation. In larger teams nobody can review all code. Tools can help, but for critical parts of the system, people should review, since only they can ask for reasons and judge them in context. Inspecting small, well-chosen parts of the code usually keeps the effort reasonable.

Back to the diagram

6 · Analyze and evaluate

Ask yourself at regular intervals whether your decisions and concepts still achieve the desired effect from today’s perspective. This simple feedback loop is the basis of every iterative process: deciding and acting without reflection easily leads to missed goals and actionism. A methodical look in the rear-view mirror either confirms your decisions (great, move on!) or reveals weaknesses and risks early enough to plan appropriate improvements.

Back to the diagram

Put the method to work

Six activities, one template, twenty years of practice. Start with the download; the method comes built in.

Download arc42 Explore the template Learn it in a workshop