Control Flow

Add loops, conditions, and other control structures to sequences.

Loops

Repeat a section of messages:

@seq
[participants]
  client:Client
  api:API
  db:Database

[messages]
  client->api:GET /items?page=1

  [loop: for each page]
    api->db:SELECT ... LIMIT 10
    db-->api:rows
  [end]

  api-->client:all items

Rendered diagram

Conditions (Alt)

Show alternative paths:

@seq
[participants]
  client:Client
  api:API
  cache:Cache
  db:Database

[messages]
  client->api:GET /user/123

  [alt: cache hit]
    api->cache:GET user:123
    cache-->api:cached user
  [else: cache miss]
    api->db:SELECT user
    db-->api:user
    api->cache:SET user:123
  [end]

  api-->client:user data

Rendered diagram

Optional (Opt)

Conditional execution:

@seq
[participants]
  api:API
  validator:Validator
  db:Database

[messages]
  [opt: if validation enabled]
    api->validator:Validate input
    validator-->api:OK
  [end]

  api->db:Save data

Rendered diagram

Parallel (Par)

Concurrent execution:

@seq
[participants]
  api:API
  users:Users
  orders:Orders
  inventory:Inventory

[messages]
  [par]
    api->users:Get user
    users-->api:user
  [and]
    api->orders:Get orders
    orders-->api:orders
  [and]
    api->inventory:Check stock
    inventory-->api:stock
  [end]

Rendered diagram

Notes

Add explanatory notes:

@seq
[participants]
  client:Client
  api:API

[messages]
  client->api:Request

  [note: over api]
    Processing may take
    up to 30 seconds
  [end]

  api-->client:Response

Rendered diagram

Full Example

@seq
[participants]
  user:User|actor
  app:App|client
  api:Gateway|service
  auth:Auth|service
  db:Database|database

[messages]
  user->app:Login

  [alt: has saved credentials]
    app->app:Load saved token
    app->api:Validate token
    api->auth:Check token
    auth-->api:Valid
  [else: no credentials]
    app-->user:Show login form
    user->app:Enter credentials
    app->api:POST /login
    api->auth:Authenticate
    auth->db:Check user
    db-->auth:User found

    [opt: 2FA enabled]
      auth-->api:Requires 2FA
      api-->app:Need 2FA
      app-->user:Enter code
      user->app:2FA code
      app->api:Verify 2FA
      api->auth:Check 2FA
    [end]

    auth-->api:Token
  [end]

  api-->app:Authenticated
  app-->user:Welcome!

Rendered diagram

Next Steps

• Examples - Complete sequence diagrams