Docs / Writing diagrams
Lanes and arrows
Lanes are the columns, arrows are the calls between them.
Lanes
A lane is one participant in the flow: a person, a browser, a service, a queue, a database or a third party. Each lane is a column with a vertical lifeline, and arrows between lifelines are the messages.
You never declare a lane. It appears the first time a message, a note or an order: line names it:
Browser -> Shop: Open the checkout page
Shop -> Payments: Create a chargeThat is three lanes: Browser, Shop and Payments. Names are matched exactly, so Auth Server and Auth server are two different lanes. When the editor suggests a lane name as you type, accepting it avoids that mistake. See Writing in the editor.
Lane names can contain spaces, digits and most punctuation. They cannot contain commas or colons, cannot start with //, and cannot contain anything that reads as an arrow.
Ordering lanes
By default, lanes appear left to right in the order they are first named. To choose the order yourself, add an order: line, usually near the top:
order: Browser, Shop, Payments, DatabaseLanes the order: line leaves out follow in the order they first appear. You can also move lanes without typing: open the lane's menu in the diagram and choose Move left or Move right (the menu names the lane, as in Move Shop left). Volley writes or updates the order: line for you. See Reading a diagram.
Renaming a lane
To rename a lane everywhere at once, open its menu in the diagram and choose Rename. Every message, note and order: line that names it is updated in one step, and you can undo it from the notice that appears.
Messages
A message is one arrow from one lane to another:
App -> Auth Server: POST /tokenThe part before the first colon holds the two lanes and the arrow. Everything after it is the message text, which can contain Markdown, more colons, and even arrows. The text is optional.
Arrow styles
title: Arrow styles
order: A, B
A -> B: -> request
B --> A: --> response
A => B: => bold
A ->> B: ->> open head
A -x B: -x lost
A <-> B: <-> both ways
A <- B: <- written right to left
A -> A: -> self message
| Arrow | Use it for |
|---|---|
-> | A call or request. The default. |
--> | A reply. Dashed arrows are paired with the request they answer, as described below. |
=> | A step you want to stand out. |
->> | An asynchronous message: an event, a queued job, a webhook. |
-x | A message that is lost, times out or fails before it arrives. |
<-> | Traffic in both directions, such as a WebSocket or a sync. |
<- | A message from the right lane to the left one, when the sentence reads better that way. A <- B: push is a message from B to A. |
The pieces combine: the line is -, -- or =, and each end can be >, >> or x. So -->>, =>>, <--> and <=> all work. Write arrows with x heads with spaces around them.
Self messages
When a lane does work on its own, point the arrow back at it:
Orders -> Orders: Validate the cartReplies and response pairing
A dashed arrow answers the most recent unanswered solid or bold arrow that went the other way between the same two lanes. Volley links the two:
- Selecting the request highlights its reply, and the other way round.
- The inspector shows Responds to on the reply and Response on the request, with links between them.
- If the request has no
out:block of its own, the inspector shows the reply's output under the request, so readers find the response either way.
App -> API: GET /me
API -> Database: SELECT user
Database --> API: row
API --> App: 200 OKHere row answers SELECT user, and 200 OK answers GET /me, because the inner request was already answered.
Inside an if section, each branch can answer the same request. This is how you show a success and an error response to one call:
title: One request, two possible replies
App -> Auth Server: POST /token
if: Valid code
Auth Server --> App: 200 OK
out: Token
```json
{ "access_token": "eyJhbGciOi...", "expires_in": 3600 }
```
else: Expired code
Auth Server --> App: 400 Bad Request
out: Error
```json
{ "error": "invalid_grant" }
```
end
Pairing matters beyond the drawing. Update from a recording uses it to check status codes and to tell which branch the real server took.
Numbering messages
Add autonumber on its own line to number every message in order. Numbers are drawn on the arrows and used in the inspector, in exported text, and by agents.
Even without autonumber, every message has a number, starting at 1 in the order it appears in the source. That number is what the inspector shows as #3, what J and K step through, and what agents use to refer to a step.