Drawing sequence diagrams

A .drawio sequence diagram in the same visual language as the other drawing-* skills: light page, white cards with hairline borders, Google's palette on the arrows.

Build it with seq_drawio.py (this directory). Look at it with preview.py.

Where the files go

Everything this skill produces lives in one folder, never loose in the project root:

docs/diagrams/
  login-sequence.py             # the script that builds it
  login-sequence.drawio         # the diagram
  login-sequence.preview.svg    # what you looked at

Use the folder the user names. Otherwise put it under docs/diagrams/ when the project has a docs/ directory, and diagrams/ at the project root when it does not — the build script, the .drawio, and any preview or PNG together. write() creates the folder if it is missing, so f.write("docs/diagrams/login-sequence.drawio") is all it takes, and preview.py writes the SVG beside its input.

Never leave a build script, a .drawio or a preview in the project root, and never write outside the project you were pointed at. One folder, named files — a diagram whose script sits next to it can be regenerated; one scattered across a repository root cannot be found again.

What this draws, and what it does not

Reach for this one when the answer to "why is this slow" or "what happens if that times out" is in the picture. If nothing waits for anything, a step flow says the same thing in less space.

The output contract

1. Every call that blocks has blocking=True and a matching reply(). The activation bar is the diagram's whole point: it shows the window in which the caller can do nothing else.
2. Replies are reply(), not another call() pointing back. They are dashed with an open head, which is what a reader expects.
3. A message that nobody waits for is send() — a queue publish, a webhook, an audit event. Drawn amber and open-headed so it does not read as a request.
4. Participants are declared left to right in the order they first act. Crossing arrows are information; crossing them for no reason is not.

The pieces

from seq_drawio import Sequence

s = Sequence("Login with federated identity", "browser · api · idp")
br  = s.actor("Browser", "the person", "onprem/client/users.png")
api = s.actor("Session API", "FastAPI", "gcp/compute/run.png")
idp = s.actor("Entra ID", "token issuer")

s.call(br, api, "POST /login", blocking=True)
s.call(api, idp, "authorise (PKCE)", blocking=True)
s.call(idp, idp, "check MFA")            # same participant: a self-call
s.reply(idp, api, "id_token + groups")   # closes the bar opened above
s.reply(api, br, "Set-Cookie: session")
s.send(api, audit, "audit event")        # nobody waits
s.note(idp, "tokens live 60 minutes", row=3)
s.frame("alt · MFA required", rows=[1, 3])
s.write("docs/diagrams/login.drawio")

call() and reply() pair up on their own: a reply closes the most recent blocking call still open on that participant, and the bar is drawn between them. A bar that never closes means a call you said would block and never answered — usually a missing reply(), occasionally a real bug in the design.

A self-call's label sits beside the loop rather than on it: a plate in the middle covers the leg that makes it read as a loop at all.

frame() boxes a run of rows for an alt, a loop, an opt. Name the condition, not the shape: "alt · MFA required" beats "alt".

Rows are time

Every message takes the next row, so write the calls in the order they happen. Row pitch is 52 — enough for a label above the arrow and clear space between. The lifeline runs to the last row.

Before handing it over

S=~/.claude/skills/drawing-sequence-diagrams
python3 "$S/preview.py" docs/diagrams/login.drawio             # writes docs/diagrams/login.preview.svg
rsvg-convert -w 1400 -o docs/diagrams/login.png docs/diagrams/login.preview.svg

check_routing.py works here but has little to say: sequence messages run between fixed points on lifelines rather than between boxes, so there are no corridors to get wrong. Read the picture instead — for a bar that never closes, a reply with no call, a participant that receives everything and sends nothing.

Common mistakes

preview.py writes a plain SVG — open it in any browser if you have no rsvg-convert. The PNG step is for pasting into a document, not for looking at it.