Sequence Diagram

One scenario as an ordered exchange of messages between participants, with time on the vertical axis and the failure paths drawn rather than assumed.

Type Behavioural View Stage Design Topic Sequence Diagrams Area Architecture Communication

sequenceDiagram
  autonumber
  participant C as Client
  participant G as API Gateway
  participant O as Order Service
  participant P as Payment Gateway
  participant Q as Event Log

  C->>G: POST /orders (Idempotency-Key)
  G->>O: create order
  O->>O: persist as PENDING
  O->>P: authorise (deadline 3s)
  alt authorised
    P-->>O: approved + auth id
    O->>O: mark CONFIRMED
    O->>Q: OrderConfirmed
    O-->>G: 201 Created
  else declined
    P-->>O: declined
    O->>O: mark REJECTED
    O-->>G: 402 Payment Required
  else timeout
    P--xO: no response by deadline
    O->>O: keep PENDING
    O-->>G: 202 Accepted (poll for status)
    Note over O,P: reconciliation job settles<br/>PENDING against the provider
  end
  G-->>C: response

What it is

A single scenario, drawn as an ordered exchange between named participants, with time running down the page. It is the only common diagram where order is the content: everything else shows what exists, this shows what happens and when.

The valuable half is the alt blocks. A sequence diagram of only the happy path documents the case nobody needed help with.

When you produce it

For any interaction where the ordering, the timeouts or the failure semantics are genuinely contested — distributed transactions, payment flows, authentication handshakes, saga compensation, anything with a retry in it. Not for CRUD.

Who reads it

Engineers implementing either side of the exchange. Reviewers checking whether the failure modes have actually been thought about. Support engineers, later, at three in the morning.

What good looks like

Participants are systems or components, not people and not classes.
Timeouts and deadlines are on the diagram with numbers.
At least one alternative flow, and it is the one you were unsure about.
Synchronous and asynchronous messages are visually different.
Self-calls are used sparingly — they usually mean the participant list is drawn at the wrong altitude.

Common mistakes

Happy path only. The reason to draw this at all is the branch.
Twenty participants. Above about seven lifelines it stops being readable; split the scenario.
Documenting a whole system. One diagram is one scenario. A set of six scenarios is a good deliverable; one diagram covering six is not.
No timeouts. If the diagram does not say how long a participant waits, it has not described the interesting part.