Skip to content
Flowmark

Sequence diagrams

Use a sequence diagram when order is the point. Participants stay on a horizontal axis and time moves downward, so a reader can see calls, replies, concurrency, and alternatives in context.

A complete request

Section titled “A complete request”
diagram.flowmark
sequence "Place order" {
  autonumber


  browser: actor "Browser"
  api: gateway "API"
  orders: service "Orders"
  database: database "Postgres"


  browser -> api "POST /orders"
  activate api
  api -> orders "PlaceOrder"
  activate orders
  orders -> database "insert"
  database --> orders "order"
  orders --> api "201 Created"
  deactivate orders
  api --> browser "order id"
  deactivate api
}

Participants use the same id: kind "Label" form as flow diagrams. Messages are rendered in source order. Dashed replies use -->; events can use => or ~> when that distinction helps.

Show work with activations

Section titled “Show work with activations”

activate participant starts an execution bar; deactivate participant ends it. Use activations for ownership of work, not around every message.

Explain branches and concurrency

Section titled “Explain branches and concurrency”
diagram.flowmark
alternate "payment accepted" is success {
  orders -> fulfillment "ShipOrder"
} else "payment declined" is danger {
  orders -x orders "reject order"
}


parallel "reserve inventory" {
  orders -> inventory "Reserve"
} and "authorize payment" {
  orders -> payments "Authorize"
}

Available structured fragments include alternate, optional, loop, parallel, critical, and break. Keep fragment labels short and factual. Deeply nested fragments are a sign that the sequence is trying to document an implementation rather than explain a scenario.

Add context without another participant

Section titled “Add context without another participant”
diagram.flowmark
note over orders, payments "Authorization expires after 15 minutes"
divider "PaymentCaptured signal"

Notes explain a constraint. Dividers mark a meaningful phase or time jump. Neither should narrate what the messages already say.

Create and destroy temporary participants

Section titled “Create and destroy temporary participants”

Use create and destroy when lifecycle matters:

diagram.flowmark
create shipment: subprocess "Ship order"
orders -> shipment "start"
activate shipment
shipment --> orders "shipped"
deactivate shipment
destroy shipment

Study a realistic example

Section titled “Study a realistic example”

The example below combines a queue, parallel work, a signal, an alternative, and a temporary child process. Use it as a ceiling, not a baseline—most useful sequences are much smaller.

Edit source — diagram updates live
Source

Use a workflow instead when business states and branches matter more than the exact order of messages.