Vloam Mermaid

Docs

Sequence diagrams

Show who sends messages to whom with participants, sync and async arrows, and short notes.

Scroll to zoom · drag to pan

A sequence diagram answers one question: who talks to whom, and in what order?

Time moves down the page. Each participant has a vertical line. Messages cross from left to right (or back again).

Start the diagram

sequenceDiagram
  participant User
  participant API
  User->>API: Request data
  API-->>User: Response

The first line must be sequenceDiagram. Then list people or systems with participant or actor.

  • participant — a system or component
  • actor — a person (drawn a bit differently)

Choose the arrow

Arrow Meaning
->> Solid line, often a call
-->> Dashed line, often a reply
-> Solid line without a filled arrowhead
--> Dashed line without a filled arrowhead

A common pattern: request with ->>, reply with -->>.

Give people short names

Long names clutter the chart. Use an alias:

sequenceDiagram
  participant FE as Front end
  participant BE as Back end
  FE->>BE: POST /login
  BE-->>FE: 200 OK

Readers see Front end. The syntax still uses FE.

Add a note

Notes explain timing or rules without fake messages:

sequenceDiagram
  participant App
  participant DB
  App->>DB: Query
  Note right of DB: Cache miss
  DB-->>App: Rows

Put the note next to the participant it describes.

Show a choice or a loop

Use alt / else for branches and loop for repeats:

sequenceDiagram
  participant Client
  participant Server
  Client->>Server: Ping
  alt Healthy
    Server-->>Client: OK
  else Down
    Server-->>Client: Error
  end

Keep these blocks short. Nested alt blocks get hard to read fast.

Writing tips

  • Name participants after real roles: User, Editor, Auth.
  • One message = one clear action.
  • If two systems chat more than six times, split the story into two diagrams.