sequence-diagram

name	sequence-diagram
description	Author Mermaid sequence diagrams for service interactions including async, parallel, and error paths. Use when documenting request flows, integration contracts, or incident timelines.

Sequence Diagram

Sequence diagrams expose when and in what order components talk - the dimension C4 container/component diagrams hide. This skill standardises Mermaid 11+ syntax so diagrams stay diff-friendly, render in GitHub/GitLab, and survive refactors.

Stack Baseline (2026)

Concern	Recommended
Notation	Mermaid 11+ sequenceDiagram
Async	-) arrow + Note for fire-and-forget; par for fan-out
Errors	alt / else blocks with explicit failure path
Versioning	.mmd files in repo, rendered in CI via mermaid-cli
Fallback	Export PNG/SVG only for slides; source of truth is text
Linting	mermaid-cli + markdownlint-cli2 MD046

When to Use

• Documenting a new API or event flow during RFC review.
• Capturing an incident timeline in a post-mortem.
• Aligning two teams on the contract at a service boundary.
• Replacing screenshots from whiteboards in the wiki.

Prerequisites

• Container/component boundaries already named (from C4 L2/L3).
• Each participant maps to a deployable unit, not a class.
• Known auth, retry, and timeout policy for the flow.
• Mermaid renderer available (GitHub, VS Code, Backstage TechDocs).

Instructions

1. Synchronous request/response

sequenceDiagram
  autonumber
  actor User
  participant BFF as BFF (Edge)
  participant Order as Order Service
  participant DB as Postgres
  User->>BFF: POST /checkout
  BFF->>Order: gRPC PlaceOrder
  Order->>DB: BEGIN; INSERT order
  DB-->>Order: ok
  Order-->>BFF: OrderId
  BFF-->>User: 201 Created

2. Async + parallel fan-out

sequenceDiagram
  autonumber
  participant Order
  participant Bus as Event Bus
  participant Inv as Inventory
  participant Pay as Payments
  Order-)Bus: OrderPlaced (async)
  par
    Bus-)Inv: OrderPlaced
    Inv-)Bus: StockReserved
  and
    Bus-)Pay: OrderPlaced
    Pay-)Bus: PaymentAuthorized
  end
  Note over Order: Saga waits for both events<br/>before transitioning

3. Error path with retry

sequenceDiagram
  participant Client
  participant API
  participant Down as Downstream
  Client->>API: GET /resource
  API->>Down: fetch
  alt 5xx or timeout
    API->>Down: retry (exp backoff, max 3)
    Down-->>API: 200
  else circuit open
    API-->>Client: 503 + Retry-After
  end
  API-->>Client: 200

4. Conventions

• One verb per arrow; include protocol (HTTP, gRPC, AMQP).
• autonumber for any diagram referenced in prose.
• Use actor for humans, participant for systems.
• Keep <= 8 participants; split flows that exceed it.
• Time flows top-to-bottom; never use lifeline gaps for "later".

5. Storage and review

• Save under docs/diagrams/<flow>.mmd next to the ADR/RFC.
• Embed via fenced ```mermaid block in the markdown.
• CI step: mmdc -i docs/diagrams -o build/diagrams to fail on syntax errors.

Common Pitfalls

Pitfall	Symptom	Fix
Class-level participants	30 lifelines, unreadable	Collapse to deployable units
Hidden async	Sync arrow for queue publish	Use -) and Note for async
No error path	Only happy path documented	Always add alt for failure
Missing protocol	Reader guesses HTTP vs gRPC	Label arrows with protocol+verb
Drifted PNGs	Image and reality diverge	Source of truth is .mmd, render in CI

Output Format

• .mmd file committed in docs/diagrams/.
• Embedded fenced block in the owning ADR/RFC.
• Optional SVG export for slide decks (regenerated, never hand-edited).

Authoritative References

• Mermaid sequence syntax - https://mermaid.js.org/syntax/sequenceDiagram.html
• Mermaid CLI - https://github.com/mermaid-js/mermaid-cli
• UML 2.5.1 sequence diagrams (semantics reference) - https://www.omg.org/spec/UML/
• Simon Brown, C4 Model dynamic diagrams - https://c4model.com/diagrams/dynamic
• arc42 8.x - Runtime view section 6 - https://docs.arc42.org