Sequence diagrams: alt / opt / loop / par / critical / break / note

Sequence diagrams aren’t just A -> B. The control-flow keywords are what make them useful.

alt / else — branches

The most common pattern. alt is “if”, else is “else”:

@startuml
title Login response
participant FE
participant API

FE -> API: POST /login
alt success
  API --> FE: 200 + JWT
else bad credentials
  API --> FE: 401
else user locked
  API --> FE: 423
end
@enduml

Three flat branches; else follows alt, multiple else are valid.

opt — optional block

opt has refresh_token
  FE -> API: POST /refresh
  API --> FE: 200 + new JWT
end

opt has no else; equivalent to if (cond) { ... }.

loop — iteration

loop every 10s
  FE -> API: GET /health
  API --> FE: 200
end

loop up to 3 times
  FE -> API: retry
end

The label after loop shows up on the divider.

par — parallel branches

par
  FE -> API: GET /user
else
  FE -> API: GET /orders
end

Two things happen at once — common for concurrent frontend requests.

critical — try/recover style

critical DB write
  API -> DB: BEGIN
  API -> DB: INSERT
  DB --> API: ok
option rollback on failure
  API -> DB: ROLLBACK
  API --> FE: 500
end

option = else, but reads better for error-handling flows.

break — early exit

1
2
3

break user cancelled
  API --> FE: 499
end

break jumps out of the rest of the sequence. Useful for cancellation paths.

note — annotations

Place alongside a lifeline or spanning several:

note over FE, API
  Requests carry Idempotency-Key
end note
note right of API
  Cache hit ratio ~60%
end note

note over A, B for multi-actor spans; note left of A / note right of A for single-sided.

Real example

A “payment” sequence stitching several of the above together:

@startuml
title Payment flow
participant User
participant FE
participant API
participant Bank

User -> FE: click pay
FE -> API: POST /pay
opt balance low
  FE -> User: top-up dialog
  User -> FE: top up
end
API -> Bank: charge
Bank --> API: ok
alt success
  API --> FE: 200
  FE --> User: success
else failure
  critical refund
    API -> Bank: REFUND
    Bank --> API: ok
  option refund failed
    API --> User: contact support
  end
else timeout
  loop up to 3 times
    FE -> API: poll order
  end
end
@enduml

Tips

alt / par must end with end. One missing end and the whole diagram fails silently.
If a note over body contains , or :, wrap it in triple-quotes: note over A """multi-line with, chars""".
In loop labels, stick to ASCII numbers and English words. Some renderers choke on full-width characters in label lines.