Skip to content
Software Architecture Guide

Component View Refinement Levels

Explanation

Section titled “Explanation”

The arc42 building block view is not one diagram. It is a hierarchy of black boxes and white boxes. A black box shows what a block does from the outside. A white box opens the block and shows its inner parts. (See the Component View and Nested Components and Subsystems articles for the building blocks themselves.)

How the levels work

  • Level 1 is the first breakdown of the system into blocks.
  • Level 2 zooms into selected blocks of level 1.
  • Level 3 zooms into selected blocks of level 2.
  • This continues as deep as it is useful.

The word “selected” matters. You do not open every block at every level. Each deeper level covers only the blocks that need more explanation.

How deep to go

Relevance beats completeness. Refine a block when it is important, risky, complex or volatile. “Volatile” means likely to change. Leave out the normal, simple, boring or standardized parts. Readers then spend their time on the parts that matter.

Comparison with C4

The C4 model uses the same idea of zooming. It defines a set of hierarchical diagrams: system context, containers, components and code. Each diagram sits one step closer to the details. See the C4 Model article for more.

Example

Section titled “Example”

A team documents an online shop. Level 1 shows a few main blocks, such as catalog, ordering, payment and a standard login component. Ordering is complex and changes often, so level 2 opens it and shows its inner parts. One of those parts is risky, so level 3 opens it too. Catalog, payment and the standard login stay as black boxes. The team does not draw them in more detail.

Trade-offs

Section titled “Trade-offs”

Refining only some blocks keeps the documentation short and focused. The cost is that some blocks stay unexplained. Readers must trust that the skipped parts are simple or standardized. Deciding what counts as important, risky, complex or volatile takes judgment.

Each level zooms into selected blocks of the level above.

Diagram source 
flowchart TD
  L1[Level 1: all main blocks]
  A[Selected block A]
  B[Other blocks: stay black boxes]
  L2[Level 2: inside block A]
  C[Selected part of A]
  L3[Level 3: inside that part]
  L1 --> A
  L1 --> B
  A --> L2
  L2 --> C
  C --> L3

Checks

Section titled “Checks”
  • The building block view is a hierarchy of black boxes and white boxes, not a single diagram.
  • Each deeper level zooms into selected blocks of the level above, not into every block.
  • Refined blocks are the important, risky, complex or volatile ones.
  • Simple or standardized parts are left out of the refinement.
Section titled “Related”

Sources

Section titled “Sources”