C4 系統說明 — drawmiat

C4 Architecture Diagrams Official C4 Model

drawmiat 的 C4 renderer 依照官方 c4model.com 的 abstraction、diagram level、notation 與 review checklist 實作，並參考 c4sharp 的 theme、typed containers/components、relationship position hints、layout hints 來重構。支援 System Context、Container、Component 三種核心圖。

支援的 diagram level

`diagram_level`	scope	顯示的主要元素
`context`	`{"type":"software_system","id":"SYS1"}`	人員 + 軟體系統
`container`	`{"type":"software_system","id":"SYS1"}`	系統內 containers + 直接相連的 people/systems
`component`	`{"type":"container","id":"CT1"}`	container 內 components + 直接相連的 containers/people/systems

官方對齊規則

每張圖必須有明確標題，且標題需描述 diagram type 與 scope
每個元素都要有 type label、name、description
每個 container / component 都要明示 technology
每條關係線都要有單向 label；container-to-container 關係建議提供 technology / protocol
每張圖都會輸出 legend，使 notation 可自解釋
renderer 會依 level 自動忽略 out-of-scope 抽象層，以維持 C4 合規

c4sharp 導向擴充欄位

欄位	適用範圍	說明
`diagram_layout`	全圖	`top_down` 或 `left_right`
`type`	container	例如 `api`、`database`、`queue`、`spa`
`type`	component	例如 `database`、`queue`
`position`	relationship	`down` / `up` / `left` / `right` / `neighbor` / `none`

JSON 結構

{
  "diagram_title": "Component diagram for Drawmiat Runtime - Flask Web Container",
  "diagram_level": "component",
  "diagram_layout": "left_right",
  "scope": { "type": "container", "id": "CT1" },
  "persons": [
    { "id": "P1", "name": "Diagram Author", "description": "Creates and validates architecture diagrams.", "external": true }
  ],
  "systems": [
    { "id": "SYS1", "name": "Drawmiat Runtime", "description": "Renders diagram JSON into SVG artifacts.", "external": false },
    { "id": "SYS2", "name": "Opencode Caller", "description": "Invokes drawmiat MCP tools.", "external": true }
  ],
  "containers": [
    { "id": "CT1", "type": "api", "name": "Flask Web Container", "technology": "Python Flask", "description": "Hosts MCP and web routes.", "systemRef": "SYS1" }
  ],
  "components": [
    { "id": "C1", "name": "MCP Tool Layer", "technology": "Python module", "description": "Validates MCP input and dispatches service calls.", "containerRef": "CT1" }
  ],
  "relationships": [
    { "id": "R1", "source": "SYS2", "target": "C1", "description": "Invokes MCP tool", "technology": "MCP stdio", "position": "left" }
  ]
}

欄位說明

欄位	必填	說明
`diagram_title`	建議	官方建議每張圖都應有標題
`diagram_level`	是	`context` / `container` / `component`
`diagram_layout`	否	`top_down` / `left_right`；參考 c4sharp 的 `DiagramLayout`
`scope`	是（除非可唯一推斷）	定義 in-scope software system 或 container
`persons`	否	People / actors / roles / personas
`systems`	依 level	Software systems；含 scope system 與 external systems
`containers`	container/component 圖需要	Applications 或 data stores，不是 Docker；可用 `type` 標示 `api` / `database` / `queue` 等
`components`	component 圖需要	Container 內的功能群組，不是 deployable units；可用 `type` 補充資料庫/佇列型元件
`relationships`	建議	單向關係，需有意圖明確的 description；可用 `position` 給 routing hint

下載

下載 C4 範本 JSON
C4 JSON Schema：webapp/c4/c4.schema.json
合規範例：Example/C4_component.json
參考上游：refs/c4sharp/、refs/C4-PlantUML/

drawmiat