Skip to content
Software Architecture Guide

Architecture Level

Explanation

Section titled “Explanation”

An architecture level is a degree of detail. You start with the whole system and move step by step toward its inner parts.

arc42 shows this in its building block view (see the article on the arc42 Architecture Documentation Template). A building block is a part of the system, such as a component or subsystem. The view is hierarchical:

  • Level 1 shows the overall system split into its main building blocks.
  • Level 2 zooms into some of the level 1 blocks and shows their insides.
  • Level 3 zooms into some of the level 2 blocks, and so on.

Each level adds detail to selected blocks of the level above. The hierarchy can continue as deep as needed, so levels can be subdivided further.

You do not have to zoom into every block. arc42 advises describing only the blocks that matter. These are blocks that are important, surprising, risky, complex or volatile (likely to change). Simple, stable blocks can stay at the higher level.

Example

Section titled “Example”

A team documents an online shop. Level 1 shows a few large blocks: storefront, orders, payments and catalog. Payments is risky and complex, so level 2 zooms into it and shows its inner parts. One of those parts is especially tricky, so level 3 zooms into it. The catalog is simple and stable, so it gets no lower-level description.

Trade-offs

Section titled “Trade-offs”

Zooming deeper gives more detail but adds more documentation to write and keep current. Limiting the zoom to important, risky, complex or volatile blocks keeps the effort focused. The cost is that unzoomed blocks stay described only at a high level.

Each level zooms into selected blocks of the level above.

Diagram source 
flowchart TD
  A[Level 1: whole system and its main blocks] --> B[Level 2: zoom into selected level 1 blocks]
  B --> C[Level 3: zoom into selected level 2 blocks]
  C --> D[Further levels where needed]

Checks

Section titled “Checks”
  • Each deeper level of the building block view zooms into selected blocks of the level above.
  • The hierarchy continues to further levels only where details of a block need describing.
  • Blocks chosen for a lower-level description are important, risky, complex or volatile; other blocks are not forced to have one.
Section titled “Related”

Sources

Section titled “Sources”