---
name: Sequence Diagram
status: draft
description: PROCESS/STRUCTURE family. The UML sequence diagram — a top-to-bottom script of who messages whom, in what order, across a set of participants over time.
sources:
  - title: Booch, Grady; Rumbaugh, James; Jacobson, Ivar (1999), The Unified Modeling Language User Guide, Addison-Wesley
    url: https://openlibrary.org/works/OL1927706W
  - title: Fowler, Martin (1997), UML Distilled, Addison-Wesley
    url: https://openlibrary.org/works/OL463953W
---

# Sequence Diagram

## Why it matters

A sequence diagram is a picture of an interaction unfolding through time. Each participant — an actor, a service, a component, a department — stands as a column at the top, with a vertical "lifeline" hanging straight down beneath it. Time runs downward, and every message one participant sends another is a horizontal arrow between two lifelines, labelled with what was said. Read top to bottom, the page becomes a script: who called whom, in what order, what came back, and under what conditions. Its whole job is to make the *ordering* of an interaction explicit — the round-trips, the waits, the dependencies that a box-and-line picture of the same system leaves invisible.

For example: a team is debugging a checkout that occasionally double-charges a card. The architecture diagram shows a tidy client, payment service, and bank — no obvious fault. Drawn as a sequence diagram from the actual logs, the bug becomes visible the moment you read down the page: the client sends "charge," the payment service forwards it to the bank, the bank is slow to answer, the client times out and *retries* — and now two "charge" arrows are in flight before the first return arrow ever arrives. The defect was never in any one component. It was in the *order and timing* of the messages between them, which is exactly what the diagram makes you see.

- **What it shows.** A time-ordered conversation between a small set of participants — who sends which message to whom, in what sequence, with which responses, under which conditions.
- **When to reach for it.** An interaction or protocol whose interest lies in its *ordering* and coordination — API call sequences, authentication handshakes, an escalation path — rather than in the participants themselves.
- **How to read it.** Find the participants across the top, then read straight down: each horizontal arrow is the next thing that happens, a solid arrow a call out and a dashed arrow the answer back.
- **What you'd miss without it.** The round-trips and race conditions — the retries-before-replies, the blocking waits, the out-of-order arrivals — that only become visible once messages are pinned to a shared downward timeline.
- **Where it misleads.** It flatters an interaction into one clean linear run; a real system's branches, retries, and parallel paths have to be drawn in explicitly (with combined fragments), or the diagram quietly hides them.

## How to read it

Start across the top. Each **participant** — Client, Browser, Auth Server, Resource Server, or Customer, Agent, Database — is a labelled box, and from each box a thin vertical **lifeline** drops down the page. The participants are usually ordered left to right in reading order: the one that kicks things off on the left, the deepest backend dependency on the right. Nothing about the *space* between lifelines carries meaning — only the vertical axis does, and the vertical axis is **time**, flowing downward. The top of the page is the beginning of the interaction; the bottom is the end.

Now read straight down, like a script. Every **message** is a horizontal arrow from the sender's lifeline to the receiver's, labelled with what is being sent — and the label is the whole point, so it names the actual call and its payload ("POST code + verifier to /token"), not a generic "request." Arrow *style* is vocabulary you read at a glance: a **solid arrowhead** is a call going out, a **dashed arrow** is the return coming back, and an open arrowhead marks an asynchronous "fire-and-forget" that doesn't wait for a reply. A thin **activation bar** — a narrow rectangle laid over a lifeline — shows the stretch of time that participant is busy handling something; nested bars mean a call made while still inside another.

Two things let a sequence diagram show more than a straight line. First, **combined fragments**: boxed regions that wrap part of the conversation and label it — `alt` for either/or branches (consent granted vs denied), `opt` for something that only sometimes happens, `loop` for repetition, `par` for messages that run in parallel. Read the box's label first, then the messages inside it as conditional or repeated. Second, the simple discipline of reading the *gaps*: a long drop on a lifeline between sending a call and getting its dashed return is a wait — a round-trip you're paying for — and two outbound arrows stacked before any return is a sign of overlap or a retry. Read back, a good sequence diagram tells you not just *what* the participants do but the exact order they do it in, where they block, and where the conversation can fork.

## When to use it

The sequence diagram belongs to the **PROCESS / STRUCTURE family** — the diagrams that make a system's behaviour legible — and within it the sequence diagram is the *inter-actor-over-time* member: the one you reach for when the question is "who messages whom, in what order" across several participants. That places it next to a few close relatives, and the boundaries are how you pick the right one:

- A **flowchart** maps the branching logic of *one* process — its steps, decisions, and loops — from a single point of view. Reach for it when the interest is one actor's internal control flow, not a conversation between several.
- A **state diagram** shows the configurations *one* object moves through and the transitions between them, independent of who triggers them. Reach for it when the interesting thing is the state space, not the message order.
- A **C4 architecture diagram** shows static structure — which components exist and how they connect — with no time axis at all. Reach for it to answer "what are the pieces," not "in what order do they talk."

Reach for a sequence diagram when an interaction spans multiple components and its correctness or cost lives in the *ordering*: an API call sequence, an OAuth or login handshake, a service-to-service protocol, a customer-support escalation, a post-incident reconstruction of who-notified-whom-when. Skip it when there is really only one actor (a flowchart is clearer), when the subject is a single object's lifecycle (a state diagram), or when you only need the static wiring (a C4 diagram). And keep it small: a sequence diagram that sprawls to dozens of participants and hundreds of messages is telling you the interaction is too tangled to read as a single sequence — abstract some messages or split it into several.

## How Ora builds it

Ora produces a sequence diagram from a **semantic spec** — a structured description naming the participants (with optional short aliases), the ordered list of messages (each with a sender, a receiver, a label, and a type: synchronous call, asynchronous send, or return), the activation bars (mostly derived automatically from the call-and-return arrows), and any combined fragments (`alt`, `opt`, `par`, `loop`) that wrap conditional or repeated stretches of the conversation. That spec is then **rendered** to a diagram by a sequence-diagram engine (Mermaid or PlantUML), which lays out the lifelines, places each arrow at its point in time, and emits an SVG — paired with a layered text description and keyboard navigation across the messages in temporal order, since the arrows alone are not accessible.

The diagram is the visual face of Ora's process- and protocol-design work: when you ask "walk me through this auth flow as a sequence diagram" or "reconstruct what happened, in order, during the incident," that work names the participants, orders the messages, and surfaces the branches — and this artifact is how it shows the result. Its natural producing contexts are system and protocol design (API call patterns, distributed-system interactions), service design (a customer journey traced through its backend touchpoints), and post-incident analysis (the message order that reveals where a chain broke).

The notation is the work of **Grady Booch, James Rumbaugh, and Ivar Jacobson**, who unified their separate object-oriented methods into the Unified Modeling Language in the mid-1990s and set the sequence diagram out as one of UML's core interaction diagrams in *The Unified Modeling Language User Guide*; Martin Fowler's *UML Distilled* later made the form widely accessible to working developers. UML's sequence diagram descends in turn from the **Message Sequence Charts** standardized for telecommunications-protocol specification, which themselves grew out of the time-sequence diagrams long used to teach how processes talk to one another.

## Related

- **State Diagram** — the PROCESS-family sibling for *one* object's lifecycle: the states it occupies and the transitions between them, where the sequence diagram instead tracks messages between many participants over time.
- **Flowchart** — the single-actor view: the branching steps and decisions inside one process, where the sequence diagram shows the conversation *between* processes.
- **C4 Architecture Diagram** — the static-structure counterpart: which components exist and how they connect, with no time axis — the still photograph to the sequence diagram's script.
- **Process Mapping** (mode) — the analytical operation that inventories actors, orders steps, and traces handoffs and dependencies, which this diagram renders as a time-ordered interaction.

## Sources

- [Booch, Grady; Rumbaugh, James; Jacobson, Ivar (1999), The Unified Modeling Language User Guide, Addison-Wesley](https://openlibrary.org/works/OL1927706W)
- [Fowler, Martin (1997), UML Distilled, Addison-Wesley](https://openlibrary.org/works/OL463953W)