Excalidraw Diagram Generator

.excalidraw

Quick Start

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

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

Critical Rules

1. NEVER Use Diamond Shapes

#ffa8a8

#c92a2a

#ffd8a8

#e8590c

2. Labels Require TWO Elements

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

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

4. Arrow Edge Calculations

(x + width/2, y)

(x + width/2, y + height)

(x, y + height/2)

(x + width, y + height/2)

references/arrows.md

Element Types

rectangle

ellipse

text

arrow

line

references/json-format.md

Workflow

Step 1: Analyze Codebase

packages/*/package.json

docker-compose.yml

• Glob

  →

  **/package.json

  ,

  **/Dockerfile

  ,

  **/*.tf

• Grep

  →

  app.get

  ,

  @Controller

  ,

  CREATE TABLE

• Read

  → README, config files, entry points

Step 2: Plan Layout

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

references/examples.md

Step 3: Generate Elements

1. Create shape with unique

   id

2. Add

   boundElements

   referencing text
3. Create text with

   containerId

4. Choose color based on type

references/colors.md

Step 4: Add Connections

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

   points

   array
4. Match stroke color to destination type

references/arrows.md

Step 5: Add Grouping (Optional)

• Large transparent rectangle with

  strokeStyle: "dashed"

• Standalone text label at top-left

Step 6: Validate and Write

docs/

references/validation.md

Quick Arrow Reference

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

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

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

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

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

references/colors.md

Quick Validation Checklist

• 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

references/validation.md

Common Issues

label

elbowed: true

roundness: null

roughness: 0

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