8 min read · Last updated: 30 June 2025
Why sequence diagrams matter
Sequence diagrams show how components exchange messages over time. They are ideal for API flows, authentication hand-offs, and debugging distributed systems because order and responsibility are visible at a glance. Unlike architecture diagrams that emphasize boxes and lines, sequence diagrams answer the question: what happens next, and who calls whom?
Basic syntax
Start with the sequenceDiagram keyword, then declare participants implicitly through messages. A simple request-reply looks like Client->>Server: GET /health followed by Server-->>Client: 200 OK. Solid arrows represent calls; dashed arrows represent replies. Name participants on the left side when you need readable labels, for example participant API as Public API.
Branches, loops, and optional steps
Use alt and else for success and failure paths, loop for repeated polling, and opt for steps that may not run. Every fragment must close with end. These blocks mirror how engineers describe behavior in design reviews, which makes diagrams easier to maintain alongside code changes.
Exporting and sharing
When the diagram is ready, export SVG for crisp docs, PNG for slides, or PDF for PDF-first workflows. Keep the Mermaid source in your repository so updates stay diff-friendly. The drawflow.io editor stores drafts locally in your browser until you export or copy notation elsewhere.