Syntax and core ideas

The language has a small, consistent grammar. Learn these rules once and they hold across every family.

Core ideas#

Because attributes are positional, the same value means the same thing everywhere. A palette colour is always a colour, a shape word is always a shape, a set/name token is always an icon. You rarely write a key.

Cache [cylinder, red, bold]
Worker [server, green]
Queue [queue, orange, outline]

Ids are optional too. A node's name is its label, and its id is the slugified name. You only reach for an explicit id when a label is long or repeated. A name first seen inside an edge is auto-declared, so quick sketches need no declarations at all.

Frontend -> Backend -> Database

Lexical rules#

• Statements are line-oriented; they end at the newline. { … } blocks span lines.
• // starts a comment, a whole line or a trailing one.
• Blank lines are ignored.
• Names may contain spaces and most characters unquoted. Quote a name with "…" only when it contains a reserved token: ->, <->, -->, :, =, ,, [, ], {, }, or //.
• Everything after : in an edge, message, or control statement is a label. It runs to the end of the line (or to a trailing […] attribute list) and needs no quotes.

API Gateway -> Auth service    // spaces in names are fine
"A -> B" [note]                // quote a name with a reserved token
Worker -> Queue: retry with backoff, then drop   // label runs to end of line

Naming and ids#

• Name [attrs] declares a node whose label is the name and whose id is the slug of that name (API Gateway → api-gateway).
• id = Name [attrs] gives an explicit id. Reach for this when a label is long, when two nodes share a label, or when an edge would be clearer referring to a short id.
• Edges reference a node by its id or its exact name.

db = Primary datastore [cylinder, blue]
web = Web frontend [browser]

web -> db: query

Declaring the family#

The first meaningful line may declare the family. Omit it and you get architecture, a graph that flows right. Each header is documented on its own page:

flowchart        // top-down process diagram
bpmn             // swimlane process
orgchart         // reporting tree (alias: org)
statemachine     // states + transitions (aliases: state, fsm)
sequence         // lifelines and messages
erd              // entities and relationships
class            // UML class boxes (alias: uml)
wireframe        // UI mockup screens
mindmap          // central topic with branches
chart bar        // a real chart shape

Next: attributes and styling, the words that colour, shape, and decorate a node.