# Component View Refinement Levels

**In short:** A building block view is built in levels. Each level zooms into chosen blocks of the level above. Only important, risky, complex or volatile blocks get refined. Simple or standard parts are left out.

## 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

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

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.

```mermaid
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

- 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.

## Related

- [Component View](https://arc.fuet.ch/concepts/documentation/component-view.md)
- [Nested Components and Subsystems](https://arc.fuet.ch/concepts/modeling-uml/nested-components-and-subsystems.md)
- [C4 Model](https://arc.fuet.ch/concepts/documentation/c4-model.md)
- [Container Diagram (C4 Level 2)](https://arc.fuet.ch/concepts/documentation/c4-container-diagram.md)
- [C4 Component Diagram](https://arc.fuet.ch/concepts/documentation/c4-level-3-component-diagram.md)
- [arc42 Architecture Documentation Template](https://arc.fuet.ch/concepts/documentation/arc42-documentation-template.md)
- [UML Component Diagram](https://arc.fuet.ch/concepts/modeling-uml/uml-component-diagram.md)
- [Package Diagram](https://arc.fuet.ch/concepts/modeling-uml/package-diagram.md)

## Sources

- [5 - Building block view | arc42 Documentation](https://docs.arc42.org/section-5/) — docs.arc42.org, accessed 2026-11-09
- [Home | C4 model](https://c4model.com/) — c4model.com, accessed 2026-11-09