Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

docs: C4 multi-page drill-down demo in READMEs (#58)

Agents365.aiacb2a3ec4cac
diff --git a/README.md b/README.md
index 3b5c861..e295de6 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,7 @@ A skill that turns natural-language descriptions into `.drawio` XML and exports
- **IaC → architecture diagram** — turn **Terraform** configs, **Kubernetes** manifests, or **docker-compose** files into an architecture diagram where every resource renders as its **official AWS / Azure / GCP / K8s icon**, edges derived from actual references (role ARNs, selectors, volume mounts)
- **SQL DDL → ER diagram** — parse `CREATE TABLE` statements into per-table nodes with PK/FK markers and crow's-foot foreign-key edges
- **Deterministic sequence diagrams** — describe participants + messages as JSON; lifelines, auto-tracked activation bars, and arrows are computed, never hand-placed
+- **C4 model with drill-down** — one command generates the multi-page System Context → Container → Component set with official C4 shapes; parent elements **click through** to their child page
- **Search 10,000+ official shapes** — resolve the exact AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN icon style instead of guessing (no more blank-box `shape=mxgraph.*` typos)
- **AI / LLM brand logos** — 321 logos (OpenAI, Claude, Gemini, Mistral, Llama, Ollama, LangChain…) that draw.io has none of, for LLM-app architecture diagrams
- **Self-check + auto-fix** — reads its own PNG output and auto-fixes overlaps, clipped labels, stacked edges, and more (up to 2 rounds)
@@ -151,8 +152,24 @@ python3 scripts/composeimports.py compose.yml -o graph.json # services + named v
# Data & interactions
python3 scripts/sqlerd.py schema.sql -o graph.json # SQL DDL → ER diagram
python3 scripts/seqlayout.py seq.json -o sequence.drawio # sequence diagram, direct to .drawio
+python3 scripts/c4.py c4.json -o c4.drawio # C4 model, multi-page + drill-down
```
+<table>
+ <tr>
+ <td align="center" width="50%">
+ <img src="assets/demo-c4-context.png" alt="C4 System Context" width="100%"><br>
+ <b>C4 Level 1</b> · System Context<br>
+ <sub>Clicking the blue system box in draw.io drills down to…</sub>
+ </td>
+ <td align="center" width="50%">
+ <img src="assets/demo-c4-containers.png" alt="C4 Containers" width="100%"><br>
+ <b>C4 Level 2</b> · Containers<br>
+ <sub>…the Containers page — one <a href="assets/demo-c4-input.json">JSON</a>, one multi-page <a href="assets/demo-c4.drawio">.drawio</a>.</sub>
+ </td>
+ </tr>
+</table>
+
<p align="center">
<img src="assets/demo-terraform.png" width="820" alt="Serverless architecture diagram generated from Terraform — every resource rendered as its official AWS icon">
</p>
@@ -256,6 +273,7 @@ Behind the scenes: **check dependencies → plan layout → generate `.drawio` X
| IaC → architecture diagram | ❌ | ✅ Terraform / K8s / compose → official cloud icons |
| SQL DDL → ER diagram | ❌ | ✅ `CREATE TABLE` → PK/FK tables, crow's-foot edges |
| Sequence diagrams | ❌ hand-placed coordinates | ✅ deterministic geometry engine (`seqlayout.py`) |
+| C4 model | ❌ | ✅ multi-page Context→Container→Component with click-to-drill-down |
| Auto-layout for large graphs | ❌ hand-places, overlaps | ✅ Graphviz placement, ortho routing, nested containers |
| Structural validation | ❌ | ✅ deterministic `.drawio` linter |
| Official shape search | ❌ guesses, blank boxes | ✅ exact style for 10k+ AWS/Azure/GCP/UML shapes |
diff --git a/README_CN.md b/README_CN.md
index 071485c..3a053a2 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -27,6 +27,7 @@
- **IaC → 架构图** —— 把 **Terraform** 配置、**Kubernetes** manifest 或 **docker-compose** 文件直接变成架构图,每个资源渲染为**官方 AWS / Azure / GCP / K8s 图标**,连线来自真实引用(role ARN、selector、volume 挂载)
- **SQL DDL → ER 图** —— 解析 `CREATE TABLE` 语句,生成带 PK/FK 标记的表节点和鸦爪外键连线
- **确定性时序图** —— 用 JSON 描述参与者 + 消息序列,lifeline、自动追踪的激活条、箭头几何全部计算得出,无需手摆坐标
+- **C4 模型 + 下钻** —— 一条命令生成多页 System Context → Container → Component 全套,官方 C4 形状配色,父元素**点击跳转**到子层页面
- **搜索 10,000+ 个官方形状** —— 直接拿到 AWS / Azure / GCP / Cisco / Kubernetes / UML / BPMN 图标的精确 style,不靠猜(杜绝 `shape=mxgraph.*` 拼错变空白框)
- **AI / LLM 品牌图标** —— 321 个 draw.io 自身没有的 logo(OpenAI、Claude、Gemini、Mistral、Llama、Ollama、LangChain……),专为 LLM 应用架构图准备
- **自检 + 自动修复** —— 读取自己导出的 PNG,自动修复重叠、截断标签、连线堆叠等问题(最多 2 轮)
@@ -149,8 +150,24 @@ python3 scripts/composeimports.py compose.yml -o graph.json # 服务 + 命名卷
# 数据与交互
python3 scripts/sqlerd.py schema.sql -o graph.json # SQL DDL → ER 图
python3 scripts/seqlayout.py seq.json -o sequence.drawio # 时序图,直接生成 .drawio
+python3 scripts/c4.py c4.json -o c4.drawio # C4 模型,多页 + 下钻
```
+<table>
+ <tr>
+ <td align="center" width="50%">
+ <img src="assets/demo-c4-context.png" alt="C4 系统上下文" width="100%"><br>
+ <b>C4 第 1 层</b> · System Context<br>
+ <sub>在 draw.io 里点击蓝色系统框即可下钻到……</sub>
+ </td>
+ <td align="center" width="50%">
+ <img src="assets/demo-c4-containers.png" alt="C4 容器层" width="100%"><br>
+ <b>C4 第 2 层</b> · Containers<br>
+ <sub>……容器层页面 —— 一份 <a href="assets/demo-c4-input.json">JSON</a>,一个多页 <a href="assets/demo-c4.drawio">.drawio</a>。</sub>
+ </td>
+ </tr>
+</table>
+
<p align="center">
<img src="assets/demo-terraform.png" width="820" alt="由 Terraform 直接生成的 serverless 架构图 —— 每个资源渲染为官方 AWS 图标">
</p>
@@ -254,6 +271,7 @@ Skill 会提取配色、形状、字体和连线风格,渲染预览图,**确
| IaC → 架构图 | ❌ | ✅ Terraform / K8s / compose → 官方云图标 |
| SQL DDL → ER 图 | ❌ | ✅ `CREATE TABLE` → PK/FK 表节点 + 鸦爪连线 |
| 时序图 | ❌ 手摆坐标易出错 | ✅ 确定性几何引擎(`seqlayout.py`) |
+| C4 模型 | ❌ | ✅ 多页 Context→Container→Component + 点击下钻 |
| 大图自动布局 | ❌ 手动摆放、易重叠 | ✅ Graphviz 布点、正交路由、嵌套容器 |
| 结构校验 | ❌ | ✅ 确定性 `.drawio` linter |
| 官方形状搜索 | ❌ 靠猜、变空白框 | ✅ 1 万+ AWS/Azure/GCP/UML 形状的精确 style |
diff --git a/assets/demo-c4-containers.png b/assets/demo-c4-containers.png
new file mode 100644
index 0000000..260a116
Binary files /dev/null and b/assets/demo-c4-containers.png differ
diff --git a/assets/demo-c4-context.png b/assets/demo-c4-context.png
new file mode 100644
index 0000000..e07687d
Binary files /dev/null and b/assets/demo-c4-context.png differ
diff --git a/assets/demo-c4-input.json b/assets/demo-c4-input.json
new file mode 100644
index 0000000..577f9af
--- /dev/null
+++ b/assets/demo-c4-input.json
@@ -0,0 +1,45 @@
+{
+ "title": "Internet Banking",
+ "levels": [
+ {
+ "name": "System Context",
+ "elements": [
+ {"id": "customer", "type": "person", "label": "Personal Customer", "desc": "A customer of the bank"},
+ {"id": "ibs", "type": "system", "label": "Internet Banking System", "desc": "Lets customers view accounts and make payments", "children": "Containers"},
+ {"id": "mainframe", "type": "external", "label": "Mainframe Banking", "desc": "Stores core banking data"},
+ {"id": "email", "type": "external", "label": "E-mail System", "desc": "Microsoft Exchange"}
+ ],
+ "relations": [
+ {"from": "customer", "to": "ibs", "label": "Views accounts via"},
+ {"from": "ibs", "to": "mainframe", "label": "Gets data from"},
+ {"from": "ibs", "to": "email", "label": "Sends e-mail via"}
+ ]
+ },
+ {
+ "name": "Containers",
+ "elements": [
+ {"id": "spa", "type": "container", "label": "Single-Page App", "tech": "React", "desc": "Banking UI in the browser"},
+ {"id": "mobile", "type": "container", "label": "Mobile App", "tech": "Flutter", "desc": "iOS / Android client"},
+ {"id": "api", "type": "container", "label": "API Application", "tech": "Java / Spring MVC", "desc": "Business logic via JSON/HTTPS API", "children": "Components"},
+ {"id": "db", "type": "database", "label": "Database", "tech": "PostgreSQL", "desc": "Accounts, transactions"}
+ ],
+ "relations": [
+ {"from": "spa", "to": "api", "label": "JSON/HTTPS"},
+ {"from": "mobile", "to": "api", "label": "JSON/HTTPS"},
+ {"from": "api", "to": "db", "label": "JDBC"}
+ ]
+ },
+ {
+ "name": "Components",
+ "elements": [
+ {"id": "signin", "type": "component", "label": "Sign-In Controller", "tech": "Spring MVC", "desc": "Auth endpoints"},
+ {"id": "accounts", "type": "component", "label": "Accounts Controller", "tech": "Spring MVC", "desc": "Account summary endpoints"},
+ {"id": "security", "type": "component", "label": "Security Component", "tech": "Spring Bean", "desc": "Credentials check"}
+ ],
+ "relations": [
+ {"from": "signin", "to": "security", "label": "Uses"},
+ {"from": "accounts", "to": "security", "label": "Uses"}
+ ]
+ }
+ ]
+}
diff --git a/assets/demo-c4.drawio b/assets/demo-c4.drawio
new file mode 100644
index 0000000..7144593
--- /dev/null
+++ b/assets/demo-c4.drawio
@@ -0,0 +1,87 @@
+<mxfile>
+ <diagram id="system-context" name="System Context">
+ <mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0"/>
+ <mxCell id="1" parent="0"/>
+ <mxCell id="customer" value="Personal Customer&#xa;[Person]&#xa;A customer of the bank" style="shape=mxgraph.c4.person2;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#083F75;strokeColor=#06315C;" vertex="1" parent="1">
+ <mxGeometry x="160" y="0" width="200" height="180" as="geometry"/>
+ </mxCell>
+ <UserObject label="Internet Banking System&#xa;[Software System]&#xa;Lets customers view accounts and make payments" link="data:page/id,containers" id="ibs">
+ <mxCell style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#1061B0;strokeColor=#0D5091;" vertex="1" parent="1">
+ <mxGeometry x="140" y="250" width="240" height="120" as="geometry"/>
+ </mxCell>
+ </UserObject>
+ <mxCell id="mainframe" value="Mainframe Banking&#xa;[Software System]&#xa;Stores core banking data" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#8C8496;strokeColor=#736782;" vertex="1" parent="1">
+ <mxGeometry x="0" y="430" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="email" value="E-mail System&#xa;[Software System]&#xa;Microsoft Exchange" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#8C8496;strokeColor=#736782;" vertex="1" parent="1">
+ <mxGeometry x="280" y="430" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="e0" value="Views accounts via" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="customer" target="ibs">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="260" y="180"/><mxPoint x="260" y="230"/></Array></mxGeometry>
+ </mxCell>
+ <mxCell id="e1" value="Gets data from" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="ibs" target="mainframe">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="190" y="370"/><mxPoint x="190" y="420"/></Array></mxGeometry>
+ </mxCell>
+ <mxCell id="e2" value="Sends e-mail via" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="ibs" target="email">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="330" y="370"/><mxPoint x="330" y="420"/></Array></mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+ <diagram id="containers" name="Containers">
+ <mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0"/>
+ <mxCell id="1" parent="0"/>
+ <mxCell id="spa" value="Single-Page App&#xa;[Container: React]&#xa;Banking UI in the browser" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#23A2D9;strokeColor=#0E7DAD;" vertex="1" parent="1">
+ <mxGeometry x="0" y="0" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="mobile" value="Mobile App&#xa;[Container: Flutter]&#xa;iOS / Android client" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#23A2D9;strokeColor=#0E7DAD;" vertex="1" parent="1">
+ <mxGeometry x="280" y="0" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <UserObject label="API Application&#xa;[Container: Java / Spring MVC]&#xa;Business logic via JSON/HTTPS API" link="data:page/id,components" id="api">
+ <mxCell style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#23A2D9;strokeColor=#0E7DAD;" vertex="1" parent="1">
+ <mxGeometry x="140" y="190" width="240" height="120" as="geometry"/>
+ </mxCell>
+ </UserObject>
+ <mxCell id="db" value="Database&#xa;[Container: PostgreSQL]&#xa;Accounts, transactions" style="shape=cylinder3;size=15;boundedLbl=1;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#23A2D9;strokeColor=#0E7DAD;" vertex="1" parent="1">
+ <mxGeometry x="140" y="370" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="e0" value="JSON/HTTPS" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="spa" target="api">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="190" y="120"/><mxPoint x="190" y="170"/></Array></mxGeometry>
+ </mxCell>
+ <mxCell id="e1" value="JSON/HTTPS" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="mobile" target="api">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="330" y="120"/><mxPoint x="330" y="170"/></Array></mxGeometry>
+ </mxCell>
+ <mxCell id="e2" value="JDBC" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="api" target="db">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="260" y="310"/><mxPoint x="260" y="360"/></Array></mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+ <diagram id="components" name="Components">
+ <mxGraphModel dx="800" dy="600" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+ <root>
+ <mxCell id="0"/>
+ <mxCell id="1" parent="0"/>
+ <mxCell id="signin" value="Sign-In Controller&#xa;[Component: Spring MVC]&#xa;Auth endpoints" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#63BEF2;strokeColor=#2086C9;" vertex="1" parent="1">
+ <mxGeometry x="0" y="0" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="accounts" value="Accounts Controller&#xa;[Component: Spring MVC]&#xa;Account summary endpoints" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#63BEF2;strokeColor=#2086C9;" vertex="1" parent="1">
+ <mxGeometry x="280" y="0" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="security" value="Security Component&#xa;[Component: Spring Bean]&#xa;Credentials check" style="rounded=1;arcSize=10;html=1;whiteSpace=wrap;fontSize=12;fontColor=#ffffff;align=center;fillColor=#63BEF2;strokeColor=#2086C9;" vertex="1" parent="1">
+ <mxGeometry x="140" y="190" width="240" height="120" as="geometry"/>
+ </mxCell>
+ <mxCell id="e0" value="Uses" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="signin" target="security">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="190" y="120"/><mxPoint x="190" y="170"/></Array></mxGeometry>
+ </mxCell>
+ <mxCell id="e1" value="Uses" style="endArrow=blockThin;endFill=1;endSize=10;html=1;fontSize=11;fontColor=#404040;strokeColor=#828282;labelBackgroundColor=#ffffff;rounded=0;" edge="1" parent="1" source="accounts" target="security">
+ <mxGeometry relative="1" as="geometry"><Array as="points"><mxPoint x="330" y="120"/><mxPoint x="330" y="170"/></Array></mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>