Hoe je een mermaid sequence diagram schrijft

Het minimum

Declareer het diagramtype, schrijf dan één regel per bericht. Participants worden aangemaakt bij eerste vermelding, in de volgorde waarin ze verschijnen.

sequenceDiagram
  User->>API: POST /orders
  API->>DB: INSERT order
  DB-->>API: order id
  API-->>User: 201 Created

💡Declareer participants expliciet met participant User wanneer je een specifieke volgorde van links naar rechts wilt, in plaats van de volgorde van eerste vermelding.

Pijltypes

De conventie die het waard is om aan te houden: doorgetrokken voor de aanroep, gestippeld voor het antwoord. Een lezer kan dan een verzoek van een antwoord onderscheiden zonder ook maar één label te lezen.

Participants en aliassen

sequenceDiagram
  participant U as Browser
  participant A as API gateway
  participant S as Order service
  U->>A: GET /orders
  A->>S: list(userId)
  S-->>A: orders
  A-->>U: 200 OK

Gebruik actor U as Browser in plaats van participant om een stokfiguur te tekenen — de moeite waard voor de mens aan de linkerrand van een authenticatieflow.

Activatiebalken

Activatiebalken laten zien hoe lang een participant bezig is. Markeer ze expliciet met activate/deactivate, of voeg + en - toe aan de pijlen, wat korter is en minder snel uit balans raakt.

sequenceDiagram
  User->>+API: POST /pay
  API->>+Bank: charge
  Bank-->>-API: authorised
  API-->>-User: receipt

Loops, voorwaarden en parallel werk

sequenceDiagram
  User->>API: POST /import
  loop every row
    API->>DB: upsert row
  end
  alt all rows valid
    API-->>User: 200 OK
  else some failed
    API-->>User: 422 with errors
  end
  par notify
    API->>Email: send summary
  and audit
    API->>Log: write entry
  end

• loop <label> … end — herhaling.
• alt <label> … else <label> … end — elkaar uitsluitende vertakkingen.
• opt <label> … end — een vertakking die simpelweg niet hoeft te gebeuren.
• par <label> … and <label> … end — dingen die tegelijk gebeuren.
• critical / break — een sectie die niet onderbroken mag worden, en een vroegtijdige uitgang.

Notities

sequenceDiagram
  User->>API: POST /login
  Note right of API: Rate limited<br>5 per minute
  API-->>User: token
  Note over User,API: Token is valid for 30 days

Note over A,B overspant twee participants en is de juiste plek voor een beperking die bij de interactie hoort in plaats van bij een van beide kanten ervan.

Een volledig voorbeeld

sequenceDiagram
  actor U as User
  participant A as App
  participant P as Provider
  U->>+A: Click "Sign in"
  A-->>-U: Redirect to provider
  U->>+P: Authorise
  P-->>-U: Redirect back with code
  U->>+A: GET /callback?code=…
  A->>+P: Exchange code for token
  P-->>-A: access token
  Note right of A: Session cookie set here
  A-->>-U: Signed in