Reading Architecture Diagrams: C4, Sequence and State

Objectives

By the end of the lesson, you can decide what question an architecture diagram answers, recognise the levels of the C4 model, and interpret sequence and state diagrams.

Why is one diagram not enough?

A diagram always answers one question. If users, modules, database tables and server instances are put on the same drawing, the reader does not know at what level to interpret the arrows. The diagrams of this course therefore always name which view they show (see 1.1).

The C4 model

The C4 model provides views that can be zoomed into one another; the four levels are Context, Container, Component and Code.

Level	What does it show?	Who is it useful for?
Context	The system as a single box, with users and external systems	Everyone
Container	The runnable units: applications, data stores	Developers, operators
Component	The internal responsibilities of a container	Those working on that unit
Code	Classes, interfaces	Only when a solution must be understood

In C4, a container means an application or a data store; not necessarily a Docker container. Of the levels, only those needed for the question should be used.

flowchart LR
  U["User"] -->|"uses"| S["The system under study"]
  S -->|"sends a request"| X["External system"]

The diagram is a C4-style Context view in generic Mermaid notation; the boxes are not official C4 icons, the level is given by the title and the label.

Sequence diagram

A sequence diagram shows the messages of the cooperating participants in time order: the vertical lines are the participants, time runs from top to bottom. It explains who communicates with whom and in what order. The times are not to scale: the distance of two arrows does not mean a measured latency.

sequenceDiagram
  participant K as Client
  participant S as Service
  K->>S: Request
  alt Success
    S-->>K: Result
  else Failure
    S-->>K: Error signal
  end

alt marks an alternative path. A solid arrow means a request, a dashed one a response; a response must not be read as success.

State diagram

A state diagram shows the possible states of a single element and the transitions between them. It tells what is allowed when the element is in a given state.

stateDiagram-v2
  [*] --> Waiting
  Waiting --> Running: picked up
  Running --> Done: success
  Running --> Failed: final failure
  Done --> [*]

The two diagrams complement each other: the sequence shows the communication, the state diagram the consequence. A missing transition does not mean that such a message cannot arrive in reality; late or repeated messages must also be handled.

Checking a diagram

Three questions help when reading: which view am I looking at, what do the arrows mean (direction, initiator, synchronous or asynchronous), and what was left out. An arrow that only says "connects to" does not tell who initiates and what it asks for.

Common misconceptions

Statement	Clarification
"A C4 container is a Docker container."	It means a runnable application or data store.
"A sequence diagram also shows a time scale."	It shows only order; time must be given separately.
"If there is no such arrow on the diagram, it cannot happen."	In reality, late or repeated messages not on the diagram may arrive.
"One good diagram is enough to describe the system."	Every diagram answers one question; several views are needed.

In short

• A diagram answers one question and must name its view.
• The four C4 levels: Context, Container, Component, Code.
• The sequence diagram shows order, the state diagram shows the life cycle.
• The meaning of the arrow must always be given.

Review questions

1. Which C4 level would you use for an overview meant for an external partner, and which to explain the internal structure?
2. What does a sequence diagram not show?
3. Why is the label "connects to" not enough on an arrow?

Learning resources

• C4 model: diagrams — the official description of the four levels and the supplementary views.
• Mermaid documentation — the diagram notation used in the course.