| 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
