sequence-diagram

Sequence Diagram (Mermaid)

Generate sequence diagrams using Mermaid sequenceDiagram syntax. The deliverable is the source in a fenced ```mermaid block — it renders natively on GitHub, GitLab, and most Markdown viewers. The canonical online editor is mermaid.live.

The output is Mermaid source, not an image. The fenced block is the diagram: wherever GitHub-flavored Markdown renders, the diagram renders. No render script, no export step.

Validation and preview via MCP, when present. If the session has the Mermaid MCP server tools, the skill uses them to validate the diagram with the real Mermaid parser, render it, and return a mermaid.live preview link. It is runtime detection, not setup: the skill does not prescribe how to run the server — that is documented in the repo README. Without the MCP, the delivery is the ```mermaid block alone, editable at mermaid.live.

Workflow

Step 1: Understand the flow

Before writing notation, get clarity on:

• Participants — who/what are the actors? (user, services, databases, external APIs)
• Order of interactions — what happens first, second, third?
• Direction — who initiates each call?
• Sync vs. async — does the caller wait for a response, or fire-and-forget?
• Branches and loops — are there conditional paths or retries?
• Failure paths — what errors change the system's behavior at a level the user cares about? Think security rejections (CSRF / token tampering), user denials (consent refused, payment declined), invalid/expired inputs, and downstream unavailability. List the ones worth showing, separately from "every possible status code".

If the user gave a vague description (e.g. "diagram of the login flow"), ask one or two targeted questions before drawing. Always confirm which failure paths matter — a happy-path-only diagram is rarely what the user actually wants. Do not invent participants the user did not mention.

Step 2: Write the notation

Use the syntax in the Essential syntax section below. For uncommon constructs (boxes/grouping, create/destroy, background highlighting, links, theming, etc.) load references/syntax.md for the full reference.

Conventions:

• Start with sequenceDiagram on its own line. Add a title via YAML frontmatter above it:

  ---
  title: Order checkout
  ---
  sequenceDiagram
  

• Use descriptive participant aliases (participant API, participant Gateway as Payment Gateway) — short but meaningful, never A/B/C unless the user explicitly asks for placeholders. Use actor for human participants. Mermaid has no database/boundary/control shapes — represent a store as a participant (alias it, e.g. participant Users as Users DB).
• Use ->> for requests (solid line, arrowhead) and -->> for responses (dashed line, arrowhead). Switch to -) / --) (open arrowhead) only when the flow is clearly fire-and-forget (queues, events, webhooks). Beware: -> and --> draw lines without arrowheads — almost never what you want.
• Group related steps with alt/opt/loop/par when it clarifies the logic. Don't over-fragment.
• Add Note over X: ... for context the arrows can't express (preconditions, side effects). Line breaks inside notes and messages use <br/>, not \n.

HTTP flows (when applicable)

When the interactions are HTTP calls and you know the endpoint, verb, headers, body, status codes, or other request/response details, encode them with this convention:

• Request arrow label — METHOD path, e.g. POST /users, GET /orders/{id}, DELETE /sessions/{sid}. Include path params with {}.
• Response arrow label — status code + short reason, e.g. 201 Created, 404 Not Found, 502 Bad Gateway. Avoid full sentences here.
• Notes for the rest — use Note over <caller>,<callee>: ... for things that don't fit cleanly on the arrow:
  • Authentication / authorization headers (Authorization: Bearer ..., X-Api-Key: ...)
  • Content-Type, Accept, Idempotency-Key, custom protocol headers
  • Request body shape (use a one-line JSON sketch, not full schema)
  • Response body shape (same)
  • Query parameters when too many to fit on the arrow

Placement: put request-side notes immediately before the request arrow, and response-side notes immediately after the response arrow. Span the note across the two participants involved (Note over Client,API: ...) so it visually attaches to the exchange.

Only include details the user actually shared. Do not invent header values, status codes, or body fields.

Example:

---
title: Create user
---
sequenceDiagram
    actor Client
    participant API
    participant Users as Users DB

    Note over Client,API: Authorization: Bearer {{token}}<br/>Content-Type: application/json
    Client->>API: POST /users
    Note over Client,API: body: {"email":"...","name":"..."}
    API->>Users: INSERT user
    Users-->>API: row
    API-->>Client: 201 Created
    Note over Client,API: body: {"id":"u_42","email":"..."}

Modeling failures (default, not optional)

A flow that only shows the happy path is half a diagram — much of the value of sequence diagrams is making the alternative routes legible. Model the failures that change the system's behavior, not every possible error code.

Use:

• alt <success> / else <failure reason> when the two outcomes are mutually exclusive and the failure side has its own meaningful sequence. End the failure branch with the user-facing consequence (redirect to error page, exception surfaced, retry scheduled) — that already signals the flow stops there.
• break <condition> for an early-exit guard checked in-flight, outside an alt. It is a fragment of its own (with body and end), and Mermaid renders it as the UML break frame — the flow stops there. Use it for things like CSRF state mismatch right after a callback. Form:

  break state divergente do guardado
      Note over Client: rejeita - possível ataque
      Client-->>Browser: 400 Bad Request
  end
  

• opt <error condition> for cleanup, logging, or notification steps that only run on failure.
• critical <action> / option <failure> when something must happen and each failure mode has its own short handling (e.g. acquire a connection / timeout / credentials rejected). Rarer than alt — reach for it only when the "must happen" framing is the point.

Pick the failures worth drawing using these criteria — at least one must hold:

1. Different action by the caller (e.g. retry, fall back to another provider, surface error to user).
2. Security implications (e.g. CSRF state mismatch, token verification failed — silently rejecting matters for the reader).
3. User explicitly asked about it.

Don't enumerate every HTTP 4xx/5xx — that turns the diagram into a flowchart. Group cousins under one branch (e.g. "expired or invalid code" instead of separate 400 invalid_grant and 401).

Order of preference

Escalate only when needed:

1. Happy path with no fragments — the cleanest diagram. Use when failure cases don't need to be visible.
2. Happy path + break for early-exits — still one diagram, still readable. Best when failures are "check and abort" (CSRF, expired token, signature mismatch). The happy path stays as the visual spine.
3. alt/else — only when both branches have substantial content (≥2 messages each). For "success vs. immediate error response", break reads cleaner.
4. Multiple diagrams — one for the happy path, a separate "errors" diagram (or one per scenario) for failures. Default to this for complex protocols (OAuth, two-phase commit, multi-leg handshakes) where 3+ fragments would be needed in a single diagram.

Keeping diagrams readable

A sequence diagram should read top-to-bottom as a story. If a single diagram needs more than 2 fragment blocks (alt, opt, loop, par, break, critical combined), it has stopped being a sequence and turned into a decision tree — split it. The natural split is "happy path" diagram + one "errors" diagram covering the failure branches from a common starting point (or one diagram per failure when scenarios are very different).

Example:

sequenceDiagram
    participant Browser
    participant Client
    participant Auth

    Client->>Auth: POST /token
    alt valid code + PKCE matches
        Auth-->>Client: 200 OK
        Note over Client,Auth: body: {"access_token":"...","id_token":"..."}
    else expired code or PKCE mismatch
        Auth-->>Client: 400 invalid_grant
        Client-->>Browser: 302 Found
        Note over Browser,Client: Location: /login?error=session_expired
    end

The redirect on the failure branch is what tells the reader the flow ends there.

Step 3: Validate and self-review (do not skip)

Skipping this step is the most common cause of broken diagrams — syntax slips (unbalanced fragments, a stray end, a typo'd arrow) are trivially catchable here.

Run two checks:

(a) Authoritative validation via Mermaid MCP — when available. If the session has the Mermaid MCP server tools (a tool whose function is validate and render a Mermaid diagram), run it against the produced source. It uses the real Mermaid parser, not a superficial check. Read each error, fix the diagram, and re-run until clean. Identify the tool by function, not by a fixed id — the slug depends on the name the user gave when registering the server. The tool also returns a mermaid.live preview link — keep it for Step 4.

If the MCP tools are not present, there is no mechanical validation at this step: rely on the self-review (b), and remember the block can be pasted into mermaid.live to check by hand. Running and registering the server is the user's decision (see the repo README) — the skill does not prescribe setup.

(b) Self-review against the quality checklist. Re-read the diagram as if a colleague just handed it to you — not as the author looking for confirmation. Check:

• Failure paths — if Step 1 identified failure modes that matter, are they in the diagram (or in a sibling diagram if you split)?
• Fragment count — ≤2 fragment blocks (alt + break + opt + loop + par + critical) per diagram? If 3+, split.
• Title — present (YAML frontmatter) and descriptive.
• Arrow polarity — every response uses -->> (or --) for async), not the request arrow ->> again. And nothing uses ->/--> (headless lines) by accident.
• Activation balance — every activate/+ has a matching deactivate/-; unbalanced activations are a parser error.
• Participant names — descriptive aliases (Cliente, API, Users DB), not A/B/C unless the user asked for placeholders.
• HTTP convention — for HTTP flows: METHOD path on requests, status + reason on responses, headers/body in adjacent notes (not on the arrow).
• No invented details — every header value, status code, and body field came from what the user said.

If any check fails: fix the diagram and re-validate. Only then proceed to Step 4.

Step 4: Deliver

Reply to the user with:

1. The source in a fenced code block with the mermaid language tag — that's what makes GitHub/GitLab render it inline.
2. If the MCP validated it, the preview link on its own line, prefixed with "Preview:" so the user can open it in one click.
3. If the MCP was not available, one line noting that the block renders inline on GitHub/GitLab and can be opened or edited at https://mermaid.live.

Essential syntax (covers ~90% of diagrams)

Participants

---
title: Order checkout
---
sequenceDiagram
    actor Customer
    participant Web
    participant Pay as Payment Gateway
    participant Orders as Orders DB

Only two shapes exist: participant (rectangle) and actor (stick figure). Use as to alias: the id comes first, the display name after (participant Pay as Payment Gateway). Declare participants explicitly when order matters; otherwise Mermaid creates them in order of first use.

Messages

sequenceDiagram
    Customer->>Web: place order
    Web->>Pay: charge $50
    Pay-->>Web: 200 OK
    Web-->>Customer: order confirmed

Arrow	Meaning
A->>B	Request (solid line, arrowhead)
A-->>B	Response / return (dashed line, arrowhead)
A-)B	Async fire-and-forget (solid line, open arrowhead)
A--)B	Async return / event (dashed line, open arrowhead)
A-xB	Lost message (solid line, cross)
A--xB	Lost response (dashed line, cross)
A->>A	Self-call

A->B and A-->B draw lines without arrowheads — valid syntax, rarely what you want.

Notes

sequenceDiagram
    participant Web
    participant Pay
    Note over Web: validates session
    Note over Web,Pay: shared HTTPS channel
    Note left of Web: starts here

Line breaks inside a note or message label: <br/>.

Activations (lifeline bars)

sequenceDiagram
    Customer->>+Web: place order
    Web->>+Pay: charge
    Pay-->>-Web: ok
    Web-->>-Customer: confirmed

The +/- shorthand on arrows activates the receiver / deactivates the sender. The explicit form is activate Web / deactivate Web on their own lines. Either way, every activation needs a matching deactivation.

Alt / Opt / Loop / Par / Break / Critical

sequenceDiagram
    participant Web
    participant Pay
    participant Email

    alt valid card
        Pay-->>Web: 200 OK
    else insufficient funds
        Pay-->>Web: 402 Payment Required
    end

    opt user opted in
        Web->>Email: send receipt
    end

    loop until expires
        Web->>Pay: poll status
    end

Parallel branches are separated by and (not else):

sequenceDiagram
    participant Web
    participant Email
    participant Analytics

    par send receipt
        Web-)Email: send receipt
    and log event
        Web-)Analytics: log event
    end

break <condition> ... end renders an early-exit frame; critical <action> / option <failure> ... end frames a must-happen step with its failure handling (see Modeling failures above).

Autonumber

sequenceDiagram
    autonumber
    Customer->>Web: GET /
    Web-->>Customer: 200

Comments

Lines starting with %% are ignored:

%% This is a comment

Full examples

Example 1: simple HTTP request/response

---
title: Login
---
sequenceDiagram
    actor User
    participant Browser
    participant API
    participant Users as Users DB

    User->>Browser: enters credentials
    Browser->>API: POST /login
    API->>Users: SELECT by email
    Users-->>API: row
    API-->>Browser: 200 + session cookie
    Browser-->>User: redirect to dashboard

Example 2: branching with alt + activations

---
title: Payment authorization
---
sequenceDiagram
    actor Customer
    participant Checkout
    participant Gateway as Payment Gateway
    participant Ledger

    Customer->>+Checkout: confirm order
    Checkout->>+Gateway: authorize $120

    alt approved
        Gateway-->>Checkout: 200 auth_id=xyz
        Checkout->>+Ledger: insert pending charge
        Ledger-->>-Checkout: ok
        Checkout-->>Customer: order placed
    else declined
        Gateway-->>Checkout: 402 declined
        Checkout-->>Customer: payment failed, try another card
    end
    deactivate Gateway
    deactivate Checkout

Example 3: async event flow

---
title: Order placed - downstream events
---
sequenceDiagram
    participant Checkout
    participant Bus as Order Bus
    participant Inventory
    participant Email
    participant Analytics

    Checkout-)Bus: OrderPlaced id=42
    Note over Bus: fan-out to subscribers

    par reserve items
        Bus-)Inventory: reserve items
    and send confirmation
        Bus-)Email: send confirmation
    and track conversion
        Bus-)Analytics: track conversion
    end

When to load references/syntax.md

Read references/syntax.md only if the user asks for any of:

• Grouping participants in colored boxes (box ... end)
• Create / destroy participants mid-flow
• Background highlighting of a region (rect)
• Autonumber offsets and resumed numbering
• Links / menus attached to participants (link, links)
• Escaping special characters (entity codes, the end keyword trap)
• Theming / configuration (YAML frontmatter config, %%{init}%% directives)

For the common 90% above, the essential syntax in this file is enough. For a construct not covered even there, fetch the official syntax document via the Mermaid MCP tool when available (the one whose function is get the Mermaid syntax document for a diagram type), or consult mermaid.js.org.

Output template

When delivering, use this exact shape:

Aqui está o diagrama:

​`​`​`mermaid
<source>
​`​`​`

Preview: <mermaid.live link returned by the MCP>

(Adapt the lead-in to the user's language. Without the MCP, replace the Preview line with a note that the block renders inline on GitHub/GitLab and can be edited at https://mermaid.live.)

Common mistakes to avoid

• Headless arrows. -> and --> draw lines without arrowheads in Mermaid. Requests use ->>, responses -->>. This is the single most common Mermaid mistake.
• par with else. Parallel branches are separated by and. else belongs to alt only.
• \n for line breaks. It renders literally. Use <br/> inside notes and message labels.
• Inventing shapes. There is no database, boundary, control, or entity — only participant and actor. Represent a store as participant Users as Users DB.
• Wrong comment marker. Comments are %%, not # or //.
• Alias direction. It is participant id as Display Name — id first, display after.
• Unbalanced activations. Every activate/+ needs a matching deactivate/-; Mermaid rejects the diagram otherwise (Trying to inactivate an inactive participant).
• The word end in labels. A bare end inside a participant name or message can terminate a fragment early and corrupt parsing. Wrap the text in quotes or parentheses, or reword.
• Single-letter participants by default. Use real names. Only use A/B if the user is asking for an abstract example.
• Over-using Note. A note for every step is noise. Only annotate things the arrows can't express.
• Missing title. Every diagram should have one, via YAML frontmatter; it shows up in the rendered image.
• Over-fragmenting one diagram. More than 2 fragment blocks (alt, break, opt, loop, par, critical) in a single diagram make it a decision tree, not a sequence. Split into multiple diagrams (typically: happy path + errors).

Limitations to keep in mind (vs. richer sequence editors): no custom participant shapes, no icon participants, no per-arrow color/weight styling (theming is global via configuration), no collapsible/expandable sections. If the user explicitly needs those, say so instead of forcing them into Mermaid — but that is the rare case; for everything else, native Markdown rendering wins.