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

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.

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

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.

Client -> Server: request
Server --> Client: async event
Server <-> Cache: read / write

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

Oracle, Twitter, RSS -> Ingest -> 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; [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].

User -> Payments: charge card [red]
Payments -> Ledger : [flow]
Ledger -> Archive: nightly [head: circle]

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