What is a Sequence diagram?
Time-ordered messages between actors and systems.
Use a Sequence when…
API request/response timelines
Authentication and OAuth flows
Multi-actor workflows where order matters
The minimal syntax
Copy this and you have a working sequence. Build from here.
sequenceDiagram autonumber participant U as User participant W as Web app participant A as API participant D as Database U->>W: Click class="code-str">"Save" W->>A: POST /diagrams A->>D: INSERT INTO diagrams D-->>A: id = 4f2… A-->>W: 201 Created W-->>U: ✓ Saved
Patterns worth memorizing
autonumber
Add `autonumber` at the top — every arrow gets a step number, perfect for RFCs.
Notes
`Note over A,B: text` spans multiple actors and is great for assumption callouts.
loop / alt / opt
Use control blocks for retries, branches, and optional steps without leaving the diagram.
The things that will trip you up
Mermaid silently ignores misspellings — these are the failures we see most.
- 01
Solid `->>` is synchronous; dashed `-->>` is the response — mixing them up reads as a different protocol.
- 02
Participants render in declaration order. If you want a specific order, declare them up front.
- 03
Long messages overflow — break them with `<br/>` inside the label.