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 |
| type decision "In stock?" | Diamond, for a yes/no branch. diamond works too |
| type group Backend | A labelled box around other nodes. See Groups |
| type origin Request | Circle, for where a flow starts. circle works too |
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.
A <-> B: sync
Two-way
One arrow with a head at each end, for a back-and-forth relationship.
A goes to B: label
Words instead of an arrow
"goes to" reads the same as ->, as long as it comes before the colon.
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".
Two arrows between the same boxes
Give the same pair of boxes two arrows with different labels and you get two parallel arrows, one per label. Repeat an arrow with the same label and it's drawn once.
Client -> API: request Client -> API: retry
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
Groups
A group is a labelled box drawn around nodes that belong together: a service and its components, a tier, a team, a cloud account. Declare the group, then say what's inside it.
type group "Auth Backend" Customer -> Auth API: log in Auth API -> "User DB": check password Auth API -> "Session Store": create session Auth API, "User DB", "Session Store" in "Auth Backend"
| Syntax | Description |
|---|---|
| type group Backend | Declares a group. Its name is shown on the box's top-left corner |
| API, Worker in Backend | Puts one or more nodes, separated by commas, into a declared group |
| Worker belongs to Backend | Long form of in. Creates the group if you haven't declared it |
| Backend belongs to "AWS" | Groups nest: a group can sit inside another group |
Where you put the membership line doesn't matter. Top of the file, bottom, or next to the arrows it relates to, the diagram comes out the same. A node sits in one group at a time, and when you drag a node in the editor its box stretches to follow.
Tip: in only means membership when the name after it is a group you declared, so a node called Sign in Page is still just a node.
There's a worked example on the web app architecture diagram page, with three tiers drawn as groups.
Short Names
Long names get tiring to retype. Give a node a short name with as, use the short name in your arrows, and the diagram still shows the full one.
type actor Customer as c Auth Backend as AB type database "User DB" as db c -> AB: log in AB -> db: look up user AB -> c: session token
It works with or without a type, and for groups too (type group "Auth Backend" as AB). Three rules:
- A short name gets its own line. Writing
Auth Backend as AB -> dbinside an arrow isn't supported. - The short name never appears in the picture. It only stands in for the full name while you type.
- If a real node name contains the word "as", quote it so it isn't read as a short name:
"Sign in as guest".
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, type database Name (or db / storage) for a cylinder, type decision Name for a diamond, type origin Name for a starting circle, and type group Name for a labelled box around other nodes.
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 do I draw a box around several nodes?
Declare a group with type group Backend and list its members: API, Worker in Backend. The box is drawn around them with the group's name on its corner. See Groups.
Can I use a short name instead of typing a long one every time?
Yes. Auth Backend as AB on its own line lets you write AB in arrows while the diagram shows "Auth Backend". See Short Names.
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.