Excalidraw Diagram Generator

Generate valid .excalidraw JSON files representing system architecture from codebase analysis.

When to Activate

• User asks to create an architecture diagram
• User wants to visualize system design
• User asks for a flowchart or data flow diagram
• User wants to document system structure visually
• User mentions Excalidraw or diagram generation

Quick Start

Works without existing diagrams, Terraform, or specific file types. Analyzes any codebase structure.

Critical Implementation Rules

Four non-negotiable constraints:

1. No Diamond Shapes: Diamond arrow connections are broken in raw Excalidraw JSON. Use styled rectangles instead:

   • Orchestrators: coral background with thick stroke
   • Decision points: orange background with dashed stroke

2. Label Architecture: The label property does NOT work in raw JSON. Every labeled element requires:

   • A shape with boundElements referencing the text element
   • A separate text element with containerId pointing to the shape

3. Arrow Formatting: Multi-point arrows need:

   • "elbowed": true
   • "roundness": null
   • "roughness": 0

4. Edge Positioning: Arrows must start/end at shape edges, not centers:

   • Top: (x + width/2, y)
   • Bottom: (x + width/2, y + height)
   • Left: (x, y + height/2)
   • Right: (x + width, y + height/2)

Generation Workflow

1. Analyze codebase structure - Identify components, services, and relationships
2. Plan layout grid - Determine rows, columns, and spacing
3. Generate shape elements - Create rectangles, ellipses, text labels
4. Add connection arrows - Connect components with proper edge positioning
5. Apply grouping - Group related elements (namespaces, services, etc.)
6. Validate and write output - Check all constraints before writing file

Input Parsing

Extract from user's request:

• scope: What part of codebase to diagram (full, specific module, etc.)
• type: Type of diagram (architecture, data flow, deployment, etc.)
• depth: Level of detail (high-level overview vs detailed)
• output: Output file path (defaults to ./architecture.excalidraw)

Output Format

Generate a valid .excalidraw JSON file with:

• Proper file structure (type, version, elements, appState)
• All shapes with unique IDs
• Proper text bindings for labels
• Correct arrow connections at shape edges
• Logical groupings with dashed rectangles

Validation Checklist

Before writing output, verify:

• No duplicate element IDs
• All labels have proper shape-text bindings
• No diamond shapes used
• All arrows positioned at shape edges
• JSON is valid and properly formatted

Reference Documentation

For detailed implementation guidance, see:

• JSON Format Reference - Complete element structure
• Arrow Routing Guide - Arrow positioning and patterns
• Color Palettes - Component type color schemes
• Examples - Layout patterns and templates
• Validation Rules - Pre-output verification