sparklabx/drawio-ai-kit

drawio‑ai‑kit – AI‑driven, validated draw.io diagram generation

What it is

• A self‑contained CLI (drawio‑ai) plus a skill that lets LLM agents (Claude, Gemini, etc.) build cloud‑architecture diagrams in draw.io without hand‑tuned coordinates.
• The kit guarantees that every stencil ID used in the diagram actually exists in draw.io’s AWS/Azure/GCP libraries and that the layout follows a set of codified design principles.

Key components

Component	Role
Declarative Catalog	A single JSON‑based source mapping every draw.io stencil ID (mxgraph.aws4.*, Azure, GCP, etc.) to its taxonomy, canonical colour palette and connection points.
Design Principles	A markdown file (principles.md) that encodes architectural and visual rules (e.g., no overlapping nodes, fixed aspect ratios, colour consistency).
Structural Validator	A static‑analysis engine that parses the generated draw.io XML, checks stencil validity, enforces the principles, and reports any violations before the file is saved.
CLI (drawio‑ai)	Bundled as a single Bun‑minified file (dist/cli.mjs). It exposes commands for searching icons, rendering PNGs, validating XML, auditing aesthetics, and installing the skill.
Skill (skills/drawio/)	A tiny instruction set that an LLM can call: it asks the user what to draw, loads the appropriate domain reference (AWS, Azure, GCP, Databricks, BPMN), runs the build‑validate‑render loop, and returns a finished .drawio file.

How it works for an AI agent

1. The agent issues a natural‑language request (e.g., “draw an AWS 3‑tier web app”).
2. The drawio‑ai skill prompts the agent for missing details (cloud provider, topology type).
3. The agent writes a short script using the kit’s TypeScript API (Diagram, group, icon, renderTree, etc.).
4. drawio‑ai run <script> executes the script, the layout engine computes coordinates automatically, and the diagram XML is produced.
5. drawio‑ai validate lints the XML; any hallucinated stencil IDs are caught.
6. Optionally drawio‑ai render turns the XML into a PNG for a vision‑based self‑check.
7. The final .drawio file is handed back to the user.

Installation & usage

• Zero runtime dependencies – only Node ≥ 20.6 or Bun 1.4+. The installer (install.sh) drops a single binary (drawio‑ai) into ~/.local/bin and registers the skill.
• One‑liner: curl …/install.sh | sh (or manual npm i -g drawio‑ai‑kit && drawio‑ai skill install).
• Programmatic use: import { Diagram, group, icon, renderTree } from "drawio‑ai‑kit"; – the library ships with full TypeScript typings.
• Safety: No post‑install scripts, no hidden telemetry, and the bundled dist/ is a reproducible build of the readable source.

What you can build

• Cloud landing zones (AWS Control Tower, Azure CAF, GCP Shared VPC).
• Network topologies (VPCs, subnets, route tables, EKS clusters, etc.).
• Multi‑cloud or hybrid diagrams (on‑prem ↔ AWS ↔ Azure).
• Databricks lakehouse, MLOps pipelines, BPMN process flows.
  All examples live under examples/ and can be scaffolded with drawio‑ai scaffold.

Why it matters

• Reduces hallucination: AI agents often invent stencil IDs; the validator catches these before the diagram is saved.
• Consistent visual style: By enforcing a catalog of official icons and a colour/size palette, diagrams look professional and are instantly recognizable.
• Model‑friendly: The skill’s steps are small and deterministic, allowing even cheap LLMs (Claude Haiku) to drive the whole pipeline.

Bottom line drawio‑ai‑kit is a practical bridge between large language models and precise, standards‑compliant draw.io diagrams, providing both a CLI for developers and a skill that LLM agents can invoke automatically.