Basic sequence diagram example
sequenceDiagram
autonumber
actor U as User
participant W as Web App
participant A as Auth API
participant D as Database
U->>W: Submit login form
W->>A: POST /login
A->>D: Find user by email
D-->>A: User record
alt password valid
A-->>W: 200 + session token
W-->>U: Redirect to dashboard
else invalid
A-->>W: 401 Unauthorized
W-->>U: Show error
endSequence diagrams show the order in which participants exchange messages. They are the go-to diagram for API calls, authentication handshakes, microservice interactions and any flow where timing matters.
Mermaid sequence diagrams read almost like a script: each line is one message from one participant to another. Mermaid handles lifelines, arrow alignment and spacing, and you get blocks for loops, alternatives, optional steps and parallel work.
When to use a sequence diagram
- Documenting REST and GraphQL API request/response flows
- Explaining OAuth, SSO and other authentication handshakes
- Designing event-driven and microservice interactions
- Debugging race conditions by laying out message order
Sequence Diagram syntax reference
| Syntax | What it does |
|---|---|
sequenceDiagram | Start a sequence diagram. |
participant A as Alice | Declare a participant with an alias (controls order). |
actor U | Declare a participant drawn as a stick figure. |
A->>B: text | Solid line with arrowhead (synchronous call). |
A-->>B: text | Dotted line with arrowhead (response). |
A-)B: text | Async message (open arrow). |
A-xB: text | Message with a cross at the end (failure / lost). |
activate A / deactivate A or A->>+B / B-->>-A | Show an activation bar on the lifeline. |
Note right of A: text / Note over A,B: text | Add notes beside or spanning participants. |
loop / alt ... else / opt / par ... and / critical / break | Control-flow blocks, each closed with end. |
rect rgb(240,248,255) ... end | Highlight a region with a background color. |
autonumber | Number every message automatically. |
Sequence Diagram examples
Retry loop with activations
Activation bars (+ and -) show when a participant is busy; loop shows retries.
sequenceDiagram
participant C as Client
participant S as Service
participant Q as Queue
C->>+S: Create job
S->>Q: Enqueue
loop Every 5s until done
C->>S: GET /status
S-->>C: pending
end
S-->>-C: completedParallel calls
par blocks show work happening at the same time.
sequenceDiagram
participant G as API Gateway
participant U as Users
participant O as Orders
participant R as Recommendations
G->>U: Get profile
par fetch in parallel
G->>O: Recent orders
and
G->>R: Suggestions
end
O-->>G: orders
R-->>G: items
Note over G: Merge and respondA login form is a poor fit for a conversation. A mermaid sequence diagram earns its place when the reader has to see who calls whom, what comes back, and which branch runs when the answer is no. The syntax table covers the arrows. This section is about the order of the lifelines, the split between requests and replies, and one charge flow you can copy.
Order, arrows, and blocks
Declare every participant before the first message, in the left-to-right order you want on the page. The first time a name appears is the order Mermaid keeps. If the first message invents the cast, a service you mention late jumps to the right edge and the eye reads the story backwards.
Use a solid ->> for a request and a dotted -->> for a reply. That single habit makes a long chart scannable. When every arrow is solid, replies look like new work and a review turns into a guessing game.
autonumber stamps each message. A pull-request comment can then say "step 4" instead of quoting a label. Put it once, near the top. If you also type numbers into the message text, every line wears two numbers and the stamps stop helping.
alt and else are a fork, closed with end. loop and end are a repeat. They nest, and each block needs its own end. An else that never opened an alt is a parse error. The diagram is telling you the branch has no question.
Worked example
A shop charges a card through a pay service, and the pay service asks the bank. The bank either approves or declines. After that the shop polls status. Two poll arrows are enough to show the retry without drawing the whole timer.
sequenceDiagram
autonumber
participant Shop as Shop
participant Pay as Pay
participant Bank as Bank
Shop->>Pay: Charge card
Pay->>Bank: Authorize
alt approved
Bank-->>Pay: OK
Pay-->>Shop: Paid
else declined
Bank-->>Pay: No
Pay-->>Shop: Fail
end
loop status poll
Shop->>Pay: Status
Pay-->>Shop: Pending
endShop, Pay, and Bank sit in call order. Step 1 is the shop's request. Step 2 is Pay handing the card to the bank. The alt splits the reply: a dotted OK becomes Paid, a dotted No becomes Fail. The loop sits after the decision, so a reader can see that polling is a separate habit, not a third outcome of the bank. If the poll should happen only while the charge is pending, say so in the loop title. The title is the only place that nuance fits without a paragraph on the arrow.
Keep message text short. "Authorize" is enough. The HTTP path and the error code belong in the doc under the diagram, or the arrow becomes a sentence and the lifelines get pushed apart.
When this is the wrong diagram
A flowchart is the better picture when the story is a policy of yes and no, and the actors don't matter. A state diagram is the better picture when one object sits in Draft, Review, and Live, and the arrows are events that move it. Reach for a sequence diagram when you would otherwise explain the feature by listing calls in order.
Common mistakes
- Leaving out the colon, as in
Shop->>Pay Charge card. The parser wantsShop->>Pay: Charge card, and without the colon the line isn't a message. - Opening
altorloopand forgettingend, or writingelsewhen noaltis open. Both fail the parse, and the preview stops at that line. - Letting the first message declare participants, then wondering why Bank sits on the left. Declare
participantlines first, in the order the reader should meet them. - Turning on
autonumberand also typing "1." into the message text. Pick one numbering scheme so a review comment points at a single step.
Where to go next
The AI sequence diagram generator will draft the participants from a paragraph. Tighten the arrows in the editor, and keep the arrow forms on the cheat sheet. For a longer handshake, the OAuth sequence template shows the same blocks on an authorization code flow.
If you want the maker workflow rather than the token list, start with a free sequence diagram maker. Loops are in a sequence diagram with loop, forks are in sequence diagram alt, and the tool choice is sequence diagram software.
Tips and best practices
- Declare participants up front to control their left-to-right order instead of relying on first mention.
- Use solid arrows (->>) for requests and dotted arrows (-->>) for responses to make the flow scannable.
- Turn on autonumber for diagrams that will be discussed in reviews so people can reference steps.
- Keep messages short; push details into notes so the diagram stays readable.
Generate a sequence diagram with AI
Not sure where to start? Describe what you need and the AI sequence diagram generator writes the Mermaid code for you. Try prompts like:
- “OAuth 2.0 authorization code flow with PKCE”
- “Checkout with payment provider webhook confirmation”
- “Chat message delivery with read receipts”
Sequence Diagram templates
Sequence diagram of the OAuth 2.0 authorization code flow with PKCE between user, client, authorization server and API.
Sequence diagram of a REST request through CDN, load balancer, API server, cache and database.
Sequence diagram explaining the TCP handshake, data transfer and connection teardown.
Sequence Diagram FAQ
What arrow types does a Mermaid sequence diagram support?
Common ones are ->> (solid with arrowhead), -->> (dotted with arrowhead), -> and --> (no arrowhead), -x and --x (cross), and -) / --) for asynchronous messages.
How do I show if/else logic in a sequence diagram?
Use an alt block: alt condition, the messages, else other condition, more messages, and close with end. For a single optional branch use opt ... end.
Can participants be grouped?
Yes. Wrap participant declarations in box Title ... end (optionally with a color, e.g. box Aqua Backend) to draw a labelled box around them.
How do I show an actor as a person?
Declare it with actor instead of participant, for example actor U as User.