diagram infrastructure for agents

A structured protocol and runtime for AI agents to create, edit, and render diagrams. Semantic operations, deterministic execution, stable versioning.

Read the docs Try the playground View on GitHub →

zindex architecture

the protocol

DSP (Diagram Scene Protocol) is the machine interface for diagrams. Agents describe what exists, not how to draw it.

example.scene.json

{
  "schemaVersion": "0.1",
  "scene": {
    "id": "payments-arch",
    "units": "px"
  },
  "elements": [
    {
      "id": "api",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway"
    },
    {
      "id": "queue",
      "kind": "node",
      "nodeType": "queue",
      "label": "Job Queue"
    },
    {
      "id": "e1",
      "kind": "edge",
      "from": { "elementId": "api" },
      "to": { "elementId": "queue" },
      "router": "orthogonal"
    }
  ]
}

Semantic, not geometric

Agents declare nodes, edges, and relationships. Layout is computed, not hand-placed.

Patchable

Stable IDs enable incremental updates. Add a node, move an edge — without regenerating the entire diagram.

Renderer-agnostic

One canonical scene, multiple outputs: SVG, PNG, Excalidraw, canvas.

Deterministic

Same input, same output. Validate → normalize → layout → render. Every step is inspectable.

why zindex

LLMs can generate diagram markup. The hard problem is everything else.

Incremental editing

Patch-based updates instead of full regeneration. Agents can modify individual elements while preserving the rest.

Deterministic execution

Consistent output across runs. Failures are explainable. The pipeline is inspectable at every step.

Durable state

Revision history, diffs, stable IDs. Diagrams are versioned artifacts, not ephemeral outputs.

Multi-agent ready

Shared infrastructure for multiple agents collaborating on diagrams. Not just a single-shot generator.

Domain-aware

Purpose-built for architecture diagrams, workflows, data pipelines, system topology — not generic vector shapes.

Production-grade

16 operation types. 40+ semantic validation rules. Auth, rate limiting, PostgreSQL storage.

where it fits

Zindex is the middle layer between agent reasoning and visual output.

agents / LLMs decide what should change

zindex apply changes through DSP protocol

renderers display the result

the simplest way to think about it:

Zindex is to diagrams what a database is to application state.

A reliable system of record and execution, not just a generator.