Sequence diagrams

A sequence diagram is lifelines and the messages between them, read top to bottom. Declare it with the sequence header.

Lifelines are declared like nodes (Name or id = Name), or auto-created at first use, left to right in order of appearance. A [label: …] at first use renames the lifeline; an icon attribute ([monitor], [tech/react]) renders in the actor's header.
-> is a solid message, --> a dashed reply or return. <- and <-- reverse it; <-> draws arrowheads on both ends. The text after : is optional.
Self-calls (app -> app) draw the loop-back arrow.

sequence
title: Login

user = Visitor
app = Web App

user -> app: enter credentials
activate app
app -> auth0: POST /token
auth0 --> app: JWT
app -> app: cache session
app --> user: dashboard
deactivate app

Activations#

activate X and deactivate X draw an activation bar on X's lifeline. The bar starts at the message just sent when X is part of it (the usual activate-after-the-call style), and runs to the latest message at deactivate. Unclosed activations run to the end.

sequence
client -> server: GET /report
activate server
server -> db: query
db --> server: rows
deactivate server
server --> client: 200 OK

Notes#

note over X: text draws a note on X's lifeline; note over X, Y: text spans two; note left of X: and note right of X: sit beside it. A note takes its own vertical slot, following the latest message.

sequence
client -> server: GET /report
note right of server: cache miss
server -> db: query
db --> server: rows
server --> client: 200 OK

Blocks#

Blocks group messages into frames, and they nest. An else or and branch becomes a second adjacent frame, matching how the canvas draws them.

loop <condition> { … }
alt <condition> { … } else <condition> { … }
opt <condition> { … }
par <label> { … } and <label> { … }
break <condition> { … }

sequence
app = Web App

app -> auth0: refresh token
alt token valid {
  app -> user: dashboard
} else {
  app -> user: error page
}
opt remember me {
  app -> app: persist cookie
}

Putting it together, a checkout flow with an activation, a parallel block, and a retry loop.

sequence
title: Checkout

user = Shopper
app = Storefront

user -> app: place order
activate app
app -> inventory: reserve items
inventory --> app: reserved
par charge and email {
  app -> payments: charge card
} and {
  app -> email: send receipt
}
payments --> app: authorised
loop until confirmed {
  app -> user: order confirmed
}
deactivate app

An OAuth authorization-code exchange between four participants.

sequence
title: OAuth 2.0 code flow

user = User
app = Client App

user -> app: click "Sign in"
app -> authz: redirect to /authorize
authz -> user: consent screen
user -> authz: approve
authz --> app: authorization code
app -> authz: exchange code + secret
authz --> app: access + refresh token
app -> api: request with access token
api --> app: protected resource
app --> user: signed in