💬 Mermaid

Sequence diagram

Show how systems and people talk to each other

Open this example in the editor Generate one with AI

What is a Sequence diagram?

A sequence diagram shows messages exchanged between participants over time: API calls, authentication flows, microservice communication. It is the standard way to document interactions in software architecture.

Sequence diagrams earn their place in design reviews and incident write-ups, where the question is always the same: who called whom, in what order, and what came back. Nothing shows an ordering bug or a missing timeout faster. What they cannot show is state — a lifeline says a participant is busy, never which of its internal states it is in, or what it remembers between two runs.

Live example

Mermaid code

sequenceDiagram
    autonumber
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /login
    A->>D: SELECT user
    D-->>A: user row
    A-->>U: 200 + JWT token
    U->>A: GET /profile (Bearer)
    A-->>U: 200 profile

Live example

When to use it

Document API flows, authentication and payment protocols

Design microservice interactions before implementation

Debug production incidents by mapping the actual call chain

Common mistakes

Activations left open

Every + needs a matching -, and every activate a deactivate. An unbalanced pair either draws a bar running to the bottom of the diagram or fails with “Trying to inactivate an inactive participant”.

Participant order is declaration order

Mermaid places participants left to right in the order it first meets them, so one mentioned only in an error branch lands on the far right. Declare every participant line up front, in the order you want them drawn.

A single arrow is not a call

A->B draws a solid line with no arrowhead, which reads as if nothing happened. Synchronous calls are ->>, replies -->>, and fire-and-forget messages -). The dashes only set the line style; the head carries the meaning.

Basic syntax

.mmd

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Sync request
    B-->>A: Async response

sequenceDiagram autonumber
autonumber prefixes every message with a number, so reviewers can refer to “step 4” in a comment instead of describing which arrow they mean.
U->>+API: POST /orders API-->>-U: 201 Created
A + on an arrow opens an activation bar on the receiver and a - closes it, showing exactly how long each participant stays busy handling the call.
note over API,DB: single transaction
Notes carry the detail arrows cannot: transaction boundaries, retry policy, timeouts. Use note left of or note right of to attach one to a single participant.
box Payment domain participant PSP end
A box draws a labelled frame around participants belonging to the same system or team. Put a colour name before the label to tint the frame.

Questions about this diagram

What do the arrow types mean in a Mermaid sequence diagram?

Solid arrows (->>) are synchronous calls, dashed arrows (-->>) are responses or async messages. Activations show when a participant is busy processing.

Can I show loops and conditions?

Yes — Mermaid supports loop, alt (if/else), opt (optional) and par (parallel) blocks to express real-world protocol logic.

Can I put a sequence diagram in a GitHub pull request description?

Yes — paste the code in a fenced block tagged mermaid and GitHub renders it inline in pull requests, issues and comments. Unlike a screenshot, the diagram then diffs as text on the next change.

Can a Mermaid sequence diagram show elapsed time or latency?

No. The vertical axis is order only — there is no time scale, so two arrows a millisecond apart look identical to two an hour apart. Put the number in a note, or use a Gantt chart when duration is the point.

How do I show a participant that only exists for part of the flow?

Declare it where it appears with create participant Worker, and end it with destroy Worker. The lifeline then starts at the creating message and finishes on a cross, which is how you draw a job, a session or a temporary process.

How do I highlight a group of messages?

Wrap them in rect rgb(240,240,255) … end to shade the background, which is useful for marking a retry block or a transaction. Rect blocks nest, so a retry inside a transaction still reads. The loop, alt and opt blocks draw their own labelled frame.

Sequence diagram or another diagram type?

Sequence diagram or flowchart?

Count the systems. One process running inside one component is a flowchart; two or more participants exchanging messages is a sequence diagram. If you catch yourself writing “Service B receives…” inside a flowchart box, switch — lifelines do that work for you.

Sequence diagram or state diagram?

Both describe behaviour over time. A sequence diagram follows one run through the system and shows the traffic between participants; a state diagram covers every run of one participant and shows what it remembers. Debug with the first, specify with the second.

Explore other diagram types

🔀 Flowchart 🧩 Class diagram 🗄️ Entity-relationship diagram 🔄 State diagram 📅 Gantt chart 🥧 Pie chart 🧠 Mind map 🌿 Git graph 🕰️ Timeline 🚶 User journey 🎯 Quadrant chart

Create your Sequence diagram now

Describe it in plain language — the AI writes the Mermaid code for you.

Open Mermaid Studio