OAuth 2.0 sign-in
Authorize redirect, consent, the callback with the code, and the server-side token exchange. The diagram to paste into an RFC when someone asks why the code goes to your backend and not the browser.
5 participants · 14 messages
Sequence Diagram Templates
Eight fully-drawn interaction flows, responses and all. Open one and it's on the canvas right away. Then talk it into your system: "put the queue between the API and the worker, add a retry, drop the email service."
Pick a template
Every diagram here is rendered from the same structured definition you get when you import it — nothing is a touched-up screenshot. Click any preview to see it at full size. "Refine in chat" puts the diagram on the canvas and opens the conversation panel, so your first sentence can start changing it; "Use this template" drops it into the editor and leaves the rest to you.
Checkout & payment callback
Storefront to order service to payment provider, with the asynchronous webhook that confirms the charge after the shopper has already seen a spinner.
6 participants · 16 messages
Cached API read
CDN edge, Redis and the database, showing both the hit and the miss path. Useful for explaining exactly which layer a stale response came from.
5 participants · 13 messages
Password reset
Request, single-use token, email delivery, and the token check on redemption. Draw it once and the security review gets shorter.
5 participants · 16 messages
Order fulfillment across services
Event bus in the middle, warehouse and shipping reacting, customer notified last. The shape of a choreographed flow rather than an orchestrated one.
6 participants · 14 messages
Direct file upload
Pre-signed URL, browser uploads straight to object storage, worker picks it up afterwards. The picture that explains why the file never touches your API.
5 participants · 16 messages
Webhook delivery & retry
Queue, delivery attempt, non-2xx, backoff, and the point where a failing endpoint gets disabled and a human is told. Support asks about this flow constantly.
5 participants · 15 messages
Chat message delivery
Websocket gateway, persistence, fan-out and a push notification for the recipient who is offline. Two clients on one diagram, which is where sequence diagrams earn their keep.
6 participants · 14 messages
How to use these templates
1. Take the flow with the most participants
Counter-intuitive, but it works: pick the template with more services than you need. Deleting a column you can see is a two-second decision; noticing a hop you forgot to draw usually happens during the incident it caused.
2. Open it — the whole interaction is already drawn
The diagram is on the canvas the moment the page loads, with participants in the order they first appear, responses drawn as dashed lines, and the asynchronous hops marked as such.
3. Talk it into your system
Open the chat panel and correct it in sentences: "put a queue between the API and the worker, add a retry after the timeout, rename Payment provider to Stripe, drop the email service." The assistant edits the same structured diagram you are looking at, so each turn returns a redrawn version rather than a fresh guess.
4. Hand-edit and export
The split view puts the Mermaid source next to the preview for the last few touches. Then SVG for docs that get zoomed, PNG for slides and tickets, or the raw source committed next to the code it describes.
What is a sequence diagram?
A UML sequence diagram shows an interaction over time: which participant sends which message to which other participant, and in what order. Each participant gets a vertical lifeline, time runs down the page, and every arrow is one message. It answers "who calls whom, and what comes back" — not "what is this system made of", which is a class diagram, and not "what happens next", which is a flowchart.
It is the diagram that settles arguments about distributed systems. Once the hops are drawn in order, the questions answer themselves: where the latency is, what happens if the third call fails, whether that callback can arrive before the response it depends on. Most of the value shows up while you are drawing it, not after.
Mermaid's sequenceDiagram syntax covers what engineering docs need: participants with readable labels, solid request arrows, dashed responses and self-calls. It stops short of full UML — no combined fragments with formal guards. In practice a note or a second diagram for the failure path reads better than nested frames anyway.
Sequence diagram syntax reference
Six things carry almost all the meaning in a sequence diagram. The one people get wrong is the dashed arrow: leave the responses out and the diagram becomes a call graph with no sense of time.
Participant
participant id as LabelEach column is a participant: a user, a service, a queue, a database. The short id is what arrows refer to; the label is what readers see, so it can contain spaces.
Time flows down
top → bottomThere is no arrow numbering — order on the page is order in time. Declaration order sets the left-to-right layout, so declare participants roughly in the order they first appear and the arrows stop crossing.
Request
->>A solid line with a filled arrowhead: one participant calls another and waits. Most arrows in an API diagram are this one.
Response
-->>A dashed line back to the caller. Use it for returns, callbacks and events — anything that is not a fresh request. Drawing the response is what turns a call graph into a timeline.
Self-call
api->>apiA participant messaging itself, drawn as a loop back into its own lifeline. Good for validation, retries and internal work that would otherwise be invisible.
Message text
: textEverything after the colon rides on the arrow. Be specific — "POST /login (email, password)" documents an interface; "login" documents nothing.
Nothing close enough?
Describe the interaction in a sentence or two and let the generator draw the first version — then refine it exactly the same way.
Open the generatorFrequently asked questions
How do I change a template after importing it?
Two ways, suited to different edits. Chat is for structural changes described in words — "add a queue between the API and the worker", "drop the email service", "move the token exchange to the backend" — and returns a redrawn diagram each turn. The split-view editor is for surgical ones: fix a typo in a message, rename a participant, reorder two calls. Most people import, talk the shape into place, then polish in the editor.
Does the assistant actually understand the imported diagram?
Yes, because the template is structured data rather than a picture or a blob of text. The imported participants and messages become the conversation's working state, so "delete the email service" removes that exact column and the messages attached to it — the assistant is not re-guessing your diagram from a description of it.
What is the difference between a solid and a dashed arrow?
Solid (->>) is a request: one participant calls another. Dashed (-->>) is what comes back — a return value, a callback, an event. The convention matters because a diagram of solid arrows only shows who calls whom; adding the dashed replies is what turns it into a timeline you can reason about.
How do I show something asynchronous?
Draw the reply as a dashed arrow that arrives later than the request it answers, with everything that happened in between still visible. The webhook and fulfillment templates both do this: the response to the shopper goes out before the payment confirmation arrives, which is exactly the property worth documenting.
What is the difference between a sequence diagram and a flowchart?
A sequence diagram is organised by participant: the columns are services or people, and the arrows between them are messages. A flowchart is organised by step: the boxes are actions, and there is no notion of who performs them. If your question is "which service calls which, and in what order", draw a sequence diagram.
How many participants can one diagram hold?
Readability, not the tool, is the limit. Past six or seven columns the arrows start crossing and the diagram gets wide enough to need horizontal scrolling. Split by phase — authentication in one diagram, fulfillment in another — rather than drawing the whole request lifecycle at once. The templates here sit deliberately at five or six.
What export formats are supported?
SVG, PNG, and the raw Mermaid source. SVG stays sharp at any zoom, which matters for wide diagrams; PNG pastes cleanly into slide decks and issue trackers; and the Mermaid source can be committed alongside your code so the diagram is reviewed like everything else.
Related
AI sequence diagram generatorStart from prose instead of a template: describe the interaction, get Mermaid.UML diagrams from textClass, sequence and state diagrams — the whole UML family in one place.Flowchart templatesFor when the order of steps matters more than who performs them.Class diagram templatesThe structural companion: eight ready-made UML class diagrams.