excalidraw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excalidraw Diagram Generator

Excalidraw 架构图生成器

Generate architecture diagrams as

.excalidraw

files directly from codebase analysis.

通过代码库分析直接生成 .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:

Analyze the codebase (any language/framework)
Identify components, services, databases, APIs
Map relationships and data flows
Generate valid
```
.excalidraw
```
JSON with dynamic IDs and labels

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

用户只需提出如下请求：

"为这个项目生成架构图"
"创建系统的 Excalidraw 图"
"将此代码库可视化为 Excalidraw 文件"

Claude Code 会执行以下操作：

分析代码库（支持任意语言/框架）
识别组件、服务、数据库、API
映射关系与数据流
生成带有动态ID和标签的有效 .excalidraw JSON

无前置要求： 无需现有图表、Terraform 或特定文件类型即可使用。

Critical Rules

关键规则

1. NEVER Use Diamond Shapes

1. 禁止使用菱形形状

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

Semantic Meaning	Rectangle Style
Orchestrator/Hub	Coral ( `#ffa8a8` / `#c92a2a` ) + strokeWidth: 3
Decision Point	Orange ( `#ffd8a8` / `#e8590c` ) + dashed stroke

在原始 Excalidraw JSON 中，菱形箭头连接存在问题，请改用样式化矩形：

语义含义	矩形样式
编排器/中心枢纽	珊瑚色（ `#ffa8a8` / `#c92a2a` ）+ strokeWidth: 3
决策点	橙色（ `#ffd8a8` / `#e8590c` ）+ 虚线描边

2. Labels Require TWO Elements

2. 标签需要两个元素

The

label

property does NOT work in raw JSON. Every labeled shape needs:

json

// 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"
}

label

属性在原始 JSON 中无法正常工作。每个带标签的形状都需要：

json

// 1. 包含 boundElements 引用的形状
{
  "id": "my-box",
  "type": "rectangle",
  "boundElements": [{ "type": "text", "id": "my-box-text" }]
}

// 2. 带有 containerId 的独立文本元素
{
  "id": "my-box-text",
  "type": "text",
  "containerId": "my-box",
  "text": "My Label"
}

3. Elbow Arrows Need Three Properties

3. 肘形箭头需要三个属性

For 90-degree corners (not curved):

json

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

对于90度转角（非弧形）：

json

{
  "type": "arrow",
  "roughness": 0,        // 线条清晰
  "roundness": null,     // 转角锐利
  "elbowed": true        // 90度模式
}

4. Arrow Edge Calculations

4. 箭头边缘计算

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

Edge	Formula
Top	`(x + width/2, y)`
Bottom	`(x + width/2, y + height)`
Left	`(x, y + height/2)`
Right	`(x + width, y + height/2)`

Detailed arrow routing: See

references/arrows.md

箭头必须从形状边缘而非中心开始/结束：

边缘	计算公式
顶部	`(x + width/2, y)`
底部	`(x + width/2, y + height)`
左侧	`(x, y + height/2)`
右侧	`(x + width, y + height/2)`

详细箭头路由： 参见

references/arrows.md

Element Types

元素类型

Type	Use For
`rectangle`	Services, databases, containers, orchestrators
`ellipse`	Users, external systems, start/end points
`text`	Labels inside shapes, titles, annotations
`arrow`	Data flow, connections, dependencies
`line`	Grouping boundaries, separators

Full JSON format: See

references/json-format.md

类型	用途
`rectangle`	服务、数据库、容器、编排器
`ellipse`	用户、外部系统、起始/结束点
`text`	形状内标签、标题、注释
`arrow`	数据流、连接、依赖关系
`line`	分组边界、分隔符

完整 JSON 格式： 参见

references/json-format.md

Workflow

工作流程

Step 1: Analyze Codebase

步骤1：分析代码库

Discover components by looking for:

Codebase Type	What to Look For
Monorepo	`packages/*/package.json` , workspace configs
Microservices	`docker-compose.yml` , k8s manifests
IaC	Terraform/Pulumi resource definitions
Backend API	Route definitions, controllers, DB models
Frontend	Component hierarchy, API calls

Use tools:

```
Glob
```
→
```
**/package.json
```
,
```
**/Dockerfile
```
,
```
**/*.tf
```
```
Grep
```
→
```
app.get
```
,
```
@Controller
```
,
```
CREATE TABLE
```
```
Read
```
→ README, config files, entry points

通过以下方式发现组件：

代码库类型	关注要点
单体仓库	`packages/*/package.json` 、工作区配置
微服务	`docker-compose.yml` 、k8s 清单
基础设施即代码	Terraform/Pulumi 资源定义
后端API	路由定义、控制器、数据库模型
前端	组件层级、API调用

使用工具：

```
Glob
```
→
```
**/package.json
```
,
```
**/Dockerfile
```
,
```
**/*.tf
```
```
Grep
```
→
```
app.get
```
,
```
@Controller
```
,
```
CREATE TABLE
```
```
Read
```
→ README、配置文件、入口点

Step 2: Plan Layout

步骤2：规划布局

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

垂直流（最常用）：

第1行：用户/入口点（y: 100）
第2行：前端/网关（y: 230）
第3行：编排层（y: 380）
第4行：服务层（y: 530）
第5行：数据层（y: 680）

列：x = 100, 300, 500, 700, 900
元素尺寸：160-200px × 80-90px

其他模式： 参见

references/examples.md

Step 3: Generate Elements

步骤3：生成元素

For each component:

Create shape with unique
```
id
```
Add
```
boundElements
```
referencing text
Create text with
```
containerId
```
Choose color based on type

Color palettes: See

references/colors.md

针对每个组件：

创建带有唯一
```
id
```
的形状
添加引用文本的
```
boundElements
```
创建带有
```
containerId
```
的文本
根据类型选择颜色

调色板： 参见

references/colors.md

Step 4: Add Connections

步骤4：添加连接

For each relationship:

Calculate source edge point
Plan elbow route (avoid overlaps)
Create arrow with
```
points
```
array
Match stroke color to destination type

Arrow patterns: See

references/arrows.md

针对每个关系：

计算源边缘点
规划肘线路径（避免重叠）
创建带有
```
points
```
数组的箭头
匹配目标类型的描边颜色

箭头模式： 参见

references/arrows.md

Step 5: Add Grouping (Optional)

步骤5：添加分组（可选）

For logical groupings:

Large transparent rectangle with
```
strokeStyle: "dashed"
```
Standalone text label at top-left

针对逻辑分组：

带
```
strokeStyle: "dashed"
```
的大型透明矩形
左上角的独立文本标签

Step 6: Validate and Write

步骤6：验证并写入

Run validation before writing. Save to

docs/

or user-specified path.

Validation checklist: See

references/validation.md

写入前运行验证。保存至

docs/

或用户指定路径。

验证清单： 参见

references/validation.md

Quick Arrow Reference

快速箭头参考

Straight down:

json

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

L-shape (left then down):

json

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

U-turn (callback):

json

{ "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

垂直向下：

json

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

L形（先左后下）：

json

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

U形转弯（回调）：

json

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

箭头宽/高 = 点的边界框：

points [[0,0], [-440,0], [-440,70]] → 宽度=440, 高度=70

同一边缘的多个箭头 - 错开位置：

5个箭头：边缘宽度的20%, 35%, 50%, 65%, 80%位置

Default Color Palette

默认调色板

Component	Background	Stroke
Frontend	`#a5d8ff`	`#1971c2`
Backend/API	`#d0bfff`	`#7048e8`
Database	`#b2f2bb`	`#2f9e44`
Storage	`#ffec99`	`#f08c00`
AI/ML	`#e599f7`	`#9c36b5`
External APIs	`#ffc9c9`	`#e03131`
Orchestration	`#ffa8a8`	`#c92a2a`
Message Queue	`#fff3bf`	`#fab005`
Cache	`#ffe8cc`	`#fd7e14`
Users	`#e7f5ff`	`#1971c2`

Cloud-specific palettes: See

references/colors.md

组件	背景色	描边色
前端	`#a5d8ff`	`#1971c2`
后端/API	`#d0bfff`	`#7048e8`
数据库	`#b2f2bb`	`#2f9e44`
存储	`#ffec99`	`#f08c00`
AI/机器学习	`#e599f7`	`#9c36b5`
外部API	`#ffc9c9`	`#e03131`
编排层	`#ffa8a8`	`#c92a2a`
消息队列	`#fff3bf`	`#fab005`
缓存	`#ffe8cc`	`#fd7e14`
用户	`#e7f5ff`	`#1971c2`

云厂商专用调色板： 参见

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

写入文件前：

每个带标签的形状都包含 boundElements + 文本元素
文本元素的 containerId 与形状匹配
多点箭头包含
```
elbowed: true
```
,
```
roundness: null
```
箭头的x,y坐标基于形状边缘而非中心
箭头终点偏移至目标边缘
无菱形形状
无重复ID

完整验证算法： 参见

references/validation.md

Common Issues

常见问题

Issue	Fix
Labels don't appear	Use TWO elements (shape + text), not `label` property
Arrows curved	Add `elbowed: true` , `roundness: null` , `roughness: 0`
Arrows floating	Calculate x,y from shape edge, not center
Arrows overlapping	Stagger start positions across edge

Detailed bug fixes: See

references/validation.md

问题	修复方案
标签不显示	使用两个元素（形状+文本），而非 `label` 属性
箭头呈弧形	添加 `elbowed: true` , `roundness: null` , `roughness: 0`
箭头悬浮	基于形状边缘计算x,y坐标，而非中心
箭头重叠	沿边缘错开起始位置

详细 bug 修复： 参见

references/validation.md

Reference Files

参考文件

File	Contents
`references/json-format.md`	Element types, required properties, text bindings
`references/arrows.md`	Routing algorithm, patterns, bindings, staggering
`references/colors.md`	Default, AWS, Azure, GCP, K8s palettes
`references/examples.md`	Complete JSON examples, layout patterns
`references/validation.md`	Checklists, validation algorithm, bug fixes

文件	内容
`references/json-format.md`	元素类型、必填属性、文本绑定
`references/arrows.md`	路由算法、模式、绑定、错开策略
`references/colors.md`	默认、AWS、Azure、GCP、K8s 调色板
`references/examples.md`	完整JSON示例、布局模式
`references/validation.md`	清单、验证算法、bug修复

Output

输出

Location:
```
docs/architecture/
```
or user-specified
Filename: Descriptive, e.g.,
```
system-architecture.excalidraw
```
Testing: Open in https://excalidraw.com or VS Code extension

位置：
```
docs/architecture/
```
或用户指定路径
文件名： 具有描述性，例如
```
system-architecture.excalidraw
```
测试： 在 https://excalidraw.com 或 VS Code 扩展中打开