architecture-diagram

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Diagram Generator

架构图生成器

Produces self-contained

.html

files: inline SVG icons, CSS Grid nested zones, JS-driven SVG connection overlay with color-coded semantic line types and arrowhead markers. Zero external dependencies.

生成自包含的

.html

文件：包含内联SVG图标、CSS Grid嵌套区域、带有颜色编码语义线条类型和箭头标记的JS驱动SVG连接覆盖层。无外部依赖。

Workflow

工作流程

Parse user input → extract: components (with descriptions), containment hierarchy (zones/nesting), connections (with semantic types), and any provider context
Read
```
references/icons.md
```
— select or create icons for each component
Read
```
references/layout-patterns.md
```
— choose topology pattern, set grid-template-columns
Read
```
references/connections.md
```
— define connection array with types, side-forcing, routing
Start from
```
assets/template.html
```
— use its CSS/JS structure as the base
Assemble the HTML:
- Set
```
{{DIAGRAM_TITLE}}
```
  ,
```
{{BG_COLOR}}
```
  ,
```
{{MAX_WIDTH}}
```
- Populate
```
{{LEGEND_ITEMS}}
```
  — one entry per connection type used
- Build zone hierarchy as nested
```
div.zone > span.zone-label + div.zone-content
```
- Place nodes with
```
data-node-id
```
  , each containing:
```
.node-icon
```
  (inline SVG),
```
.node-title
```
  ,
```
.node-desc
```
- Populate the
```
connections
```
  JS array
- Apply provider theming if applicable
Output final
```
.html
```
to the working directory or user-specified path

解析用户输入 → 提取：组件（含描述）、包含层级（区域/嵌套）、连接（含语义类型）以及任何提供商上下文
读取
```
references/icons.md
```
— 为每个组件选择或创建图标
读取
```
references/layout-patterns.md
```
— 选择拓扑模式，设置grid-template-columns
读取
```
references/connections.md
```
— 定义包含类型、侧边强制、路由的连接数组
以
```
assets/template.html
```
为基础 — 使用其CSS/JS结构作为框架
组装 HTML：
- 设置
```
{{DIAGRAM_TITLE}}
```
  、
```
{{BG_COLOR}}
```
  、
```
{{MAX_WIDTH}}
```
- 填充
```
{{LEGEND_ITEMS}}
```
  — 每个条目对应一种使用到的连接类型
- 构建区域层级为嵌套的
```
div.zone > span.zone-label + div.zone-content
```
- 放置带有
```
data-node-id
```
  的节点，每个节点包含：
```
.node-icon
```
  （内联SVG）、
```
.node-title
```
  、
```
.node-desc
```
- 填充
```
connections
```
  JS数组
- 若适用则应用提供商主题
输出最终的
```
.html
```
文件到工作目录或用户指定路径

Node construction

节点构造

Every node must have:

Unique
```
data-node-id
```
(semantic:
```
fusion-hcm
```
,
```
edi-adaptor
```
, not
```
node-7
```
)
```
.node-icon
```
with inline SVG from the icon registry (or custom-generated following registry constraints)
```
.node-title
```
— short name (1–3 words, bold)
```
.node-desc
```
— extended description text (protocols, module lists, capabilities). Populate this whenever the user provides detail beyond just a name. This is critical for professional-quality diagrams.

每个节点必须包含：

唯一的
```
data-node-id
```
（语义化命名：如
```
fusion-hcm
```
、
```
edi-adaptor
```
，而非
```
node-7
```
）
```
.node-icon
```
包含来自图标注册表的内联SVG（或遵循注册表约束自定义生成）
```
.node-title
```
— 短名称（1-3个单词，加粗）
```
.node-desc
```
— 扩展描述文本（协议、模块列表、功能）。只要用户提供了名称之外的详细信息，就需要填充此字段。这对生成专业质量的图表至关重要。

Key structural invariants

关键结构约束

Every
```
div.zone
```
has exactly one
```
span.zone-label
```
and one
```
div.zone-content
```

Every

div.zone-content

has explicit

style="grid-template-columns: ..."

Zone depth class (
```
zone-depth-0
```
to
```
zone-depth-3
```
) matches actual nesting level
All SVG icons are inline inside
```
.node-icon
```
— no external image references
Connection overlay SVG with
```
<defs>
```
(arrow markers for each color) sits after the diagram div
Connection renderer
```
<script>
```
is last before
```
</body>
```
Legend div sits above the diagram div, containing only types actually used

每个
```
div.zone
```
恰好包含一个
```
span.zone-label
```
和一个
```
div.zone-content
```

每个

div.zone-content

都有明确的

style="grid-template-columns: ..."

区域深度类（
```
zone-depth-0
```
到
```
zone-depth-3
```
）与实际嵌套层级匹配
所有SVG图标都内联在
```
.node-icon
```
中 — 无外部图片引用
带有
```
<defs>
```
（每种颜色对应箭头标记）的连接覆盖SVG位于图表div之后
连接渲染器
```
<script>
```
位于
```
</body>
```
之前的最后位置
图例div位于图表div上方，仅包含实际使用的类型

Connection type selection

连接类型选择

Match connection semantics to the appropriate type:

realtime
(blue solid): REST, SOAP, API calls, synchronous requests, real-time data
batch
(red dashed): SFTP, file transfers, EDI, scheduled batch jobs, bulk data
event
(green solid): event-driven triggers, pub-sub, webhooks, callbacks, business events
control
(orange dashed): management plane, monitoring, config push, admin flows
default
(blue solid): when semantic type is ambiguous or only one flow type exists

When the user doesn't specify flow semantics, default all connections to

default

type and omit the legend.

将连接语义与合适的类型匹配：

realtime
（蓝色实线）：REST、SOAP、API调用、同步请求、实时数据
batch
（红色虚线）：SFTP、文件传输、EDI、定时批处理任务、批量数据
event
（绿色实线）：事件驱动触发器、发布-订阅、Webhook、回调、业务事件
control
（橙色虚线）：管理平面、监控、配置推送、管理流程
default
（蓝色实线）：当语义类型不明确或仅存在一种流类型时使用

当用户未指定流语义时，所有连接默认使用

default

类型并省略图例。

Design defaults

设计默认值

Background:
```
#f0ece4
```
(warm neutral) or
```
#e8eef5
```
(cool blue-gray) — choose based on provider/context
Zone borders: dashed, colored by depth (warm browns → reds)
Icons: 44×44px,
```
--icon-color: #3a3a3a
```
(or provider-specific)
Node title: 12px bold, node desc: 10.5px regular #555
Connections: 2px stroke, curved by default
Font: Segoe UI / system-ui stack
Max-width: 1400px typical, increase for complex diagrams

背景色：
```
#f0ece4
```
（暖中性色）或
```
#e8eef5
```
（冷蓝灰色）— 根据提供商/上下文选择
区域边框：虚线，按深度着色（暖棕色→红色）
图标：44×44px，
```
--icon-color: #3a3a3a
```
（或提供商特定颜色）
节点标题：12px加粗，节点描述：10.5px常规#555
连接线：2px描边，默认带弧度
字体：Segoe UI / system-ui字体栈
最大宽度：通常为1400px，复杂图表可增大

Handling ambiguity

歧义处理

Infer zone nesting from naming conventions (Region > VPC > Subnet, etc.)
Default to
```
default
```
connections and no legend if flow types are unspecified
Place management/observability services outside the main data-path zones
Use generic icon set and warm-neutral background unless provider is specified
Ask for clarification only when component list or topology is fundamentally ambiguous

从命名约定推断区域嵌套（如Region > VPC > Subnet等）
若未指定流类型，默认使用
```
default
```
连接并不显示图例
将管理/可观测性服务放置在主数据路径区域之外
除非指定提供商，否则使用通用图标集和暖中性背景
仅当组件列表或拓扑存在根本性歧义时才请求澄清

Error Handling

错误处理

Problem	Cause	Fix
`assets/template.html` missing	File deleted or skill directory incomplete	Regenerate from skill defaults: reconstruct the CSS/JS skeleton using the structure documented in this SKILL.md and the reference files
Icon reference not found in `references/icons.md`	Component type not in the registry	Fall back to the generic box icon defined in `references/icons.md § Generic Fallback` ; log the missing icon name in a comment
Connection lines overlap or route through nodes	Dense graph with auto-routing conflicts	Adjust zone layout: increase `grid-template-columns` spacing, add intermediate waypoint nodes, or use `side-forcing` attributes from `references/connections.md`
Playwright render failure during HTML-to-image export	Chromium not installed or script error	Run `playwright install chromium` ; check browser console via `--headed` flag; verify no JS syntax errors in the connection renderer script
Zone nesting exceeds depth-3 styling	Architecture has more than 4 containment levels	Flatten by combining the deepest two levels into a single zone, or split into two separate diagrams linked by description

问题	原因	修复方案
`assets/template.html` 缺失	文件被删除或技能目录不完整	从技能默认值重新生成：使用本SKILL.md和参考文件中记录的结构重建CSS/JS框架
`references/icons.md` 中未找到图标引用	组件类型未在注册表中	回退到 `references/icons.md § Generic Fallback` 中定义的通用方框图标；在注释中记录缺失的图标名称
连接线重叠或穿过节点	密集图的自动路由冲突	调整区域布局：增大 `grid-template-columns` 间距、添加中间路点节点，或使用 `references/connections.md` 中的 `side-forcing` 属性
HTML转图片导出时Playwright渲染失败	Chromium未安装或脚本错误	运行 `playwright install chromium` ；通过 `--headed` 标志检查浏览器控制台；验证连接渲染器脚本中无JS语法错误
区域嵌套超过depth-3样式	架构包含4个以上的包含层级	通过将最深的两个层级合并为单个区域来扁平化，或拆分为两个通过描述关联的独立图表

References

参考资料

```
references/icons.md
```
— 28+ SVG icon definitions, custom icon rules, provider color table
```
references/layout-patterns.md
```
— node structure, zone nesting, 5 topology patterns, interior grid guidance, sizing table
```
references/connections.md
```
— connection schema, 6 semantic types with colors, side-forcing, route modes, legend markup
```
assets/template.html
```
— complete HTML skeleton: CSS, legend, zone/node styles, marker defs for all colors, connection renderer JS with auto side-detection

```
references/icons.md
```
— 28+ SVG图标定义、自定义图标规则、提供商颜色表
```
references/layout-patterns.md
```
— 节点结构、区域嵌套、5种拓扑模式、内部网格指南、尺寸表
```
references/connections.md
```
— 连接 schema、6种带颜色的语义类型、侧边强制、路由模式、图例标记
```
assets/template.html
```
— 完整HTML框架：CSS、图例、区域/节点样式、所有颜色的标记定义、带自动侧边检测的连接渲染器JS