Generating Excalidraw Architecture Diagrams

This skill creates and updates Excalidraw diagrams that visualize application architecture. It analyzes codebases to identify components, services, data flows, and relationships.

Workflows

This skill supports two primary workflows:

1. Create: Generate a new architecture diagram from codebase analysis
2. Update: Modify an existing Excalidraw diagram to reflect current codebase state

Workflow Structure

The skill follows a phased approach with Stages and Steps:

Phase 1: Discovering and Clarifying
├── Stage 1.1: Determining User Intent
└── Stage 1.2: Defining Scope

Phase 2: Analyzing Architecture
├── Stage 2.1: Exploring Codebase
├── Stage 2.2: Identifying Components
└── Stage 2.3: Mapping Relationships

Phase 3: Generating Diagram
├── Stage 3.1: Planning Structure
├── Stage 3.2: Creating Diagram
└── Stage 3.3: Applying Styling

Phase 4: Validating and Refining
├── Stage 4.1: Validating Diagram
├── Stage 4.2: Reviewing with User
└── Stage 4.3: Iterating on Feedback

Phase 1: Discovering and Clarifying

Establish user intent and scope through interactive questions.

Stage 1.1: Determining User Intent

• Ask user to choose Create or Update workflow
• For Update workflow, locate existing .excalidraw file

Stage 1.2: Defining Scope

• Define architecture scope (full system, subsystem, data flow, integration)
• Set detail level (high-level, detailed, comprehensive)
• Gather additional context about focus areas

Phase 2: Analyzing Architecture

Use agent-driven exploration with tools and subagents to analyze the codebase.

Stage 2.1: Exploring Codebase

• Use Glob, Grep, and Read to identify project structure
• Spawn Explore subagents for thorough directory analysis
• Detect architecture style and technology stack

Stage 2.2: Identifying Components

• Use subagents to find services, modules, and applications
• Search for database, cache, and storage configurations
• Identify external integrations and message systems

Stage 2.3: Mapping Relationships

• Trace dependencies through imports and configurations
• Use subagents to map service communication patterns
• Build connection inventory from discovered relationships

Phase 3: Generating Diagram

Create or update the Excalidraw diagram file.

Stage 3.1: Planning Structure

• Choose layout strategy (hierarchical, grid, grouped)
• Assign components to layers
• Plan connection routing

Stage 3.2: Creating Diagram

• Execute scripts/generate-diagram.js (Create workflow)
• Execute scripts/update-diagram.js (Update workflow)
• Validate generated file structure

Stage 3.3: Applying Styling

• Apply component type colors and shapes
• Style connections by communication pattern
• Format labels consistently

Phase 4: Validating and Refining

Verify and iterate on the diagram with user feedback.

Stage 4.1: Validating Diagram

• Verify all components are represented
• Check connection completeness
• Identify visual issues

Stage 4.2: Reviewing with User

• Present diagram summary
• Request user feedback using AskUserQuestion
• Document requested changes

Stage 4.3: Iterating on Feedback

• Apply user-requested changes
• Regenerate diagram
• Return to Stage 4.2 for approval

Quick Reference

Component Types and Styles

Connection Types

Scripts

# Generate new diagram
node scripts/generate-diagram.js --config <config.json> --output <diagram.excalidraw>

# Update existing diagram
node scripts/update-diagram.js --existing <current.excalidraw> --config <config.json> --output <updated.excalidraw>

Exploration Tools

Phase 2 uses agent-driven exploration rather than scripts:

Supporting Documentation

• REFERENCE.md – Excalidraw JSON schema and script API
• EXAMPLES.md – Example configurations for common architectures