Layout Engine
Zindex ships with a built-in layout engine. Agents describe what the diagram contains - nodes, edges, the relationships between them - and the engine figures out where each element should sit, how each edge should route around obstacles, and where each label should land.
The engine is implemented from scratch with zero external layout dependencies. It uses a Sugiyama-style layered layout pipeline (the same family of algorithms behind tools like Graphviz and Mermaid) and runs deterministically: identical input always produces identical output.
Building an agent integration? The skill’s authoring guide covers writing scenes: element kinds, families, auto-layout, constraints, styles and icons. The Zindex skill covers the edit loop.
Why this exists
Most diagram tools assume the human knows where every box and line goes. That assumption breaks down for agents. An LLM generating an architecture diagram knows the services and the connections, but asking it to also produce pixel-perfect coordinates is asking for a worse diagram and a worse use of tokens.
The layout engine inverts the contract: agents describe the graph, the engine handles the geometry. Agents that want pixel control can still provide explicit layout on individual elements - the engine respects user-supplied positions and fills in the gaps; a later edit moves a positioned node only in the cases Positions are kept lists, such as making room for a node that grows. This mixed mode is the most common pattern in practice: pin the critical elements, let the engine arrange the rest.
What you get
- No coordinates required. Leave
layoutoff the nodes and the engine positions them.layoutStrategy: { direction: "TB" }turns the layered layout top to bottom; flowcharts run top to bottom without it. - Mixed mode. Some nodes have explicit
layout, others don’t - the engine places the others next to their neighbors and leaves the fixed nodes where they are, unless an edit needs the room or places them again (Positions are kept). A node at exactlyx: 0, y: 0counts as not placed: the engine places it and sizes it to its content, so pin a node at any other position. - Positions are kept. Nodes keep their positions after the first save, and an edit moves a placed node only in the cases Positions are kept lists. The engine records each position in the node’s
layout. New nodes are placed next to their neighbors; edges and frames are redrawn each time; sequence diagrams follow message order. SendautoLayoutto lay out again. - Smart edge routing. Edges enter the side of the target that faces the source, at its center or straight across where the nodes line up, unless an endpoint’s
anchornames the side (Where an edge enters its target), route around obstacles via step paths when an L would collide, and go around unrelated nodes wherever a route exists. When none does, the router keeps its best route even if it crosses a node.straightandcurvededges run between the nodes’ centers and end on their outlines, a curve bowing to the side that clears other nodes where one does, but neither is routed round nodes (Edge routing). - Crossings routed again. Three kinds of edge that cross another route are routed once more, at most eight per layout. Edge routing names them and the limits.
- Labels keep apart. Each placed label reserves space so later labels keep visible breathing room. When an edge has no clear place for its label, the label is wrapped narrower where that finds one, and can still overlap where it doesn’t (see label placement below). In a Google Cloud diagram the cloud layout arranges, a label also keeps 10 px from other lines and from every card but its edge’s ends, where there is room (label placement).
- Clean output. Sub-pixel artifacts are stripped from edge paths so arrow markers orient correctly.
- Deterministic. The same scene always produces the same layout - layouts are diffable and versionable.
What auto-layout handles and what it doesn’t
Auto-layout is powerful but has a specific scope. Understanding the boundary prevents frustration:
Auto-layout handles (no coordinates needed):
- Node positioning - the planner assigns x/y/width/height based on graph topology
- Edge routing - orthogonal paths with obstacle avoidance, entry at the facing side’s center or straight across, step-path fallbacks
- Edge label placement - on a stretch only its own edge draws, clear of nodes, other labels, arrowheads and ER glyphs, frame borders and other edges’ lines (12 px off) where the edge allows, longest-segment-biased, or beside its diamond for a decision’s branch
- Crossing reduction - minimizes edge crossings via median heuristic
- Aesthetic scoring - evaluates several candidates and picks the best, when the engine lays out every node
Auto-layout also handles frames and containers:
- Frames auto-size from children. Omit
layoutfrom a frame and the engine computes its bounds from the union of its children’s positions, plus padding and title reserve, made wider about its center when the title needs it. A frame with its ownlayoutkeeps that box, except where making room moves it or a member that grew, or was pushed by one, would cross its border (Making room). A pool’s or lane’slayoutis only a minimum: pools and lanes always grow to hold their members (Pools and lanes), and so do AWS and Google Cloud groups in a diagram the cloud layout arranges (AWS architecture diagrams, Google Cloud architecture diagrams). A title wider than the frame runs past its border, andTEXT_OVERFLOWgives the width it needs (not for pools and lanes, whose titles run along their header strips). Laying out every node of an architecture, flowchart, workflow, UI flow or entity-relationship diagram, or one without a family, the planner lays each frame without alayoutout with its members: they sit together in every rank they share, no other node or frame comes inside, and the frame’s padding and title get room. In a diagram with AWS Cloud, Region, VPC, Availability Zone or subnet presets, or Google Cloud’s boundary, Region or subnet presets, the cloud layout places those groups by what they are instead (AWS architecture diagrams, Google Cloud architecture diagrams). The bandsextensions.autoGroupdraws in an architecture diagram, or one without a family, are laid out the same way, apart from each other; where positions the nodes keep would make two bands overlap, none is drawn (Diagram families: Architecture). Pools and lanes are laid out with their members by rules of their own, with or without alayout(Pools and lanes). Fragments and frames inside a pool, such as a subprocess in a lane, are not laid out with their members: a frame inside a pool is fitted round its members after they are placed. Network and org chart layouts place nodes without regard to frames, so there a fitted frame can overlap another frame or take in a node that isn’t its member; the warningsFRAME_OVERLAP_DETECTEDandNODE_IN_WRONG_FRAMEsay so. A node placed later, or named inautoLayout’selements, goes clear of frames it isn’t in, and a new member of a placed frame goes inside it. Where the frame has its ownlayoutand no room is left in it clear of the frames inside it, the new member goes just outside it, still clear of every frame it isn’t in, andNODE_OUTSIDE_FRAMEsays so: make the frame bigger withresizeElement. A new frame round new nodes is placed with them, as one block, clear of the other frames. An edge between a new node and a frame places the node a rank before or after the frame, centered on it. Frames an edit adds round placed nodes are covered in Positions are kept. - Pools and lanes are laid out as BPMN tools lay them out in architecture, flowchart, workflow, entity-relationship and UI flow diagrams and diagrams without a family. Lanes run along the flow and stack across it, in the order the pool lists them; every node a lane lists is placed inside it, each lane is as deep as its contents need, and columns are shared across lanes and pools, so the flow reads as time. Their members need no positions (Pools and lanes).
- Activation bars follow their messages. In sequence diagrams, a
sequence.activationwithextensions.startsAtruns on the lifeline that message arrives at, from its arrow to the arrow ofextensions.endsAt, or one row tall withoutendsAt. A message to or from that lifeline in those rows ends at the bar’s side, so its arrowhead shows. Bars that overlap on one lifeline are stacked (Rendering: Lifeline rendering). A bar with a box and nostartsAtis drawn over the messages its box covers on the nearest lifeline, and one with neither spans the messages of the lifeline with the most. Name the messages, so the bar moves with them. - An edge with no sequence type is a message. In sequence diagrams, an edge between two participants with no
sequence.*type takes a row like asequence.*message (Rendering: Message rendering). An edge with an end that isn’t a participant gets no row: it is drawn outside the message rows, withFAMILY_SEQ_ORPHAN_MESSAGE; join it to two participants, or remove it (Validation rules). - A note with no anchor goes over the message above it. See Element types: Node types.
- Combined fragments are laid out with their rows. In sequence diagrams, a
fragmentframe runs from its first message or note to its last, with a header row above for its operator and guard, and is as wide as its rows, the bars they meet and its nested fragments need; its ownlayoutis ignored. Its edges, its guards and where they start are in Rendering: Combined fragments. Each operand (extensions.operands[]) starts at a message or note in the fragment (startsAt, after its first), and gets a dashed divider above that row with its guard under it, for every operator. - Participant boxes and highlight bands are laid out with what they hold. In sequence diagrams, any other frame is a box round the lifelines it lists or a band behind the rows it lists, and its own
layoutis ignored (Rendering: Participant boxes and highlight bands). - Fragments elsewhere. A fragment that holds no message or note isn’t drawn. Outside a sequence diagram a fragment keeps its
layout, and draws no dividers but those stored with aybefore 8.0.0. - Layers. In architecture diagrams and diagrams without a family, frames written
containerType: "layer"stack as rows in the order listed, each card in its layer’s row (Layers). - Nested frames. Frames inside frames are resolved leaf-to-root via topological sort.
What still needs explicit coordinates:
- Members of a frame with its own
layout. Laying out a new diagram, the planner places a fixed frame’s members by graph topology, not inside its box: give them positions inside it, or leave the frame’slayoutout so it fits them. Nodes that aren’t its members are kept clear of it (below). A member added later is placed inside its frame where there is room. One outside its frame gets the warningNODE_OUTSIDE_FRAME: move it inside.autoLayoutwithoutelementsdrops a frame’s ownlayoutin the families above, except a pool’s, a lane’s or a fragment’s (Laying out again).- Pools and lanes need no member positions: a pool or lane with its own
layoutgrows to hold its members (Pools and lanes). - AWS and Google Cloud groups in a diagram the cloud layout arranges need none either, and a group’s own
layoutis a minimum (AWS architecture diagrams, Google Cloud architecture diagrams).
- Text, images and a frame you place yourself: you write their coordinates, and the engine keeps nodes clear of them.
- A
textorimagealways needs alayout. With an absolute one, at coordinates from 0 on, it stays where you write it on every layout,autoLayoutincluded. Below 0 the engine shifts the whole drawing to make room. A frame with its own absolutelayoutand a size follows the frame rules above. A frame in a sequence diagram never counts, since its ownlayoutis ignored there. - On a new diagram, and for
autoLayoutwithoutelements, the engine moves the whole drawing right or down where it would cover a text, an image or a frame with its ownlayout. A frame’s own members are never kept clear of it. Pools, lanes, fragments and cloud groups the cloud layout arranges are part of the drawing, not obstacles. The drawing moves by the least distance that leaves the node spacing (30 px, orlayoutStrategy.nodeSpacing) between it and the element. A node an edit adds goes clear of the same elements. - The arrangement stays the same and moves as one. A title written at the top left puts the drawing below it. A thin note across the middle can end between two ranks, where the gap holds it with the node spacing on each side; otherwise the drawing moves right of it or below it, whichever is nearer. A drawing that doesn’t overlap the element doesn’t move, even when it stands closer than the node spacing.
- The engine doesn’t center the drawing around a text, an image or a frame with its own absolute
layout. Nodes start at the top left, unless the drawing moves clear of the element (above), and the canvas grows to hold the element (Canvas size is a minimum). - The drawing doesn’t move in three cases, so a text written over it stays over it:
- A pool or lane with a
layoutof its own anchors the drawing at its corner. - A sequence diagram’s participants, messages and fragments are placed from the order you write them.
- A node you give a position stays there.
- A pool or lane with a
- With a pool or lane that has a
layout, or nodes you positioned, create the diagram, read the positions withdiagram_get(view: "dsp"), then add the text in the space they leave. - A sequence diagram’s nodes stay at
x: 0, y: 0, so the dsp view shows no positions. Read where they are drawn in the SVG thatdiagram_renderlinks to, where each element is a group named by its id, then write the text right of the last lifeline: the image grows to hold it. A text written below the last message makes every lifeline run down to it.
- A
- Regions on a named side - grouping nodes into regions needs no coordinates: put each region’s nodes in a frame without a
layout, and the planner keeps them together (in the families above). Which side each region lands on follows the flow of the graph; anorderconstraint between nodes of two frames (for exampleleftOf) orders the frames too. For an arrangement beyond that (e.g. “frontend on the left, backend on the right” against the flow), give coordinates. AWS and Google Cloud groups are the exception: the cloud layout places each by what it is, AWS’s Availability Zones as columns and subnets as rows (AWS architecture diagrams), Google’s zones as columns and tiers as rows (Google Cloud architecture diagrams). - Custom spatial relationships beyond what the constraint solver handles. Note: the engine supports hard ordering constraints via
type: "order"(with relationsabove,below,leftOf,rightOf,sameRank) that agents can use to control rank and position ordering when the engine lays out every node, and on a saved diagram, where adding one places its two nodes again when they aren’t already in that order. For relationships not expressible as pairwise ordering, explicit coordinates are still needed.
The rule of thumb: omit coordinates from everything. The engine auto-positions nodes, edges, frames, activation bars, and fragments. Provide explicit layout only when you need pixel-precise control or a specific spatial arrangement the planner can’t infer from the graph structure.
Positions are kept
A saved diagram’s nodes stay where they are, unless:
- a node grows into them (Making room)
- a new node’s edge label needs more room than the column it joins (below)
- a new task in a pool needs room in its lane or a column of its own (Pools and lanes)
- a node an edit inserts in a flowchart, between two placed nodes, needs room along the flow (below)
- a node an edit adds to a frame without a
layouthas no room there that keeps the frames round it clear of what lies beside them (below) - an AWS diagram’s row or column grows for a node or a spanning frame’s header an edit adds, or for the room round a tier frame (AWS architecture diagrams)
- an edit moves an AWS Region’s column right to keep a labeled line into it clear
- a Google Cloud diagram (Google Cloud architecture diagrams):
- a row, zone column, Region or project’s box grows for what an edit adds or for a group’s title it widens
- a gap opens between two Regions, two projects or two zone columns
- sibling projects’ boxes saved overlapping are cleared: the later project, and what lies right of it, move right
- a line crosses an item in a row, or moves an item under it
- a Region saved with less than 24 px under what it holds is drawn lower, and the rows under the Regions move down with it, before any edit: it happens on any draw
- an edit moves one to another lane
- a stack of layers (Layers): a layer grows for a row, a taller card or a sub-group a card joins, or a layer is added, and what follows it along the flow moves; a card that grows wider moves the cards after it in its row
- an edit that adds or deletes a frame, or adds an
orderconstraint, places them again (below)
The engine records each position it chooses in the node’s layout, and every later edit starts from those positions:
- New nodes are placed next to their neighbors, clear of the other nodes, which move only in the cases above. For a new node’s edge label, a node inserted in a flowchart and a new member of a crowded frame, only nodes an edit adds move others: nodes placed on a first save or by
autoLayout’selementsmove none. There a frame with its ownlayoutpast the line moves, one across it grows, as a pool or lane does, and a fragment with its ownlayoutacross it keeps everything where it is. The save’schangedlists the nodes that moved, and a compare lists them as changed. - Room for a new node’s edge label. A new node often joins the nearest existing column (or row, in
TBandBT), whose gap was sized for the labels already there. When its edge label would cross a frame’s border or cover a node or arrowhead in that gap, the column and everything beyond it, away from the new node’s neighbor, move just far enough for the label to sit clear. Nodes on the neighbor’s side don’t move. - Nodes inserted in a flowchart. New nodes between two placed nodes go on the first one’s line, just past it, and every node in the ranks after it moves along the flow just far enough for them. Nodes before them stay, and room a deleted node left counts, so a step that replaces one takes its place. This holds when any exit but a decision’s way aside enters them and they lead to a placed node further along the flow, in a flowchart whose frames, if any, have their own
layout. A new way aside goes beside its decision instead (right inTBandBT, below inLRandRL), moving nothing but what its edge label needs (above). - A new member of a crowded frame. In architecture, flowchart, workflow, entity-relationship and UI flow diagrams and those without a family, a new node goes inside the frames that hold it, and each of those without a
layoutgrows round it by its padding and title. AWS and Google Cloud diagrams place only nodes outside their arrangement this way. Where no place keeps those frames clear of the frames and nodes beside them, the node goes past the frame’s members in its column: below them inLRandRL, right of them inTBandBT. The frame grows, everything past its far border moves across the flow by the growth, and the frames round it grow with it. - A card in a stack of layers is placed as Layers says, not by the rule above.
- A node whose content changes (label, shape, type, icon, columns, text style or font) is measured again and resized where it stands, by the rule in Element types: Nodes the engine places. A node whose label is set to wrap (
textStyle.wrap"word"or"character") keeps itswidth, and itsheighttoo unless its layout hasautoSize: "content", which grows it down to the height its label and icon need. If it grows into its neighbors, the engine pushes them out of the way (see Making room). - A deleted node leaves its space, and the canvas doesn’t shrink.
- Edges, labels and frames are redrawn from the node positions every time, and the engine stores none of them. A frame with a
layoutof its own keeps it, unless making room grows or moves it. - Frames an edit adds or deletes. A
createFramethat lists placed nodes leaves them where they are, and so does deleting the frame that held them. The exception is a frame that, fitted round them where they are, would overlap another frame or hold a node that isn’t its member, or a node that would lie inside a frame it isn’t in. The engine places those nodes again, together, as it places new nodes, clear of the other frames and nodes. The save’schangedlists them. A placed node an edit puts in a lane, by creating the lane round it or withupdateNode’sframe, is always placed again, inside its lane, in its column. A node whoselayoutthe same edit sets stays where the edit puts it. A frame with its ownlayoutkeeps its box wherever its members are, so its overlaps are left toFRAME_OVERLAP_DETECTEDandNODE_IN_WRONG_FRAME. So are the overlaps a saved diagram already has: an edit that adds or deletes no frame moves none of their nodes. SendautoLayoutto lay such a diagram out again with its frames apart. - An
orderconstraint an edit adds. When its two nodes are placed and don’t already stand that way around, the engine places both again, in order, around the other nodes, and the save’schangedlists them (order). In AWS and Google Cloud diagrams they trade places where their places fit: in their row or column in an AWS diagram, in their row in a Google Cloud diagram (AWS architecture diagrams, Google Cloud architecture diagrams). Nodes already in order stay where they are. - Members of a frame with its own
layout. When the engine lays out every node again, a pool or a lane keeps itslayout(a minimum), and so does a fragment outside a sequence diagram and every frame in an org chart or network. Their members keep their positions. Any other frame drops itslayoutand is laid out with its members. Name members inautoLayout’selementsto place them again inside their frame. A lane grows to hold its member when the member’s column has no room; in any other frame, one that doesn’t fit lands outside, and the save’s warnings includeNODE_OUTSIDE_FRAME. - Sequence diagrams follow message order: the engine lays them out from their messages on every save, and their nodes stay at
x: 0, y: 0. - Nodes with a relative
layoutfollow the node they’re placed against.
Making room
When a node is drawn bigger than the box its layout gives it, the engine moves the nodes in its way just far enough to keep the gap they had. A larger gap absorbs the push, so nodes past it stay where they are. The gap kept is at most the drawing’s spacing:
- Layered layouts:
layoutStrategy.nodeSpacingacross the flow andrankSpacingalong it (defaults). - Org charts: 30 px between cards and 80 px between levels.
- Network diagrams: 30 px.
The engine stores every node it moves, and every node that grew to fit its content, at the size it is drawn, whether it pushed something or not. A growth of 1 px or less isn’t stored, and an autoSize height never is. The save’s changed lists the moved and grown nodes under updated.
A node whose edges dock on a smaller box than it draws (Element types: Node size and wrapped text lists these nodes) is the exception. It is stored only where the engine places or moves it, an edit measures it again, or its growth pushes a neighbor or a frame border.
A node grows when:
- an edit changes its content (label, shape, type, icon, columns, text style or font) and it measures bigger;
- its label wraps with
autoSize: "content"and needs more height. This growth stays out of the storedlayout, so the nodes below keep the full spacing from it; - its
layoutis smaller than its content needs, because alayoutsize is a minimum. This happens on a create and on the edit that writes such a box, and the save stores the size it grows to; resizeElement, or anupdateNodewhose new box contains the old one, makes it bigger.
How the push works:
- Order. The engine resolves the cross-flow direction first, then the flow direction, and nodes keep their order. In the layered families, a node measured again after an edit keeps its rank’s center, so growing along the flow pushes the rank before it back and the rank after it on, and a rank can end up ragged. A node whose
layoutis too small, or that grows withautoSize, grows from its top-left corner, so it pushes only forward. A BPMN event or gateway, or auiflow.entryoruiflow.exit, whose label is drawn outside its shape grows round the shape instead, which stays where itslayoutputs it. - In a stack of layers, a card that grows keeps its row’s near edge instead of its rank’s center (Layers).
- Frames. A frame without a
layoutgrows with its members, and its growth pushes what is around it. It keeps the gaps it had, as a node does, or the full spacing when a member grows withautoSize. A node outside a frame pushes the frame, with its members inside it. A frame moves as one block with the nodes and frames inside it; text and images inside it stay where they are. A frame with its ownlayoutgrows on each side a grown or pushed member would cross, keeping the gap the member had to that border (at most the 20 px padding, plus 24 px for a title on top), and the engine stores its new box. Its growth pushes what is around it, as a fitted frame’s does. - Pools and lanes. Nodes push each other within their lane, and in a pool without lanes, within the pool. A pool or lane grows to hold its members, with or without its own
layout, which is a minimum. A lane that grows moves the lanes after it, and the pools after its pool, across the flow as far as they need the room, never back (Pools and lanes). Pools and lanes never getNODE_OUTSIDE_FRAME. - Org charts. A pushed card brings its reports. A manager that wasn’t pushed stays where it is, so it can sit off-center over its reports.
- Canvas. The canvas grows to fit and never shrinks back. That is the info-level
CANVAS_AUTO_EXTENDED, which the API doesn’t return.
What doesn’t push:
- Coordinates an agent writes. A
createNode, or anupdateNodeormoveElementthat moves a node onto another one, keeps both where they are. - Nodes the same edit adds. The engine places them after the push, around its result. Their growth pushes nothing, but placing one can move others (Positions are kept lists when).
- Deleting or shrinking a node. Its space stays, and nothing is pulled back.
- Sequence diagrams, nodes with a relative
layout(they follow the node they’re placed against), text and image elements, and a node that asameSizeconstraint makes bigger. - Overlaps already in the document. Two nodes whose layouts overlap stay as they are.
- A frame’s title. A frame without a
layoutthat a longer title widens doesn’t push;FRAME_OVERLAP_DETECTEDorNODE_IN_WRONG_FRAMEreports what it now covers. A Google Cloud group is the exception: what lies past its growth moves by it (Google Cloud architecture diagrams). - External labels. An event’s, gateway’s,
uiflow.entry’s oruiflow.exit’s label drawn outside its shape pushes only a node or frame it would come within 8 px of, far enough to leave 8 px (or the gap it had, if that was smaller); the shape keeps its gaps as any node does. A frame with its ownlayoutstill grows round the label, and so do a lane and a pool.
NODE_OVERLAP_DETECTED still reports the overlaps the engine can’t make room for: coordinates an agent writes, overlaps already in the document, and a node with a relative layout in the way. Its fix names a node drawn bigger than its layout.
A saved version whose node layout is smaller than the node is drawn shows the stored size until an edit stores the drawn size, and lists the node under updated. That edit can move the node’s neighbors, even when it didn’t name them, and changed lists them. Stored images of earlier versions don’t change.
Laying out again
To lay out again, send autoLayout; the engine keeps the new positions too. { "op": "autoLayout" } lays out every node, as on a new diagram, and sizes the canvas to fit. In architecture, flowchart, workflow, entity-relationship and UI flow diagrams, and diagrams without a family, every frame but a pool, a lane or a fragment drops its own layout and is laid out with its members, fitted round them, as a frame written without a layout is. { "op": "autoLayout", "elements": ["cache"] } places only the named nodes again, around the others, and keeps every frame’s layout. elements names nodes only. A new layoutStrategy or diagramFamily set with updateScene, or removing one, lays out every node too, the same way.
The engine lays out every node only on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily. The last two move nodes an agent positioned as well, except the members of frames that keep their own layout: pools, lanes and fragments, and every frame in an org chart or network. Those members keep their positions, the engine places the other nodes around them, and the canvas keeps its size. Apart from frames an edit adds or deletes, an order constraint it adds, the column a new node’s edge label pushes (Positions are kept), the room a task an edit adds to a pool or moves to another lane takes (Pools and lanes), and the room an edit takes in an AWS or Google Cloud diagram’s rows and columns for what it adds (AWS architecture diagrams, Google Cloud architecture diagrams), every other save places only the nodes that have no position yet.
Pools and lanes
A process with lanes needs no coordinates. Write a frame with containerType: "pool" whose children are frames with containerType: "lane", list each task, event and gateway in its lane’s children, and leave layout off all of them. In the layered families (architecture, flowchart, workflow, entity-relationship and UI flow diagrams, and diagrams without a family) the engine lays them out as BPMN tools such as bpmn-js and yFiles do:
- Lanes run along the flow and stack across it, in the order the pool’s
childrenlist them. Every node a lane lists is placed inside that lane. A lane with no members is kept, at its least depth. - Columns are shared by every lane of a pool and by every pool, so the flow reads as time from one lane to the next.
- Lane depth (across the flow) fits the lane’s contents, with a least depth: the larger of 60 px and the length of the lane’s title plus 16 px, since the title runs along the lane’s header strip. A lane’s own
layoutsize is a minimum; itsxandyare ignored, because the pool places its lanes. - Direction. Lanes always stack across the flow.
laneDirection: "vertical"stacks a pool’s lanes top to bottom, which BPMN calls a horizontal pool, and the flow runs left to right (LR, orRLwhenlayoutStrategy.directionasks for it).laneDirection: "horizontal"puts the lanes side by side, a vertical pool, and the flow runs top to bottom (TB, orBT). WhenlayoutStrategy.directionruns along the lanes’ stacking, the pool’slaneDirectionwins, and the edit returns the warningPOOL_FLOW_DIRECTION, whose fix names thelaneDirectionthat gives the flow you asked for. WithoutlaneDirection, lanes stack across the scene’s direction: top to bottom in a left-to-right flow (the default outside flowcharts and org charts), side by side in a top-to-bottom one. The first pool in document order with alaneDirectionsets the flow for the whole diagram; a later pool whoselaneDirectiondisagrees getsPOOL_FLOW_DIRECTIONtoo, and its lanes run across the flow anyway. - A pool’s
layoutis a minimum anchored at its corner: the pool grows right and down from there to hold its lanes and members. On a new diagram whose nodes have no positions, the engine places the drawing so that the first pool with alayouthas its corner at thatxandy, and doesn’t center the drawing in the canvas. When nodes already placed need more room than the box, such as a task too close to the pool’s left edge for its header strips, the pool grows to hold them instead, and the nodes keep their positions. - Several pools stack across the flow in document order, at least 40 px apart, and are all as long as the longest, since they share columns. A pool with no member nodes, such as a black-box participant that only sends and receives message flows, is drawn at its least depth, as long as the other pools, after the pool before it in document order, or, when it comes first, before the pool after it.
createFrameneeds at least one child, so add a pool with no members by writing it in the scene sent todiagram_create. - Nested lanes. A lane can list lanes in its
children(BPMN’s nested lanes). Each level adds a header strip. - Nodes outside lanes. Nodes that a pool, or a lane that holds lanes, lists directly beside its lanes are drawn in an untitled band after the last lane, with the warning
POOL_NODE_OUTSIDE_LANE. A lane that no pool lists is drawn as a pool of one lane, with the warningLANE_OUTSIDE_POOL. Pools and lanes always grow to hold their members, so they never getNODE_OUTSIDE_FRAME.
Rendering: Lane and pool rendering shows how they are drawn.
Edits keep the picture. Nodes already placed stay where they are, and the engine makes only the room a change needs:
- A task added to a lane.
createNodewithframeset to a lane’s ID, and nolayout, adds a task to a lane that already exists. The task takes a free place in its column inside its lane. When the lane has no room there, the lane grows, and everything past its far border (the lanes after it, the pools after its pool, and anything beyond them) moves across the flow by the growth. - A task between two placed columns. A task an edit adds to a pool, fed by a task in one placed column and feeding a task in the next, opens a column between them: that column and everything past it move along the flow, in every lane.
- A task moved to another lane.
updateNodewithframenaming another lane moves a placed task there, and the engine places it again in its new lane, in its column. A task whoselayoutthe same edit sets stays where the edit puts it. - Adding or reordering lanes.
createFramewithframeset to the pool’s ID adds a lane to a saved pool, after its other lanes; the lanes before it keep their places. No operation changes the order of a saved pool’s lanes:updateNode’sframemoves nodes only, andupdateFramedoesn’t changechildren. To reorder them, in one edit,deleteElementthe pool andcreateFrameit again with the sameid,titleandlaneDirectionand its lanes inchildrenin their new order (Operations: createFrame). Deleting a frame leaves its members where they are, so the lanes and their tasks stay. Placed tasks keep their positions and lanes are never pulled back, so lanes the new order moves later are pushed past the lanes now before them; sendautoLayoutfor a compact picture. - A lane whose members reach into the lane before it, such as positions you wrote that overlap that lane, is pushed across the flow, away from the lanes before it, with every lane after it. Lanes are never pulled back.
The engine stores every node these moves place in its layout, and the edit’s changed lists them, as it lists the nodes making room moves.
Routing. A sequence flow crosses lane borders freely: a lane of the pool that holds an end of the flow isn’t an obstacle to it, and lane borders stay unbroken where flows cross them. A message flow crosses the lanes of the pools it connects and keeps clear of other pools. A pool’s or lane’s header strip counts as its title, so edges keep off it as they keep off other frames’ titles (Edge routing).
In org charts and network diagrams, whose layouts place nodes without regard to frames, the engine still draws pools and lanes round their members: each lane grows to hold its members and pushes the lanes after it, but columns aren’t shared and POOL_FLOW_DIRECTION isn’t reported.
What pools and lanes don’t do:
- Lanes along the flow, such as phases or milestones, aren’t supported: lanes always run across the flow, so use lanes across it.
- Reordering. Lane order is the order of the pool’s
children, and pool order is document order. The engine doesn’t reorder either to reduce crossings, so list lanes and pools in the order a reader should meet them. - Frames inside a lane. A frame inside a lane, such as a subprocess, is fitted round its members after they are placed. It isn’t laid out with them as a cluster, as frames outside pools are.
- External labels. An edge can still run through a BPMN gateway’s or event’s external label in some layouts.
Layers
A stack of layers needs no coordinates. Write each layer as a frame with containerType: "layer". List its cards, and any plain frames that stand as sub-groups, in its children. List the layers top to bottom in one frame’s children; layers at the root stack in the order they appear in elements. Leave layout off the layers and their cards. In architecture diagrams and diagrams without a family, the engine stacks the layers as rows in the order listed and draws each one solid, so a dashed sub-group reads as nested in it.
- The listing sets the order. The first layer listed is the top row, and a stack listed bottom to top draws bottom to top. Lines never reorder layers. With no
layoutStrategy.directiona stack runs top to bottom, whatever the family’s usual direction;LRandRLmake the layers columns, andBTruns the stack upward. - Each card stands in its layer’s row. Within a layer the engine orders the cards to cut the crossings between layers; it doesn’t promise the fewest. A layer wider than 1,400 px wraps into rows of near-equal count. A sub-group is laid out by its own lines and stays whole in its row.
- The layers share one width. Every layer is as wide as the widest. Each gap between layers holds the lines that bend in it. Lines run through the layers and cross each border at a right angle, and a line between two cards of one layer with another card between them runs in a lane under the row.
- A layer keeps room for its title. In a stack of rows, each layer keeps room for its title left of its top row’s first card. A line into that card from above clears the title by at least 16 px. A long title widens every layer, since the layers share one width, and never changes where the line enters the card. A stack of columns (
LR,RL) keeps no such room, since its titles stand above the cards. - Lines between two cards of the stack stay inside its borders. A line between two cards of the stack stays at least 16 px inside its left and right borders (the top and bottom in a stack of columns). A layer that such a line passes through without ending in it keeps at least 32 px between the frame fitted round its cards and the stack’s right border (the bottom border in a stack of columns). Every layer widens to give it, unless another layer already reaches that far. A line with a card outside the stack at either end isn’t held between the borders.
- Cards in no layer, such as clients, stand above the stack in a new layout when more of their lines run into it than out, and below it otherwise.
- No anchors are needed. A line leaves a card on the side facing the layer it goes to, and enters on the side facing the layer it comes from. A line that ends on a layer ends on its border.
- A pinned card (one with a
layoutof its own) stays where it is while a stack none of whose cards has alayoutis arranged around it. That stack (a first save, or an edit that creates its cards) is arranged as a new layout arranges it. - Where that stack stands. It stands 56 px clear of the pinned cards, or
layoutStrategy.nodeSpacingwhen that is larger. It stands after the pinned cards that lead into it, those with more lines into it than out of it, as cards in no layer stand above a new stack. With none of those, it stands before the other pinned cards it has lines with, and otherwise past them all. It slides along the flow past a pinned card in its way. - Pinned cards on both sides. When pinned cards stand on both sides, the stack stands after those that lead into it and doesn’t move toward the others. A line from it to one of those runs the whole way across the space between the stack and that card. A frame round pinned cards counts as one pinned card.
- A layer with a
layoutof its own divides such a stack. The layers listed before it stand before it, and the ones listed after it stand after it.
What it doesn’t do:
- It arranges the first stack of a scene only: the stack whose first layer comes first in
elements. A layer in any other stack is placed as a generic frame and getsLAYER_NOT_ARRANGED. List all the layers of a stack in one frame (Validation rules). - In an AWS or Google Cloud diagram, a stack is arranged only inside a generic frame of its own, or inside a cloud boundary that holds no Region. At the root, inside a VPC, zone or subnet, or beside Regions, its layers are placed as generic frames and get
LAYER_NOT_ARRANGED. - A layer with a layout of its own keeps that box and is placed as a generic frame, and the API returns no warning for it. To arrange it, write the layer without a
layout. Or sendautoLayoutwithoutelements: it places every node again and takes thelayoutoff every frame but a pool, lane or fragment (Laying out again).diagram_getwithview: "dsp"shows a layer’slayout. - A layer inside a pool, lane or fragment, and a layer in any other family, gets
LAYER_NOT_ARRANGED. Each is placed as a generic frame, and its border stays solid. A layer inside a layer is a sub-group of it, at info level. - It never takes the order from the lines. A sub-group is laid out as any frame is, by its own lines. In a stack of columns (
LR,RL), read wide as tall and above as before; a line past a card of its column has no lane.
A saved stack keeps every card where it is, so it draws the same each time. A saved stack whose top row’s first card stands nearer a layer’s left edge than the title needs is drawn with its layers wider to the left, on any draw. A saved stack with a line between two cards that passes through a layer is drawn with its layers wider on the right (the bottom in a stack of columns), on any draw, where no other layer already reaches that far (above). No card moves in either case. An edit moves a saved card only to make room:
- A card an edit adds to a layer, or moves into one, stands in that layer’s row, at the free place nearest the cards its lines run to, inside the stack’s width where it fits. A card with no line to a placed card stands after the layer’s last card, or starts a row after the layer’s last when it would stand past the stack’s width. An edit never widens a row past 1,400 px. A card moved into a layer whose row it already stands on keeps its place.
- A card added to a sub-group stands in a new row after the card whose line runs to it, or at the end of a row when no line does, and the sub-group grows. When it grows wider, the cards to its right in the layer’s row move over by the growth. When it grows taller, the layer grows, as below.
- A layer that grows for a card an edit adds, a new row or a taller card, moves the layers after it along by the growth, so every gap between layers stays what it was. A card in no layer that stands after the stack moves along with them.
- A card that grows, by a changed shape or a longer label, keeps the edge of its row nearest the start of the stack, so the layers before it never move. A card that grows wider moves the cards after it in its row over, at the gaps they had. What lies after a taller card moves only as far as its growth reaches, so a gap can narrow.
- A layer you add with
createFramegoes after the others and is arranged as a new stack arranges a layer; the layers before it stay. When a frame lists the stack’s layers, setframeto it, or the layer isn’t part of the stack.- No operation puts a layer between two others. In one edit,
deleteElementthe layers,createFrameeach again in the new order with its cards and sub-groups inchildren(andframeset to the frame that lists the layers, if one does), then sendautoLayoutwithoutelements. The saved cards keep their places, so without thatautoLayoutthe layers draw in the old order. - A line that ends on a layer is deleted with the layer: create the line again.
- No operation puts a layer between two others. In one edit,
autoLayoutwithelementsplaces those cards again in their layers’ rows. Withoutelementsit lays the whole diagram out again, stack included, and takes thelayoutoff every frame but a pool, lane or fragment, a layer pinned by hand among them.- Deleting a card or a line, or adding a line in an architecture diagram, moves no saved card.
A card an edit adds in no layer is placed by the diagram’s general rules, next to its neighbors, with the stack’s cards in place: it doesn’t stand above or below the stack as in a new layout. List it in a layer, or send autoLayout without elements, which moves every node.
AWS architecture diagrams
An AWS diagram needs no coordinates. Write diagramFamily: "architecture" (or no family), frames for AWS’s groups with their presets nested as AWS nests them, aws.cloud > aws.region > aws.vpc > aws.az > aws.subnet.public and aws.subnet.private, nodes with aws:* icons listed in the frame they run in, and leave layout off all of them. When an architecture diagram, or one without a family, has an AWS Cloud, Region, VPC, Availability Zone or subnet preset, the engine arranges it containment first, as AWS’s reference diagrams draw it and as Lucidscale and AWS’s diagram-as-code place cloud containers by type before drawing the edges:
- Availability Zones are columns in the order the VPC lists them, all as wide and as tall as each other and evenly spaced. Subnets are rows shared by every AZ: each AZ’s first public subnet in the first row, its second in the second, then its private subnets the same way, so an AZ’s rows line up with the next AZ’s. Rows are evenly spaced. A subnet spans its AZ’s width; one AZ without a subnet the others have leaves a gap in that row. Subnets a VPC lists without an AZ make one column of their own, after any AZs’ columns. Nodes and frames an AZ lists outside its subnets go in a row after them, except a frame round subnets next to each other in its rows, a tier (see “A tier round an AZ’s subnets” below). Within a row, nodes are placed by their edges. A node alone in its subnet stands over the middle of the nodes it connects to in its AZ’s next row down, and those sit centered in their subnet: a task stands over the cache and database it uses, and its lines run down one trunk and fork to both. A node alone in its subnet that connects to nothing below it is centered in its subnet.
- Gateways sit on the VPC’s border, facing what they connect to. An internet gateway, virtual private gateway, VPC endpoint or transit gateway attachment (
aws:internet-gateway,aws:vpn-gateway,aws:vpc-endpoints,aws:transit-gateway-attachment, or one of their aliases) that the VPC lists directly is drawn on its border, its icon centered on the line and the border broken under it. It docks on the side its neighbors outside the VPC lie on, as AWS’s VPC and Site-to-Site VPN figures dock a gateway that serves one AZ or subnet: the left for what lies before AWS Cloud (users, a data center) and the right for what lies after it (inLR;RLswaps the two, andTBandBTput them on the top and the bottom), the right for the Region’s column of services, the top for AWS Cloud’s global row or a VPC stacked above in the Region, the bottom for one stacked below. An edge to anything else outside the VPC, such as another Region, counts for the top. The side most of its outside edges reach wins; a tie, or no edge outside, means the top. It docks on the left or right only when its lines inside the VPC all end in the AZ column nearest that side, or at an item in the row above the AZs or beside a lone AZ on that side, and on the bottom only when they all end in the last row; otherwise it docks on the top, as AWS draws an internet gateway serving two AZs. Its edges to what is outside the VPC leave by the face on its side, those to what is inside by the opposite face. Other gateways are ordinary nodes: list a NAT gateway in a public subnet. - Where on the border. On the top, a gateway stands over the nodes it connects to inside (centered on the gap between the AZ columns when those nodes lie in several AZs), clear of the VPC’s title, and on the bottom likewise under them, its label below the icon, outside the VPC. On the left or right, it stands level with the middle of the nodes it connects to inside, below the VPC’s header, its label centered under the icon across the border, as AWS’s VPN figure draws it; the VPC widens on that side so the label keeps 16 px from what the VPC holds.
- Other nodes the VPC lists directly span the AZs, such as the load balancer, and so do frames it lists other than AZs, subnets and a frame round all its AZs, each laid out as one block. Such an item stands among the AZs only when its edges into the VPC’s subnets all end in the second row or below: with two AZs it sits between the columns, in the row just above the first row its edges reach, and the columns part to hold it; with one AZ it sits beside the AZ’s column on the side its traffic comes from, the left when everything leading into it lies left of the VPC (users before AWS Cloud, a gateway docked on the left), else the right. Otherwise these items get a row of their own above the AZs, centered: with three or more AZs, with an edge into the first row (a load balancer in front of web servers in the public subnets, or of a VPC whose first row is private), with no edge into the subnets, or with a frame round the AZs (see “Frames between the presets” below).
- A Region’s VPCs stack on its left in the order it lists them, and its other nodes and frames (regional services such as S3, SQS, Lambda, Cognito) form a column to their right, each level with the nodes it connects to; those connected only to what is placed later go at the top. Where that column would be more than 1.5 times as tall as the VPCs beside it, it splits into two columns side by side, the first holding at least half where it can. Two nodes an
aboveorbelowconstraint orders stay in one half, so the break moves to the next place past half that parts no such pair, else the last before half, and the column stays whole when every place would part one. It never splits into more, so a Region with many services grows taller. AWS Cloud’s row and the outside columns don’t split. - AWS Cloud’s Regions sit side by side, with any VPCs it lists directly, in the order it lists them, and the nodes it lists beside them (global services such as Route 53, CloudFront, WAF) form a row above them, each over the nodes it connects to.
- What lies outside AWS Cloud goes before it (left, in
LR) when it has more edges into the cloud than out of it, such as users or an on-premises data center, and after it otherwise, such as a payment provider the services call. InTBthese go above and below the cloud, andRLandBTswap the sides. A VPC’s rows always run top to bottom. - Items outside that an edge joins go to one side together, directly or through other items outside, so the line between them doesn’t run around the cloud. They go before it when any of them has more edges into the cloud than out, as users do, and after it otherwise. A frame outside counts and moves as one block.
- Other frames that AWS Cloud, a Region or a VPC lists, or that lie outside AWS Cloud, and an AWS Cloud or Region holding no Region, VPC, AZ or subnet (a serverless diagram), are laid out with their members as any frame is and placed as one block, presets inside them included, except a frame round whole VPCs or round all of a VPC’s AZs (see “Frames between the presets” below). A frame in a subnet, such as a security group or Auto Scaling group, is laid out in its subnet’s row with the subnet’s other members, and one an AZ lists goes in the AZ’s row after its subnets, unless it is a tier (below).
A diagram can start at AWS Cloud, a Region or a VPC: a VPC with no Region or AWS Cloud around it is arranged the same way. A Region that lists Availability Zones or subnets directly arranges them as a VPC would, with no VPC frame drawn: the AZs as columns and the subnets as rows, below any VPCs it lists. With no VPC border, nothing docks on one: a gateway or load balancer the Region lists joins its column, so list those in a VPC. A subnet a Region lists directly also gets the warning AWS_GROUP_NESTING. An Availability Zone or a subnet that no VPC or Region lists, such as one in AWS Cloud or at the top, is laid out as any frame, so put AZs and subnets in a VPC. This scene draws two AZs with a public and a private subnet each, the internet gateway on the VPC’s border over the load balancer between the AZs, Route 53 above the Region and the uploads bucket beside the VPC:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"scene": { "id": "bookings-aws", "title": "Bookings on AWS", "canvas": { "width": 1200, "height": 900 } },
"elements": [
{ "id": "cloud", "kind": "frame", "containerType": "aws.cloud", "title": "AWS Cloud", "children": ["route53", "region"] },
{ "id": "region", "kind": "frame", "containerType": "aws.region", "title": "Region us-east-1", "children": ["vpc", "uploads"] },
{ "id": "vpc", "kind": "frame", "containerType": "aws.vpc", "title": "VPC 10.0.0.0/16", "children": ["igw", "alb", "az_a", "az_b"] },
{ "id": "az_a", "kind": "frame", "containerType": "aws.az", "title": "Availability Zone A", "children": ["pub_a", "app_a"] },
{ "id": "az_b", "kind": "frame", "containerType": "aws.az", "title": "Availability Zone B", "children": ["pub_b", "app_b"] },
{ "id": "pub_a", "kind": "frame", "containerType": "aws.subnet.public", "title": "Public subnet", "children": ["nat_a"] },
{ "id": "pub_b", "kind": "frame", "containerType": "aws.subnet.public", "title": "Public subnet", "children": ["nat_b"] },
{ "id": "app_a", "kind": "frame", "containerType": "aws.subnet.private", "title": "Private subnet", "children": ["task_a", "writer"] },
{ "id": "app_b", "kind": "frame", "containerType": "aws.subnet.private", "title": "Private subnet", "children": ["task_b", "reader"] },
{ "id": "users", "kind": "node", "nodeType": "actor", "label": "Customers", "icon": "aws:users" },
{ "id": "route53", "kind": "node", "nodeType": "service", "label": "Amazon Route 53", "icon": "aws:route53" },
{ "id": "igw", "kind": "node", "nodeType": "service", "label": "Internet gateway", "icon": "aws:internet-gateway" },
{ "id": "alb", "kind": "node", "nodeType": "service", "label": "Application Load Balancer", "icon": "aws:application-load-balancer" },
{ "id": "nat_a", "kind": "node", "nodeType": "service", "label": "NAT gateway", "icon": "aws:nat-gateway" },
{ "id": "nat_b", "kind": "node", "nodeType": "service", "label": "NAT gateway", "icon": "aws:nat-gateway" },
{ "id": "task_a", "kind": "node", "nodeType": "service", "label": "API task", "icon": "aws:ecs-task" },
{ "id": "task_b", "kind": "node", "nodeType": "service", "label": "API task", "icon": "aws:ecs-task" },
{ "id": "writer", "kind": "node", "nodeType": "database", "label": "Aurora writer", "icon": "aws:aurora" },
{ "id": "reader", "kind": "node", "nodeType": "database", "label": "Aurora reader", "icon": "aws:aurora" },
{ "id": "uploads", "kind": "node", "nodeType": "objectStorage", "label": "S3 uploads", "icon": "aws:s3" },
{ "id": "e_dns", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "route53" }, "label": "DNS" },
{ "id": "e_https", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "igw" }, "label": "HTTPS" },
{ "id": "e_igw", "kind": "edge", "from": { "elementId": "igw" }, "to": { "elementId": "alb" } },
{ "id": "e_alb_a", "kind": "edge", "from": { "elementId": "alb" }, "to": { "elementId": "task_a" } },
{ "id": "e_alb_b", "kind": "edge", "from": { "elementId": "alb" }, "to": { "elementId": "task_b" } },
{ "id": "e_sql_a", "kind": "edge", "from": { "elementId": "task_a" }, "to": { "elementId": "writer" } },
{ "id": "e_read_b", "kind": "edge", "from": { "elementId": "task_b" }, "to": { "elementId": "reader" } },
{ "id": "e_repl", "kind": "edge", "from": { "elementId": "writer" }, "to": { "elementId": "reader" }, "label": "replication", "style": { "dash": [6, 4] } },
{ "id": "e_upload", "kind": "edge", "from": { "elementId": "task_b" }, "to": { "elementId": "uploads" }, "label": "originals" }
]
}
Customers lie before AWS Cloud, on the left, but the internet gateway’s line inside runs to the load balancer between the AZs, so the gateway docks on the VPC’s top: from the left, that line would cross AZ A’s public subnet and its NAT gateway. With one AZ, or with the load balancer in a row above the AZs, the same gateway would dock on the left, facing Customers.
Every group’s box comes from its members on every layout, so the positions the engine stores redraw the same picture. A preset’s own layout is a minimum anchored at its corner: where its members need more room, such as a hand-placed diagram whose rows don’t fit the presets’ headers, the members move down or right, rows push the rows after them and wider AZs push what lies right of them, and the save’s changed lists what moved. order constraints order nodes within one row or column: leftOf and rightOf within a subnet’s row or AWS Cloud’s row, above and below within a Region’s column or an outside column. One between nodes of different rows or columns, and sameRank, is ignored. extensions.autoGroup draws no bands here.
Edges are routed after the layout. They cross a VPC’s Availability Zones as a sequence flow crosses a pool’s lanes: an edge with an end inside the VPC can run across an AZ that holds neither of its ends, such as the load balancer’s lines into each AZ, replication between AZs, or a write to another AZ’s database, and keeps 16 px off an AZ’s border it runs beside when a route with as many bends can. A subnet, or any other group that holds neither end, is kept off as any frame is (Edge routing). A fork’s branches, lines drawn alike, run on one trunk until they part, with a dot there. Lines drawn differently don’t share a trunk, except where noted below (Lines drawn differently). Lines of different edges that must run side by side keep 16 px apart where there is room. An edge between two members of one row that would pass another member between them runs in a lane under the row; when that edge ends in an arrowhead, it rises from the lane into the side of its target facing its source, so the arrowhead meets the icon. A line from a subnet’s member that would pass a row-mate on its way to the Region’s column, or to an item beside the VPC, runs in that lane too, where the lane and the way on are clear. Edges keep off the groups’ headers, and edge labels keep out of the band each header spans.
The rules below are for AWS diagrams. The passes behind Group borders, Crossed labels, End legs, Other ways apart, Clear of nodes and borders, Lines drawn differently and Labels also run in Google Cloud diagrams, with Google’s groups in place of AWS’s (Google Cloud architecture diagrams):
- Group titles. Every AWS group’s header, an Availability Zone’s title too, keeps 16 px from an edge’s inner segments. A straight drop that crosses the top of the groups round its lower end runs 16 px clear of their titles, the AZ widening to the right for it, and an AZ keeps 32 px under its title when a route leaves its first row upward. In an AWS or Google Cloud diagram, when lines drawn differently leave one card, the tracks of their runs keep off every frame’s title, an Availability Zone’s included.
- Group borders. A line closer than 32 px to a group’s side for more than 120 px, in a channel 64 px wide or more, moves with the channel’s other lines to evenly spaced tracks across it, as Graphviz spaces a channel’s tracks, 32 px in from its sides where the tracks still keep 16 px apart; where that can’t be kept, it alone moves 32 px off the side. A line’s first turn out of its source, closer than 32 px beside the source’s box in a channel 64 px wide or more, moves the same way, as libavoid centers a zigzag segment in its channel: a load balancer’s line into an AZ runs down the middle of the channel between its box and the AZ. In a channel narrower than 64 px, the lines beside a group’s side spread evenly across it, a lone line to its middle, where they still keep 16 px apart and off the sides, and a first turn stays where it was routed. Segments of different edges within 16 px of one line, end to end less than 64 px apart with nothing between them, move apart to 16 px.
- Crossed labels. A Group borders move (above) is kept only when each labeled line it crosses keeps a stretch of its run, clear of the lines crossing it. The stretch is as long as its label needs, or as it had been. A move makes no room for a label: where a gap has none, the label takes the place with the least serious faults (label placement).
- End legs. The last segment into or out of a node is nudged apart from another edge’s parallel segment closer than 16 px, side by side for 24 px or more or in line with it end to end, as libavoid nudges the final segments attached to shapes: the end slides along its face to 16 px, a straight two-point line moves both ends, and two end legs that can’t each move alone share the move.
- Other ways apart. An end leg can instead move past the other line to 16 px on its far side, when the drawing then has fewer crossings. Some end legs can’t move: a bundle’s shared trunk, an end on a face its family fixes, and an end with an
anchor, with or without anoffset. Then the other line’s middle segment moves across to 16 px, with its bends, unless another line’s run shares it. - Clear of nodes and borders. An end-leg move never brings a line within 8 px of another node, or of a frame’s border the line runs beside, on an AWS icon node too. A line already nearer than that gets no nearer. Among the moves allowed, the smallest that keeps the line 16 px off nodes and borders is taken, or the smallest of all when none does.
- Lines drawn differently. Lines that differ in stroke color, width, dash or opacity don’t leave or enter one point on a shared trunk. Each group of lines drawn alike takes a port of its own, 12 px or more from the next on the face (13.6 px in Google Cloud), in the order that adds no crossing. A group of lines drawn alike keeps one port and forks with a dot.
- Where lines drawn differently still share a port. A line keeps its ports when it has an
anchorwith anoffsetat either end, is astraightedge, runs straight between two nodes, or has an end the cloud layout places. The other groups stand a port gap beside it. A move that would cross a node or add a crossing isn’t made, and that line keeps its port. A face too narrow for a port gap parts the groups half as far. Where even that doesn’t fit, they share the port. - Other diagrams aren’t covered. In them, lines drawn differently can still share a stretch, as in an org chart’s bus.
- Labels. An edge label keeps out of line with another edge’s straight run, as yFiles avoids ambiguous label places, so it doesn’t read as that edge’s label. A run counts as continuing two label heights past its end or corner. A diagram the cloud layout doesn’t arrange doesn’t count that continuation.
- Room for lines and labels. Nodes in one subnet’s row keep room between them for a labeled edge joining them, and for a fan-out’s shared stretch on the same line, and lines from other rows into such a pair come in by a top or bottom face. The Region’s column stands far enough right of the VPCs that a labeled line from a VPC into it keeps a clear stretch for its label past the lines from outside the VPCs that cross it. An item between two AZ columns, such as a load balancer, keeps at least 64 px each side, so its lines into the AZs run 32 px or more from the AZ borders and from its own box. A saved diagram keeps this room when a tier frame widens its AZs (“A tier frame added”, below). An item beside a lone AZ keeps its lines 32 px or more off the AZ’s border too. A line from it into a member behind a nearer row-mate comes down into the member’s top from the row’s lane. An outside node whose line runs into a gateway on a VPC’s top or bottom is placed so the line runs 16 px under every AWS header it crosses.
A border or first-turn move is kept only when it adds no crossing and keeps nodes, headers and labels their room. A move that parts two lines reading as one doesn’t land a line within 8 px of a frame’s border. An end-leg move is kept only when it adds no crossing, keeps off every node (see “Clear of nodes and borders” above), leaves fewer pairs of lines closer than 16 px and makes no new pair. It is also refused when it would lay a segment on another edge’s line, drawn as one line that forks, or leave a line seeming to run through an icon (below). Otherwise the line stays as routed. An end on an AWS icon’s west face level with an end on its east face reads as one line through the icon, so one of the two moves along its face toward its line’s turn; a straight line’s end has no turn, so when the other end can’t move, the straight line moves whole, both ends together. A chain of straight lines through an icon stays on one line. In any diagram, the ends on an AWS icon drawn alone are spread too: ends on one face keep 16 px apart, within the face’s middle half when it holds them, else along the rest of it; a top or bottom face that can’t hold them sends an end whose route comes from beside the icon round to that side; a short jog just before an end moves with the end, so its last leg runs straight; and an end on a round icon (a gateway, load balancer or endpoint) meets its circle (Rendering: AWS icons). An arrowhead into an icon from below meets a side of the icon, not the label under it, when a route one bend longer gets there; a straight line from below keeps the bottom. In any diagram with an AWS group or a node with an aws:* icon, in any family, an edge that sets no endArrow and whose edgeType is unset, default, or an er.*, network.* or org.* type ends in AWS’s open arrow, an open V; the workflow, sequence and UI flow edge types keep their own arrowheads (Element types: Edge types).
Edits keep every position, except those of the two nodes an order constraint they add finds the wrong way around (below), and grow rows and columns, as a table inserts a row or a column. The Region’s column also moves right, as one, when an edit places nodes in it or joined to it by an edge (nodes it adds, or the two an order constraint places again) and leaves a labeled line from a VPC into it too little clear run, as on a fresh layout (above); what lies right of the Region moves right with it:
- A node added to a subnet takes the free place in its row nearest the nodes it connects to, else the row’s end. When the row is full, every AZ of the VPC widens to the right to match, and what lies right of the growth moves right by it. The nodes already placed keep their places, so they sit left of their subnets’ centers until
autoLayoutarranges the diagram again. - An AZ added with
createFrame’sframebecomes a new column right of the last, its nodes in the rows the column before it uses, and what lies right of the VPC moves right to make room. - A gateway added to a VPC docks on the side a fresh layout would dock it on, as above. On the top it goes over the nodes it connects to inside, and when the VPC’s top needs more room to hold it, what lies below moves down by that room. On the bottom it goes under them, and when its icon needs more room below what the VPC holds, the VPC grows down and what is stacked below it moves down. On the left or right it goes level with the nodes it connects to inside, and the VPC widens on that side when its label needs the room. A gateway already placed keeps its side, so one an earlier engine docked on the top stays there until
autoLayout. - A node added to a Region, to AWS Cloud or outside it takes the free place in its Region’s column, AWS Cloud’s row or the outside column nearest the nodes it connects to, new nodes that fit one place sharing it. When that place is too small, as in a full column, the column or row opens there: the items after it move along it (down a column, right along a row) by the room the new ones need, and the group grows. Nothing off that column or row moves, except the Region’s column, and what lies right of the Region, when a labeled line into the column needs room (above).
- Items outside AWS Cloud. A node an edit adds outside goes on the side of the saved items outside it’s joined to. When those stand on both sides, it goes on the side more of its edges reach. A line an edit adds between two saved items outside moves neither. When they stand on opposite sides,
autoLayoutputs them on one side. - An edge added into the Region’s column. An edit that only adds edges gets the same check when one of them ends in the column: a labeled line from a VPC, or a line that crosses a VPC’s labeled line into the column. When a labeled run is left too little room, the column moves right as one, and what lies right of the Region moves with it.
- A spanning frame added round subnets deepens the row lane above its top row for its header, in every AZ; one round what subnets hold deepens the lane under their headers (Spanning frames). What lies below moves down by that room, and its targets keep their places in their rows.
- A tier frame added round an AZ’s subnets, or one the diagram already has, widens every AZ of its VPC by 20 px on each side. Its header takes room above its first subnet (see “A tier round an AZ’s subnets” below). Each gap round the AZs that this narrows gets back what the tier took, up to the room a fresh layout keeps there: beside a load balancer between two AZs, that is 64 px each side. What lies right of the gap or below it moves right or down by that much.
- Anything else (a member of another frame, a node the VPC lists directly) is placed as in any diagram.
- An
orderconstraint an edit adds whose two nodes stand the wrong way around in one row or column swaps them: each takes the other’s place, and nothing else moves but a Region’s column that needs room for a label (above). When they can’t simply trade places, as when they stand in the two halves of a Region’s split column, both are placed again as nodes an edit adds are, which can grow their row or column and move what lies past it. Nodes already in order stay where they are.
The save’s changed lists every node these moves place, and a compare lists them as changed; the colored diff paints amber only what changed besides its place (Rendering: Visual diff rendering).
What the cloud layout doesn’t do:
- Other clouds. It arranges AWS’s presets as above and Google Cloud’s by Google’s own rules (Google Cloud architecture diagrams). Azure has no presets: draw it with generic frames, laid out as any frame.
- Other families. It arranges architecture diagrams and diagrams without a family. In a network, workflow or other family’s diagram the presets draw AWS’s groups, and that family’s layout places the nodes;
AWS_FRAME_HIDES_GROUPS, which concerns the arrangement, isn’t raised there. - Guessing groups from titles. A frame titled “VPC” without
containerType: "aws.vpc"is laid out as any frame, whatever its title. When it holdsaws:*icons and its title is an AWS group’s own name, it getsAWS_GROUP_UNTYPED, which names the preset to set or says to leave the frame generic. Validation rules says which titles count. - Reordering. AZs keep the VPC’s order and rows the AZs’ order; the engine doesn’t reorder them to cut crossings. List them in the order they should read.
- Centering every row. A node alone in its subnet that connects to only some of the nodes in the row below stands over those, off its subnet’s center. When every node alone in an AZ’s subnets stands over only part of the row below, the AZ has nothing to center on: it fits what it holds, and its rows can sit off center. A row whose nodes on the right have wider labels than those on the left can sit a little left of center.
- Picking a gateway’s side. No field picks it: the engine docks a gateway by where its neighbors lie (above). A gateway whose lines inside reach several AZs, or the load balancer between two, docks on the top even when what it connects to lies beside the VPC, such as a virtual private gateway joining a data center on the VPC’s left to services in both AZs: its line runs over the VPC’s top. Gateways on one side stack along it.
- Groups across AZs as members. Membership is one frame per element, so a security group or Auto Scaling group that crosses Availability Zones can’t hold their subnets. Write it with
spansinstead ofchildren, naming the subnets or the nodes it surrounds: it is drawn round them, and their rows keep room for its header (Spanning frames). - Nesting AWS doesn’t use. An account holding Regions is arranged as AWS Cloud is; a preset where AWS doesn’t nest it is laid out as any frame, with the warning
AWS_GROUP_NESTING(a subnet a Region lists directly is arranged in the Region’s columns and rows, above, and warned about too). - Frames between the presets. A generic frame round all of a VPC’s Availability Zones (an EKS cluster round them), the VPC listing no AZ or subnet beside it, or round whole VPCs of a Region (a Production frame round its VPC), is read through, as AWS’s diagram-as-code nests stacks: the presets inside keep AWS’s arrangement, the frame is fitted round them under its own header, and with a frame round the AZs, the VPC’s other items, such as the load balancer, take the row above them. A frame that holds a Region or a VPC at the top, in AWS Cloud or in another such frame is arranged as AWS Cloud is, its Regions and VPCs side by side. Any other frame between the presets keeps its own box, and the presets inside it lose the arrangement: a generic frame round some of a VPC’s AZs, round an AZ’s subnets that aren’t next to each other in its rows, or round presets mixed with other members, and an account or security group there. Between a Region and its VPC, or a VPC and its AZs, it is laid out as any frame with everything inside it: no AZ columns of one size, no subnet rows across them, no gateway on the VPC’s border. A Region left with no VPC, AZ or subnet of its own is then laid out as one block too. Between an AZ and its subnets it goes in the AZ’s row after its subnets, everything in it on that one row, so its subnets form no rows with the other AZs’. A generic one gets the warning
AWS_FRAME_HIDES_GROUPS, which names the groups it hides and the group to list them in; a preset getsAWS_GROUP_NESTINGfor it or the group inside it. A frame round nodes only, such as a tier’s services in a subnet, gets no warning. List the AZs or subnets in their VPC or AZ directly, or put the frame round the whole VPC or Region. A group across AZs round subnets, or round what they hold, can be a spanning frame instead (Spanning frames); one round AZs or VPCs gets no room for its header. - A tier round an AZ’s subnets. A generic frame in an Availability Zone that holds only subnets next to each other in the AZ’s rows (public first, then private, each in the AZ’s order) is read through too. Its subnets join the AZ’s rows, shared with the other AZs. For a tier across several AZs, write one frame with
spansnaming their subnets; it is fitted 10 px round them (Spanning frames).- The frame is fitted round its subnets as a group nested in the AZ, as AWS nests its groups. Its border stands 20 px out from them, its header in the room kept above its first subnet. The AZ’s border stands 20 px out from it on the left, the right and the bottom.
- Every AZ of a VPC that holds a tier starts its subnets 40 px in from its left and right borders, so every subnet keeps one width and the AZs stay as wide as each other.
- In a saved diagram, what lies past the AZs moves right or down by the room the tier takes, up to what a fresh layout keeps (“A tier frame added”, above). A diagram saved with such a frame drawn as a box keeps its nodes where they are until
autoLayout.
- Rearranging a saved diagram. After the first save an edit places only what it adds, and the two nodes of an
orderconstraint it adds that stand the wrong way around. It moves other nodes only to make room, as above. So a diagram that grew unevenly (a node at the end of a column, a load balancer placed for one AZ in a VPC that now has two, a gateway an earlier engine docked on the top) keeps its shape untilautoLayoutarranges it again.autoLayoutmoves every node, hand-placed ones too.
Google Cloud architecture diagrams
A Google Cloud diagram needs no coordinates: leave layout off every frame and node. Write diagramFamily: "architecture" (or no family) and frames for Google’s groups with their presets, nested as Google nests them: gcp.cloud > gcp.project (optional) > gcp.region > gcp.subnet > gcp.tier or gcp.instanceGroup. Write the services as nodes with gcp:* icons, each listed in the frame it runs in, and the users outside gcp.cloud. Draw the VPC network round its subnets, and each zone round its cards, as spanning frames with spans.
When an architecture diagram, or one without a family, has a gcp.cloud, gcp.region or gcp.subnet frame, the engine arranges it top to bottom, as Google’s Architecture Center diagrams draw it:
- Zones are columns. A tier’s cards stand in the columns of the zones that span them, in the order the scene lists the Region’s zones, and each column runs through every tier of the Region. Every zoned card takes the widest one’s width, and a row’s cards share a height, so the zone strips line up. Two cards of one tier in one zone stand side by side, and that column widens. A card in no zone stands after the last column, and a tier with no zoned card is centered on the columns.
- Tiers are rows. A subnet’s tiers, and the nodes it lists directly, form rows from top to bottom in the order its edges run:
- Each tier is a row of its own; tiers at the same place in the flow stack in the order the subnet lists them.
- Nodes at the same place in the flow between two tiers share a row, each near the nodes it connects to, as the internal load balancer between the web and app tiers does.
- Nodes at a tier’s place in the flow form a row above it, wherever the subnet lists them. So a cache the app tier feeds stands between the app and database tiers, and the app tier’s line to the database runs past it.
- Nodes no edge joins to the rest of the subnet go last.
- A stacked card’s box holds its copy. A node with
style.multiple: truehas a box 4 px wider and 4 px taller than its card (Google Cloud cards). Columns and rows count the box. So a stack’s strip lines up with its neighbors’, and its card is 4 px narrower and shorter than a single card beside it. - Cards that stand together share a width. In a new layout and after an
autoLayoutwithoutelements, cards that stand together are drawn in runs, each at the width of its widest card. The engine orders them by the width their labels need. A card joins the previous card’s run when it has the same icon and needs at most 24 px more, or needs at most 8 px more, whatever its icon. Cards stand together:- in one row of a subnet, of the boundary or of a project;
- among the cards a Region lists directly above its subnets, and likewise below them, whichever row by flow they stand in;
- in one frame, such as a GKE cluster;
- outside the boundary, on one side.
- The steps add up. A step is the extra width a card needs beyond the card before it. Same-icon cards that need 150, 170 and 190 px all take 190 px. A card whose step is over the limit starts a new run: same-icon cards that need 150 and 190 px keep those widths. So a long label widens the cards in its run, not the ones further off. Cards of different products more than 8 px apart keep the width their labels need. The limits are exact: a step of 24 px joins a run of the same icon and 24.01 px doesn’t, and another icon’s step of 8 px joins and 8.01 px doesn’t.
- Zoned and stacked cards. Zoned cards follow the zone rule above, and a stacked card keeps the width its copy needs.
- Lines past a row of nodes. A node in a subnet’s row of nodes stands a node’s clearance aside from a line that runs past it, from a row above it to one below or down out of the subnet. A cache the app tier feeds stands beside the tier’s line to the database tier this way. It goes to the same side in every Region, within its Region’s tiers where they leave room, else right of them, and the subnet widens. An internal load balancer, both of whose lines run through it, stays on its chain.
- Regions stand side by side, mirrored. Regions stand left to right in the order the boundary lists them, read through a project or a generic frame round them. Rows that match across Regions share a top and height: a tier by its preset and title, a row of nodes by their icons. So the second Region reads as a copy of the first, and replication between them runs straight where no card stands between its ends (routing, below). A Region with no subnet, such as one of Cloud Run, Pub/Sub and Firestore, is laid out with what it holds as any frame is, level with the others.
- The VPC network is one band. A
gcp.vpcis drawn as one straight band across the Regions that hold its subnets, its title before the first Region, and its subnets share a top and height in every Region. - A Region keeps 24 px under what it holds. That is its lowest card, row of items or subnet. It keeps 21 px at its sides, and 24 px from the subnets under a VPC band too. Regions that stand level share one bottom, so one with less in it keeps more. A Region with a
layoutof its own keeps it as a minimum and can stand further off. - Global items are what the boundary or a project lists besides Regions. The boundary’s items form a row above the Regions and a row below. A project’s items stand over or under its own Regions (below):
-
An item with more edges leading into the Regions than coming from them goes above, such as the load balancer and Cloud DNS.
-
Any other item joined to the Regions goes below, such as dual-region storage, BigQuery and a bucket the Regions write and read, one line each way, except where calls from outside change it (below).
-
An item joined only to items of its row takes their side, as Cloud Armor stands beside the load balancer it protects.
-
An item joined only to items outside the boundary goes above.
-
An item a party outside the boundary calls counts those calls with its lines into the Regions. A sign-in service that the users and a Region both call goes above, near its callers. It goes below when the lines the Regions send it outnumber its lines into the Regions and the calls from outside added together.
-
A dashboard service (a node with the
gcp:looker,gcp:looker-studioorgcp:looker-studio-proicon, or the aliasgcp:data-studio) goes below the Regions, so the line from the warehouse that feeds it runs down, when both hold:- The lines the Regions send it equal its lines into the Regions plus the calls from outside.
- Every card of the Regions that feeds it ends its Region’s flow. In a Region with subnets, that is a card in the row below the subnets. In a Region with none, it is a card with no line to another card of the Region.
Otherwise the rule above decides. With calls from outside, it puts a tie above, whatever the service.
-
An item joined to nothing goes last in the row below, as an observability card does.
-
- A project is one box. A project, or a generic frame round whole Regions, holds its Regions and the global items it lists itself. A shared network project that lists its load balancer draws it over its Region, beside the service projects’ boxes. On a new layout the boxes of sibling projects don’t overlap, whichever order
gcp.cloudlists them in, and a project’s box stays clear of a Region listed beside it.- A project’s items stand in a row of their own over its Regions, or under them by the rule above. When the row is wider than the project’s Regions, the box grows equally on both sides, and the project after it stands further right.
- The items
gcp.cloudlists stand over every project’s box, or under it. The items of sibling projects stand on one line. - A project that holds every Region has no other box beside it. Its items stand near the nodes they connect to, and its box widens on the side they need.
- A line that drops through a row of a frame’s own items makes the row stand aside from it. The line comes from an item outside the boundary or a global item over the row, and ends under it. A DNS zone’s line to a card of a project’s Region is one. The row is a project’s, or the one
gcp.cloudlists. A line from a card of a project’s Region to an item under the project passes the row under its Regions the same way. - Items in the line’s way move past it, 16 px clear. The row keeps its order and the gap between items. A load balancer over the gap between two Regions is the exception (below). The project’s box grows when the row then runs past it, and the box beside it moves on by the growth. A line to an item of the row, or between two items of it, moves nothing.
- A line that runs level across a card, such as one between items of two projects’ rows, can’t be stood aside from. The router draws it round the cards. It crosses a card only where no route round the cards exists. The API returns no note for it, so check the image (EDGE_OBSTACLE_GRAZED).
- A project’s title stands at the top center. It moves to the top left when a line between an item above and a card under the title would run down closer than 16 px to it. It stays at the center when a line would be in the way at the top left too.
- Each project is decided on its own, so one title can stand at the left beside another at the center. A title also stays centered when the project is no wider than its title needs, since the left clears no more than the center does. A project with an
icondraws its title at the left already. - The engine moves no card in a Region’s row to clear a title.
- A saved diagram keeps its places, except where an edit needs room (below). The other exception is sibling projects’ boxes saved overlapping. The next edit moves the project listed later, and what lies right of it, to the right, until the boxes are as far apart as on a new layout.
changedlists them, and a drawing before that edit shows them moved already.
- Regional items are what a Region lists besides its subnets, such as Cloud Run, Pub/Sub or a tier listed in the Region itself. They stand above or below the Region’s subnets by the same rule, in one row or, past 1,400 px, in rows by flow (below). Calls from outside don’t count for them.
- A Region with a subnet stands the items it lists directly in one row on each side while that row runs no wider than 1,400 px, whatever their edges. A frame it lists directly, such as a cluster, stands as one block.
- Each item’s own lines decide its side, so a chain that loops back through the subnets has a line that runs up. Say a pipeline feeds an approval gate, the gate feeds a serving subnet, and the subnet’s monitoring restarts the pipeline. The gate stands over the subnet and the pipeline under it, so the line from the pipeline to the gate rises. The engine doesn’t stand a chain down the rows.
- Past 1,400 px the items stand in rows by flow. Each item stands one row below the lowest item with an edge into it, so callers come first and the datastore they write to comes last. A frame counts the edges into the nodes it holds.
- An edge back up to a higher item is ignored. Two items joined each way and to nothing else stand in the order the Region lists them. An item with no edge stands last.
- Within a row by flow, the items stand in an order chosen to cut the crossings between rows, not always to the fewest. An item with a line down into the subnets tends toward the left of its row. Where lines don’t decide the order of two items, they stand as the Region lists them.
- A row by flow wider than 1,400 px wraps onto further rows, as evenly as the items allow. The order is chosen for the whole row, then cut, so lines into the lower rows of a wrapped row can still cross.
- A Region with no subnet is laid out as any frame is (above), and its items stand in no rows by flow.
- Items on one item’s sides. In a global row, a Region’s row or a row of nodes in a subnet, two or more items joined only to the same item share its sides, so each line runs straight to it. The first half, in the order their edges run and then as listed, stand before it and the rest after: Cloud Armor and Cloud CDN stand either side of the load balancer. Lines from outside the boundary can change this for a load balancer over the gap between two Regions (below).
- A load balancer over the gap between two Regions keeps its place when lines from outside the boundary pass through its row. It stands over the gap when it feeds the first tier of each of two neighboring Regions and
gcp.cloudlists it, or the project that lists it holds both Regions (below). On a new layout, an item of its row that a line from outside the boundary crosses moves clear of the line:- It stands in the free place nearest to where it stood, beside the load balancer: 16 px clear of every line, with no line or other item between the two. That can be the other side from the one the order above gives.
- Where no place beside is free, it stands over the load balancer,
layoutStrategy.nodeSpacingclear (30 px by default), or the room a label on the line between them needs if that is more. The load balancer stands nearest the Regions, whichever order the boundary lists the two in. - Any other load balancer, such as one that feeds a single Region, has no gap to stand over, so its row stands aside as any row does (above).
- Two items that
gcp.cloudlists in the row over the Regions never touch on a new layout. A saved diagram keeps the gap it was saved with, touching items included, untilautoLayout, which stands them apart. - What lies outside the boundary goes above it when it has more edges into the boundary than out, such as users or an on-premises box, and below it otherwise, such as a payment provider the services call. With
layoutStrategy.directionLRthese go left and right of it instead, andRLandBTswap the sides; the rest of the arrangement runs top to bottom whatever the direction. - A party whose every line with the boundary reaches the row below the Regions stands below the boundary, near the item it calls, so its line is a short rise. A carrier that only delivers files to a landing bucket the Regions write more often than outside parties call it (the row rule above) is one. A party with a line to or from a Region or an item of the top row stays above. The user-icon rule below can still keep a party above.
- Parties an edge joins that would stand above go below only when every line any of them has with the boundary reaches that row. They would stand above when any of them has more edges into the boundary than out.
- A user icon keeps a party above when it has more edges into the boundary than out, even if they all reach the row below the Regions. A node outside has one when its
iconisgcp:user,gcp:users,aws:user,aws:users,lucide:userorlucide:users; no other icon counts. A system drawn with one is a user too. A frame outside has one when a node inside it does.- A user whose every line with the boundary reaches a dashboard service below the Regions stands below the boundary with it, so the line is a short rise.
- A user who also has a line with another item of the boundary stays above, such as a Region’s card, the landing bucket or a top-row item. Its line to a dashboard service below the Regions runs around the Region.
- A user of a dashboard service that stands above the Regions stays above too.
- Analysts who only read the landing bucket stand above the boundary and keep a long line down its side.
- Items outside that an edge joins go to one side together, directly or through other items outside, so the line between them stays on that side. They take the side users take when any of them has more edges into the boundary than out, and the other side otherwise, except as the two bullets above say. A frame outside counts and moves as one block. Above the boundary, a clinic whose staff use the app (one edge in) stands beside the vendors its kiosks load a widget from (two edges out).
- A frame outside orders its members by where their lines go. Above the boundary the members stand left to right in the order of the items their lines go to. That keeps the lines leaving the frame from crossing just under it. A data center lists its ERP system, then its operations staff. The ERP calls a gateway at the right of the boundary’s top row and the staff call a link at its left, so the staff stand first. Members whose lines don’t decide stand as listed.
A diagram can start at the boundary or at a Region: a Region with no boundary round it is arranged the same way. This scene draws two mirrored Regions, each subnet a web tier over a database tier in two zones, the load balancer over the gap between the Regions and the backups bucket below them:
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"scene": { "id": "orders-gcp", "title": "Orders on Google Cloud", "canvas": { "width": 1200, "height": 900 } },
"elements": [
{ "id": "cloud", "kind": "frame", "containerType": "gcp.cloud", "title": "Google Cloud", "children": ["glb", "region_1", "region_2", "backups"] },
{ "id": "region_1", "kind": "frame", "containerType": "gcp.region", "title": "Region: us-central1", "children": ["subnet_1"] },
{ "id": "subnet_1", "kind": "frame", "containerType": "gcp.subnet", "title": "Subnet 10.10.0.0/20", "children": ["web_1", "db_1"] },
{ "id": "web_1", "kind": "frame", "containerType": "gcp.instanceGroup", "title": "Web tier", "children": ["web_1a", "web_1b"] },
{ "id": "db_1", "kind": "frame", "containerType": "gcp.tier", "title": "Database tier", "children": ["primary"] },
{ "id": "region_2", "kind": "frame", "containerType": "gcp.region", "title": "Region: us-east1", "children": ["subnet_2"] },
{ "id": "subnet_2", "kind": "frame", "containerType": "gcp.subnet", "title": "Subnet 10.20.0.0/20", "children": ["web_2", "db_2"] },
{ "id": "web_2", "kind": "frame", "containerType": "gcp.instanceGroup", "title": "Web tier", "children": ["web_2a", "web_2b"] },
{ "id": "db_2", "kind": "frame", "containerType": "gcp.tier", "title": "Database tier", "children": ["replica"] },
{ "id": "vpc", "kind": "frame", "containerType": "gcp.vpc", "title": "VPC", "spans": ["subnet_1", "subnet_2"] },
{ "id": "zone_1a", "kind": "frame", "containerType": "gcp.zone", "title": "us-central1-a", "spans": ["web_1a", "primary"] },
{ "id": "zone_1b", "kind": "frame", "containerType": "gcp.zone", "title": "us-central1-b", "spans": ["web_1b"] },
{ "id": "zone_2a", "kind": "frame", "containerType": "gcp.zone", "title": "us-east1-a", "spans": ["web_2a"] },
{ "id": "zone_2b", "kind": "frame", "containerType": "gcp.zone", "title": "us-east1-b", "spans": ["web_2b", "replica"] },
{ "id": "users", "kind": "node", "nodeType": "actor", "label": "Customers", "icon": "gcp:users" },
{ "id": "glb", "kind": "node", "nodeType": "service", "label": "Global load balancer", "icon": "gcp:cloud-load-balancing" },
{ "id": "web_1a", "kind": "node", "nodeType": "service", "label": "Web server 1", "icon": "gcp:compute-engine" },
{ "id": "web_1b", "kind": "node", "nodeType": "service", "label": "Web server 2", "icon": "gcp:compute-engine" },
{ "id": "web_2a", "kind": "node", "nodeType": "service", "label": "Web server 1", "icon": "gcp:compute-engine" },
{ "id": "web_2b", "kind": "node", "nodeType": "service", "label": "Web server 2", "icon": "gcp:compute-engine" },
{ "id": "primary", "kind": "node", "nodeType": "database", "label": "Orders primary", "icon": "gcp:cloud-sql" },
{ "id": "replica", "kind": "node", "nodeType": "database", "label": "Orders replica", "icon": "gcp:cloud-sql" },
{ "id": "backups", "kind": "node", "nodeType": "objectStorage", "label": "Backups", "icon": "gcp:cloud-storage" },
{ "id": "e_https", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "glb" }, "label": "HTTPS" },
{ "id": "e_glb_1", "kind": "edge", "from": { "elementId": "glb" }, "to": { "elementId": "web_1" } },
{ "id": "e_glb_2", "kind": "edge", "from": { "elementId": "glb" }, "to": { "elementId": "web_2" } },
{ "id": "e_sql_1", "kind": "edge", "from": { "elementId": "web_1" }, "to": { "elementId": "primary" } },
{ "id": "e_sql_2", "kind": "edge", "from": { "elementId": "web_2" }, "to": { "elementId": "replica" } },
{ "id": "e_repl", "kind": "edge", "from": { "elementId": "primary" }, "to": { "elementId": "replica" }, "label": "replication", "style": { "dash": [6, 4] } },
{ "id": "e_backup", "kind": "edge", "from": { "elementId": "primary" }, "to": { "elementId": "backups" }, "label": "backups" }
]
}
A Google group’s box comes from its members on every layout, and a save stores only the members’ places. A group’s own layout is a minimum anchored at its corner. The frames that share its span grow with it: a tier given a wider box widens every tier of its Region, and a taller one its row in every Region. extensions.autoGroup draws no bands here.
A saved Google Cloud diagram is drawn with the frames the layout gives its members. A Region saved with less than 24 px under what it holds is drawn lower, and the rows under the Regions move down with it. No node inside a Region moves, and the next edit saves the rows where they stand.
order constraints act within one row: leftOf and rightOf order the items of a global row, a Region’s row, a row of nodes in a subnet or the outside row. A tier’s cards keep their zones’ columns, and the other relations are ignored (Constraints: order).
Edges are routed after the layout, as Google draws its lines:
- A global load balancer that feeds the first tiers of two neighboring Regions stands over the gap between them when
gcp.cloudlists it, or the project that lists it holds both Regions. The gap opens for one line down it. The line forks under the subnets’ titles into the top center of each tier. Where those lines are drawn in more than one way, the gap opens for one line per way, 13.6 px apart, the outer ones at least 16 px off a Region’s border. Each way’s line runs to its tier on a track of its own. - Another global item’s line leaves the item’s side facing its target, above the Regions, and drops into the target’s top center. It leaves the item’s bottom instead in three cases:
- The target lies under the item.
- Another item stands less than 32 px beside that side, as Cloud Armor stands beside the load balancer.
- The drop into the target’s top, moved off center clear of a title, would stand less than 16 px from the item’s side.
- A line between an item outside the boundary, above it, and a global item above the Regions runs from the upper item’s bottom to the global item’s top. The upper item can stand in a frame or on its own. The line lands off center, clear of the title of the frame that holds the global item, when a drop into the middle would cross it. Two such lines into one top come in at least 13.6 px apart, as two arrowheads side by side on a face do in a Google Cloud diagram (Rendering: Google Cloud edges).
- Where the upper item doesn’t stand over the global item it calls, the line shifts sideways in the gap above the boundary. It stays clear of the item or frame it leaves and of the boundary, and crosses the boundary’s blue straight down. The router keeps the line off the blue when any route does, and runs along it only when none does, such as where the gap is too narrow for the shift. In a new diagram the gap opens to hold these lines and their labels.
- The gap above the boundary doesn’t open for a line from an item outside into an item deeper in, such as a tier or a card. An item that takes a lane stands over its lane instead (below).
- A line into a card from a row above it lands on the card’s top clear of the title of a group it enters, off center when it must. When a tier’s title leaves the card’s top no clear place, the Region’s tiers reach out on the title’s side until it does, and the cards keep their spacing.
- A line into a card of a Region with no subnet, from a global item above the Regions or an item outside the boundary, lands on the card’s top 16 px clear of the Region’s title and 13.6 px or more from the other lines into that card. When the title leaves the top no such place, the Region reaches out on the title’s side and the cards keep their places in the Region.
- Where the line can’t drop straight to that place, the router picks the face, so keep the title of a Region with such lines short.
- A line between an item above the VPC bands and one below them has no row to pass through, so it runs down beside the Regions. The item is a global item, an item outside the boundary, or an item a Region lists above or below its subnets.
- Two more kinds of line run there. One is from a global item or an item outside the boundary, above the Regions, into a card past the bands’ first row. The other is from a global item below the Regions, or an item outside the boundary below it, into a card before their last row. The rows of cards between stand in their way.
- A line that has a lane through the tiers (below) isn’t one of these: it runs through the subnet. A line into a card where no gap takes it has no lane, so it counts.
- The margin before the band’s first Region opens for each such line, 16 px from the band’s title, from the next line and from the Region’s border. A fresh layout moves the Regions by it. A line from above that ends at a card of the first row isn’t counted, and neither is one from below that ends at a card of the last row: the router takes the room that is left. A line between two items of one Region, which runs inside the Region, and one between two items outside the boundary, which goes around it, aren’t counted either.
- A line into a card of a tier from inside the boundary gets the reach above; one from an item outside it doesn’t. It lands clear of a tier’s title only where that item stands over a clear place on the card’s top. Elsewhere the router picks the face and can cross a wide tier title where no route round it exists, so keep the title of a tier such a line enters short.
- A line from a Region’s row above its subnets to an item below them, such as a nightly export to a database, can’t drop straight past the subnets. It runs along the gap over the VPC band and the gap under it. In a new diagram those gaps open to leave 16 px on each side of the line. The gap under the band also opens for a line from a party outside the boundary to such an item. A line from a tier or a node of a subnet’s own row isn’t this one: it runs beside the tiers (below).
- A line between two cards of a tier runs under their zone strips, inside the tier, as failover between zones does:
- A labeled line has room kept under it for its label, so the label doesn’t cover the line. When the line that drops down a gap between zone columns (below) crosses a labeled line, that line runs lower, in the middle of a deeper space under the cards, with its label under it.
- The room is sized by the label’s height, not its width. A label wider than 200 px wraps, and the room grows by its lines (Rendering: Label width). A label the placer later wraps narrower (label placement) doesn’t change the room: it is sized for the label as measured. A label wider than the line hangs out past its ends, wrapped or not, because wrapping stops at 200 px and not at the line’s length.
- An unlabeled line between two cards next to each other, in one zone or both in none, runs straight between their facing sides instead. A labeled one between them goes under the strips too.
- Replication between matched rows of two Regions runs as one straight line when no card stands between its ends. When a card of one of the two tiers does, such as a standby between a primary and its replica:
- Where a labeled line between two cards of the tier keeps room under its run for its label (above), the replication runs under the tier’s cards, below that room, clear of the label. The tier is deeper to hold it, in every Region of the row. That line’s label stays under its own run and covers no line.
- Where no line between two cards of the tier is labeled, or a line down a gap between zone columns crosses the labeled one (above), the tier keeps no such room. The router draws the replication as it draws any line (Edge routing).
- A labeled line that runs straight between matched rows of two neighboring Regions opens the gap between them only as far as its label needs.
- The label sits on one stretch of the line between borders or cards. The stretches run from each end to the borders the line leaves its Region through, and across the gap itself.
- When no stretch is as wide as the label plus its room, the gap grows to that width. The room is 24 px, or more for a line with arrowheads at both ends.
- A replication between the far zone columns of the two Regions crosses empty columns inside both tiers, and its label sits there. The gap stays as it is.
- The gap doesn’t open for a line between rows that differ, past a card standing between its ends, between Regions that aren’t neighbors, or into a Region with no subnet. The label placer places those labels, and a label can cover a border (label placement).
- A line into an item in the row below the Regions leaves its card’s bottom and enters the item’s side facing it. A Region’s items below its subnets stand a node’s clearance aside from such a line, and the Region widens for them when they need the room. A tier’s line enters the item’s top instead when the item stands under the tier with no node between them. That holds below the Regions and below a Region’s subnets.
- A line from an item outside the boundary, above it, to an item in the row below the Regions prefers a way around each Region it neither starts nor ends in to crossing it. A Region is a cost, not a wall: the line can still cross one when going around is far longer.
- A subnet or a tier is passed around only when the way is short, as any frame is (Edge routing), so a line between stacked tiers crosses the tiers in between.
- An AWS diagram doesn’t use this rule (AWS architecture diagrams).
- A line from a tier past another tier of its Region drops straight down a gap between zone columns. It ends at a lower tier, a node of a subnet’s own row, or a node the Region lists below its subnets. This needs two or more zone columns with every card in a zone. Where a tier the line passes has a card beside the gap, the gap opens through every Region. The node the line feeds stands under it. The line crosses the tiers in between, as any line between stacked tiers does (Edge routing).
- Where no zone columns take it, a line past a tier to a node the Region lists above or below its subnets runs beside the tiers, inside the subnet. It leaves a tier or a node of a subnet’s own row, or a card of a tier when the node is below. It runs along the gap next to its row, then drops straight into the node’s top, and the node stands under it. For a node above, it meets the node’s bottom and the node stands over it.
- The subnet’s inset on the side the lines run down, and the gap between the tiers, open to hold them, each line 16 px from the others and from the tiers. A side serves one node, the first a line lists. Where no zone gap takes it, the router draws any other line past a tier, such as one up from a card, one to a node of a subnet’s own row or one to a second node.
- A line from an item outside the boundary, above it, into a tier past another tier of its Region takes the same lane, and the item stands over it. The item takes lanes only as the last bullets say:
- Where the Region has two or more zone columns with every card in a zone, the line drops straight down a gap between the columns onto the tier’s top. It runs 16 px off the cards beside it and crosses the tiers it passes, between their cards.
- Otherwise it runs down the right of the tiers, inside the subnet, 16 px off the tiers and the subnet’s border. It turns along the gap over the tier’s row and lands on the tier’s top.
- A Region’s items above its subnets keep their order and stand aside from the lane, 16 px clear, and the Region widens when they need the room. The row of global items above the Regions stands 16 px clear of it too.
- Two lines from one item run in lanes 16 px apart.
- Each item takes one gap, in the order the scene lists its first line, and an item past the last gap gets no lane. Beside the tiers the lane serves the item whose line is listed first, and any other gets none.
- An item with no lane stands beyond the items that have lanes, left or right of them, where it wouldn’t fit between two of them.
- The lane also serves a line from outside to a node of a subnet’s own row. Through a gap between zone columns it serves a line to a card of a tier: the line lands on the card’s top and turns in the tier’s header. The turn can cross a wide tier title, so keep tier titles short (above). A line to a card with no gap to take is the router’s.
- An item takes lanes only if all its lines lead into one Region. Each goes into a tier, a card or a node of a subnet’s own row past another tier, and none is drawn curved. A line to another item outside the boundary doesn’t count.
- Any other line leaves the item without a lane, and its lines, the gaps and the ports are as without lanes. Examples: a line into a tier, card or node with no tier above it, to a global or regional item, to a second Region, or up from a tier.
- In a frame outside, each node counts for itself. A node with a line the lane doesn’t serve takes no lane, and the lines of the nodes with lanes all lead into one Region.
- A line from a global item over the Regions gets the lane for a tier only. The item takes a lane only if each other line it has is one of those, or runs to or from an item outside the boundary. A load balancer that also feeds both Regions’ first tiers gets none. A global item a project lists gets lanes only into that project’s Regions.
- A
straightedge keeps the item over its lane and draws one segment. The segment runs down a gap to a tier or a node, runs slanted to a card, and beside the tiers crosses the tiers in its way. Where it crosses a card it gets EDGE_CROSSES_NODE: leaverouteroff to take the lane. Acurvededge gets no lane. - Only a top-to-bottom flow gives an item outside the boundary a lane, or a bottom-to-top flow for an item that a top-to-bottom flow would stand below the boundary. In a left-to-right or right-to-left flow the line is drawn as without lanes.
- A line between two items outside the boundary, such as browsers loading a script from a CDN, runs between them on their side of it. When a saved diagram has them on opposite sides, it goes around the boundary (Edge routing).
- The AWS passes for group borders, crossed labels, end legs and clearance (AWS architecture diagrams) also run, with Google’s groups in place of AWS’s. Each move is kept only where it adds no crossing; otherwise the line stays as routed.
- In a diagram the cloud layout arranges, a label keeps out of line with another edge’s straight run, as in AWS diagrams (AWS architecture diagrams, Labels).
- A Google label keeps a 10 px floor from other lines and from every card but its edge’s ends, and sits at least twice as near its own line as any other, where there is room. It stays out of a frame’s title row too (label placement).
- Lines drawn differently out of or into one point take ports of their own, with the exceptions listed for AWS diagrams (AWS architecture diagrams).
- Lines keep apart. On a new layout, two lines in a Google Cloud diagram the cloud layout arranges never run side by side under 13.6 px apart, the room two arrowheads need, for 40 px or more. A diagram the layout doesn’t arrange, such as one of cards with no Region or subnet, keeps the 12 px the generic router spaces parallel lines at.
- Lines keep off the cards they pass. The rules in Edge routing for lines near nodes hold here. Spreading or nudging lines never moves one through a card. Where no route keeps its distance, the router draws the line round the cards, near a border, or across a title, if it must. A line crosses a card it doesn’t end on only where no route round the cards exists. The API returns no note for these, so check the image (EDGE_OBSTACLE_GRAZED). A
straightorcurvededge is never routed round cards: where it crosses one, it gets EDGE_CROSSES_NODE. - Lines keep off every title. In a Google Cloud diagram the cloud layout arranges, an orthogonal line is routed round every group’s title, the VPC’s included, and can still cross one where the router finds no route round it. A
straightorcurvededge keeps its one segment and can cross a title. - Lines prefer a channel to a narrow strip between two borders. In a Google Cloud diagram the cloud layout arranges, an orthogonal line takes a channel clear of both borders over a strip between two frame borders closer than 32 px, such as the strip between a Region’s border and its subnet’s, when the detour costs the router less than the run it saves. Where the detour costs more than the run saves, the line runs in the strip. The margin beside the VPC band is such a channel. A
straightorcurvededge keeps its one segment. Other diagrams, AWS’s included, have no such preference. - A straight shortcut isn’t taken across a line already drawn. In a Google Cloud diagram the cloud layout arranges, when two cards face each other but aren’t centered on one another, the router doesn’t join them with one straight segment where it would cross a line already drawn, including one that turns into the same face of the target from the side. The line takes another route, chosen as for any line (Edge routing says what the router does about other crossings). A
straightorcurvededge keeps its one segment. Other diagrams, AWS’s included, don’t make this check. - Two lines out of one face nest. A failover and a replication that leave one card’s face and come back to faces of two other cards, such as into another Region, nest as Where an edge enters its target describes, so neither crosses the other. A tier leaves room under its cards for one line, so the outer line of a nested pair runs on the tier’s bottom border. The exception is a replication that runs under the tier’s cards (above): the tier is deeper then, and the line runs inside it.
- A generic frame keeps a lane for a line past its cards. In a top-to-bottom Google Cloud diagram, a line leaves a card of a generic frame laid out as a block (a GKE cluster, a service perimeter) for a card outside the frame, and another card of the frame is in the line’s way. In a new layout and after an
autoLayoutwithoutelements, the frame then keeps a lane beside or under its cards, and a second line that would cross the first in one lane gets the lane over them. The line runs in it at least 16 px off the cards and the frame’s border, and leaves its card by the face on the lane’s side.- Two lines down the cards that would cross in one lane take the two sides of the cards.
- No lane: a line to a frame, a line from a card whose face toward the line’s other end is free, a frame inside another generic frame (the outer frame’s lanes serve its cards), and any diagram with
layoutStrategy.directionother thanTB. - A saved diagram keeps its frame and its cards where they are: an edit that adds such a line opens no lane until
autoLayoutwithoutelements.
- Two lines past a frame’s cards take its lane under them and its lane over them. When two such lines to cards beside the frame would cross in one lane, one runs in the lane under the cards and the other in the lane over them. The frame’s top grows until the line over the cards runs 16 px under the frame’s title.
- A line from above that ends on a generic frame laid out as a block lands clear of its title where it can. In a top-to-bottom Google Cloud diagram it lands on the frame’s top, 16 px clear of the title, where it can still drop straight under the item. Where the title leaves no such place, or the item has other lines down, it lands where the router puts it, which can be just above the title.
Draw an edge to a tier rather than to each of its cards, as Google’s diagrams do: an edge to each card draws an arrowhead into each one.
Edits keep every position and grow rows, zone columns, Regions and project boxes, as a table inserts a row or a column. What lies past a growth moves by exactly the growth. An edit also moves these saved nodes:
- a load balancer over the gap between two Regions, to stay over it, or under an item of its row that stays in its way,
layoutStrategy.nodeSpacingclear (30 px by default;autoLayoutwithoutelementsarranges the row again and moves every node); - the items joined only to that load balancer in its row or outside the boundary, such as Cloud Armor beside it and the users over it, by the same move where their row has room, else they stay until
autoLayout; - an item alone in a subnet’s row and joined only to tiers, such as an internal load balancer between two, to stay centered on them when they widen;
- an item of a subnet’s row of nodes that a line the edit adds crosses, aside from the line as on a new diagram (above);
- an item of a Region’s row below its subnets that a line the edit adds crosses, aside from the line where the row has room within the subnets, else it stays in the line’s way until
autoLayout; - an item outside the boundary that lies right of a gap between zone columns an edit opens for a lane, by the opening (below);
- the later of two sibling projects whose boxes were saved overlapping, and what lies right of it, until the boxes are as far apart as on a new layout;
- the two nodes of an
orderconstraint the edit adds, when they stand the wrong way around (below).
Each kind of edit places what it adds:
- Cards’ widths. An edit doesn’t draw cards at one width again: a card it leaves alone keeps its width unless its own label needs more. A card it adds to a tier in a zone takes the width the zoned cards share, wider where its label needs it; a card it adds elsewhere takes the width its own label needs. A layout of every node, such as
autoLayoutwithoutelementsor anupdateScenethat removeslayoutStrategy, draws the cards that stand together at one width again (Google Cloud architecture diagrams). - A card added to a tier stands in its zone’s column.
- Send
createNodewithframeset to the tier, andupdateFramewith the zone’sspanslisting its cards, the new one included. - The card stands in the column’s middle when the tier has no card in that zone, else right of the tier’s last card there, and the column widens through the Region. A card in no zone goes last in its row.
- A card wider or taller than the others widens its column, or makes its row taller in every Region.
- A card that comes to stand between the ends of a replication line, such as one placed right of the standby, sends the line under the tier’s cards when the failover is labeled, as on a new diagram (see the routing above). The tier gets deeper in every Region, and what lies under it moves down by that growth.
- Send
style.multiple: trueset on a saved card grows its box to hold the copy, by up to 4 px across and 4 px down. It grows less where the saved box has room to spare, as a zoned card’s shared width often has. A card first saved as a stack keeps the stack’s box whenmultipleis setfalseor removed, the single card filling it, untilautoLayout.- A new zone comes after its Region’s others, as
createFrameadds it, so its first card makes the Region’s last column. - A new tier or row of nodes goes in at its place in the subnet’s flow, and the rows after it move down in every Region.
- A new Region goes right of the last, its rows level with the others’, and the VPC band and the boundary widen.
- A project’s title place isn’t saved. Every layout works it out again from the places the cards have, by the rule above. An edit that adds a line from above into a card under the title can move it to the top left, and one that removes the line can return it to the center.
- An item added to a project takes the free place in the project’s own row, nearest the nodes it connects to.
- With another box beside the project, it stands within the project’s width. The box grows when the row has no room, and the project after it moves right by the growth, so the boxes keep their gap.
- A project that holds every Region has no box beside it, so it widens on the side the item needs, as on a new layout (above).
- An item the project lists under its Regions grows the box down, and the boundary’s items below move down by that.
- The new item stands clear of a line that passes through the row, 16 px off it, as on a new layout. No saved item moves for the line.
- A line added through a saved row of a project’s own items moves no saved card. The router draws the line round the row’s cards where a route round them exists. The API returns no note where none does, so check the image (EDGE_OBSTACLE_GRAZED).
autoLayoutmakes the row stand aside from the line, as on a new layout, and moves every node. - A card added to a Region’s rows of cards joins a row and adds no row.
- It joins the row after the lowest card with an edge into it, or the last row when none follows. With no such edge it joins the row before the highest card it has an edge into, or the first row when none precedes. With neither, it joins the last row.
- When its place in the row is too small, the cards after it in that row move along.
- An edit never reorders the saved cards or arranges them by flow again, so a Region whose one row grows past 1,400 px by edits keeps that row, and a new card joins it.
autoLayoutwithoutelementsarranges the cards by flow again.
- A node added to a Region, to the boundary or outside it takes the free place in its row nearest the nodes it connects to. When that place is too small, the row opens there, and the items after it move along. A Region’s first item below its subnets makes the Regions taller by its row, and what lies below them moves down by that. New items below its subnets stand clear of the lines falling past their row, as on a new diagram, and the Region widens for them when they need the room.
- A load balancer’s line into a second Region. When
gcp.cloudlists the item, or the project that lists it holds both Regions, an edge that makes a global item feed the first tiers of two neighboring Regions opens the gap between them for the line, and the subnets get room above their first tiers for its fork. The item moves to stay over the gap, and the items joined only to it move with it (above). What lies right of the gap moves right, and what the Regions hold moves down, by that room. - A label on a straight line between two neighboring Regions’ matched rows. An edit that adds such a line with a label, or labels one, opens the gap only in the cases a new diagram does (see the routing above). The second Region and what lies right of it move right by what the gap opens, and no card within a Region moves. A saved gap that is already wide enough stays as it is.
- Items outside the boundary. A node an edit adds outside goes on the side of the saved items outside it’s joined to. When those stand on both sides, it goes on the side more of its edges reach. A line an edit adds between two saved items outside leaves them where they stand. When they stand on opposite sides, the line goes around the boundary until
autoLayoutputs them on one side. - A saved party’s lines into the row below the Regions. An edit that gives a saved party outside the boundary lines only into that row leaves it on its side.
autoLayoutmoves it below, unless it has a user icon and a line to anything but a dashboard service below the Regions. A node an edit adds outside goes below, as on a new diagram, when its lines reach only that row and none goes to a saved item outside. It also needs either no user icon or lines to dashboard services below the Regions only. - A line from outside into a global item. An edit that adds one moves nothing and keeps the gap above the boundary as saved. Where that gap is under 32 px, a line that shifts sideways in it passes nearer than 16 px to one side.
autoLayoutopens the gap as on a new diagram (see the routing above). - A line past the subnets from the row above them. An edit that adds one moves nothing and keeps the gaps over and under the VPC band as saved. Where a gap is under 32 px, a line that runs along it passes nearer than 16 px to one side of it.
autoLayoutopens them as on a new diagram (see the routing above). - The members of a frame outside keep their saved order and places, even when a line an edit adds would reorder them.
autoLayoutorders them by their lines, as on a new diagram. - Saved global and regional items keep their rows when lines an edit adds would give them the other row.
autoLayoutputs each in the row its lines give it. - A line into a card under a tier title too wide for it. When an edit adds the line or widens the title, the Region’s tiers reach out on the title’s side, as on a new diagram (see the routing above). No card moves when nothing stands on that side of the Region. Otherwise what lies past the growth moves by it, the Region’s own cards included when the title is at its left.
- A line into a card of a Region with no subnet. When an edit adds the line or lengthens the Region’s title, the Region reaches out on the title’s side, as on a new diagram (see the routing above). No node moves when nothing stands on that side of the Region; otherwise what lies past the growth moves by it.
- A line between the two sides of the VPC bands. A line an edit adds opens the margin as on a new diagram (see the routing above). The band and the frames around it grow on that side, and no node moves.
- A tier’s line past another tier. An edge an edit adds from a tier past another tier opens its gap between zone columns (see the routing above), and what lies right of the gap moves right by the opening. A node of a subnet’s own row that the line feeds stays under it.
- A line from outside into a lower tier. An edit that adds an item outside with its line opens the lane as on a new diagram.
- Down a gap between zone columns, the gap opens and what lies right of it moves right by the opening. The saved cards left of it stay.
- Beside the tiers, the subnet’s inset and the space between the tiers open. The rows under the space move down by the opening, as for a line past a tier beside the tiers (below).
- The new item takes the free place nearest the lane in its row, as any new item does (above). Where that place is over the lane, a line into a tier is straight down a gap, and beside the tiers it turns along the gap over the tier’s row. Where saved items hold it, the line bends to reach the lane.
- An item you add with a line into a card or a node stands over that card or node, and its line bends to reach the lane.
- An edit that gives a saved item a line the lane doesn’t serve, such as one into the first tier, leaves the item without a lane. The router draws all its lines, the saved ones included, and no saved node moves.
- A line the lane serves that you add from a saved item that already has a line it doesn’t serve takes no lane.
- When an edit removes that other line, the lane opens as above. The item doesn’t move toward it: it moves by the opening when it lies right of the gap, and otherwise stays. Its line then reaches the lane in two bends at most down a gap, or four beside the tiers.
- A line past a tier beside the tiers. The subnet’s inset and the gap between the tiers open as on a new diagram (see the routing above). Saved lines there keep their places, the new line runs 16 px outside them, and a node below the subnets that it feeds moves under it. What lies under the gap moves down by its opening, and what lies right of the subnet moves right by the growth.
- An
orderconstraint an edit adds swaps its two nodes when they stand the wrong way around in one row and their places fit each other; nothing else moves. Two that don’t fit are placed in order as new nodes are, which can open the row. A load balancer over the gap between two Regions keeps its place, and the other node stands beside it in the order asked. New nodes a constraint joins in one row go in the order asked. - A whole boundary, or a Region with no boundary round it, added to a saved diagram is laid out as on a new diagram. It stands where a new layout would put it next to the saved nodes it connects to, such as the users above it, and every saved node keeps its place. Where that place would cover a saved node, it stands right of everything saved instead.
- Deleting closes no gap: what stays keeps its place until
autoLayout.
The save’s changed lists every node these moves place, and a compare lists them as changed.
What the arrangement doesn’t do:
-
Other families. It arranges architecture diagrams and diagrams without a family. In a network, workflow or other family’s diagram the presets draw Google’s groups, the zones and the VPC aren’t drawn (
SPAN_NOT_DRAWN), and that family’s layout places the nodes. -
Guessing groups from titles. A frame titled “Subnet” without
containerType: "gcp.subnet"is laid out as any frame, whatever its title. When it holdsgcp:*icons and its title is a Google group’s own name, it getsGCP_GROUP_UNTYPED, which names the preset to set or says to leave the frame generic. A VPC or a zone takesspans, notchildren: delete the frame and create it again withspans. Validation rules says which titles count. -
Reordering. Regions keep the boundary’s order, zones the order the scene lists them in, and a subnet’s rows the order their edges run. The engine doesn’t reorder them to cut crossings. The one order it chooses by counting crossings is that of the items a Region lists directly, where they stand in rows by flow (above).
-
A project’s item over another project’s Regions. An item stands over the Regions of the project that lists it. So a load balancer’s line down the gap between two Regions forms only when
gcp.cloudlists it, or the project that lists it holds both Regions. To draw a load balancer over the service projects it feeds, list it ingcp.cloud, not in one project. -
Zone columns outside tiers. Only a tier’s cards stand in zone columns. A node a subnet or Region lists directly stands in its row near its neighbors, or in a row by flow (above). A tier a Region lists directly is laid out as one block in the Region’s row above or below its subnets. Put cards in a tier, and tiers in a subnet.
-
Frames between the groups. A project, or a generic frame round whole Regions, is read through for its Regions, and its box is fitted round its Regions and the items it lists itself (above). A generic frame at the top that holds Regions is arranged as the boundary is. Any other frame between the groups is laid out as one block in its row, and what it holds loses the arrangement:
- a generic frame in a Region round subnets, which gets
GCP_FRAME_HIDES_GROUPS; - a generic frame in a subnet round tiers, which gets
GCP_FRAME_HIDES_GROUPStoo; - a generic frame round cards, such as a GKE cluster or node pool, whose cards stand in no zone column.
List subnets in their Region, tiers in their subnet and cards in their tier directly.
- a generic frame in a Region round subnets, which gets
-
Nesting Google doesn’t use. A preset where Google doesn’t nest it, such as a subnet no Region lists, is laid out as any frame, with the warning
GCP_GROUP_NESTING. -
Two clouds. A diagram with both AWS’s and Google’s groups arranges each its own way, side by side in the order the scene lists them. What lies outside them goes left and right when the first is AWS’s, and above and below when it is Google’s.
-
Arranging what
updateFramemakes Google’s. A diagram whose framesupdateFramemakes Google groups keeps its nodes where they are. A node added later goes inside its frames, clear of the others, but outside Google’s rows and columns untilautoLayoutarranges the diagram: send it in the same edit as theupdateFrameops, or later. -
Rearranging a saved diagram. After the first save an edit places only what it adds, and moves other nodes only to make room, as above. So a diagram that grew unevenly, such as one with a new card right of a tier’s others, keeps its shape until
autoLayoutarranges it again.autoLayoutmoves every node, hand-placed ones too.
Numbered steps
An edge’s step, a whole number from 1 to 99, draws a numbered badge at the start of its line, as AWS’s architecture diagrams number the path a request takes. Its stepText adds the edge’s line to a step list beside the drawing. Steps are drawn in every family, and a sequence diagram can also number every message itself (Numbered messages). Rendering: Step badges shows how they look.
{ "id": "e_upload", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "api" }, "label": "HTTPS", "step": 1, "stepText": "The customer uploads a photo to the API." }
In every family but sequence diagrams:
- Where a badge goes. Beside its line’s first stretch from the source, above or left of it first, 10 px clear of icons, captions, labels, other lines, frame borders and headers, and other badges. It takes the first clean place along the line, twice as far from other edges’ lines as from its own where its line has such a place. Past a fork its step shares, it sits on its own branch where there is a clean place. With no clean place, it takes the place that overlaps least, as a label does.
- Badges that face each other. Two badges either side of one line read as a pair, so the one whose line it isn’t reads as that line’s (yFiles counts a label between two edges as ambiguous). Once every badge is placed, a badge whose center is within 62.5 px of another badge’s line, opposite that badge, moves once. It takes the first clean place along its own line that is twice as far from other edges’ lines as from its own, where it faces no badge and none faces it. Where its line has no such place, it stays.
- One badge per step per source. Edges with the same
stepand the same source share one badge, beside the stretch they share. The same number on edges from two sources draws two badges. - Room. Badges are placed after the routes, so lines don’t go round them, and edge labels keep 10 px off them. When the engine lays out every node, an edge with a step keeps room for its badge beside its label, so the ranks hold both. Adding a step to a saved diagram moves no node: its badge takes the clearest place left.
In every family:
- The step list. It stands 40 px right of the drawing, top-aligned with it, with no panel. The canvas grows to hold it, with the drawing’s margin past it to the right and bottom edges. Steps appear in number order, each with its badge and then its edges’
stepTextin document order, wrapped at 280 px. A step with text on several edges gives each its own bullet.
What steps don’t do:
- Number for you. The engine draws the numbers you give. Apart from a sequence diagram’s
autonumber, it doesn’t number edges or check that the numbers run in order. - List labels. The list shows
stepTextonly, and labels stay on their lines. A step whose edges have nostepTexthas no entry, and a diagram with nostepTexthas no list. - Hidden edges. A hidden edge, or one with a hidden end, draws no badge and has no line in the list.
- Mermaid. A flowchart’s
view: "mermaid"leaves steps out, with the noteSTEPS_NOT_EXPORTED, and a Mermaid edit keeps them. AsequenceDiagramwrites a message’s step as anautonumberline and leaves out onlystepText(Mermaid scope).
Numbered messages
A sequence diagram draws a message’s number as Mermaid does: a numbered badge centered on the start of its arrow, on the sender’s lifeline. An arrow that leaves an activation bar starts on the bar’s face, and its badge is centered on that bar’s axis, half a bar back from the face, as is a self-message’s on the bar its loop leaves. Of stacked bars, that is the one whose face the arrow leaves (Rendering: Lifeline rendering). An arrowhead at the start points at the badge (Rendering: Step badges).
To number every message, set autonumber in the document’s top-level extensions, beside showLifelineFeet:
{ "schemaVersion": "0.1", "diagramFamily": "sequence", "extensions": { "autonumber": { "start": 10, "increment": 10 } }, "scene": { "title": "Login" }, "elements": [] }
- The count.
truecounts from 1 by 1. An object sets where the count starts (start) and what it goes up by (increment), each a whole number from 1 and 1 when left out. Messages are numbered in row order each time the diagram is drawn. - Edits. Adding, deleting or moving a message renumbers the messages after it without changing them. The colored diff shows each version’s own numbers, and a removed message’s ghost keeps its old one.
updateScenewithextensionssets or removes the setting (Operations: updateScene). - A message’s own
stepis drawn as given, and the count goes on from it, as Mermaid’s and PlantUML’sautonumber 20restarts the count partway down. - What takes no number. Notes, hidden messages and messages to or from a hidden lifeline take none, and the count skips them.
- Room. A numbered row keeps the badge’s room below its arrow, so a note, divider or fragment end after it clears the badge, and labels keep 10 px off it. A message with
stepTextis listed in the step list under its ownstep.
What numbering doesn’t do:
- Numbers like 1.1, or PlantUML’s number formats. Numbers are whole. Write such numbering in the label instead.
- Other families.
autonumberdraws nothing outside a sequence diagram, and the diagram gets the warningAUTONUMBER_NOT_DRAWN: give each edge you want numbered astep.
Spanning frames
A frame written with spans instead of children is drawn round the nodes and frames it names, outside the containment tree, as AWS draws an Auto Scaling group or a security group across Availability Zones. It holds nothing: each target keeps its own frame. Spanning frames are drawn in architecture diagrams and diagrams without a family.
{ "id": "asg", "kind": "frame", "containerType": "aws.autoScalingGroup", "title": "Auto Scaling group", "spans": ["app_a", "app_b"] }
- Its box is the union of its targets’ boxes, 10 px out on the sides and the bottom, with its header on top. An edge’s last leg can cross the border to reach an end with a glyph, such as an arrowhead. On that side the border keeps the glyph’s reach from the end instead: its depth at the widest theme stroke plus 4 px, 20 px for an arrowhead. So the border runs through no arrowhead in any theme. It is at least as wide as its header, and has no fill.
- Room in an AWS diagram. Rows are shared, so the row lane above the frame’s top row deepens for its header in every Availability Zone, and its top border runs between the rows. A frame round what subnets hold deepens the lane under the subnets’ headers instead. Room is kept only when every target is a subnet in one VPC’s rows, or sits in one. A spanning frame round Availability Zones or VPCs, or with a target in a Region’s column, AWS Cloud’s row or the outside columns, gets none.
- In a Google Cloud diagram. In Google’s arrangement a
gcp.vpcis drawn as one band across the Regions that hold its subnets, not round its targets, and agcp.zoneas a strip under each node it spans (Google Cloud architecture diagrams). Any other spanning frame there gets no room for its header and is drawn in the room its targets have. - Room elsewhere. When the engine places nodes, each target keeps a margin: 10 px round it and the header’s depth above. A target that an edge from outside the frame ends on with a glyph keeps that glyph’s reach on its sides instead. A spanning frame added to a saved diagram moves no node there; it is drawn in the room its targets have.
- Its header is placed after the routes, where its preset puts it along the top edge (an Auto Scaling group’s centered under its icon). Where that place comes within 16 px of a line, or of another frame’s side beside it, the header moves along the edge to the nearest place that keeps 16 px from both. Edge labels and badges keep off it.
The box is one rectangle, so a node inside it that it doesn’t span reads as spanned: the warning SPAN_COVERS_NODE names it. Add the node to spans when it belongs there, or span only targets that sit together. autoLayout places every node again with a margin round each target, which clears a node pressed against one but not one between two.
What spanning frames don’t do:
- Hold members. A spanning frame holds nothing, and its targets keep their frames. Element types: Spanning frames has the rules it follows and
SPAN_INVALID. - Other families. Outside architecture diagrams and diagrams without a family, nothing is drawn, with the warning
SPAN_NOT_DRAWN. - Mermaid.
view: "mermaid"leaves spanning frames out, counted inCONSTRUCT_DROPPED, and a Mermaid edit keeps them, apart from what deleting a node removes (SPAN_REMOVED).
The pipeline
A layout of every node runs the scene through five phases. Each phase has well-defined inputs and outputs and can be inspected in isolation. When some nodes already have positions, phases 2 to 4 place only the others, next to their neighbors (moving placed nodes only in the cases Positions are kept lists); measurement, edge routing and label placement run on every save.
1. Measurement
Every node and every edge label is measured before any positioning happens. Node sizes come from intrinsic measurements (text width, padding, fixed shape constraints). Edge labels are measured to the pixel so the planner can leave room for them between ranks: the label as drawn, its backdrop’s padding, the arrowheads and ER glyphs at both ends at the widest theme stroke, both nodes’ outlines and, where the border of a frame laid out with its members (or, for a node placed later, any frame) lies between the ranks, 6 px of clear space either side of it. A label wider than 200 px is measured wrapped, narrower and taller: a flow left to right reserves its width between ranks, and one top to bottom its height.
The gap holds no room for a fan-out’s fork, so a label on a short branch past the fork can still sit near its sibling’s line or over its own arrowhead.
A layout of saved positions keeps its gaps, so there a label can still cross a frame’s border or cover its own arrowhead when the gap is too narrow: a new edge between two saved nodes, a longer label on a saved edge, a saved label wider than 200 px, or a label that only comes within 6 px of a border. A new node’s label that needs more room pushes the column it joins (Positions are kept).
An edge with a step also keeps room for its badge beside its label when the engine lays out every node (Numbered steps). autoLayout without elements lays every node out again with this room, moving the nodes you positioned (Laying out again).
2. Layer assignment
Nodes are assigned to ranks (rows for TB, columns for LR) based on the directional flow of the graph. Cycles are detected and broken using a feedback arc set heuristic, so the algorithm always produces a finite layering even on cyclic input.
3. Crossing reduction
Within each layer, nodes are reordered to minimize the number of edges that cross. The algorithm uses the median heuristic: each node’s preferred position is the median index of its neighbors in the adjacent layer. The down sweep aligns each layer with its predecessors, the up sweep aligns each layer with its successors, and a fixed number of iterations is enough to converge for any normal graph.
When two nodes have nearly the same median position, the algorithm tiebreaks by input order. This preserves natural reading order: if you declare api1 before api2, they’ll appear in that order even when the heuristic could swap them to save a single crossing. Substantial median differences still trust the heuristic, so this never produces a worse layout - it just prevents counter-intuitive reorderings.
4. Coordinate assignment
Once layer order is fixed, each node gets its position along its layer in three steps:
- Barycentric placement. Each node’s target is the mean of its neighbors’ positions in the adjacent layers, projected onto a non-overlapping arrangement with Pool Adjacent Violators (PAVA), the L2-optimal monotonic sequence under the spacing constraints. The down and up sweeps repeat a fixed number of times, the centroid normalized to zero after each pass.
- Chains lined up. Rank by rank, each node lines up with the nearer of its median neighbors in the rank before (Brandes and Köpf’s alignment, as dagre and ELK use it). It doesn’t when that neighbor is taken or the pair would cross a pair already lined up. Long edges come first, as Graphviz weighs an edge’s straightness: when one of a node’s two median neighbors is a long edge passing through the rank, the node lines up with it. Each chain is then placed as one, every spacing kept.
- Straightened. A chain shifts onto a neighbor across an edge that isn’t straight when every node in it has the room. No shift bends a long edge to straighten a short one.
So a chain of single-parent / single-child nodes is one straight line, and a worker connected only to a job queue sits exactly under it. A node with several children lines up with one of them. When each child lines up with another node or would cross a pair already lined up, the node sits among them instead. Nodes in a rank keep the layout’s node spacing apart (Aesthetic scoring says which spacing that is). What it doesn’t line up:
- Entity-relationship diagrams keep the barycentric placement. Their edges dock on table rows, not on centers, so lining centers up straightens nothing.
- A decision or gateway (a diamond, not an
er.relationship) lines up only across a side it has one edge on. With two or more branches leaving a side it keeps its place among their targets, so each branch has a tip facing it. Each of those targets then ends on the decision’s line or clear of it. The engine makes these moves for all the diagram’s decisions at once, and only when every one keeps the layout’s spacing; otherwise it makes none.- A decision whose label is inside it (a
decisionor another plain diamond, or aworkflow.decision) lines up a target whose shape already spans its line, so that branch runs straight. - A gateway whose label sits outside its diamond lines up only a target already on its line.
- Any other target keeps its box 16 px off the line and its center 16 px past the decision’s tip on its side. Its branch leaves the tip on a leg and turns once, as BPMN modelers draw a gateway’s branches. A wide decision with targets on both sides makes the drawing wider, since each target’s center sits past its tip.
- A decision whose label is inside it (a
- An edge that runs against the flow doesn’t line its ends up. The router draws it as a loop round the outside of the ranks it spans (Edge routing).
A flowchart (diagramFamily: "flowchart") is placed by its decisions’ answers (Diagram families: Flowcharts):
- The way on. A decision’s way on is the exit it sends straight on (Diagram families: Flowcharts). The decision lines up with that target, whatever its other branches.
- The main path starts at each node that no edge enters along the flow. It follows each node’s one exit and each decision’s way on, and stops at a fork, a decision with no way on, an end or a node already on a path. It lines up before any other chain, so it runs straight.
- The ways aside. Each other answered exit’s target, and the long edge to it, lies past its decision’s line in every rank it reaches: right in
TBandBT, below inLRandRL. Anorderconstraint, or another decision’s way aside, wins over this. - Loops. The router draws a loop across two or more ranks round the low side (left in
TBandBT, above inLRandRL), away from the ways aside, unless the other side crosses fewer nodes or edges.
A decision with no way on keeps the decision rules above. So do the checks of an else-if ladder, and every decision in a flowchart whose frames are laid out with their members; that flowchart’s loops still keep to the low side (Diagram families: Flowcharts).
The canvas-aware spread then scales every gap by one factor, so a straight chain stays straight and a target clear of a decision’s line stays clear.
In a diagram whose frames are laid out with their members, each frame is placed with them. In layer assignment its members are pulled into neighboring ranks, and in crossing reduction it moves as one block among its siblings. Here its two borders are positions of their own, solved with the nodes, so members keep the frame’s padding and other nodes stay out of it.
In such a diagram, chains line up too, across a frame’s border where an edge enters or leaves the frame along the flow. A member doesn’t line up with a node beside its frame in a rank the frame spans. Long edges don’t come first there, and a decision lines up with one of its branches as any node does, its targets left where they are placed.
In an AWS diagram the cloud layout arranges, some frames are each placed as one block, such as a generic frame outside the VPCs, or a serverless diagram’s AWS Cloud or Region (AWS architecture diagrams lists them). One that holds no frame of its own is laid out as a diagram without frames, so its chains line up as above, long edges first, and its decisions follow the rules above. One that holds frames lines up its chains as a diagram whose frames are laid out with their members does (above). The cloud layout places the rest by its own rules: a VPC’s rows and Availability Zones, a Region’s column and the items outside AWS Cloud.
5. Edge routing
After every node has a position, edges are routed. The router walks a ranked list of anchor candidates for each edge. When the source lines up with the target (its center inside the target side’s range), the same-axis pair of step 3 leads, so the edge runs straight; when it doesn’t but the two facing sides overlap, the router first tries a straight line through the overlap, and when a node in between blocks the straight line, a straight line beside that node (Where an edge enters its target):
- The visually preferred centered entry: leave the source perpendicular to the line connecting the centers, enter the target through a centered N/S or E/W face. The L’s terminal leg lands on the target’s center column / row.
- If the centered L collides with an obstacle, try a 5-point step path that routes through the gap between source and target while still entering the target perpendicular to a centered face.
- If both fail, fall back to the same-axis pair (E↔W or N↔S) so the bend hugs the target’s edge. Its target end runs straight across at the source’s coordinate when that lands clear of the target side’s corners (8 px, more past a rounded corner), and otherwise enters the side’s center; a BPMN sequence flow or UI-flow transition enters the center unless it is less than 16 px off (Where an edge enters its target). When no candidate is clear of obstacles, the router searches for a route round the nodes, and crosses a node only where none exists.
A frame, whatever its containerType, is a container for the edges that end inside it and an obstacle for the rest: an edge between two children of a swimlane is never reported as colliding with the lane itself, and an edge with neither end in a frame goes round it, as the list below says. Every lane of a pool that holds an end of an edge is a container for that edge too, so a flow between two lanes crosses the lanes between them (Pools and lanes). So is every Availability Zone of a VPC that holds an end of an edge, in a diagram the cloud layout arranges, so an edge crosses the AZ columns between its ends; the subnets in them are not (AWS architecture diagrams). Groups are neither. Frames and groups are also valid edge endpoints: when an edge’s from or to references a frame ID, the router computes anchors against the frame’s bounds and the arrow terminates at the frame’s border, exactly as it would for a node target. This is the platform mechanism behind the edges-to-a-group-as-a-whole authoring convention.
What the router keeps to around frames:
- An edge crosses the border of a frame that holds one of its ends, or that it ends on, and runs freely inside it. It keeps 16 px off the border of a frame that holds neither end and goes around that frame rather than through it, unless the way around is far longer. In a diagram of frames stacked as tiers, an edge between two tiers crosses the tier between them.
- An edge between two items outside a cloud provider’s boundary, a
gcp.cloudoraws.cloudframe, goes around it, however long the way. A line across a trust boundary would read as data crossing it. Routing doesn’t move the nodes the edge joins;autoLayoutputs them on one side (Google Cloud, AWS). Two kinds still cross:- a
straightorcurvededge, which keeps its own line; - an edge the router finds no clear way for at all, which crosses the boundary on a route round the cards. The API returns no note for it, so check the image (EDGE_OBSTACLE_GRAZED).
- a
- An edge between two members of a frame stays inside that frame.
- An edge doesn’t run along the border of a frame it crosses when a route with as many bends keeps 16 px from it. Between two frames drawn closer than 32 px apart, no route can, and a bundle of edges leaving one frame forks halfway across the gap. An edge leaving or entering a frame’s member turns 16 px past the frame’s border rather than on it, when every route that turns sooner would run along the border.
- An edge keeps off frame titles, and a pool’s or lane’s whole header strip counts as its title. A title is an obstacle: the edge leaves its node a little further along the same face, takes more bends, or enters its target by another face to avoid crossing one, and crosses it only when no way in keeps off every title (a member wedged under its frame’s header between the frame’s border and its neighbors). A header that carries an icon (an AWS group’s icon and title) gets a node’s clearance: an edge’s inner segments keep 16 px off it, its end legs 4 px. In a diagram the cloud layout arranges, so does every AWS group’s header, an Availability Zone’s title too (AWS architecture diagrams). A plain title is kept 4 px off, as Graphviz and ELK let lines pass a cluster’s label.
- An edge may cross a spanning frame’s border, which breaks where a line crosses it. A line keeps off that border as off any border it crosses. The room kept for its header, from its top border down to its targets, counts as a frame’s header: a line runs along it only where no route keeps out, and crosses it on the way in. Lines come in where the route is shortest, often into a target’s side below that room.
- Groups draw no border or title and are not considered. Back edges that loop round the nodes they span, such as a retry or a rollback, are not held to these rules yet. Such a loop can run close inside a frame’s border.
After routing, every path but a straight or curved edge’s (whose ends lie exactly on their outlines) is run through a simplification pass that snaps near-equal coordinates, drops consecutive duplicates, and removes colinear midpoints. This eliminates the sub-pixel wiggles that come from planner-driven width mismatches and keeps arrow markers oriented cleanly.
A channel routing refinement then detects interior edge segments that overlap or run in parallel within the same corridor (from different edges) and spreads them into distinct tracks. This prevents multiple edges from visually overlapping when they share the same horizontal or vertical segment. Edges that come the same way to one point, such as a bundle leaving one point of a node before it forks, are one track in every channel, as ELK routes the edges of one port as one hyperedge: they stay on one line and part only where their routes do. Different bundles, edges that share no end point, keep off one line where they would run end to end with their ends under 32 px apart and no node or frame border between, as Graphviz gives every segment in a channel its own track: they take tracks up to 24 px apart where the channel has room, at least 8 px. Where 24 px would leave an edge label less of its run than it needs (to a frame border or its end), when it had the room on the shared line, the tracks spread less, down to 16 px; a label that still doesn’t fit sits beside its own bend, its padding over the border if need be, rather than over its own line. A fork’s branches keep 9 px apart where the channel has room, so the dots at the fork never touch; in an AWS diagram those drawn alike run on one line until they part instead, and the tracks of different edges keep 16 px apart, not 8, where the channel has room. Two that are further apart, or parted by a node, may share a line; so may the legs that dock on a node. Track spacing is constrained by the available gap between nearby nodes.
A node’s exits that leave one face turn at one depth, so a fan-out reads as one trunk, but only when their risers then keep off one line. Exits that would run one over another keep their own tracks. So do exits that would run end to end with their ends under 32 px apart, except in an AWS diagram the cloud layout arranges.
Labeled exits that leave one face and turn the same way nest as a staircase, so each label sits beside its own line. Each turns past the one before by its label’s width and 12 px either side. They nest only where that crosses no more lines and keeps 16 px from other nodes, and not in an AWS diagram the cloud layout arranges; otherwise they keep the channel’s tracks.
In flowchart, workflow, UI flow, architecture and entity-relationship diagrams, and in a diagram with no family, labeled lines between the same two nodes in neighboring ranks are spread evenly along each node’s side. If that leaves two neighbors nearer than half of one label’s height plus half of the other’s, the lines keep at least that distance plus 8 px apart instead. On a top or bottom side the widths count.
These lines aren’t spaced this way:
- Edges across several ranks.
- A sequence diagram’s messages (Message rows).
- An org chart’s lines.
- The lines of a diagram the cloud layout arranges, which has no ranks.
The engine grows the two nodes to fit their labels in two cases: a layout of every node (Laying out again), and a node an edit adds. A node that keeps its saved size keeps its side. If that side is too short, every gap between the lines shrinks in the same proportion, and a label can land on another line (Label placement).
Canvas-aware spread
When scene.canvas is set and the laid-out content uses substantially less space than the canvas allows, the planner scales node positions and rank centers around their centroid so the layout fills the available area. Auto-spread only widens gaps, never narrows them. This means agents who set a larger canvas get a layout that uses the space, instead of content clustered into one corner. Spread is capped (3x maximum scale factor) to prevent absurd spacing on tiny graphs that happen to live in a generous canvas.
So a canvas much larger than the drawing needs leaves wide gaps between nodes. Leave scene.canvas out, or set it near the content’s size, for a compact drawing.
A diagram whose frames the planner lays out with their members (see frames above) is not spread: wider gaps would pull members away from their frame’s border and leave frames hollow. It keeps the node and rank spacing, centered in the canvas, and a canvas far too large for it is tightened (below). Pools and lanes count as such frames. A drawing with a pool that has its own layout isn’t centered either: the first such pool’s corner stays where its layout puts it (Pools and lanes). Set layoutStrategy.nodeSpacing and rankSpacing for more room.
Placing a text or an image yourself doesn’t stop the planner spreading nodes into a larger canvas. Neither does a frame with its own absolute layout (What auto-layout handles and what it doesn’t). A pool or a lane is the exception: the planner lays it out with its members, with or without a layout, so the rule above applies.
Spread happens when the engine lays out every node. After the first save the nodes keep their positions (Positions are kept), so a larger canvas set with updateScene adds room on the right and at the bottom; send autoLayout to spread the nodes into it.
Canvas size is a minimum, with per-axis tightening on over-declared canvases
Declared scene.canvas dimensions act as a lower bound: when content exceeds them the engine auto-extends the canvas to fit. When the declared canvas is larger than what node spacing requires, the engine auto-spreads (above) to fill the available area, except in a diagram whose frames are laid out with their members.
When the declared canvas on either axis exceeds the comfortable centered-content size by more than 30% AND the engine lays out every node, the engine tightens that axis to content x 1.4 to avoid shipping with excessive slack. Width and height are tightened independently and per-axis. This is the only path where the engine reduces a declared canvas dimension, and the canvas it picks is saved with the diagram.
A layout in which some nodes already have positions, given by an agent or kept from an earlier save, leaves the declared canvas untouched, and so does one with a text, an image or a frame that has an absolute layout (What auto-layout handles and what it doesn’t). The declared size counts as part of that positioning intent.
Summary:
- A bigger declared canvas gives more room. The engine spreads the nodes to fill it, unless frames are laid out with their members.
- A smaller declared canvas gives a tighter layout, down to the auto-extension floor.
- A layout of every node tightens a much-too-large declared canvas to a comfortable margin per axis, unless a text, an image or a frame has an absolute
layout.
Auto-spread only widens gaps.
Neither change comes back as a warning: the API returns no info-level drawing diagnostics. Rendering: Render diagnostics describes when each happens and what to change if you want a different size.
Bonus phase: label placement
For each labeled edge, the placer samples positions along every segment of the routed path, beside the line (above or below a horizontal segment, right or left of a vertical one) and on it, which scores below a place beside it on the same run. A slanted line’s label sits on it. A curve’s label prefers the curve’s middle by length: beside it where it runs level, else on it; when no such place is clear, beside it where it runs within 25 degrees of level. A candidate is clear when its knockout, the label’s backdrop, meets no node, previously-placed label, other edge’s line, arrowhead or ER glyph (sized for the widest theme stroke, or the edge’s own stroke when wider, so the place is clear in every theme). A frame’s inside is open to labels, so a label can sit inside a frame that holds an end of its edge instead of being pushed into the gaps between frames. A frame’s border (6 px either side of it, measured from the label’s knockout), its title (for an AWS group or a frame with an AWS icon, a band across the frame’s whole width, as deep as its header) and each node’s outline are obstacles, and so is the space 16 px round the label of a node that draws its label outside its shape (a BPMN event’s or gateway’s name, a UI flow entry or exit point’s, below or above its shape, or the label under an AWS icon drawn alone), a line’s height, so an edge label doesn’t read as that name’s second line. Such a node counts as its shape and that label, not the box round both, so an edge label can sit beside the shape where the label leaves room. So are a sequence fragment’s tab and guard, each operand’s divider and guard, a spanning frame’s header, and a step badge with 10 px round it; a self-message’s label keeps off its own loop. A label that only touches an obstacle is clear of it.
A clear place must also read as its own edge’s. The label sits 6 px from its own line. A node other than its edge’s ends keeps 16 px from the label’s knockout, the room the router keeps between a line and a node. An edge’s own end is exempt only beside the face its line leaves or enters. Nearer a node than that, the label reads as the node’s caption. The layered engines space an edge label from other nodes as they space a node: ELK lays edge labels out as nodes at spacing.nodeNode 20 (its spacing.labelNode 5 is a node’s own captions), dot keeps nodesep about 24 px, dagre 50.
Inside a frame, a label keeps 16 px from the frame’s title, and from the kind an instance group writes opposite it (“Regional MIG”), as from a node’s outside label. Nearer, a label under the title reads as the frame’s second title. A pool’s or lane’s header strip and a fragment’s divider keep 6 px. With no room, a label comes nearer; of two places by one node, the farther wins.
A label also stays out of a frame that holds neither end of its edge, where its line has a clear place outside such frames. Inside one, it reads as a note on what that frame holds. When a pool or a VPC holds an end, its lanes or Availability Zones don’t count: a line crosses them on purpose. Nor does a spanning frame round an end or round a frame that holds one. A sequence message’s label keeps its row instead of these rules (Message rows).
In a Google Cloud diagram, a label keeps off the boundary’s blue, as Google’s reference diagrams do. The blue is the part of gcp.cloud outside the filled groups it holds (projects, Regions, tiers). Where the line has a clear place on one of those groups or outside the boundary, the label goes there. Where it has none, as on Cloud Armor’s line into the load balancer beside it, the label stays on the blue, at the contrast Rendering: Google Cloud edges gives it.
Wrapping is the placer’s last step. A label with no clear place is tried in two lines, then three (or the lines it has, if more), and takes the widest wrap that has a clear place. A label with a clear place keeps it and its box, whatever another label does.
In a Google Cloud diagram the cloud layout arranges, a label also keeps a floor. Its knockout stays 10 px from every other edge’s line and from every card but its edge’s ends, and at least twice as near its own line as any other line. Other diagrams weigh labels without the floor.
Where no place at the measured box is clear, the placer checks the least faulty one. If that place breaks the floor, covers a line or a node, or crosses a border, the label takes the widest wrap whose place does none of these. That place needn’t be clear by the rules below. The wrap can be three lines, with the label sitting on its edge’s own line. A label with a clear place never changes.
A Google label also stays out of a frame’s title row, so it doesn’t read as part of the title. Inside a frame, its middle stands at least its own height (40 px at most) from the middle of the title, wherever along the frame’s width it is. A place in a title’s row isn’t clear.
The floor doesn’t make room. Where lines run closer together than the label is wide, or a drop is shorter than the label is tall, no wrap may fit. The label then takes its least faulty place, which can break the floor. The placer doesn’t move lines for a label.
Only the label’s box changes. The nodes, the rooms the layouts keep for labels (a tier’s lane under a labeled line, a message row) and the routes stay as laid out for the measured box, and the narrower box is placed clear of what stands there.
These labels aren’t narrowed:
- A sequence message’s label.
- A label with
textStyle.wrap: "none". - A label that can’t break, such as one long identifier.
- A label under 100 px wide whose least faulty place covers no node or label, has no line under its text and crosses no frame’s border.
A place where only the label’s padding reaches something its text clears isn’t narrowed either: the knockout is trimmed there (Rendering: Contrast). With no clear place at any width, the label takes the place its measured box has, as below.
Parallel lines can run closer together than a label is tall, as on a node’s side too short for them (Edge routing). Such a label has no clear place at any width. It lands on the least faulty place, and its text may cover another line. Shorten the label to give it a clear place.
A clear place keeps other edges’ lines 12 px or more from the label. Beside a vertical segment, no other edge’s horizontal line runs along half the label’s width or more within 30 px above or below it. The knockout covers no stretch of its own line other than the one it labels.
A fan-in whose repeated label is drawn once (EDGE_LABEL_SUPPRESSED_FANIN) is one label’s edges, and their lines don’t count against it. Any other edge with the same label draws its own, clear of the others’ lines like any label. On a segment it shares with other edges (a fan-out’s trunk, a fan-in’s), a label is centered on the stretch only its own edge draws, past the fork.
In every family but sequence diagrams, another edge’s line can also end a label’s own stretch on a horizontal or vertical segment. It does when it crosses that segment and its arrowhead or ER glyph lies within two label heights of the crossing. A label beside that line’s end would read as that line’s, so it is centered on the longest stretch between such crossings, as Esri’s Maplex keeps street labels off intersections. A line that only crosses the segment, its ends farther off, doesn’t end the stretch. On a short run with several such crossings, the label can still sit near one.
The clear candidates are scored by combining segment-centeredness (prefer mid-segment, or mid-stretch on a shared segment) with a longest-segment preference (prefer the most prominent visual run of the edge). A label on an edge out of a diamond (a decision’s or a BPMN gateway’s branch, not an er.relationship’s line) prefers instead the clear place nearest the diamond along its path, within 200 px, on the branch’s first run when it fits there, as flowchart guides write yes and no beside the decision. Branches that share a vertex and split each sit centered on their own arm past the split. The chosen position is then reserved as an obstacle for subsequent placements, so neighboring labels keep visible breathing room.
When no sampled place is clear, the placer tries more places. It tries the label centered in each gap between obstacles along a horizontal or vertical segment, and just past each frame border’s band. Then it tries each place between two samples, 1 px apart. A clean place at least 1 px wide is found wherever it lies; a narrower one isn’t promised.
When no place along an edge is clear (say, an edge that runs only through a gap narrower than its label), the label takes the place with the least serious faults, compared in this order:
- The least node and label area covered.
- The fewest other edges’ lines under it.
- The least arrowhead or ER glyph covered.
- The fewest frame borders its text crosses.
- The fewest stretches of its own line covered.
- The fewest frame borders under only its padding.
- In a Google Cloud diagram, the fewest lines and cards nearer than the floor (10 px), or lines less than twice as far as its own line.
- In a Google Cloud diagram, the fewest frame titles whose row it stands in, within its own height (40 px at most) of the title’s middle.
- In a Google Cloud diagram, the fewest other edges’ straight runs that carry on into it.
- The fewest other edges’ lines nearer than 12 px, and those farthest off.
- The fewest nodes nearer than 16 px, and those farthest off.
- The least frame border band.
- The fewest frames around it that hold neither end of its edge.
- The fewest Google Cloud boundaries whose blue is under it.
Where the least faulty place has another edge’s line under its knockout, the label takes a place with fewer lines under its text, if there is one. The knockout is trimmed short of the lines only its padding reaches (Rendering: Contrast), so they stay drawn whole. The text keeps 2 px clear of those lines and of its edge’s end nodes. This doesn’t apply to a sequence message’s label or to a label in a Google Cloud diagram the cloud layout arranges.
Where the least faulty place still crosses a frame’s border, two more places are tried. First, beside its line’s end, inside the frame the line enters or leaves, as dot’s headlabel and ELK’s head placement put a label. Its knockout sits 6 px past the arrowhead or the outline the line ends on. The head end is tried before the tail, and only a place clean by every rule above is taken. Then on its own line, slid across the border, while at least 8 px of the line stays under its text. A sequence message, a self-loop and a curve skip both. So a label can still cross a frame’s border, cover a frame’s title or overlap a node.
Labels that still crowd one row (parallel edges whose midpoints line up) then slide along their own edges or step above or below the row, by their own height. A step never leaves a label half over its own line, or more than 14 px from it. It never puts a label onto a Google boundary’s blue, or into a frame its line only passes through, that it wasn’t on already. A label that only crowds another stays beside its own line.
A label that covers another label steps off it even past 14 px from its line, because two texts over each other read as neither. A label moves only to a place clear of nodes, other labels, arrowheads and other edges’ lines, and no worse placed by the fallback’s order, or else stays put. A sequence message’s label keeps its place (Message rows), and two messages between the same lifelines aren’t parallel edges.
Aesthetic scoring
The engine doesn’t just run the pipeline once and hope for the best. It evaluates several layout candidates with different planner parameters and picks the one with the lowest aesthetic penalty score. This happens when the engine lays out every node: on a new diagram whose nodes have no positions, on autoLayout without elements, and after updateScene changes or removes layoutStrategy or diagramFamily, unless members of a pool, lane or fragment with its own layout, or of a frame in an org chart or network, keep their positions. When some nodes have positions, the engine places the others around them in one pass, and the positioned nodes stay where they are, except in the cases Positions are kept lists.
The candidates vary two parameters that have the biggest impact on layout quality: node/rank spacing (how dense or spacious the layout is) and crossing-reduction thoroughness (how many optimization passes the planner runs). One candidate always uses the scene’s own defaults, so the worst case is identical to a single-pass layout. The others use fixed spacings, tighter or wider than the defaults whatever the scene sets, or the scene’s spacing with more optimization passes, so the layout that wins can space nodes and ranks closer or further apart than nodeSpacing and rankSpacing say: they are the spacing the engine aims for, not minimums. In a flowchart, no candidate puts ranks closer than 50 px.
Each candidate is scored on:
- Edge crossings - the single most impactful quality signal. Fewer crossings = more readable.
- Edge bends - fewer 90-degree bends = cleaner orthogonal routes.
- Total edge length - prefer compact layouts over sprawling ones (weak signal).
- Label overlaps - a label over a node or another label. Should be zero; heavily penalized when not. A label inside a frame, group or auto-band costs nothing.
- Labels on lines - a label whose knockout hides another edge’s line, so it costs as much as a label overlap.
- Labels across a frame’s border - a label whose knockout spans a drawn frame’s border reads on both sides of it. Each such border costs half a label overlap, more than a crossing or a shared run. An auto-band’s edge and a spanning frame’s border aren’t counted.
- Shared runs - two unrelated edges that run along each other for more than 8 px read as one line, so each such pair is penalized. Edges leaving a node from one point (a bundle), joining at one point (a fan-in), chained through one node or meeting at one ER column row are exempt.
- Area utilization - prefer layouts that fill roughly 40% of the canvas, not too sparse and not too packed.
- Canvas overflow - layouts whose content exceeds the canvas in either axis are heavily penalized, so the best-of-N selector rejects them. Combined with the canvas-aware spread step above, this means agents reliably get a layout that fits the canvas they specified.
The winner’s node positions are saved with the diagram, so later edits start from them instead of choosing again. The entire process is deterministic: same scene always produces the same layout.
For agents, this is invisible - you describe the graph, the engine does the rest. Scoring picks the cleanest of the candidates; the save’s warnings report what is still wrong.
Configuration
The layout engine reads scene.layoutStrategy:
{
"layoutStrategy": {
"direction": "TB",
"nodeSpacing": 60,
"rankSpacing": 100
}
}
| Field | Type | Default | Description |
|---|---|---|---|
direction | "TB" | "BT" | "LR" | "RL" | "LR", "TB" for flowcharts | Primary flow direction |
nodeSpacing | number | 30 | Target pixels between nodes in a rank |
rankSpacing | number | 80, 50 for flowcharts | Target pixels between ranks |
The engine picks how to place nodes from diagramFamily, not from layoutStrategy. The hierarchical pipeline is used by architecture, flowchart, workflow, entityRelationship, uiflow, and diagrams without a family; it reads these three fields, and a field left out takes the default above. Org charts use a tidy-tree planner that runs top to bottom, network topologies use a force-directed layout (since they have no inherent direction), and sequence diagrams use a dedicated time-ordered resolver; none of them reads layoutStrategy. Changing layoutStrategy on a saved diagram with updateScene lays out every node again.
Mixed mode in practice
The most common production pattern is to fix some nodes and let the engine position the rest:
{
"schemaVersion": "0.1",
"scene": { "id": "mixed-arch", "canvas": { "width": 1000, "height": 600 } },
"layoutStrategy": { "direction": "LR" },
"elements": [
{
"id": "gateway",
"kind": "node",
"nodeType": "service",
"label": "API Gateway",
"layout": { "mode": "absolute", "x": 50, "y": 250, "width": 160, "height": 80 }
},
{ "id": "auth", "kind": "node", "nodeType": "service", "label": "Auth" },
{ "id": "users", "kind": "node", "nodeType": "service", "label": "Users" },
{ "id": "billing", "kind": "node", "nodeType": "service", "label": "Billing" },
{ "id": "db", "kind": "node", "nodeType": "database", "label": "Postgres" },
{ "id": "e1", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "auth" } },
{ "id": "e2", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "users" } },
{ "id": "e3", "kind": "edge", "from": { "elementId": "gateway" }, "to": { "elementId": "billing" } },
{ "id": "e4", "kind": "edge", "from": { "elementId": "users" }, "to": { "elementId": "db" } },
{ "id": "e5", "kind": "edge", "from": { "elementId": "billing" }, "to": { "elementId": "db" } }
]
}
The gateway is pinned where the diagram’s user wants it. Auth, Users, Billing, and Postgres have no layout - the engine places each one next to its neighbors (a successor one rank after its predecessor, centered on it, as far from it as the drawing’s ranks are apart, or farther where its edge’s label needs the room, or in the next column, which moves along if its gap can’t hold the label) without moving the gateway, and routes the edges around it. Leaving layout out and giving it at exactly x: 0, y: 0 mean the same: not placed yet. The first save records where the engine put Auth, Users, Billing and Postgres in their layout, so later edits keep them there too. Only an edit that asks for a new layout moves them, or the gateway: autoLayout, or a new layoutStrategy or diagramFamily. A node that grows can also push them (Making room), and adding an order constraint they don’t meet places its two nodes again.
Hidden elements
An element with visible: false is laid out like any other and keeps its space; only drawing leaves it out. A hidden node still counts for NODE_OVERLAP_DETECTED. A hidden edge, or one with a hidden end, draws no step badge (Numbered steps).
Determinism guarantees
The engine is fully deterministic. Given the same scene document, the same layoutStrategy, and the same set of diagram-family rules, the output is bit-identical across runs. This means:
- Diagrams can be checked into git and diffed meaningfully.
- Visual regression tests don’t need to tolerate pixel jitter.
- Two agents inspecting the same scene see the same picture.
There is no random initialization, no time-based heuristic, and no external service call. Every algorithm in the pipeline is purely a function of the input.