Sequence diagrams

Use a sequence diagram for a request/response exchange: who calls whom, in what 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: ->> solid call, -->> dashed reply, -x / --x lost message (solid / dashed), -) / --) async message (solid / dashed), -> / --> plain line (solid / dashed), and <<->> / <<-->> bidirectional (solid / dashed). Text after : is the message. participant X as Label sets a display label. 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. Fragments can 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

Colour a fragment’s tab, border, and dividers with a frame directive in a vizzy fence. Name it by keyword plus condition. color: is a palette token or #hex:

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

A fragment can also carry a click-to-open hint <keyword> [condition]: … badge for extra detail. Target it the same way as frame.

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 are easy to read. 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 light 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 advances to the next stage.

Colour the participant heads to match with style <id> fill:<color>.