Skip to content
Software Architecture Guide

Runtime View Antipattern: Code-Level Activity Diagram

Explanation

Section titled “Explanation”

A runtime view shows how a system behaves while it runs. It describes how the system fulfills a task and which building blocks take part (see the article Runtime View).

The antipattern appears when someone draws a detailed activity diagram of one code execution. Typical signs are notes that name code packages or scripts, and steps such as parallel checks of a mainframe, a database and a satellite link.

Why this is a problem

  • Detailed scenarios amount to visualizing a single code execution. Developers look in the source code for details anyway, so they rarely need such diagrams.
  • The diagram does not answer the questions that matter at the architecture level. It does not show which building blocks are involved or which responsibility each one carries.
  • arc42 advises documenting details with caution, and only if stakeholders really need them.

What to do instead

  • Choose scenarios by architectural relevance. A small, representative selection beats many scenarios.
  • Write schematic scenarios. They refer to higher-level building blocks, not to code-level elements.
  • Map building blocks to activities. This assigns responsibilities to the building blocks.
  • Pick a notation that fits. arc42 lists numbered steps, activity diagrams, sequence diagrams, BPMN and state machines.
  • If you use an activity diagram, use swimlanes. They group activities by actor or building block instead of listing code internals.
  • The arc42 FAQ also suggests a numbered list that names the building block doing each step, or a sequence diagram that maps building blocks to their actions.

Example

Section titled “Example”

A team documents a “system health check” scenario. The first draft is an activity diagram with three parallel branches and notes naming a code package and a script. A reader learns what the code does, but not which building block owns the check.

The team redraws it as a numbered list. Step 1: the Monitor block asks the Gateway block for status. Step 2: the Gateway block asks each connected system. Step 3: the Monitor block reports the result. Now the reader sees who collaborates and who is responsible.

Trade-offs

Section titled “Trade-offs”

Schematic scenarios leave out detail. That is usually fine, because developers read the source code for specifics. When stakeholders really need a detailed scenario, arc42 allows one, but only with caution. Each detailed diagram also has to be kept up to date next to the code it describes.

Checks

Section titled “Checks”
  • Each runtime scenario was chosen for its architectural relevance, and the set is a representative selection.
  • Scenarios refer to building blocks, not to code-level elements such as package or script names.
  • Each scenario assigns activities to building blocks, so responsibilities are visible.
  • Activity diagrams use swimlanes for actors or building blocks.
  • Detailed single-execution scenarios exist only where stakeholders need them.
Section titled “Related”

Sources

Section titled “Sources”