Excalidraw Diagram Generator

Generate architecture diagrams as

.excalidraw

Quick Start

User just asks:

"Generate an architecture diagram for this project"
"Create an excalidraw diagram of the system"
"Visualize this codebase as an excalidraw file"

Claude Code will:

1. Analyze the codebase (any language/framework)
2. Identify components, services, databases, APIs
3. Map relationships and data flows
4. Generate valid

   .excalidraw

   JSON with dynamic IDs and labels

No prerequisites: Works without existing diagrams, Terraform, or specific file types.

Critical Rules

1. NEVER Use Diamond Shapes

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

#ffa8a8

#c92a2a

#ffd8a8

#e8590c

2. Labels Require TWO Elements

The

label

// 1. Shape with boundElements reference
{
  "id": "my-box",
  "type": "rectangle",
  "boundElements": [{ "type": "text", "id": "my-box-text" }]
}

// 2. Separate text element with containerId
{
  "id": "my-box-text",
  "type": "text",
  "containerId": "my-box",
  "text": "My Label"
}

3. Elbow Arrows Need Three Properties

For 90-degree corners (not curved):

{
  "type": "arrow",
  "roughness": 0,        // Clean lines
  "roundness": null,     // Sharp corners
  "elbowed": true        // 90-degree mode
}

4. Arrow Edge Calculations

Arrows must start/end at shape edges, not centers:

(x + width/2, y)

(x + width/2, y + height)

(x, y + height/2)

(x + width, y + height/2)

Detailed arrow routing: See

references/arrows.md

Element Types

rectangle

ellipse

text

arrow

line

Full JSON format: See

references/json-format.md

Workflow

Step 1: Analyze Codebase

Discover components by looking for:

packages/*/package.json

docker-compose.yml

Use tools:

• Glob

  →

  **/package.json

  ,

  **/Dockerfile

  ,

  **/*.tf

• Grep

  →

  app.get

  ,

  @Controller

  ,

  CREATE TABLE

• Read

  → README, config files, entry points

Step 2: Plan Layout

Vertical flow (most common):

Row 1: Users/Entry points (y: 100)
Row 2: Frontend/Gateway (y: 230)
Row 3: Orchestration (y: 380)
Row 4: Services (y: 530)
Row 5: Data layer (y: 680)

Columns: x = 100, 300, 500, 700, 900
Element size: 160-200px x 80-90px

Other patterns: See

references/examples.md

Step 3: Generate Elements

For each component:

1. Create shape with unique

   id

2. Add

   boundElements

   referencing text
3. Create text with

   containerId

4. Choose color based on type

Color palettes: See

references/colors.md

Step 4: Add Connections

For each relationship:

1. Calculate source edge point
2. Plan elbow route (avoid overlaps)
3. Create arrow with

   points

   array
4. Match stroke color to destination type

Arrow patterns: See

references/arrows.md

Step 5: Add Grouping (Optional)

For logical groupings:

• Large transparent rectangle with

  strokeStyle: "dashed"

• Standalone text label at top-left

Step 6: Validate and Write

Run validation before writing. Save to

docs/

Validation checklist: See

references/validation.md

Quick Arrow Reference

Straight down:

{ "points": [[0, 0], [0, 110]], "x": 590, "y": 290 }

L-shape (left then down):

{ "points": [[0, 0], [-325, 0], [-325, 125]], "x": 525, "y": 420 }

U-turn (callback):

{ "points": [[0, 0], [50, 0], [50, -125], [20, -125]], "x": 710, "y": 440 }

Arrow width/height = bounding box of points:

points [[0,0], [-440,0], [-440,70]] → width=440, height=70

Multiple arrows from same edge - stagger positions:

5 arrows: 20%, 35%, 50%, 65%, 80% across edge width

Default Color Palette

#a5d8ff

#1971c2

#d0bfff

#7048e8

#b2f2bb

#2f9e44

#ffec99

#f08c00

#e599f7

#9c36b5

#ffc9c9

#e03131

#ffa8a8

#c92a2a

#fff3bf

#fab005

#ffe8cc

#fd7e14

#e7f5ff

#1971c2

Cloud-specific palettes: See

references/colors.md

Quick Validation Checklist

Before writing file:

• Every shape with label has boundElements + text element
• Text elements have containerId matching shape
• Multi-point arrows have

  elbowed: true

  ,

  roundness: null

• Arrow x,y = source shape edge point
• Arrow final point offset reaches target edge
• No diamond shapes
• No duplicate IDs

Full validation algorithm: See

references/validation.md

Common Issues

label

elbowed: true

roundness: null

roughness: 0

Detailed bug fixes: See

references/validation.md

Reference Files

references/json-format.md

references/arrows.md

references/colors.md

references/examples.md

references/validation.md

Output

• Location:

  docs/architecture/

  or user-specified
• Filename: Descriptive, e.g.,

  system-architecture.excalidraw

• Testing: Open in https://excalidraw.com or VS Code extension