Supported Diagram Classes

Zindex is a stateful diagram runtime. Not all diagram types are equally well-served by the current protocol. This page defines the boundary clearly so agents and developers can make informed decisions.

Building an agent integration? See How AI Agents Should Use Zindex for the recommended workflow for scene creation, incremental edits, revision handling, validation, normalization, and rendering.

Always declare scene-level diagramFamily on every scene. Pick architecture, workflow, entityRelationship, sequence, network, orgchart, or uiflow based on what the scene represents. The field gates family-specific behaviour the engine and downstream tooling rely on; omitting it triggers a MISSING_DIAGRAM_FAMILY info diagnostic on the render response.

Capability matrix

Excellent fit

These diagram types map directly to DSP primitives with full protocol support.

Architecture diagrams

The core use case. Services, databases, queues, caches, and gateways 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

Service / system topology

Multiple service tiers connected by network or API relationships. Use node types (service, database, queue, cache, gateway, external) for semantic clarity. Frames for subsystem boundaries.

Maps to: node, edge, frame, constraint

Data flow diagrams

Directional data movement between processes, stores, and external entities. Edges with labels describe the data being transferred. Orthogonal routing keeps flows clean.

Maps to: node, edge (with labels and directional arrows)

Workflow / process diagrams

Step-by-step processes with decision points. For simple flows, use generic shapes (diamond for decisions, roundedRect for steps, ellipse for start/end). For full BPMN notation, declare diagramFamily: "workflow" to activate typed node/edge profiles with specialized rendering - see the BPMN section below.

Maps to: node (diamond, roundedRect, ellipse), edge (with labels), or diagramFamily: "workflow" for full BPMN

Agent workflows

Agent interaction sequences showing tool calls, API requests, and decision points. The same primitives as workflow diagrams, with semantic node types for each step.

Maps to: node, edge, text (for annotations)

Dependency graphs

Directed graphs showing which components depend on which. Nodes for components, directed edges for dependencies. Use layoutStrategy: "hierarchical" for automatic DAG layout, or constraints for manual arrangement.

Maps to: node, edge, constraint (align, distribute), layoutStrategy

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). Use layoutStrategy: { algorithm: "hierarchical", direction: "TB" } for automatic top-to-bottom tree layout. 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, layoutStrategy, icons

Entity-Relationship diagrams

Use er.entity or er.weakEntity nodes with extensions.columns for compartmented table-like boxes. Each column defines name, type, and optional pk/fk/nullable flags. 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). Identifying relationships render dashed (er.identifying).

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

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:

• Events: start (filled circle), end (bold circle), timer (circle + clock), error (circle + zigzag), intermediateTimer (double circle + clock), intermediateMessage (double circle + envelope), intermediateError (double circle + zigzag), intermediateThrowMessage (double circle + filled envelope), terminate (filled inner circle), messageStart (circle + envelope), messageEnd (bold circle + envelope)
• Gateways: exclusive (diamond + x), parallel (diamond + +), inclusive (diamond + circle), event-based (diamond + pentagon)
• Activities: task (roundedRect), subprocess (roundedRect with [+] collapse marker)
• Flows: sequenceFlow (solid, triangle arrowhead), messageFlow (dashed, open circle source, open arrowhead target)
• Swimlanes: pool and lane containers with automatic band layout

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

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 (UML / PlantUML / Mermaid convention; opt out via scene.extensions.showLifelineFeet: false). 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)" no longer overflow. Actors (sequence.actor) render as stick figures with the same head + foot mirror. Activation bars (sequence.activation) render as thin filled rectangles on lifelines. 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) rendered as dashed-border frames with pentagon operator labels and guard conditions.

UML notes / annotations between messages (sequence.note) render as rounded rectangles with a folded-corner accent. Anchor each note via extensions.anchor: a single string centres the note OVER the named lifeline; a string array spans the note across the named lifelines (also centred-over semantics). Matches PlantUML / Mermaid / UML 2.5 §17.4. Notes interleave vertically with messages by their position in the elements array.

Maps to: sequence.lifeline, sequence.actor, sequence.activation, sequence.note node types, sequence.message / sequence.async / sequence.reply / sequence.create / sequence.destroy edge types, fragment container type with extensions.operator

Acceptable with generic primitives

These diagram types can be represented using DSP’s generic primitives, but the protocol does not have dedicated support for their 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. No formal statechart notation (fork bars, nested states, history nodes).

Transition labels matching the UML / SCXML / BPMN convention EVENT [guard] / action render with multi-tier typography - event in 12px standard, guard [...] in 10px muted, action / ... in 10px muted italic - so the eye locks onto the event name first. See rendering reference: edge label typography. Detection is content-based (any label containing balanced [...] OR a / separator), so plain labels keep the existing single-tspan rendering.

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 frames with containerType: "pool" and containerType: "lane" with laneDirection (“vertical” or “horizontal”). The layout engine distributes lane children evenly within the pool’s bounds. Pool frames render with solid borders and a title header separator.

Limitation: Lane partitioning is automatic (equal division) - no weighted or manually-sized lanes yet.

Not yet first-class

These diagram types require notation or layout that DSP does not currently provide. They may become first-class in future protocol extensions.

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: "hierarchical") 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

These features apply to all diagram types:

• Auto-layout - set layoutStrategy: { algorithm: "hierarchical", direction: "TB" } on the scene and omit layout from nodes. The layout engine computes positions, edge routes, and label placement automatically using a Sugiyama-style hierarchical pipeline with crossing reduction and obstacle-aware routing. Supports TB, LR, BT, RL directions and mixed mode (fixed + auto-positioned nodes in the same scene).
• Render themes - pass "theme" on render requests to change aesthetics without modifying the scene. Available: clean (default), dark, blueprint, sketch (hand-drawn).
• 4 edge routers - straight, orthogonal, curved, polyline.
• 10 constraint types - align, distribute, sameSize, stack, centerIn, contain, grid, minGap, noOverlap, order.
• Inline or registry styles - control fill, stroke, text color, font, opacity per element or via named style tokens.

Guidance for agents

When deciding whether to use Zindex for a diagram:

• Excellent fit - use Zindex. The protocol has full support.
• Acceptable - use Zindex with generic primitives. The result will be structurally correct but may lack specialized notation.
• Not yet first-class - consider whether a simplified version is sufficient. If the specialized notation is essential, Zindex may not be the right tool today.
• Not supported - do not use Zindex. Use a different tool.