agent-flowviz

JSON-in, SVG-out diagram framework where icons are the semantic layer.

An AI agent generates the JSON, calls npx agent-flowviz, and produces the SVG:

# 1. Agent writes JSON to file
cat > diagram.json << 'EOF'
{
  "nodes": [
    { "id": "agent",   "icon": "mdi:robot",          "label": "AI Agent" },
    { "id": "json",    "icon": "mdi:code-json",      "label": "JSON" },
    { "id": "flowviz", "icon": "mdi:vector-polygon",  "label": "agent-flowviz" },
    { "id": "svg",     "icon": "mdi:image",          "label": "SVG" }
  ],
  "edges": [
    { "from": "agent",   "to": "json" },
    { "from": "agent",   "to": "flowviz" },
    { "from": "json",    "to": "svg" },
    { "from": "flowviz", "to": "svg" }
  ]
}
EOF

# 2. Agent calls agent-flowviz
npx agent-flowviz render diagram.json -o diagram.svg

What

One JSON, one diagram. AI writes JSON, human reads diagram.

agent-flowviz is a Node.js library and CLI designed for AI agents (Claude Code, Cursor, Copilot) to generate architecture diagrams. The agent produces a JSON describing nodes and edges, calls agent-flowviz via API or CLI, and gets back an SVG where every node carries an icon from the Iconify ecosystem (~7,000 mdi icons in v0.0.1). The human receives a readable, icon-rich diagram without writing any code.

Why

• Mermaid / PlantUML — rectangles + text. Non-technical readers struggle to parse them.
• mingrammer/diagrams — rich icons, but requires Python + Graphviz, scoped to cloud infra.
• D2 — better DSL, but Go runtime, icons are secondary.

agent-flowviz fills the gap: icon-first diagrams from a JSON schema that AI agents produce natively.

How

npx agent-flowviz render input.json -o output.svg

import { render } from "agent-flowviz";

const svg = await render({ nodes: [...], edges: [...] });

Input Format

Each node requires id, icon, label. Each edge requires from, to.

{
  "nodes": [
    { "id": "user",    "icon": "mdi:account",      "label": "User" },
    { "id": "gateway", "icon": "mdi:shield-check",  "label": "API Gateway" },
    { "id": "server",  "icon": "mdi:server",        "label": "Backend" },
    { "id": "db",      "icon": "mdi:database",      "label": "Database" }
  ],
  "edges": [
    { "from": "user",    "to": "gateway" },
    { "from": "gateway", "to": "server" },
    { "from": "server",  "to": "db" }
  ]
}

Icons use the mdi: prefix. Browse available icons at Iconify MDI.

Validation

Two-pass validation returns actionable error messages:

[ERROR] nodes[2].icon is required
[ERROR] edges[0].to references 'userr' which is not a valid node id
[ERROR] edges[1] has self-loop: from and to are both 'server'

Roadmap

v0.1.0 — Layout direction (LR/RL/BT), CONTAIN/ASSOCIATE edges, multiple icon sets, edge labels

v0.2.0 — Themes, node style variants (borderless), edge gradients, fuzzy error suggestions

License

MIT