Architecture diagrams

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.

Nodes#

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

Directives#

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:`	`badge` (default) or `inside`.
`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: badge hangs a small square off the shape's corner, inside rides the icon inline before the label.

icons: inside

Receive [aws/api-gateway]
Process [aws/lambda, green]
Store [cylinder, blue]

Receive -> Process -> Store

icons: inside puts the pictogram before the label instead of hanging it off the corner.

Groups and frames#

A group wraps members in a container. Members are node declarations, or references to nodes declared elsewhere, separated by newlines or commas.

Group attributes: colour, icon, and frame. A frame of browser, phone, tablet, or window draws the container as device chrome instead of a tinted box.
Groups nest: a group inside a group draws as a frame inside its parent's frame, and layout contracts the containers so nothing overlaps.
A node can also join a group from its own declaration with [group: Name].

group VPC [violet] {
  API Gateway [aws/api-gateway]
  Resize fn [aws/lambda, green]
  Workers [server]
}
Postgres [cylinder, blue]

Resize fn -> Postgres
Workers -> Postgres

Edges#

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:

Backend [server, blue] -> Client [browser]
Backend --> Cache [cylinder, red]: warm

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. For an unlabelled edge, anchor the attributes after a bare colon: A -> B : [flow].

User -> Payments: charge card [red]
Payments -> Ledger : [flow]

[red] colours the edge; [flow] marks a live data flow that animates on the canvas.

A three-tier web application, grouped by layer, with an animated request path and a legend.

title: Three-tier web app
direction: right

group Edge [gray] {
  Browser [browser]
  CDN [cloud, blue]
}
group Application [violet] {
  LB [server, teal]
  API 1 [server, green]
  API 2 [server, green]
}
group Data [blue] {
  Primary [cylinder, blue]
  Replica [cylinder, gray]
  Cache [cylinder, red]
}

Browser -> CDN -> LB
LB -> API 1, API 2
API 1, API 2 -> Cache : [flow]
API 1, API 2 -> Primary
Primary --> Replica: replicate

legend {
  green: Stateless
  blue: Storage
  -->: Async
}

An event-driven pipeline with cloud icons and a fan-out to workers.

title: Event pipeline

Producer [aws/api-gateway]
Topic [aws/simple-queue-service, orange]
Fn A [aws/lambda, green]
Fn B [aws/lambda, green]
Warehouse [aws/simple-storage-service, blue]
Alerts [aws/simple-notification-service, red]

Producer -> Topic
Topic -> Fn A, Fn B
Fn A --> Warehouse: batch [flow]
Fn B --> Alerts: notify