Sequence Diagrams: How to Read and Create Them

What Is a Sequence Diagram and When Should You Use One?

A sequence diagram is a UML behavior diagram that shows participants — services, browsers, databases, queues — as columns across the top, with time flowing downward and messages drawn as horizontal arrows between them. Where a flowchart shows the decision logic inside one component, a sequence diagram shows the conversation between components: who calls whom, in what order, and what comes back. That makes it the natural format for anything involving more than two systems, which in a microservices world is nearly everything.

Reach for a sequence diagram when you are designing an API contract, documenting an authentication flow, writing an incident postmortem, or explaining to a new hire why one request takes four network hops. The format forces you to name every participant and every message, which surfaces missing error paths and undefined timeout behavior on the whiteboard instead of in production.

How Do You Read Sequence Diagram Notation?

Each participant sits in a box at the top of the diagram with a dashed vertical line — the lifeline — dropping down from it. The lifeline represents that participant's existence over time; anything drawn lower on the page happens later. Activation bars are the thin rectangles drawn on top of a lifeline, and they show when a participant is actively processing. When your API service's activation bar stretches from the incoming request down past three database calls, you are looking at exactly how long that request handler stays busy.

Arrows carry the semantics. A solid line with a filled arrowhead is a synchronous message: the caller blocks until it gets a response, like an HTTP request or a gRPC call. A line with an open arrowhead is asynchronous: the caller fires the message and moves on, which is how you draw events published to Kafka, messages dropped on SQS, or a fire-and-forget webhook. Mixing these up is the most common notation error, and it matters — a diagram that shows your payment confirmation as synchronous when it actually rides an event bus is describing a different system.

Return messages are dashed lines with open arrowheads pointing back to the caller, usually labeled with what comes back: 200 OK, the token payload, an error code. Many people omit returns to reduce clutter, and for happy-path overviews that is fine. But if the diagram exists to pin down failure behavior — what exactly does the client see when the downstream times out? — draw every return explicitly.

What Do alt, opt, loop, and par Fragments Mean?

Combined fragments are the labeled boxes that wrap a group of messages and give sequence diagrams their control flow. An alt fragment shows mutually exclusive branches, each with a guard condition in square brackets: alt [cache hit] returns the cached value, else [cache miss] falls through to the database. An opt fragment is a single conditional block — the messages inside happen only if the guard holds, like opt [token expired] wrapping a refresh call.

A loop fragment repeats its contents, with the guard stating the bound: loop [retry up to 3 times with backoff] is worth a hundred words of prose about your retry policy. A par fragment shows message groups that execute concurrently with no guaranteed ordering — and that lack of guaranteed ordering is precisely where race conditions live. If two par branches both write to the same row, the diagram makes the hazard visible in a way a paragraph never will.

Sequence Diagram Example: The OAuth2 Authorization Code Flow

The OAuth2 authorization code flow is the canonical sequence diagram example because it involves four participants and two distinct channels. The participants: the user's Browser, your Client App, the Authorization Server (say, Okta or Auth0), and the Resource Server (your API). The flow starts with a synchronous request from the browser to the client app, which responds with a 302 redirect to the authorization server's /authorize endpoint carrying client_id, redirect_uri, scope, and a state parameter.

The user authenticates and consents on the authorization server, which redirects the browser back to the client's callback URL with a short-lived authorization code. Everything so far is the front channel — visible in browser history and proxy logs, which is exactly why it carries only the code and never the tokens. The client app then makes a direct server-to-server call to the /token endpoint, exchanging the code plus its client_secret for an access token. On the diagram, that back-channel exchange is a solid synchronous arrow between Client App and Authorization Server with the browser lifeline untouched, and that visual gap is the entire security argument of the flow.

Finish with the client calling the Resource Server using the Bearer token and receiving data on a dashed return arrow, then wrap the refresh exchange in an opt [access token expired] fragment. Draw this once and the difference between front channel and back channel — the thing prose explanations of OAuth consistently fail to make stick — becomes unmissable.

How Do You Diagram a REST API Request With Caching?

A REST API read path with a cache layer is the other diagram every backend team ends up drawing. Participants: Client, API Service, Redis, PostgreSQL. The client sends GET /users/42; the API service issues a synchronous GET user:42 to Redis, and an alt fragment splits on the result. On [cache hit], Redis returns the serialized user and the API responds immediately. On [cache miss], the API queries Postgres, writes the result back with SETEX user:42 300, and then responds — that write-back arrow is the detail people forget, and the reason stale-TTL bugs are so hard to explain in prose.

This is where sequence diagrams decisively beat written descriptions. Prose serializes into one path per sentence; a diagram shows concurrency and timing on a single page. A par fragment exposes the cache stampede: fifty clients miss simultaneously and all fifty hit Postgres before the first write-back lands. Timeout annotations on individual arrows — Redis 50ms, Postgres 2s — show at a glance which dependency dominates your p99. A loop [retry x3, exponential backoff] fragment around a flaky downstream call documents your retry policy unambiguously, including the part prose usually omits: what the caller sees after the last retry fails.

If you are reviewing a design doc and the failure behavior exists only as paragraphs, ask for the sequence diagram. Race conditions, thundering herds, and retry-amplification bugs get caught in diagram review far more often than in prose review, because the notation forces every message and every ordering assumption onto the page. Keeping the diagram editable matters too, since these flows change every sprint — whether that is Mermaid in your README, a draw.io file in the repo, or an AI generator like AIDrawIO that outputs editable draw.io XML with version history.

Mermaid Syntax vs AI Generation: What Is the Fastest Way to Make a Sequence Diagram?

Mermaid is the fastest manual route and renders natively in GitHub, GitLab, and Notion. The core syntax fits in a few lines: start with sequenceDiagram, declare participants with participant A as API, then draw messages — A->>B: label for a synchronous call, A-)B: label for async, and B-->>A: label for a dashed return. Add + and - suffixes for activation bars, wrap blocks in alt [condition] ... else ... end, opt ... end, loop ... end, and par ... and ... end, and use Note over A,B: for timeout and TTL annotations.

Mermaid's strength is docs-as-code: version-controlled, diffable in pull requests, zero layout work. Its weakness is the same thing — you get almost no control over layout or styling, and diagrams beyond a dozen messages become unreadable. draw.io (diagrams.net) gives you full manual control for free and stores XML you can commit; Lucidchart adds real-time collaboration at a per-seat price. Honestly, many teams use both: Mermaid for diagrams that live in READMEs, a visual editor for anything headed to a design review or a slide deck.

The third route is describing the flow in plain English and letting AI draw it. In AIDrawIO, a prompt like 'Sequence diagram: browser, client app, auth server, resource API. OAuth2 authorization code flow — redirect to /authorize, callback with code, back-channel code exchange for access token, then a Bearer-token API call, with an opt fragment for token refresh' produces an editable draw.io-compatible diagram in seconds. Because the output is draw.io XML rather than a static image, you can rearrange lifelines, fix labels, and export SVG or PNG — or keep editing in diagrams.net. The free sequence diagram generator at aidrawio.com/en/tools/sequence-diagram-generator allows 5 generations per hour with no account required, which is enough to draft both worked examples from this article and refine them by hand.