New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

Diagram families

Declare diagramFamily on every scene: architecture, flowchart, workflow, entityRelationship, sequence, network, orgchart or uiflow. It selects the family’s node types, rules, layout and drawing. Without it the diagram is drawn as an architecture diagram, and nothing warns you.

Family selection guidance

Default to architecture for system-component diagrams: services, databases, queues and infrastructure. Its decisions follow no yes and no convention: each branch leaves toward wherever its target lands. Switch family when the structure matches one of these patterns:

A scene with badges or decorators stacked around a slab-shaped central node almost always wants workflow + pool / lane instead. Splitting the work into bands renders cleaner than fanning many edges out of one oversized central node.

The per-family minimal scenes below show the full element shape for each family.

Capability matrix

Diagram typeFitNotes
Architecture diagramsExcellentNodes, edges, groups, frames, constraints - full protocol support
FlowchartsExcellentTop to bottom, yes straight on and no to the right, loops round the side that crosses least, document and subroutine shapes, warnings for decisions with too few or unlabeled exits
Service / system topologyExcellentMultiple node types, edge routers, container grouping
Data flow diagramsExcellentDirectional edges with labels, orthogonal routing
Workflow / process diagramsExcellentFull BPMN via workflow family - see BPMN row below for details
Agent workflowsExcellentStep-by-step flows with typed nodes and labeled edges
Dependency graphsExcellentNodes + directed edges, layout constraints
Org chartsExcellentStructured person cards (name bold + title muted + department accent stripe + icon), automatic top-to-bottom tree layout, solid/dashed reporting lines
Entity-Relationship diagramsExcellentCompartmented entity boxes (header + attribute rows with PK/FK badges + types), crow’s-foot cardinality (5 markers), weak entity double-border, solid identifying and dashed non-identifying relationships
UI / navigation flowsExcellentScreen/modal nodes with title bar rendering, entry/exit circles, navigate/back/action edges, orphan screen validation
Class diagramsAcceptableClass boxes as labeled nodes, inheritance/association as edges - no compartments or stereotypes
State graphsAcceptableStates as nodes (ellipse/roundedRect), transitions as labeled edges - no formal statechart notation
BPMNExcellentFull BPMN coverage: 11 event types (start, end, timer, error, intermediate catch/throw, terminate, message start/end), 4 gateway types (exclusive, parallel, inclusive, event-based), subprocess with [+] collapse marker, BPMN-correct sequence/message flow arrows, swimlanes
UML sequence diagramsExcellentActivation bars (stacked when nested), sync/async/reply/create/destroy messages, created and destroyed lifelines, self-messages, numbered messages, notes over or beside lifelines, combined fragments (alt/opt/loop/par with pentagon labels and guard conditions), participant boxes, highlight bands, time-ordered layout, Mermaid sequenceDiagram both ways
UML state/activity notationNot yet first-classNo fork/join bars, nested states, or formal UML notation
Swimlane enterprise workflowsAcceptablePools and lanes laid out as BPMN tools do: lanes across the flow in your order, each fitted to its tasks, columns shared across lanes and pools; no phases along the flow
Mind mapsNot yet first-classNo radial layout
Freeform sketchingNot supportedZindex is a structured protocol, not a freeform canvas
Infographic / presentation layoutsNot supportedNo rich text formatting, image composition, or decorative layout

Excellent fit

Architecture diagrams

The core use case. Services, databases, queues and external systems as typed nodes. Connections via edges with orthogonal or straight routing. Frames and groups for logical containment. Constraints for alignment and distribution.

Maps to: node (all shapes and types), edge (all routers), frame, group, constraint

Minimal scene. The hierarchical planner walks the edge graph, assigns nodes to ranks, minimizes crossings, and routes edges orthogonally - no layout on any element.

{
  "schemaVersion": "0.1",
  "diagramFamily": "architecture",
  "layoutStrategy": { "direction": "LR" },
  "scene": {
    "id": "service-arch",
    "title": "Service Architecture",
    "canvas": { "width": 900, "height": 360 }
  },
  "elements": [
    { "id": "client", "kind": "node", "nodeType": "actor", "shape": "roundedRect", "label": "Client" },
    { "id": "api", "kind": "node", "nodeType": "service", "shape": "roundedRect", "label": "API Gateway" },
    { "id": "cache", "kind": "node", "nodeType": "storage", "shape": "roundedRect", "label": "Redis Cache" },
    { "id": "db", "kind": "node", "nodeType": "database", "shape": "cylinder", "label": "PostgreSQL" },
    { "id": "worker", "kind": "node", "nodeType": "service", "shape": "roundedRect", "label": "Worker" },
    { "id": "e1", "kind": "edge", "from": { "elementId": "client" }, "to": { "elementId": "api" } },
    { "id": "e2", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "cache" }, "label": "read/write" },
    { "id": "e3", "kind": "edge", "from": { "elementId": "api" }, "to": { "elementId": "db" }, "label": "queries" },
    { "id": "e4", "kind": "edge", "from": { "elementId": "db" }, "to": { "elementId": "worker" }, "label": "events" }
  ]
}

Recommended for blob-of-services architectures: extensions.autoGroup: "byNodeType". When the scene has no explicit frame containers, the rendered diagram is a flat cloud of floating shapes. Adding "extensions": { "autoGroup": "byNodeType" } at the scene-document root makes the engine synthesize subtle background bands grouping nodes by their nodeType (“Services”, “Databases”, “External Systems”, etc.), lifting the diagram into a layered architecture that reads in one glance. Architecture diagrams and diagrams without a family only, and opt-in: without it, there are no bands. Each band is a region: when the engine places every node (a new diagram, or autoLayout without elements), it lays each band’s nodes out together, apart from the other bands, as it does a frame’s. Skipped when the scene already authors frames containing the candidate nodes (no double-wrap), when all nodes share a single nodeType (single band is pointless), or when the nodes of a type are scattered (a node of another type sits between two of them in a column) or placed so that their band would overlap a frame or another band, as positions a saved diagram keeps can. The API doesn’t say when banding was skipped or why, so check the drawing.

Layers: a stack of rows. To draw an architecture as layers (edge, services, data), write each layer as a frame with containerType: "layer" and list the layers top to bottom; the engine stacks them in that order, each card in its layer’s row, and you write no layout. It arranges the first stack only, and not inside a pool, lane or cloud group (Layout engine: Layers).

AWS architectures: the aws.* presets. For a system on AWS with VPCs, Availability Zones and subnets, write AWS’s groups as frames with their containerType presets, nested as AWS nests them (aws.cloud > aws.region > aws.vpc > aws.az > aws.subnet.public and aws.subnet.private), and the services as nodes with aws:* icons, each listed in the frame it runs in, with no layout. The engine draws each group as AWS does, with the official AWS Architecture Icons, and arranges the diagram as AWS’s reference architectures are drawn instead of by the layered layout: Availability Zones as columns, subnets as rows across them, gateways on the side of the VPC they face (on the top when they serve several AZs or the load balancer between two), regional services in a column beside the VPCs, global services in a row above the Regions, users outside AWS Cloud.

It doesn’t:

A group across Availability Zones, such as an Auto Scaling group, is a frame with spans instead of children, drawn round what it spans. Layout Engine: AWS architecture diagrams has the whole behavior and an example scene.

Google Cloud architectures: the gcp.* presets. For a system on Google Cloud, write Google’s groups as frames with their containerType presets, and the services as nodes with gcp:* icons, each listed in the frame it runs in. Nest the groups as Google does: gcp.cloud > gcp.project (optional) > gcp.region > gcp.subnet > gcp.tier and gcp.instanceGroup, with gcp.onPremises outside gcp.cloud. Draw the VPC network round its subnets, and each zone round its nodes, as spanning frames with spans. The engine draws each node as Google’s product card and each group as Google’s Architecture Center diagrams do (Rendering: Google Cloud groups).

In an architecture diagram, or one without a family, the engine also arranges the groups as Google’s reference diagrams are drawn, instead of by the layered layout:

Leave layout off the frames and their nodes.

It doesn’t guess groups from frame titles (GCP_GROUP_UNTYPED warns when a title is a group’s own name, and names the preset to set or says the frame can stay generic), reorder Regions or zones, put cards a tier doesn’t hold in zone columns, or draw autoGroup bands. A GKE cluster, node pool or folder has no preset: draw it as a generic frame, and its cards stand in no zone column. It doesn’t arrange groups inside a frame between them, other than a project or a generic frame round whole Regions; GCP_FRAME_HIDES_GROUPS names a generic frame round subnets or tiers. Layout Engine: Google Cloud architecture diagrams has the whole behavior and an example scene.

Flowcharts

Use the generic node types: process for a step, decision for a question, document for a report or file (a wavy bottom) and database. For the start and each end, use a generic node with shape: "pill" or "ellipse". A decision is any node drawn as a diamond: a decision, or another node with shape: "diamond". Label each exit of a decision with the answer it stands for.

The engine draws a flowchart the way its readers expect:

Where it stops:

Validation warns, and the diagram still saves:

Maps to: the generic node types (process, decision, document, database, generic), the pill, ellipse, diamond, parallelogram (input and output), document and subroutine (a predefined process) shapes, labeled edges

Minimal scene. No layout and no direction: the flow runs top to bottom. Each decision’s yes goes straight down and its no to the right. “Ask for another card” stands beside the main path, so its loop back to “Charge card” runs on the right, where it crosses nothing.

{
  "schemaVersion": "0.1",
  "diagramFamily": "flowchart",
  "scene": {
    "id": "order-checkout",
    "title": "Order Checkout"
  },
  "elements": [
    { "id": "placed", "kind": "node", "nodeType": "generic", "shape": "pill", "label": "Order placed" },
    { "id": "stock", "kind": "node", "nodeType": "decision", "label": "In stock?" },
    { "id": "charge", "kind": "node", "nodeType": "process", "label": "Charge card" },
    { "id": "paid", "kind": "node", "nodeType": "decision", "label": "Payment OK?" },
    { "id": "retry", "kind": "node", "nodeType": "process", "label": "Ask for another card" },
    { "id": "backorder", "kind": "node", "nodeType": "process", "label": "Backorder items" },
    { "id": "receipt", "kind": "node", "nodeType": "document", "label": "Email receipt" },
    { "id": "done", "kind": "node", "nodeType": "generic", "shape": "pill", "label": "Order complete" },
    { "id": "e1", "kind": "edge", "from": { "elementId": "placed" }, "to": { "elementId": "stock" } },
    { "id": "e2", "kind": "edge", "from": { "elementId": "stock" }, "to": { "elementId": "charge" }, "label": "yes" },
    { "id": "e3", "kind": "edge", "from": { "elementId": "stock" }, "to": { "elementId": "backorder" }, "label": "no" },
    { "id": "e4", "kind": "edge", "from": { "elementId": "charge" }, "to": { "elementId": "paid" } },
    { "id": "e5", "kind": "edge", "from": { "elementId": "paid" }, "to": { "elementId": "receipt" }, "label": "yes" },
    { "id": "e6", "kind": "edge", "from": { "elementId": "paid" }, "to": { "elementId": "retry" }, "label": "no" },
    { "id": "e7", "kind": "edge", "from": { "elementId": "retry" }, "to": { "elementId": "charge" } },
    { "id": "e8", "kind": "edge", "from": { "elementId": "receipt" }, "to": { "elementId": "done" } }
  ]
}

A Mermaid flowchart or graph imports as a flowchart (Mermaid scope).

Org charts

Use org.person or org.role nodes for structured person cards. Cards render with a bold name, muted title, left accent stripe (department color via accentColor), and optional icon (e.g. lucide:user). Leave layout off the nodes for an automatic top-to-bottom tree; the tree doesn’t read layoutStrategy. Solid edges for direct reports (org.directReport), dashed edges for matrix/dotted-line relationships (org.dottedLine).

Maps to: org.person, org.role, org.department node types, org.directReport / org.dottedLine edge types, accentColor style, icons

Minimal scene. The tidy-tree planner gives balanced TB layouts for reporting hierarchies. style.accentColor paints the left department stripe.

{
  "schemaVersion": "0.1",
  "diagramFamily": "orgchart",
  "scene": {
    "id": "team-org",
    "title": "Engineering Team",
    "canvas": { "width": 900, "height": 420 }
  },
  "elements": [
    { "id": "cto", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Jordan Lee\nCTO", "style": { "accentColor": "#d4a843" } },
    { "id": "vp-eng", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Alex Chen\nVP Engineering", "style": { "accentColor": "#4db89a" } },
    { "id": "vp-design", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Sam Rivera\nHead of Design", "style": { "accentColor": "#4db89a" } },
    { "id": "dev1", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Pat Kim\nSenior Developer" },
    { "id": "dev2", "kind": "node", "nodeType": "org.person", "shape": "roundedRect", "label": "Taylor Ng\nSRE" },
    { "id": "r1", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "cto" }, "to": { "elementId": "vp-eng" } },
    { "id": "r2", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "cto" }, "to": { "elementId": "vp-design" } },
    { "id": "r3", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "vp-eng" }, "to": { "elementId": "dev1" } },
    { "id": "r4", "kind": "edge", "edgeType": "org.directReport", "from": { "elementId": "vp-eng" }, "to": { "elementId": "dev2" } }
  ]
}

Entity-Relationship diagrams

Use er.entity or er.weakEntity nodes with extensions.columns for compartmented table-like boxes. Each column has a name, and optionally a type, pk/fk/unique/nullable flags and a comment. The renderer produces a colored header bar (via accentColor), separator line, and attribute rows with PK/FK badges and right-aligned types. Weak entities render with double-border. Crow’s-foot cardinality markers on edges (one, many, zero-or-one, zero-or-many, one-or-many). Relationship lines are solid (er.relationship, er.identifying), as Mermaid and Information Engineering draw identifying relationships; add style.dash for a non-identifying one.

Maps to: er.entity, er.weakEntity node types, extensions.columns, accentColor style, er.relationship / er.identifying edge types, cardinality on endpoints

Minimal scene. extensions.columns turns each entity into a compartmented box with header, separator, and PK/FK badges. The second edge omits cardinality and anchors at item.order_id, so the engine infers one at the order’s key and many at the foreign key. Author-set values are always preserved.

{
  "schemaVersion": "0.1",
  "diagramFamily": "entityRelationship",
  "layoutStrategy": { "direction": "LR" },
  "scene": {
    "id": "er-orders",
    "title": "Order Schema",
    "canvas": { "width": 900, "height": 360 }
  },
  "elements": [
    {
      "id": "customer",
      "kind": "node",
      "nodeType": "er.entity",
      "shape": "rect",
      "label": "Customer",
      "extensions": {
        "columns": [
          { "name": "id", "type": "uuid", "pk": true },
          { "name": "email", "type": "text" },
          { "name": "created_at", "type": "timestamp" }
        ]
      }
    },
    {
      "id": "order",
      "kind": "node",
      "nodeType": "er.entity",
      "shape": "rect",
      "label": "Order",
      "extensions": {
        "columns": [
          { "name": "id", "type": "uuid", "pk": true },
          { "name": "customer_id", "type": "uuid", "fk": true },
          { "name": "total", "type": "numeric" }
        ]
      }
    },
    {
      "id": "item",
      "kind": "node",
      "nodeType": "er.entity",
      "shape": "rect",
      "label": "OrderItem",
      "extensions": {
        "columns": [
          { "name": "id", "type": "uuid", "pk": true },
          { "name": "order_id", "type": "uuid", "fk": true },
          { "name": "product_id", "type": "uuid", "fk": true },
          { "name": "qty", "type": "int" }
        ]
      }
    },
    { "id": "e1", "kind": "edge", "edgeType": "er.relationship", "from": { "elementId": "customer", "cardinality": "one" }, "to": { "elementId": "order", "cardinality": "many" }, "label": "places" },
    { "id": "e2", "kind": "edge", "edgeType": "er.relationship", "from": { "elementId": "order" }, "to": { "elementId": "item", "column": "order_id" }, "label": "contains" }
  ]
}

UI / navigation flows

Use uiflow.screen and uiflow.modal nodes for screen-level navigation diagrams. Screens render with a title bar strip at the top (using accentColor), with the first label line as the title and subsequent lines as body description. Modals add a drop shadow behind the card. Use uiflow.entry for app entry points (filled circle) and uiflow.exit for logout/close (bold circle). Three edge types: uiflow.navigate (solid), uiflow.back (dashed), uiflow.action (solid). Validation warns on missing screens, missing entry points, and orphan screens with no edges.

Maps to: uiflow.screen, uiflow.modal, uiflow.entry, uiflow.exit node types, uiflow.navigate / uiflow.back / uiflow.action edge types, accentColor style

BPMN

Full BPMN coverage via the workflow diagram family. Available BPMN primitives:

Maps to: workflow.start, workflow.end, workflow.timer, workflow.error, workflow.intermediateTimer, workflow.intermediateMessage, workflow.intermediateError, workflow.intermediateThrowMessage, workflow.terminate, workflow.messageStart, workflow.messageEnd node types, workflow.gateway, workflow.gatewayParallel, workflow.gatewayInclusive, workflow.gatewayEvent node types, workflow.task, workflow.subprocess node types, workflow.sequenceFlow / workflow.messageFlow edge types, pool / lane container types

Minimal scene. Setting diagramFamily: "workflow" activates BPMN-correct rendering: workflow.start as a circle, workflow.gateway as a diamond with an x marker, workflow.end as a bold-stroke circle, and workflow.sequenceFlow edges with triangle arrowheads. For a marker-less decision diamond, use workflow.decision (label inside) instead.

{
  "schemaVersion": "0.1",
  "diagramFamily": "workflow",
  "layoutStrategy": { "direction": "LR" },
  "scene": {
    "id": "approval-flow",
    "title": "Approval Flow",
    "canvas": { "width": 900, "height": 240 }
  },
  "elements": [
    { "id": "start", "kind": "node", "nodeType": "workflow.start", "shape": "ellipse", "label": "Submitted" },
    { "id": "review", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Review" },
    { "id": "gate", "kind": "node", "nodeType": "workflow.gateway", "shape": "diamond", "label": "OK?" },
    { "id": "approve", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify Approver" },
    { "id": "reject", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify Rejection" },
    { "id": "done", "kind": "node", "nodeType": "workflow.end", "shape": "ellipse", "label": "Done" },
    { "id": "e1", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "start" }, "to": { "elementId": "review" } },
    { "id": "e2", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "review" }, "to": { "elementId": "gate" } },
    { "id": "e3", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "approve" }, "label": "yes" },
    { "id": "e4", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "reject" }, "label": "no" },
    { "id": "e5", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "approve" }, "to": { "elementId": "done" } },
    { "id": "e6", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "reject" }, "to": { "elementId": "done" } }
  ]
}

UML sequence diagrams

Full UML sequence diagram support via the sequence diagram family. Lifelines (sequence.lifeline) render with header boxes and dashed tails terminating at a matching foot bar at the bottom of the diagram (the UML convention; opt out with showLifelineFeet: false in the document’s top-level extensions). Headers auto-size to fit their labels - the 100 px width is a floor, not a cap, so multi-word participant names like "Compute Endpoint\n(Metadata)" fit. Actors (sequence.actor) render as stick figures with the same head + foot mirror. Activation bars (sequence.activation) render as thin filled rectangles on lifelines, from the message named by extensions.startsAt to the one named by extensions.endsAt, and messages to or from them end at the bar’s side. Five message types: synchronous (sequence.message, filled arrowhead), asynchronous (sequence.async, open arrowhead), reply (sequence.reply, dashed with open arrowhead), create (sequence.create, dashed with filled arrowhead), and destroy (sequence.destroy, filled arrowhead with X terminator). Self-messages render as U-shaped loops. Combined fragments (alt, opt, loop, par and the rest) render as dashed-border frames with pentagon operator labels and guard conditions, laid out with the messages they hold, nested ones inside, and a divider above the row each further operand starts at (extensions.operands[].startsAt).

UML notes / annotations between messages (sequence.note) render as a rectangle with a folded top-right corner. Anchor each note via extensions.anchor: a single string centers the note OVER the named lifeline; a string array spans the note across the named lifelines (also centered-over semantics). Matches UML 2.5 §17.4. Notes interleave vertically with messages by their position in the elements array. A note with one anchor and extensions.side ("left" or "right") sits beside its lifeline instead (Rendering: Lifeline rendering).

Participant types. Six more node types head a column and say what the participant is, such as sequence.database and sequence.queue. They work as a lifeline does and differ only in the head and foot drawn (Element types).

Lifelines that start and end. A sequence.create message that is a lifeline’s first row puts the lifeline’s head on that row, and a sequence.destroy message ends the lifeline it arrives at, with no foot bar (Rendering: Lifeline rendering).

Numbered messages. extensions.autonumber at the document’s top level numbers every message, top to bottom, as Mermaid numbers them, with a badge at its arrow’s start (Layout engine: Numbered messages). A message’s own step restarts the count, and edits renumber the messages after the one they change.

Participant boxes and highlight bands. A frame that isn’t a fragment is drawn by its children, and needs no containerType. Participants draw a box round them, and messages and notes draw a filled band behind those rows. Boxes don’t nest or overlap, and one frame can’t be both (Rendering: Participant boxes and highlight bands).

Mermaid. A Mermaid sequenceDiagram imports as a sequence diagram, reads back as one and takes edits in that form (Mermaid scope: Sequence diagrams).

Maps to: sequence.lifeline, sequence.actor, sequence.boundary, sequence.control, sequence.entity, sequence.database, sequence.collections, sequence.queue, sequence.activation, sequence.note node types, sequence.message / sequence.async / sequence.reply / sequence.create / sequence.destroy edge types, fragment container type with extensions.operator and extensions.operands, plain frames for participant boxes and highlight bands

Minimal scene. No layoutStrategy and no layout on any element - the sequence family resolver auto-positions lifelines left-to-right in definition order and stacks messages vertically by their position in elements. The first message edge is topmost. sequence.reply renders as a dashed arrow. An edit puts a new lifeline, message or note between two others with after or before (Operations: Order in a sequence diagram).

{
  "schemaVersion": "0.1",
  "diagramFamily": "sequence",
  "scene": {
    "id": "auth-sequence",
    "title": "Authentication",
    "canvas": { "width": 640, "height": 360 }
  },
  "elements": [
    { "id": "client", "kind": "node", "nodeType": "sequence.actor", "shape": "rect", "label": "Client" },
    { "id": "server", "kind": "node", "nodeType": "sequence.lifeline", "shape": "rect", "label": "Auth Server" },
    { "id": "db", "kind": "node", "nodeType": "sequence.lifeline", "shape": "rect", "label": "User DB" },
    { "id": "m1", "kind": "edge", "edgeType": "sequence.message", "from": { "elementId": "client" }, "to": { "elementId": "server" }, "label": "POST /login" },
    { "id": "m2", "kind": "edge", "edgeType": "sequence.message", "from": { "elementId": "server" }, "to": { "elementId": "db" }, "label": "find user" },
    { "id": "m3", "kind": "edge", "edgeType": "sequence.reply", "from": { "elementId": "db" }, "to": { "elementId": "server" }, "label": "user record" },
    { "id": "m4", "kind": "edge", "edgeType": "sequence.reply", "from": { "elementId": "server" }, "to": { "elementId": "client" }, "label": "session token" }
  ]
}

Acceptable with generic primitives

These work with generic shapes and edges, without the specialized notation.

Class diagrams

Classes as labeled nodes, inheritance and association as edges. No compartmentalized class boxes, stereotypes, or interface notation.

Limitation: No multi-compartment shapes or formal UML stereotypes.

State graphs

States as ellipse or roundedRect nodes, transitions as labeled edges, in a flowchart or workflow diagram. No formal statechart notation (fork bars, nested states, history nodes).

A transition label written as EVENT [guard] / action draws its guard and action smaller and muted, so the eye finds the event first (Rendering: edge label typography). A label wider than 200 px wraps, between its parts first (Element types: Label wrapping). Architecture, network, entity-relationship and org chart diagrams, and a diagram with no family, draw every edge label as plain text.

Limitation: No hierarchical state nesting.

Network diagrams

Use network.* node types (network.server, network.router, network.switch, network.firewall, network.cloud, network.client) with network.dataFlow and network.controlFlow edge types. Typed semantics are available but nodes render as their declared shape without family-specific visual treatment.

Limitation: No family-specific rendering (device icons, interface markers).

Swimlane enterprise workflows

Use a frame with containerType: "pool" whose children are frames with containerType: "lane", and list each node in its lane’s children. The engine lays them out as BPMN tools do: lanes run along the flow and stack across it in the order the pool lists them, every node a lane lists lands inside it, each lane is as deep as its contents need (at least 60 px, or its title’s length plus 16 px), and columns are shared across lanes and pools, so the flow reads as time. Pools and lanes are drawn with BPMN header strips: a 30 px strip with the title, rotated in a horizontal pool (Rendering). A pool’s or lane’s layout is a minimum, not a fixed size: the pool grows to hold its lanes and members. Add a task to a lane later with createNode’s frame, and move one to another lane with updateNode’s frame.

Limitations: Lanes always run across the flow: there are no phases or milestones along it. The engine keeps lanes in the order the pool lists them and pools in document order, without reordering them to reduce crossings. A frame inside a lane, such as a subprocess, is fitted round its members rather than laid out with them. Edges can still run through a gateway’s or event’s external label in some layouts. Layout Engine: Pools and lanes has the details.

Minimal scene. No positions anywhere: set laneDirection on the pool, list the lanes as the pool’s children, and list the nodes in each lane as that lane’s children. The engine places the nodes and sizes the pool and lanes.

{
  "schemaVersion": "0.1",
  "diagramFamily": "workflow",
  "layoutStrategy": { "direction": "LR" },
  "scene": {
    "id": "approval-lanes",
    "title": "Approval with Lanes",
    "canvas": { "width": 900, "height": 420 }
  },
  "elements": [
    { "id": "pool", "kind": "frame", "title": "Approval Process", "containerType": "pool", "laneDirection": "vertical", "children": ["lane-req", "lane-rev"] },
    { "id": "lane-req", "kind": "frame", "title": "Requester", "containerType": "lane", "children": ["start", "submit"] },
    { "id": "lane-rev", "kind": "frame", "title": "Reviewer", "containerType": "lane", "children": ["review", "gate", "notify", "end"] },
    { "id": "start", "kind": "node", "nodeType": "workflow.start", "shape": "ellipse", "label": "Submitted" },
    { "id": "submit", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Submit" },
    { "id": "review", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Review" },
    { "id": "gate", "kind": "node", "nodeType": "workflow.gateway", "shape": "diamond", "label": "OK?" },
    { "id": "notify", "kind": "node", "nodeType": "workflow.task", "shape": "roundedRect", "label": "Notify" },
    { "id": "end", "kind": "node", "nodeType": "workflow.end", "shape": "ellipse", "label": "Done" },
    { "id": "e0", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "start" }, "to": { "elementId": "submit" } },
    { "id": "e1", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "submit" }, "to": { "elementId": "review" } },
    { "id": "e2", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "review" }, "to": { "elementId": "gate" } },
    { "id": "e3", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "notify" }, "label": "yes" },
    { "id": "e4", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "gate" }, "to": { "elementId": "end" }, "label": "no" },
    { "id": "e5", "kind": "edge", "edgeType": "workflow.sequenceFlow", "from": { "elementId": "notify" }, "to": { "elementId": "end" } }
  ]
}

laneDirection: "vertical" stacks the lanes top to bottom, which BPMN calls a horizontal pool, and the flow runs left to right; "horizontal" puts them side by side, a vertical pool, and the flow runs top to bottom. Lanes always run across the flow: when layoutStrategy.direction runs along the lanes’ stacking, laneDirection wins. Pools, lanes and their nodes all omit layout.

Not yet first-class

These need notation or layout DSP doesn’t have.

UML state/activity notation

Requires fork/join bars, nested composite states, history pseudo-states, and activity partitions. Generic nodes can approximate simple cases but not the full notation.

Mind maps

Hierarchical auto-layout (layoutStrategy: { "direction": "TB" }) can approximate a top-down tree structure, but there is no radial/circular layout algorithm for true mind-map branching from a central topic.

Not supported

Freeform sketching

Zindex is a structured diagram protocol, not a freeform drawing canvas. There are no pen strokes, freehand shapes, or pixel-level drawing primitives.

Infographic / presentation layouts

Zindex focuses on structured diagrams, not rich visual compositions with decorative typography, image grids, or complex text formatting.

Cross-cutting capabilities