Architecture is the default family: omit the header and you get a graph that
flows left to right, ideal for systems, services, and data flow. It shares its
grammar (nodes, groups, and edges) with flowcharts,
BPMN, org charts, and
state machines, so what you learn here carries across
all of them.
title: Image upload service
Client [browser]
API [aws/api-gateway]
Resize [aws/lambda, green]
Bucket [aws/simple-storage-service, orange]
Postgres [cylinder, blue]
Client -> API: upload
API -> Resize: invoke
Resize -> Bucket: store
Resize --> Postgres: async write
Icons, colours, and layout are the compiler's job; you write the structure.
Name [attrs] declares a node: the label is the name, the id is the slug.
id = Name [attrs] declares an explicit id.
A name first seen inside an edge is auto-declared as a plain node.
An icon on its own draws as a glyph with the label beneath it; an icon combined
with a shape or colour draws that shape, with the icon riding the corner as a
badge. See attributes for the full styling vocabulary.
[sticky] nodes render as real sticky notes; every other shape is a drawn node
in the canvas style.
Idea [sticky, yellow]
Risk [sticky, red]
Idea -> Risk: might block
Optional key lines sit at the top level, anywhere.
Directive
Values
title:
The diagram title, drawn on the wrapper frame.
direction:
right (default), down, left, up.
icons:
inside (default) or badge.
colorMode:
pastel (default), bold, outline: the default fill for every node that sets none.
left and up lay out as right and down, then mirror the result. icons sets
where every node icon renders: inside rides the icon inline before the label,
badge hangs a small square off the shape's corner.
icons: badge
Receive [aws/api-gateway]
Process [aws/lambda, green]
Store [cylinder, blue]
Receive -> Process -> Store
icons: badge hangs the pictogram off the corner instead of the default inline row.
An edge connects two names. The connector token carries the meaning.
Connector
Meaning
->
arrow
<-
arrow, reversed
<->
bidirectional
-->
dashed arrow (async or optional)
<--
dashed, reversed
<-->
dashed bidirectional
Client -> Server: request
Server --> Client: async event
Server <-> Cache: read / write
Solid, dashed, and bidirectional.
A statement is a series of hops between comma-separated name lists, read left to
right: every name in one list connects to every name in the next. That gives you
fan-out, fan-in, and chains for free.
Queue -> Worker 1, Worker 2, Worker 3
Fan-out: one source to a list of targets.
Oracle, Twitter, RSS -> Ingest -> Warehouse
Fan-in, then a chain: A, B, C all reach Ingest, which reaches Warehouse.
Nodes may declare their attributes the first time they appear inside an edge:
An attribute list at the very end of a statement, after the label, belongs to
the edge. [red] colours the arrow; [flow] animates it as a live data flow:
travelling dots on a solid line, marching dashes on a dashed one;
[head: circle] and [head: cross] change the mark at the target end, reading
as "attaches to" and "does not reach"; [invisible] ranks the layout and draws
nothing, for when one node has to sit past another without an arrow claiming a
relationship. For an unlabelled edge, anchor the attributes after a bare colon:
A -> B : [flow].