# Sequence diagram

The most consistently useful UML diagram. It answers a question people ask constantly: what actually happens when someone does this?

It ages well too, because interactions change less often than structures.

---

## When to draw one

* API and integration documentation.
* Debugging discussions, where the order is the argument.
* Design reviews of anything asynchronous.

---

## What is on the diagram

| **Element**    | **Meaning**                              |
| -------------- | ---------------------------------------- |
| Participant    | A service, component or person           |
| Solid arrow    | A call                                   |
| Dashed arrow   | A return                                 |
| Activation     | The bar showing a participant is busy    |
| alt, opt, loop | Alternatives, optional steps, repetition |
| Note           | Commentary anchored to participants      |

---

## A worked example

A login flow with an alternative path and a loop:

![Sequence diagram](https://help.gocapable.com/images/att1418133521.svg)

The source, which you can paste into a new diagram and edit:

```
sequenceDiagram
  autonumber
  actor U as User
  participant A as App
  participant S as Auth service
  participant D as Directory

  U->>A: Enter credentials
  activate A
  A->>S: POST /token
  activate S
  S->>D: Verify credentials
  D-->>S: Verified

  alt MFA required
    S-->>A: MFA challenge
    A-->>U: Enter code
    U->>A: Code
    A->>S: POST /token/mfa
  else No MFA
    Note over S: Straight to token issue
  end

  S-->>A: JWT (15 min)
  deactivate S
  A-->>U: Signed in
  deactivate A

  loop Every 14 minutes
    A->>S: Refresh token
    S-->>A: New JWT
  end
```

---

## A few things that catch people out

* Put the actor on the left and work rightwards. Readers expect the initiator first.
* Show the failure path in an alt block; happy-path-only sequence diagrams miss the interesting part.
* Note over is the right place for timing, expiry and retry rules.

---

## Related

[Use case diagramActors, a boundary, and what the system does for them.](https://help.gocapable.com/diagrams/use-case-diagram.html)

[Activity diagramFlow with forks, joins and partitions.](https://help.gocapable.com/diagrams/activity-diagram.html)

[UML diagramsBack to the UML overview.](https://help.gocapable.com/diagrams/uml-diagrams.html)

---

_Four types cover most of it._