Sequence diagrams explain interactions over time. This tutorial builds a realistic checkout flow step by step, introducing each Mermaid feature as you need it. Full syntax lives on the sequence diagram reference.
Participants and messages
sequenceDiagram
participant B as Browser
participant S as Shop API
B->>S: POST /checkout
S-->>B: 201 CreatedDeclaring participants sets their order and lets you use short aliases. ->> is a request and -->> a response.
Activations
Activation bars show when a participant is busy. Add + to activate on a message and - to deactivate.
sequenceDiagram
participant B as Browser
participant S as Shop API
participant P as Payments
B->>+S: POST /checkout
S->>+P: Charge card
P-->>-S: Charged
S-->>-B: Order confirmedAlternatives and loops
sequenceDiagram
participant S as Shop API
participant P as Payments
S->>P: Charge card
alt success
P-->>S: OK
else declined
P-->>S: Declined
loop up to 3 times
S->>P: Retry
end
endNotes, boxes and numbering
sequenceDiagram
autonumber
box Frontend
participant B as Browser
end
box Backend
participant S as API
participant D as DB
end
B->>S: Request
Note right of S: Validate input
S->>D: Query
D-->>S: Rows
S-->>B: JSONBest practices
- Keep each diagram focused on one scenario; create separate diagrams for edge cases.
- Use consistent verbs for messages (GET /x, Charge card, Emit event).
- Number messages with autonumber when the diagram will be discussed.
- Prefer notes over long message labels.
Number the messages
The checkout sketch above already has a request and a reply. This sequence diagram tutorial adds the pieces you need when a review meeting points at a line and says "which step was that": numbers, boxes, notes, parallel work, a highlight, and a second scenario.
autonumber sits under the sequenceDiagram keyword, before the messages. Mermaid writes 1, 2, 3 on the arrows in the order they appear in the file. You don't maintain the digits. Insert a message and the later numbers move, which is what you want in a draft and dangerous in a doc that says "see step 4" in a paragraph. If the paragraph cites a number, update the paragraph in the same commit.
sequenceDiagram
autonumber
participant App
participant API
App->>API: POST /password-resets
API-->>App: 202 AcceptedTurn numbering on when the diagram will be discussed. Leave it off for a two-message illustration where the numbers are noise. The full syntax, including the arrow types, is on the sequence diagram reference.
Numbers follow source order, including messages inside par, alt, and rect. They don't restart in each box. If you need a stable id that survives an inserted arrow, put a short name in the message text (POST /password-resets) and cite that in prose. Cite the autonumber only in a review that is looking at this exact revision.
Group participants in boxes
A box draws a rectangle behind a set of participants. Use it for a boundary: client versus server, or your process versus a vendor. The color is a name or an rgb() value. Hex colors are a poor bet here, because # is awkward in this grammar. box Aqua Client is enough.
sequenceDiagram
box Aqua Client
actor U as User
participant App
end
box Green Server
participant API
participant DB
end
U->>App: Open reset page
App->>API: POST /password-resets
API->>DB: Store token hashactor is a participant drawn as a person. participant is a box on the lifeline. The alias (U as User) is what messages use. The words after as are the label. Declare everyone inside the box before the end. A participant left outside the box sits in its own column, which is correct for a third party and wrong for a service you meant to group.
Order is declaration order. The first box is the left column group. Put the user on the left and the database on the right unless your readers are used to the opposite. Don't use a box as a substitute for a note. The box says where the participant lives. It doesn't say what the message means.
Notes for the decision
A note is text that isn't a message. Use it for a constraint the arrow can't hold: an expiry, a security rule, a reason you refused to do the obvious thing.
Note right of API: Hash the token sits beside one participant. Note over U,API: Link expires in 30 minutes spans two lifelines. The span is better when the constraint binds both sides, which an expiry does. The user has to open the link in time, and the API has to reject it after.
sequenceDiagram
participant U as User
participant API
U->>API: Open link
Note over U,API: Link expires in 30 minutes
API-->>U: Form or 410 GoneKeep the note shorter than the message. A note that restates the arrow is clutter. A note that says "compare hashes, don't store the raw token" is the reason the diagram exists. If you need three sentences, they belong in the paragraph under the figure, and the note should be the headline of that paragraph.
Colons still separate the note keyword from the text. One colon. Extra colons in the sentence are the failure the syntax guide shows how to rephrase.
Parallel work
par and and mark messages that happen together, then end closes the block. Password reset does this when the API emails the user and writes an audit row. Neither waits on the other. A single lifeline drawn as two sequential arrows would claim an order you don't have.
sequenceDiagram
participant API
participant Mail
participant DB
par Notify
API->>Mail: Send reset link
and Audit
API->>DB: Insert audit row
endThe words after par and and are labels for the branches. Keep them to one or two words. Inside each branch, write normal messages. Don't nest an alt inside a par until the simple form renders. You can, and the diagram becomes a puzzle. Split the puzzle into two diagrams: one for the race, one for the failure.
par is not a loop. A retry is loop or alt, which the checkout section already used. Use par only when the code actually starts both operations without waiting. If the audit write must succeed before the email goes out, draw two normal arrows. A parallel block that lies is worse than a long sequence.
Activations still work on the arrows inside par. Add + on the message that starts work and - on the reply that finishes it, the same way the checkout example did for a charge. A parallel branch with no reply looks like the work never ends. Either show the return arrow or leave activation off for that sketch. Don't mix a careful activation on one branch with a dangling bar on the other. Reviewers will think the dangling one is the bug.
Highlight a stretch
rect paints a translucent rectangle behind a run of messages. It doesn't create a branch. It tells a reader "this part is the commit" or "this part is the dangerous bit." Close it with end.
sequenceDiagram
participant App
participant API
participant DB
rect rgb(220,252,231)
App->>API: POST /password-resets/confirm
API->>DB: Replace password hash
end
API-->>App: 204 No contentPick a light rgb() color. A dark rectangle with default text fails contrast, the same problem the themes guide covers for flowchart fills. One rectangle per diagram is usually the right number. Two rectangles start to look like a second syntax for alt, and readers will think the highlight means a choice.
Use rect for the step that changes durable state. In a reset flow, that is the moment the password hash is replaced. The email, the form, and the 204 are context. The hash write is the point.
Password reset, end to end
This scenario uses the pieces together. Numbers for the review, boxes for client and server, a parallel email and audit, a note for the expiry, and a rectangle behind the hash replacement. It is a different story from checkout. The money movement is gone. The secret is a token, then a new password.
sequenceDiagram
autonumber
box Aqua Client
actor U as User
participant App
end
box Green Server
participant API
participant DB
end
U->>App: Open reset page
App->>API: POST /password-resets
API->>DB: Store token hash
par Notify
API-->>U: Email the link
and Audit
API->>DB: Insert audit row
end
Note over U,API: Link expires in 30 minutes
U->>App: Submit new password
rect rgb(220,252,231)
App->>API: POST /password-resets/confirm
API->>DB: Replace password hash
end
API-->>App: 204 No content
App-->>U: Password updatedRead it in order. The user opens the page. The app asks the API for a reset. The API stores a hash of the token, not the token. In parallel it emails the link and writes an audit row. The note is the contract on that link. Later the user submits a new password, and only the highlighted pair of messages replaces the password hash. The 204 and the confirmation screen come after the write.
What this diagram leaves out, on purpose: the unknown-email case. Many products return the same 202 whether the account exists or not, so the diagram doesn't branch on "user found." If your API does branch, add an alt under the lookup and keep the generic response in both arms. That decision is the one worth a second diagram, not another ten messages on this one.
A second thing left out is the stale-token failure. After the expiry note, a real handler can still receive a late submit. Draw that as its own small diagram: user submits, API checks the hash and the clock, API returns 410, password hash unchanged. Putting the 410 on this chart forces an alt through the rectangle and hides the happy path you numbered for the meeting. Two charts, one link between them in the doc, beat one chart with every branch.
Check the finished chart against the handler, not against your memory of the handler. The route that stores the token hash should be the message inside the first half. The route that overwrites the password should be the only write inside the rectangle. If a third write appears, either the code does something you forgot or the diagram invented a step. Delete invented steps. Add forgotten ones with a new number, and fix any sentence in the pull request that cited the old numbers.
If a message label grows past a short path, move the explanation to a note or to the prose. POST /password-resets/confirm is a label. "Constant-time compare, then overwrite the hash" is a note or a sentence under the figure. The AI prompt guide can draft this from a bullet list. You still have to check that the hash write sits inside the rectangle and that the email doesn't wait on the audit, or the other way around, matching the code you ship.
Numbering, notes, and the review
autonumber is worth turning on once the messages are stable, and worth turning off while you are still inserting steps. A number in a pull-request comment ("see message 4") goes stale the moment someone adds a lookup. If the review needs stable names, put the path in the label and leave autonumber off until the last commit.
Notes are for the fact that does not fit on the arrow. "Constant-time compare" belongs in a note or in the paragraph under the figure, not in a participant name. A note that repeats the message is noise. A note that records a timeout, a status code, or a header the arrow cannot show is the reason the note exists.
Read the chart top to bottom with the handler open. Each ->> should be a call you can find, and each -->> should be the response that call returns. If the reply goes to a participant who never sent the request, the arrow is aimed at the wrong person. Fix the target before you add another alt. The sequence diagram page keeps the syntax list, and the AI sequence generator can draft a first version from the route list. You still match each arrow to a function.
If the chart is for a public API, include the status code on the reply and leave the body schema in the prose. A sequence diagram that pastes a JSON payload into the arrow becomes a wall of text, and the activation bars are the part worth seeing.
If you are starting from a ticket instead of a blank file, read a sequence diagram from a user story. Finished pictures for login, an API, and checkout are an example of a sequence diagram.