Skip to main content

Sequence Diagrams, C4 Model, and When a Picture Pays for Itself

What This Concept Is​

Diagrams are not decoration. They are compressed language. Good diagrams earn their space by answering a question a paragraph cannot answer cleanly. Two formats carry most of the weight in day-to-day design work:

  • Sequence diagrams -- time flowing top-to-bottom, participants across the top, messages as arrows. Answers "who calls whom, and in what order, under this scenario?"
  • C4 model -- a four-level zoom (System Context -> Container -> Component -> Code). Answers "where does this piece fit, at what altitude am I looking?"

Other formats (class diagrams, ER diagrams, state machines, flow charts) each have their niche. The skill is picking the one that actually answers the question.

Why It Matters Here​

Most engineering misunderstandings are not about what each piece does. They are about how the pieces interact or at what altitude you are zoomed in. Sequence and C4 diagrams target exactly those two miscommunications. A one-screen diagram in a design doc saves three rounds of review comments.

At the same time, there is a strong norm against diagram-for-show. A class diagram with 40 boxes communicates nothing. A sequence diagram covering the happy path and silently omitting failure paths is misleading. The rule is budget: one diagram per question, at the altitude that answers it.

Concrete Example​

Sequence diagram (Mermaid) for a "redeem promo code" flow:

C4 container diagram (Mermaid, simplified) for the same system:

The first diagram answers "what is the message order during promo redemption?" The second answers "what services exist and how do they connect?" Neither tries to do both.

Common Confusion / Misconception​

"Class diagrams for everything." Class diagrams age badly, get out of sync with code, and rarely answer a real question in a design doc. Prefer a sequence diagram (interaction) or C4 container diagram (structure) unless you are specifically reasoning about inheritance or type relationships.

"One diagram to rule them all." One giant diagram that mixes structure, interaction, and data flow is harder to read than three focused ones.

"Diagrams as proof of work." Reviewers sometimes add diagrams to look thorough. A three-participant sequence diagram where everything is trivially in-process is waste. No diagram is better than a misleading one.

"Mermaid vs drawing tool." Mermaid is preferred for design docs and ADRs because it lives in the repo, diffs reasonably, and updates with code. Use higher-fidelity tools only for presentations.

"C4 is heavy." C4 is actually lightweight -- most teams only use Context and Container levels, which takes minutes. "Component" and "Code" levels are rare and usually unnecessary.

How To Use It​

Budget one diagram per question. Before drawing:

  1. Write the question the diagram answers in one sentence.
  2. Pick the format that answers that question (sequence for when, C4 for where, state chart for lifecycle, ER for data).
  3. Include the failure path if a sequence diagram covers a user-facing flow.
  4. Include legend only when your icons / arrows differ from what readers will assume.

For C4, stop at the level that answers the question. In most design docs, the Container level is enough -- the Code level is a waste if the code is already readable.

Check Yourself​

  1. Which diagram type answers "who calls whom in what order?"
  2. Why does a sequence diagram of only the happy path mislead?
  3. When is no diagram the right choice?

Mini Drill or Application​

For each scenario, pick a diagram type and sketch one:

  1. explaining a new service's place in an existing system to a new hire
  2. showing how a promo redemption handles a partial failure (DB commit but webhook fails)
  3. documenting the lifecycle of an order (created -> paid -> shipped -> delivered -> refunded)
  4. describing how three components inside one service collaborate

Read This Only If Stuck​