Skip to content
Software Architecture Guide

Component View

Explanation

Section titled “Explanation”

A component view describes the internal structure of a system. It helps readers keep an overview of the source code by looking at it through abstraction instead of file by file.

In arc42, this view is called the building block view. It is a mandatory part of the template. See the article arc42 Architecture Documentation Template for the full chapter list.

Black boxes and white boxes

The view is a hierarchy of black boxes and white boxes, each with a description. A black box shows a building block from the outside. A white box opens it up and shows the blocks inside.

Refinement level by level

The view starts with a coarse picture. You then zoom into selected blocks, one level at a time. Level 3, for example, zooms into details of selected blocks from level 2. This continues as far as it is useful.

In C4

The C4 Model also has component diagrams. They are optional. You create them only when they add value. See the article C4 Component Diagram for details.

Example

Section titled “Example”

A team documents an online shop. Level 1 treats the shop as one black box. Level 2 opens it as a white box with three blocks: catalog, orders and payments. The team then zooms into “orders” only, because it is the most complex part. That gives level 3. They leave “catalog” and “payments” as black boxes.

Trade-offs

Section titled “Trade-offs”

Zooming into selected blocks, not every block, keeps the view readable. In C4, component diagrams are optional for the same reason: create them only when they add value.

Refinement from a black box to selected inner blocks.

Diagram source 
flowchart TD
  L1[Level 1: Shop as black box] --> L2[Level 2: white box with Catalog, Orders, Payments]
  L2 --> L3[Level 3: zoom into Orders only]

Checks

Section titled “Checks”
  • The architecture document contains a building block view, since it is mandatory in arc42.
  • The building block view is organized as a hierarchy of black boxes and white boxes, each with a description.
  • Deeper levels zoom only into selected building blocks of the level above.
  • C4 component diagrams exist only where they add value.
Section titled “Related”

Sources

Section titled “Sources”