Sequence Diagram Builder

---
name: sequence-diagram-builder
description: Use when generating a Mermaid sequence diagram for service-to-service or actor-to-system interactions. Triggers on "sequence diagram", "interaction diagram", "API flow diagram", "auth flow diagram".
---

# Sequence Diagram Builder

Generate a Mermaid `sequenceDiagram` that makes a multi-actor interaction obvious. Sequence diagrams are for debugging and onboarding — they should expose ordering, async behavior, and failure modes, not paper over them.

## Required inputs

1. **The actors / participants** — services, users, external APIs, databases. 3-7 is the sweet spot.
2. **The trigger** — what kicks off the sequence (user click, cron, webhook)
3. **The messages** — in order, with whether they're sync or async (fire-and-forget)
4. **Branches and loops** — what happens on error, on cache hit, on retry
5. **The terminal state** — what does success look like? What does failure look like?

If the user lists 10+ actors, push back: "Sequence diagrams over 7 lanes are unreadable. Group some (e.g., '3rd-party APIs' as one), or split by phase."

## Mermaid syntax to use

Use `participant` to declare lanes in the order you want them rendered (left to right). Use `->>` for sync calls, `-->>` for responses, `-)` for async/fire-and-forget. Wrap branches in `alt`/`else`/`end`, retries in `loop`, and parallel work in `par`.

\`\`\`mermaid
sequenceDiagram
    actor User
    participant Browser
    participant API
    participant Auth as Auth Provider
    participant DB

    User->>Browser: Click "Sign in"
    Browser->>Auth: Redirect with client_id
    Auth-->>Browser: Auth code
    Browser->>API: POST /callback?code=...
    API->>Auth: Exchange code for token
    Auth-->>API: access_token + id_token
    API->>DB: Upsert user, create session
    DB-->>API: session_id
    API-->>Browser: Set-Cookie + redirect /home
    Note over API,DB: Session TTL = 24h
\`\`\`

For error branches, use `alt success / else error / end`. For retries, use `loop until success or max retries`. Add `Note over X,Y: ...` for assumptions or invariants the reader needs to know.

## Layout principles

- **Order participants left-to-right by who initiates.** User on the left, downstream services on the right.
- **Use `actor` for humans, `participant` for systems.** Mermaid renders them differently — humans get a stick figure.
- **Async messages** (`-)`) are visually distinct — use them when the caller doesn't wait.
- **Group parallel work** in `par` blocks — otherwise the reader assumes serial.
- **Notes are for invariants** (TTLs, retries, idempotency) — not for narration of what just happened.
- **Cap at ~25 messages.** Beyond that, split by phase ("auth phase," "checkout phase").

## Anti-patterns

- **Every message is sync** — most real systems have async events, retries, and timeouts. If your diagram has none, you're hiding complexity.
- **No error path** — every external call can fail. At minimum show the retry/fallback for the riskiest one.
- **Lanes that never send a message** — drop them.
- **Treating a database as an actor with logic** — DBs respond to queries; they don't initiate. Put logic in the service that owns the query.
- **Mixing layers of abstraction** — don't put "User" next to "TCP socket" in the same diagram. Pick one altitude.

## Rendering hints

- GitHub, Notion, GitLab render Mermaid natively. Sequence diagrams especially benefit from inline rendering in PR descriptions.
- Mermaid Live Editor (mermaid.live) for SVG export when you need a high-res image for a slide deck.
- For very long sequences, export to SVG and open in a browser — the live editor truncates very tall diagrams.

## Output

Return the ```mermaid block plus a 2-line summary: what flow is depicted, and the key failure mode the diagram exposes (if any). Sequence diagrams that don't expose at least one non-obvious thing aren't earning their keep.