Documenting software architecture with arc42

Dr. Gernot Starke

arc42 [1] provides everything you ever need to communicate and document your software architecture. It’s tool and technology agnostic, therefore you can use arc42 for arbitrary systems. arc42 is open source and completely free to use.

This article provides a quick overview of arc42 and its parts. For more information, please consult the (rather extensive) documentation [2] available on their documentation website (which, since V8/January 2022, contains several practical examples).

arc42 answers the following two questions in a pragmatic way and can be tailored to your specific needs:

• What should you document/communicate about your architecture?
• How should you document/communicate?

If you work under time or resource constraints, you will most likely skip certain parts of arc42. Our upcoming post on “lean documentation” will give guidance for such cases.

Before we dive in…

• Everything is optional - there is no need to fill in every section of the template. Treat arc42 documentation like the compartments of a cabinet, similar to the image below: The cabinet has a value, even if certain compartments remain empty.

• The order of these compartments is optimized for reading and understandability. You create your content in any order you like or your project requires. For example, in many development projects, the context (section 3) is defined and created first, followed by the top quality requirements (section 1.2).

• arc42 is completely tool agnostic. You might create and maintain arc42 in your tool chain of choice: A wiki, a collection of Office documents, plain Markdown or Asciidoc, one of the commercial UML tools or even LaTeX. Whatever your tool of choice is, arc42 has you covered.

The structure of arc42

arc42 proposes a dozen sections (aka compartments) for your documentation. These are organized top-down to improve understandability.

1. Introduction and goals

Short description of the requirements and driving forces of your system: You should provide an extract or abstract of requirements. Restrict yourself to the top three (max five) quality requirements for the architecture, which have the highest priority for the major stakeholders.

Include a table of important stakeholders with their expectation regarding architecture or documentation.

2. Constraints

Anything that constrains teams in design and implementation decisions, or decision about related processes. Constraints can sometimes go beyond individual systems and might valid for whole organizations and companies (e.g. company-wide technology choices or government regulations). Time and money are common constraints in many organizations.

3. Context and scope

The context delimits your system from its (external) communication partners (neighboring systems and users). It specifies or documents the external interfaces. You should always document the context from a business or domain perspective. If infrastructure or specific hardware plays an important role, you might also show a technical perspective.

4. Solution strategy

Summary of the fundamental decisions and solution strategies that shape the architecture: can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions.

5. Building block view

Usually, boxes and arrows, showing the high-level code structure of the system. To phrase it a little more formal: The building block view explains the static structure of the system and contains, abstractions of source-code. It refines the context view, where the complete system is depicted as a black box.

• Level 1 contains the major subsystems, components or parts of the system. In some cases, this coarse overview provides enough structural overview.
• Level 2 refines one or more elements from level 1: Create a separate white box (plus explanations) for every level-1 building block you would like to explain in detail.

You can drill down to an arbitrary level of detail, but keep in mind the following:

Recommendation Try to stick to level-1, as it often gives enough guidance and understanding for most stakeholders.

6. Runtime view

The runtime view explains the behavior or processing of one or several building blocks. It serves as companion to the static building block view from section 5 above. The runtime view might explain important use cases or features, interactions at critical external interfaces, error and exception behavior.

Recommendation Use runtime scenarios primarily during development to validate or design building block structures. They help to identify missing or unnecessary dependencies. Keep only a small number of scenarios in your documentation.

7. Deployment view

Software needs hardware to execute on, that’s where the deployment view comes into play: It shows the technical infrastructure with environments, computers, processors, networks and network-topologies. In addition, it maps the software building blocks to those infrastructure elements.

8. Cross-cutting concepts

Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architecture patterns and -styles, rules for using specific technology and implementation rules.

9. Architecture decisions

Keep a collection of architecturally significant decisions that are important, expensive, critical, large scale or risky including rationales, that are not recorded elsewhere.

Please use your judgement to decide whether an architectural decision should be documented here or whether you better document it locally (e.g. within the building block view or any cross-cutting concept). You may have already captured the most important decisions of your architecture in the solution strategy.

Recommendation: Use Architecture Decision Records to capture decisions in a simple, structured yet pragmatic way.

10. Quality requirements

Quality requirements, often described as scenarios. You may use a quality tree to provide a high-level overview. The most important quality goals should have been already described in section 1.2. (quality).

As the definition of quality scenarios is very abstract, let’s look at some examples:

11. Risks and technical debt

Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about.

In case somebody reviewed or audited your system, their findings might be included here.

12. Glossary

Important domain and technical terms that stakeholders use when discussing the system. Please include only specific terms - and avoid explaining REST, HTTPS or other words that have common explanations.

In addition, the glossary can serve as the translation reference if you work in a multi-language (international) environment.

Like what you saw?

Give it a try! Document a few of your architecture decisions, sketch your scope and context and explain a few key technical concepts - and you have your first version of your architecture documentation.

Download the template in a format you like. Unpack and start documenting. In case you have questions or want to see examples, consult the extensive documentation site [2].

In case you want to know more, we have you covered:

• I wrote about the principles of technical documentation. That deep-dive article explains the fundamental requirements, your technical documentation needs to fulfill - and many proven approaches how to achieve these.
• Another article on lean documentation is in the making, please stay tuned. Until then, watch the video “Sparsame Dokumentation” (oops, sorry, it’s in German)

Comments or questions?

Leave a comment right below - or open an issue on the arc42 site. Otherwise, thanx for reading this article.

Image of the cabinet by Jan Kolar from Unsplash