Title
Add a title to your diagram with the title keyword on its own line. It appears at the top of the rendered diagram.
title User Login Flow
The title is optional. It does make the PNG self-explanatory when it lands in Slack though, so it's usually worth the one line.
Node Shapes
Boxes are the default. You only declare a type when you want something that isn't a box.
| Syntax | Description |
|---|---|
| Web App | A plain box. The default, no declaration needed |
| type actor Customer | Stick figure, for people and external agents |
| type database "Orders DB" | Cylinder, for databases and storage |
| type db Cache | db and storage are aliases for database |
Example
type actor Customer type database "Orders DB" Customer -> Web App: browse & checkout Web App -> "Orders DB": save order
Tip: declarations can go anywhere in the source, before or after the node first shows up. The parser doesn't care about order.
Arrows & Chains
An arrow connects two nodes: Sender -> Receiver: label. The label after the colon is optional.
A -> B: label
Single step
One arrow, one label, straightforward.
A -> B -> C: label
Multi-hop chain
Draws A→B and B→C in one line. The label applies to both arrows.
A -> B
No label
No label needed. Just the connection.
Chaining across an entire flow
Chains are what make this quicker than a drawing tool. One line, whole pipeline:
App -> Backend -> Downstream Service -> Downstream Database: save data
That single line draws four boxes and three arrows, all labelled "save data".
Same arrow, new label
Write the same arrow twice and the newer label wins. Handy when you're reworking a flow you sketched five minutes ago.
A -> B: first label A -> B: this one shows
Naming & Quotes
Multi-word names mostly work without quotes. Quote them when something could misread, or when you just want to be explicit.
# works without quotes Order Service -> Payment Service: charge card # quoted for clarity "Auth API" -> "User DB": look up user
Quoted or not, the same name means the same box. Mixing styles won't create duplicates.
Standalone nodes
You can also declare a node before wiring it to anything:
type database Cache
Cache
Comments
Lines starting with # or // are ignored. Notes to yourself, basically.
# this line is ignored // so is this one Customer -> Web App: checkout
Full Example
Everything above, in one small e-commerce flow:
title E-Commerce Order Flow type actor Customer type database "Orders DB" Customer -> Web App -> API Gateway: place order API Gateway -> Order Service: create order Order Service -> "Orders DB": save order Order Service -> Payment Service: charge card Payment Service -> Order Service: payment ok Order Service -> Customer: order confirmed
Open the editor → and paste this to see it render live.
See syntax in real-world diagrams
All of it shows up in the ready-made examples. Open one and poke at the source:
Frequently asked questions
How do you write a flow diagram in plain text?
Write one arrow per line: A -> B: label. Optionally add title Your Title at the top and type actor / type database declarations for non-default shapes.
How do I chain multiple steps in one line?
Use several arrows in a row: App -> Backend -> Database: save data. The label applies to every arrow in the chain, which is most of the trick to sketching a pipeline fast.
What node shapes are available?
Boxes are the default. Use type actor Name for a stick figure, and type database Name (or db / storage) for a cylinder-shaped data store.
Do I need quotes around node names?
Only when it helps. Multi-word names generally work unquoted. Quoting, like "Auth API" -> "User DB", makes the boundaries obvious and is never wrong.
How many nodes can a diagram have?
No hard limit. The layout is happiest under fifteen or so nodes though. Past that, split the flow in two and your readers will thank you.