Sequence diagrams

Best for a request/response exchange — who calls whom, in order, and what each message carries.

sequenceDiagram
  actor User
  participant Web as Web Client
  Web->>API: POST /login {email, pw}
  API-->>Web: 200 {token}
  API->>API: validate

Arrows: ->> call, -->> dashed reply, -> / -->, -x lost, -) async. Text after : is the message. participant X as Label aliases; actor X draws a person. Note over X: text (also left of / right of) pins a note to a lifeline.

Combined fragments

Wrap a run of messages in a labeled box with loop, opt, critical, break (one compartment) or alt…else / par…and / critical…option (multiple compartments split by a dashed divider). Close every fragment with end; they nest.

sequenceDiagram
  participant API
  participant Pay as Payment
  loop up to 3 tries
    API->>Pay: charge card
    alt approved
      Pay-->>API: receipt
    else declined
      Pay-->>API: error
    end
  end

Tint a fragment’s tab, border, and dividers with a frame directive in a vizzy fence — name it by keyword + condition (color: is a palette token / #hex):

frame loop up to 3 tries  color:blue
frame alt approved        color:green

Phase swimlanes

For a long flow, group consecutive messages into labeled, tinted horizontal bands with a phase directive in a vizzy fence — the band’s label sits in a left gutter, so the stages of the flow read at a glance. Each phase anchors to its first message (A->B) and runs until the next phase begins:

phase START:     Browser->Django   color:blue
phase BOOTSTRAP: Django->S3        color:indigo  desc: bg thread
phase POLL:      Browser->Django   color:gray
phase MESSAGE:   Browser->Django   color:green

• color: is a palette token or #hex; the band is drawn as a soft tint of it.
• desc: is an optional sub-label shown under the phase name in the gutter.
• The anchor binds to the first matching message after the previous phase, so a repeated A->B simply advances to the next stage.

Tint the participant heads to match with style <id> fill:<color> for the full colour-coded look.