2nd/10_Wiki/Topics/AI_and_ML/Diagrams_as_Code.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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

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

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch
    Loading --> Loaded: success
    Loading --> Error: failure
    Loaded --> Idle: reset
    Error --> Loading: retry

Mermaid ER

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

@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

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

# .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)

// 매 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

# Architecture

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

Compare visual diagram tools

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