Skip to content
Software Architecture Guide

Matching Diagram Type to System Aspect

Explanation

Section titled “Explanation”

A system has several aspects. Its parts and their structure are one aspect. How it behaves at runtime is another. Where it runs is a third. Each aspect needs a diagram type that suits it, so the choice follows the question you want to answer.

The arc42 template (see the article “arc42 Architecture Documentation Template”) gives each aspect its own view.

  • Static structure. The building block view shows how the system breaks down into building blocks.
  • Runtime behavior. arc42 keeps this separate from static structure. Several notations fit: lists, activity diagrams, sequence diagrams, BPMN and state machines. You pick the one that suits the scenario. arc42 recommends sequence diagrams for runtime scenarios. Choose scenarios by architectural relevance. A representative selection is enough. You do not need to cover everything.
  • Infrastructure. The deployment view can use UML deployment diagrams. Other notations are also fine if they show the infrastructure nodes and the channels between them. The audience and the aspect decide.

The C4 model follows the same idea. Its core diagrams are static structure diagrams at several levels of abstraction: context, containers, components and code. For other aspects it adds supporting diagram types: landscape, dynamic and deployment. C4 also says you need not draw every level. Draw only the diagrams that add value.

Before drawing, ask two questions. What aspect do I want to show? Who will read it? Then choose the diagram type that fits both.

Example

Section titled “Example”

A team documents an online shop. For the parts of the system and how they relate, they draw a diagram of the main building blocks. For the checkout flow, they draw a sequence diagram of which part calls which, and in what order. For the servers and networks, they draw a deployment diagram. Each diagram answers one question, and none tries to answer all three.

Trade-offs

Section titled “Trade-offs”

Several diagrams cover more aspects, but they cost more effort to draw and keep up to date. That is why both arc42 and C4 favor a selection. arc42 asks for representative runtime scenarios, not all of them. C4 asks for only the diagrams that add value. Flexible notation, as in the deployment view, also helps audiences that do not know UML. It works only if the diagram still shows the required elements, such as nodes and channels.

Each system aspect maps to its own view and a fitting diagram type.

Diagram source 
flowchart LR
  A[Static structure] --> B[Building block view]
  C[Runtime behavior] --> D[Runtime view]
  E[Infrastructure] --> F[Deployment view]
  B --> G[Structural diagram]
  D --> H[Sequence, activity or state diagram]
  F --> I[Deployment diagram]

Checks

Section titled “Checks”
  • Static structure is shown in the building block view, separate from runtime behavior.
  • Runtime scenarios are chosen for architectural relevance, and each uses a notation that fits it, such as a sequence diagram.
  • The deployment view shows infrastructure nodes and channels, whether in a UML deployment diagram or another notation.
  • Only diagrams that add value are included, not every possible diagram type or level.
Section titled “Related”

Sources

Section titled “Sources”