Sequence diagram

The most consistently useful UML diagram. It answers a question people ask constantly: what actually happens when someone does this?

It ages well too, because interactions change less often than structures.

#When to draw one

• API and integration documentation.

• Debugging discussions, where the order is the argument.

• Design reviews of anything asynchronous.

#What is on the diagram

#A worked example

A login flow with an alternative path and a loop:

The source, which you can paste into a new diagram and edit:

sequenceDiagram
  autonumber
  actor U as User
  participant A as App
  participant S as Auth service
  participant D as Directory

  U->>A: Enter credentials
  activate A
  A->>S: POST /token
  activate S
  S->>D: Verify credentials
  D-->>S: Verified

  alt MFA required
    S-->>A: MFA challenge
    A-->>U: Enter code
    U->>A: Code
    A->>S: POST /token/mfa
  else No MFA
    Note over S: Straight to token issue
  end

  S-->>A: JWT (15 min)
  deactivate S
  A-->>U: Signed in
  deactivate A

  loop Every 14 minutes
    A->>S: Refresh token
    S-->>A: New JWT
  end

#A few things that catch people out

• Put the actor on the left and work rightwards. Readers expect the initiator first.

• Show the failure path in an alt block; happy-path-only sequence diagrams miss the interesting part.

• Note over is the right place for timing, expiry and retry rules.

#Related

Four types cover most of it.