---
id: wiki-2026-0508-diagrams-as-code
title: Diagrams as Code
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [diagrams as code, Mermaid, PlantUML, Structurizr, D2, IcePanel, DAC]
duplicate_of: none
source_trust_level: A
confidence_score: 0.93
verification_status: applied
tags: [documentation, diagrams-as-code, mermaid, plantuml, structurizr, d2, c4-model, devx]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: text DSL
  framework: Mermaid / PlantUML / Structurizr / D2
---

# Diagrams as Code

## 매 한 줄
> **"매 GUI drawing 의 X — 매 text 의 diagram"**. 매 git-versioned + 매 review-able + 매 generate-able. 매 modern: D2 (modern), Mermaid (markdown native), Structurizr (C4 spec). 매 LLM 의 generate / update 의 prime use case.

## 매 핵심 tool

### Mermaid
- **Strength**: GitHub / GitLab / Notion native rendering. 매 markdown 의 first-class.
- **Weakness**: 매 layout 의 limited control.
- **Best for**: Quick diagram in PR / docs.

### PlantUML
- **Strength**: 매 다양한 diagram type. 매 mature.
- **Weakness**: Java dependency, 매 syntax steep.
- **Best for**: Complex UML.

### Structurizr
- **Strength**: 매 C4 model 의 first-class. 매 multi-view.
- **Weakness**: 매 specific paradigm.
- **Best for**: Architecture documentation.

### D2 (modern, 2023+)
- **Strength**: 매 cleaner syntax. 매 better defaults.
- **Best for**: Modern alternative to PlantUML.

### Excalidraw + Mermaid
- 매 manual + text.
- 매 hybrid.

### Modern AI integration
- 매 LLM 의 prose → 매 diagram code.
- 매 git diff → 매 diagram update.
- 매 code-as-architecture (dependency-cruiser → Mermaid).

## 매 응용
1. **Architecture doc**: 매 C4 model.
2. **Sequence diagram**: 매 API flow.
3. **State machine**: 매 UI / domain.
4. **ER diagram**: 매 schema.
5. **Org chart**: 매 team structure.
6. **Network**: 매 infra.
7. **Mind map**: 매 brainstorm.

## 💻 패턴

### Mermaid C4 (in markdown)
```mermaid
C4Context
    title System Context — MyApp
    Person(user, "Customer")
    System(myapp, "MyApp", "Banking")
    System_Ext(email, "Email", "SMTP")
    Rel(user, myapp, "Uses", "HTTPS")
    Rel(myapp, email, "Sends", "SMTP")
```

### Mermaid sequence
```mermaid
sequenceDiagram
    participant User
    participant API
    participant Auth
    participant DB
    
    User->>API: POST /login
    API->>Auth: validate(email, password)
    Auth->>DB: SELECT user
    DB-->>Auth: user
    Auth-->>API: JWT token
    API-->>User: 200 + token
```

### Mermaid state diagram
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch
    Loading --> Loaded: success
    Loading --> Error: failure
    Loaded --> Idle: reset
    Error --> Loading: retry
```

### Mermaid ER
```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
    USER {
        string id PK
        string email
    }
    ORDER {
        string id PK
        string user_id FK
        decimal total
    }
```

### PlantUML C4
```plantuml
@startuml
!include <C4/C4_Container>

LAYOUT_LEFT_RIGHT()
title Container Diagram for MyApp

Person(user, "Customer")
System_Boundary(myapp, "MyApp") {
    Container(web, "Web App", "React")
    Container(api, "API", "Node.js")
    ContainerDb(db, "Database", "Postgres")
}

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "REST", "JSON")
Rel(api, db, "SQL")
@enduml
```

### Structurizr DSL
```
workspace "MyApp" {
    model {
        user = person "Customer"
        myApp = softwareSystem "MyApp" {
            web = container "Web" "React"
            api = container "API" "Node.js"
            db = container "DB" "Postgres" "Database"
        }
        user -> web "Uses"
        web -> api "REST"
        api -> db "SQL"
    }
    views {
        systemContext myApp { include * }
        container myApp { include * }
    }
}
```

### D2 (modern syntax)
```
direction: right

user: Customer
myapp: {
  web: Web App {shape: rectangle}
  api: API {shape: rectangle}
  db: Database {shape: cylinder}
  
  web -> api: REST
  api -> db: SQL
}

user -> myapp.web: HTTPS
```

### LLM-generated diagram
```python
def code_to_mermaid(repo_path):
    deps = run_dependency_cruiser(repo_path)
    
    prompt = f"""Convert this dependency graph to Mermaid flowchart.
Group by module. Show only top-level connections.

Dependencies:
{deps}

Output: Mermaid code only."""
    return llm.generate(prompt)
```

### Auto-update from code
```yaml
# .github/workflows/update-diagram.yml
- name: Generate architecture diagram
  run: |
    npx dependency-cruiser src --output-type mermaid > docs/architecture.mmd
    # 매 commit if changed
    git diff --exit-code docs/architecture.mmd || \
      (git add docs/ && git commit -m "chore: update architecture diagram")
```

### IcePanel (modern collaborative)
```js
// 매 IcePanel 의 API + 매 git
import { IcePanelClient } from '@icepanel/sdk';

const client = new IcePanelClient(process.env.ICEPANEL_TOKEN);

// 매 매 commit 의 push diagram update
async function syncDiagram(commit) {
  await client.workspace('myapp').syncFromMermaid('./docs/architecture.mmd');
}
```

### Embed in markdown / Notion
```markdown
# Architecture

\`\`\`mermaid
C4Container
title MyApp Containers
Container(web, "Web", "React")
Container(api, "API", "Node.js")
\`\`\`
```

### Compare visual diagram tools
```ts
const compare = {
  Mermaid: { ease: 'high', power: 'mid', integration: 'native' },
  PlantUML: { ease: 'low', power: 'high', integration: 'plugin' },
  Structurizr: { ease: 'mid', power: 'high (C4)', integration: 'cli + cloud' },
  D2: { ease: 'high', power: 'mid-high', integration: 'cli' },
  Excalidraw: { ease: 'high (visual)', power: 'low (text)', integration: 'web' },
};
```

## 매 결정 기준
| 상황 | Tool |
|---|---|
| Markdown / GitHub | Mermaid |
| Complex UML | PlantUML |
| C4 model | Structurizr |
| Modern alternative | D2 |
| Manual + collab | Excalidraw |
| Code → diagram | dependency-cruiser → Mermaid |
| AI-assisted | LLM + Mermaid output |

**기본값**: Mermaid (markdown native) + Structurizr (architecture).

## 🔗 Graph
- 부모: [[Architecture-Documentation]]
- 변형: [[Mermaid]] · [[PlantUML]] · [[Structurizr]] · [[D2]]
- 응용: [[C4_Model]] · [[ADR]] · [[Codebase_Maps_and_Interactive_Tours]]
- Adjacent: [[Connect-AI-Documentation]] · [[Codebase_Onboarding_Guide]] · [[Software Architecture Styles]]

## 🤖 LLM 활용
**언제**: 매 architecture doc. 매 sequence diagram. 매 onboarding. 매 living doc.
**언제 X**: 매 highly visual / aesthetic (use Figma).

## ❌ 안티패턴
- **GUI drawing 만**: 매 version control 의 lose.
- **Stale diagram**: 매 living doc 의 break.
- **Too detailed (god view)**: 매 single diagram 의 모든 것.
- **Tool monoculture**: 매 매 tool 의 strength 의 다름.
- **No CI sync**: 매 drift.

## 🧪 검증 / 중복
- Verified (Mermaid docs, PlantUML docs, Structurizr by Simon Brown, D2lang).
- 신뢰도 A.
- Related: [[C4_Model]] · [[ADR]] · [[Codebase_Maps_and_Interactive_Tours]] · [[Software Architecture Styles]] · [[Connect-AI-Documentation]].

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — tool comparison + 매 Mermaid / PlantUML / Structurizr / D2 / LLM-gen code |