sparklabx/drawio-ai-kit

What it solves

AI agents often struggle to create accurate draw.io diagrams, frequently hallucinating non-existent stencil IDs or failing to follow architectural layout standards. This kit provides a framework to ensure AI-generated diagrams are structurally precise, aesthetically standardized, and use valid cloud architecture stencils.

How it works

The project uses a three-pronged approach to guide AI agents:

1. Declarative Catalog: A source of truth that maps draw.io stencil IDs to their correct taxonomies and colors, preventing the AI from inventing shapes.
2. Design Principles: A set of codified architectural and layout rules that the AI must follow.
3. Structural Validator: A static analysis engine that audits the diagram XML to ensure stencil references are valid and design principles are met before the file is finalized.

Agents interact with these tools via a zero-dependency CLI (drawio-ai). The system also supports a layout engine that computes spatial coordinates programmatically based on a defined topology (e.g., network, pipeline, or mesh) rather than requiring the AI to guess raw pixel coordinates.

Who it’s for

Cloud architects and developers using AI agents (such as Claude Code or Gemini CLI) to automate the creation of AWS, Azure, GCP, and Databricks architecture diagrams, as well as BPMN process maps.

Highlights

• Multi-Cloud Support: Dedicated domain skills for AWS, Azure, GCP, and Databricks.
• Zero-Dependency CLI: A self-contained tool for searching stencils, validating XML, and rendering diagrams.
• Automated Layout: A layout engine that handles sizing and spacing automatically based on logical topology.
• Vision-Based Correction: Supports a render-analyze-rectify loop where the AI can render the diagram to PNG and use vision capabilities to self-correct.