| name | generating-excalidraw-architecture-diagrams |
| description | Creates and updates Excalidraw diagrams representing application architecture by analyzing codebases, identifying components, services, and their relationships. Use when users request architecture visualization, system diagrams, or need to document application structure visually. |
| allowed-tools | ["Read","Write","Glob","Grep","Bash","Edit","AskUserQuestion","Task"] |
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:
- Create: Generate a new architecture diagram from codebase analysis
- 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
| Type | Color | Shape |
|---|
| Service | Blue #a5d8ff | Rounded rectangle |
| Frontend | Purple #d0bfff | Rounded rectangle |
| Database | Green #d3f9d8 | Ellipse |
| Cache | Red #ffc9c9 | Diamond |
| Queue | Violet #eebefa | Rectangle |
| External | Yellow #fff3bf | Dashed rectangle |
Connection Types
| Type | Style | Use Case |
|---|
| Sync | Solid arrow | HTTP, gRPC, direct calls |
| Async | Dashed arrow | Message queue, events |
| Data | Dotted arrow | ETL, data pipelines |
Scripts
node scripts/generate-diagram.js --config <config.json> --output <diagram.excalidraw>
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:
| Tool | Purpose |
|---|
Glob | Find files by pattern (e.g., **/*.config.js) |
Grep | Search file contents for patterns |
Read | Read and analyze file contents |
Task (Explore) | Spawn subagents for thorough codebase exploration |
Supporting Documentation
