Swimlane diagrams

TL;DR

Ask your agent

Say who the actors are and what each one does, in order, then ask for an icon on every step and a color for each outcome. The agent writes the rest.

Use Plotwork to draw how an online order is fulfilled as a swimlane diagram with four lanes: Customer, Web app, Payments, and Warehouse. The customer places an order, the web app checks stock, and if the item is sold out the order is cancelled. Otherwise Payments charges the card. A declined card shows an error and the customer updates the card, and then Payments tries again. Once paid, the warehouse packs and ships the order, and the customer sees it delivered. Give every step an icon, and color the cancelled order red and the delivered order green.

Use Plotwork to draw an OAuth sign-in as a swimlane diagram with four lanes: Browser, App, Identity provider, and API. The browser opens the app, which redirects it to the identity provider. The user approves access, the provider sends back an authorization code, and the app exchanges it for a token. If the token is valid, the API returns the profile and the browser shows that the user is signed in. Otherwise access is denied. Use a dashed line for the reply from the API.

Use Plotwork to draw our incident response as a swimlane diagram with three lanes: On-call, Support, and Engineering. An alert wakes the on-call engineer, who triages it. If customers are affected, Support notifies them and posts updates, and pages an engineer. Engineering ships the fix and writes the review, and the incident closes when both the updates and the review are done.

Use Plotwork to draw a nightly data pipeline as a swimlane diagram with the lanes Scheduler, Queue, and Worker. The scheduler exports the orders and puts a batch on the queue, and the worker transforms the rows. A valid batch is loaded into the warehouse, which acknowledges the scheduler, and an invalid one goes to a dead letter queue. Show the hand-offs through the queue as events, and the acknowledgement as a reply.

Example

This is the order fulfilment from the first prompt. It shows four lanes, a decision whose branches carry a condition, a transition that returns to an earlier step (the card is tried again), a step with a detail line, and green and red ends. The diagram is narrow enough to read in a Markdown column, so the lanes are drawn as columns.

PictureSourceOutline

Make it readable

A swimlane reads fastest when the lanes say who acts, the cards say what they do, and the colors say how it went. Four habits do that, and an agent can write all of them in one line per step, as the order fulfilment above does.

Keep a step name to a few words and move detail into sub=. Text wider than a card or a label is cut with warning W203. Do not rely on color alone: the name and the icon say the same thing, so the diagram still reads for someone who cannot tell two tones apart.

Sign in through an identity provider

A sign-in crosses four lanes, and every transition between two of them is a hand-off. The reply from the API is dashed, and the invalid token ends in a red step.

PictureSourceOutline

An incident response

An incident response branches on one question and then runs two lanes side by side. The decision's two ways out leave from different sides of the pill, and the incident closes only when both the updates and the review have arrived.

PictureSourceOutline

A data pipeline with asynchronous hand-offs

A pipeline passes work through a queue, so the hand-offs are events. This one reads as bands, because direction=right is written in the header and the process is short enough to fit. A dotted line is an event, a dashed line is a reply, and the dead letter is red, so the line that reaches it is red too.

PictureSourceOutline

The language

A line is one statement. A # starts a comment. Ids are words such as check, in-stock or _x, labels are in double quotes, and options are written key=value. The first line is the header.

The header

swimlane "Order fulfilment" direction=right numbered=on desc="How an order moves from the shop to the customer."

Statements

tone= takes neutral, blue, violet, aqua, orange, green, amber, or red, and icon= takes a name from the closed list of icons, such as lucide:user, status:success or simple:github. A diagram cannot set a color: the theme chooses every color, in light and dark.

Lanes

A step belongs to the lane it is written in, and a step outside every lane is an error. The lanes stack in the order written, and the first is the top lane, or the left one. A lane draws its icon and its name in a rail at its start, and a tone= on the lane gives its rail and its band a color. The bands alternate in shade, so neighbours part without a heavy line.

1lane warehouse "Warehouse" tone=orange icon=lucide:warehouse {2  step pack "Pack order" icon=lucide:package-check3  step ship "Ship order" icon=lucide:send4}

A lane is for an actor, so a lane that holds no step is warning W201. Ids are shared by lanes and steps, so a lane and a step cannot have the same id.

Transitions and their labels

A transition is one line, from -> to, and a label after a colon. The three arrows say what the line means.

The label of a transition reads event [guard] / action, as in a state diagram. The picture draws the event as plain text, the guard as a tinted tag with a branch icon, and the action after a bolt icon, and the text description says "on the event, if the guard, then the action".

Use a guard on every branch out of a decision, because the condition then reads as one. A transition may return to an earlier step, as card -> charge : "retry" does above, and it may join two steps in one lane. It may not join a step to itself, because a loop is drawn through a second step. Text wider than 200 px is cut with an ellipsis and warning W203; the full text stays in the text description.

Which way it reads

A process of more than five steps in a row is wider than a Markdown column as bands and narrower as columns, so auto turns it into columns. That is warning W202 when you ask for right yourself.

Numbered transitions

Add numbered=on to the header and every transition gets a numbered badge, in the order written, so people can say "step 4" aloud. A transition with no label shows the badge alone on its line, and one with a label carries it in the left end of its pill. Write step=off on a transition to leave its badge out, or step=12 to give it the number 12, and the next continues from 13.

1swimlane "Checkout" numbered=on2
3lane shopper "Shopper" icon=lucide:user {4  step cart "Fill the cart" icon=lucide:check5}6lane shop "Shop" icon=lucide:globe {7  step total "Compute the total" icon=lucide:receipt8}9
10cart -> total : "go to checkout"11total --> cart : "show the total"

Limits and warnings

Warnings never stop a diagram from being drawn. Errors do.

The limits are checked from the text alone, so a diagram that is too big is refused at once with a hint on how to split it. Layout is plain arithmetic over a grid, so even a diagram at the limits is laid out in a few milliseconds.

W201 covers every loose end: the message says which one it is. A step is unreachable only when the diagram has a start, because a diagram with none has no place to count from.

From Mermaid

Mermaid's swimlane syntax is not read, because Mermaid has none. People draw lanes in Mermaid with a flowchart whose subgraphs are the actors, and convert_mermaid reads that as a flow diagram with groups, which keeps the nodes and the lines but not the idea that a lane is a row of a process.

To get a swimlane from a Mermaid flowchart, convert it first, then ask an agent to rewrite the converted flow diagram: each group becomes a lane, each node a step or a decision, each terminal a start or an end, and each edge a transition. Keep the labels, and move the condition of a decision's branch into a guard in square brackets. A Mermaid sequenceDiagram is a different picture, a conversation over time, and converts to a sequence diagram.

See also