squinch
The smallest useful diagram: one system, a few components, and the connections between them. Everything else here builds on this shape.
One entry point feeding many handlers. Connections spread evenly along the edge of a node rather than stacking at a single point, so the fan stays readable. Five is enough to show the spread — a dozen only made the case too wide to read in this grid.
The reverse shape: many producers all feeding one destination. Written as separate edges rather than a fan-out list, because an edge has one source — this is what several of them arriving at one port looks like.
A pipeline read left to right. Set direction right on a view and the stages run across the page instead of down it. Five stages is what it takes to read as a chain — the eight it had before ran wider than this grid.
What happens when the names are long. Labels wrap, then trim with the full text kept for hover, and the small pills on connections step aside rather than overlapping each other.
Ten services that all talk to each other. Where wires have to cross, the crossing takes a small break so it can never be mistaken for a junction.
Containers opened up inside a system with expand. Each level of nesting sits on a slightly different surface, so depth is visible without heavy borders.
The top-level view of an estate: each system is a card, with the people and outside parties that touch it. A card carries a badge for what kind of thing it is and a preview of what is inside.
Connections between things on the same row. Neighbours join straight across; ones that reach past a node drop into a lane underneath so they never run through anything.
Annotation. highlight picks out everything carrying a tag and dims the rest, and note pins explanatory text to a node, a connection, or a corner of the diagram. Tag a connection itself and that wire lights up even when the things it joins stay dim.
Asynchronous connections, written ~>. They draw dashed and drift slowly towards their target, so an event-driven estate reads differently at a glance from a request-and-response one.
Zoomed out, several connections between the same two systems collapse into a single line with a count on it. Zoom in and the individual connections are still there.
show descriptions adds a line of explanatory text under every label.
place puts one node beside another instead of below it — the shape you want for a cache, a stream processor or a dead-letter queue that belongs next to the thing it serves.
The same diagram at all three density settings, from compact to spacious.
Footer furniture. legend auto explains the line styles the diagram actually uses and nothing else; titleblock stamps the drawing. Four keys are reserved and drawn canonically — subtitle under the title, version, mono commit and a dimmed date in the meta chip — and every other key (owner, status) appends as its own chip segment. None are ever derived: a render is a pure function of its source, so the commit is what you wrote, not what git says.
zone draws a deployment boundary — a cloud, a VPC, an on-premises site — around whatever sits inside it. Boundaries cut across the ownership structure, and they nest. detail: adds the boundary's hard fact — a CIDR block, an account — as a mono segment on the chip, so digits line up between diagrams.
flow numbers a path through the diagram, so you can show how one request actually travels. In the playground you can step through it a hop at a time.
The sys icon set: generic marks for servers, storage, networking and plain shapes, for the parts of a stack no vendor draws. Each one is shown twice, as a small badge on a card and at full size. A sample rather than the whole set.
align puts two nodes on exactly the same axis, for when the automatic layout leaves them a few pixels apart and the near-miss looks like a mistake.
The logos pack: marks for the frameworks, databases and tools that make up the half of a stack your cloud provider did not build.
channel merges several connections into one trunk where they all arrive at the same place, so a shared store is approached once instead of by a fan of near-parallel lines. The connections are still declared individually.
Every place a note can go: beside, above or below a node, attached to a connection, or pinned to one of the four corners of the diagram.
The four kinds of connection — one-way, two-way, asynchronous, and undirected — and how each one is drawn.
The lines setting, three ways over the same diagram: how an edge travels. orthogonal turns square corners, curved rounds them off, and straight runs point to point. How an edge is drawn and moves is the other axis — style: and animate:, case 29-edge-styles.
route controls which side of a node a connection leaves and enters by. When two connections join the same pair of nodes, naming one of their labels picks the one you mean.
The k8s pack: official community icons (the blue heptagons from the kubernetes docs), full-colour artwork like aws/azure — no plate, no tint. Canonical ids are kubectl's short names; the long forms alias to them, and this file deliberately uses both spellings so the case exercises the alias table. A namespace draws as a zone with icon: k8s/ns, not as a node.
The azure pack: Microsoft's official Architecture Icons — the gradient artwork is drawn raw like aws/k8s, no plate, no tint. Long marketing names alias to what people actually type (azure/vnet, azure/aks, azure/cosmos), and this file leans on those short forms. A virtual network draws as a zone with icon: azure/vnet — the chip inset that keeps full-bleed artwork off the pill border is exercised right here.
How an edge is drawn and how it moves: style: solid | dashed | dotted and animate: flow | reverse | slow | fast | packets | pulse | comet, one hub with each spoke showing one thing. Dash travel needs a pattern, so a sync edge animates by declaring style: dotted first (dashed warns beside ~> edges — it is their convention); pulse breathes and works on solid lines. comet is the exception: it rides a dot along the route rather than moving the stroke, so it needs no pattern and is the way to show motion on a plain synchronous call. How an edge travels between nodes is the other axis — lines, case 25-edge-routing.
badge: puts a vendor mark on a node's icon plate. It exists because some platforms don't yet publish an official icon set that may be redistributed — Databricks is the standing example — so for now there is no pack to install. Rather than ship someone's extracted artwork, compose two things we already have a licence to: a generic sys/ concept for what the thing is, and a CC0 brand mark for whose it is*. The badge is what makes a wall of grey plates legible: every Databricks-owned box is marked, and the Kafka and S3 nodes keep their own icons, so the platform boundary reads at a glance.
expand * — the one deliberate ladder: every container open to leaf depth on one page. Frames nest to keep containment legible; only the outermost carry the recessed fill (depth would otherwise read as darkness), inner boundaries are the line and the label.
The row that used to break: expanded systems side by side with calls running between them. Same-rank cross-frame edges route wall-to-wall through reserved gutters — straight when the endpoints share a height, a mid-gutter jog when they don't (coplanar.md, approach #5). Before this, ELK saw the calls and silently re-layered the row into a stack.
The card shelf, fully loaded. icon: picks the card's own mark instead of inheriting the first child's — here a storefront glyph, deliberately not an AWS service, because the card is the system and not any one component. domain: stamps a chip on the shelf's right; past three children the preview strip truncates to +N. The second card declares neither and shows the defaults: first child's icon, no chip.
The view verbs beyond scope. only #pci keeps just the tagged slice — tags cut across systems, so no scope could ever name it. detail redraws an outside caller at its real depth instead of as its system's card. And context off clears the muted periphery when a view wants nothing but its subject.
rows pins ranks, cols pins the cross axis, and together they are the grid the language has no third construct for: rows [a b] [c] composed with cols [a c] [b] is a 2×2 with one corner empty. This is the reason the once-planned grid statement was dropped.
color: — one hue vocabulary on everything. Nine words (red, amber, green, teal, blue, violet, pink, gray, accent), never hex, each a designed pair so the same source reads right on both canvases. A leaf, a person or a system takes a spine down its left edge, an edge its stroke and head, a zone its outline. The lens view colours by tag instead — color #money red — which overrides an element's own colour and earns a legend entry per tag. Hue is annotation: async is still dashed, context still muted.
