2nd/10_Wiki/Topics/AI_and_ML/C4_Model.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-c4-model	C4 Model (Architecture Documentation)	10_Wiki/Topics	verified	self	C4 C4 model Simon Brown system context container diagram component diagram structurizr architecture diagram	none	A	0.93	applied	architecture c4-model documentation diagram structurizr plantuml mermaid system-design		2026-05-10	pending	language framework documentation Structurizr / PlantUML / Mermaid / IcePanel

C4 Model

📌 한 줄 통찰

"매 architecture 의 zoom-in". 매 4 level (Context → Container → Component → Code) 의 progressive detail. 매 Simon Brown 의 simple + 매 effective. 매 UML 의 heavy 의 escape. 매 just-enough 의 documentation.

📖 핵심

매 4 level

1. Context (System Context)

• 매 highest level.
• 매 user (actor) + 매 external system + 매 our system (single box).
• 매 audience: 매 모두 (technical + business).
• 매 question: "매 무엇 의 build?"

2. Container

• 매 deployable unit (app, database, queue).
• 매 technology choice (SPA, mobile, REST, Postgres).
• 매 audience: 매 technical.
• 매 question: "매 high-level shape."

3. Component

• 매 container 내부 의 major component.
• 매 module / library boundary.
• 매 audience: 매 developer.
• 매 question: "매 container 의 internal."

4. Code (optional)

• 매 class / interface diagram.
• 매 IDE 의 generate 가능.
• 매 보통 매 outdated 의 fast → 매 skip OK.

매 supplementary diagram

Dynamic

• 매 sequence (interaction over time).

Deployment

• 매 infra mapping (which container 매 어디).

Landscape

• 매 multi-system overview (큰 organization).

매 design principles

• C4 의 lighweight: 매 just enough.
• Notation-independent: 매 box + arrow + label.
• Hierarchical zoom: 매 each level 의 detail.
• Audience-aware: 매 level 별 의 audience.
• Tooling-friendly: text → diagram (Structurizr).

매 vs UML / 4+1

• UML: 매 heavy, 매 fall out of fashion.
• 4+1 view (Kruchten): 매 logical / process / development / physical / scenario — 매 too many.
• C4: 매 simpler, 매 hierarchical.
• arc42: 매 template — 매 C4 와 의 complementary.

매 modern tool

• Structurizr (Simon Brown): 매 official, 매 DSL.
• IcePanel: 매 modern collaborative.
• PlantUML C4: 매 text → diagram.
• Mermaid C4: 매 markdown.
• Diagrams.net / Excalidraw: 매 manual.
• Likely (AI-assist): 매 automated.

매 application

1. New project kickoff: 매 shared understanding.
2. Onboarding: 매 new dev.
3. Architecture review: 매 stakeholder.
4. Compliance: 매 audit doc.
5. Refactoring planning: 매 target state.
6. Incident: 매 blast radius.

매 ADR 와 의 관계

• ADR: 매 decision (why).
• C4: 매 structure (what).
• 매 둘 다 의 living doc.

💻 패턴

Structurizr DSL

workspace "MyApp" "Description" {
    
    model {
        user = person "Customer" "User of the system"
        myApp = softwareSystem "MyApp" "Internal banking system" {
            web = container "Web App" "User interface" "React" "Web Browser"
            api = container "API" "Business logic" "Node.js"
            db = container "Database" "Stores users" "PostgreSQL" "Database"
        }
        emailSystem = softwareSystem "Email" "External SMTP" "External"
        
        user -> web "Uses" "HTTPS"
        web -> api "Calls" "JSON/HTTPS"
        api -> db "Reads/writes" "SQL"
        api -> emailSystem "Sends emails" "SMTP"
    }
    
    views {
        systemContext myApp "Context" {
            include *
            autolayout lr
        }
        container myApp "Containers" {
            include *
            autolayout tb
        }
        component api "ApiComponents" {
            // 매 API container 의 internal
        }
        styles {
            element "Database" { shape Cylinder }
            element "External" { background #999 }
        }
    }
}

PlantUML C4

@startuml
!include <C4/C4_Container>

LAYOUT_LEFT_RIGHT()
title Container Diagram for MyApp

Person(user, "Customer", "Banking customer")
System_Boundary(myapp, "MyApp") {
    Container(web, "Web App", "React", "User UI")
    Container(api, "API", "Node.js", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Stores users")
}
System_Ext(email, "Email System", "External SMTP")

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads/writes", "SQL")
Rel(api, email, "Sends emails", "SMTP")

@enduml

Mermaid C4

C4Context
    title System Context for MyApp
    Person(user, "Customer")
    System(myapp, "MyApp", "Internal banking")
    System_Ext(email, "Email", "SMTP")
    Rel(user, myapp, "Uses")
    Rel(myapp, email, "Sends")

Generate from code (architecture as code)

# 매 dependency-cruiser 의 결과 의 C4 의 자동 generate
import json

def generate_c4_components(deps_json):
    container_name = 'API'
    components = set()
    edges = []
    
    for module in deps_json['modules']:
        component = module['source'].split('/')[1]  # 매 src/auth/x.ts → auth
        components.add(component)
        for dep in module['dependencies']:
            target = dep['resolved'].split('/')[1] if '/' in dep['resolved'] else 'external'
            if target != component:
                edges.append((component, target))
    
    # 매 Structurizr DSL output
    print(f'container "{container_name}" {{')
    for c in components:
        print(f'  component "{c}"')
    for src, tgt in set(edges):
        print(f'  {src} -> {tgt}')
    print('}')

IcePanel API (collaborative)

// 매 IcePanel 의 API 의 model 의 sync
const icepanel = new IcePanelClient(token);

await icepanel.upsertContainer({
    landscape: 'main',
    name: 'API',
    technology: 'Node.js + TypeScript',
    description: 'Business logic',
});

CI integration (architecture drift detection)

# 매 .github/workflows/arch.yml
- name: Validate architecture
  run: |
    structurizr-cli validate -workspace workspace.dsl
    
- name: Compare with code
  run: |
    npx dependency-cruiser src --output-type json > current-deps.json
    python scripts/compare_with_c4.py current-deps.json workspace.dsl
    # 매 diverge 시 의 fail

🤔 결정 기준

상황	Tool
Solo / small	Mermaid (markdown)
Team / collaborative	IcePanel / Structurizr
Code-driven	PlantUML + git
Living doc	Structurizr DSL + CI
Single deliverable	Excalidraw
AI-assisted	Likely + ChatGPT

기본값: Structurizr DSL 의 spec 기반. 매 markdown 의 Mermaid 의 light.

🔗 Graph

• 부모: Architecture-Documentation · System-Design
• 변형: Living-Documentation
• 응용: Structurizr · PlantUML · Mermaid · IcePanel
• Adjacent: ADR · arc42 · Software Architecture Styles · Bounded Contexts (DDD) · Domain-Driven-Design

🤖 LLM 활용

언제: 매 architecture documentation. 매 onboarding. 매 review. 매 refactor planning. 언제 X: 매 throwaway prototype. 매 single-class explanation.

❌ 안티패턴

• 너무 많은 detail: 매 single diagram 의 god view.
• No legend: 매 ambiguous arrow.
• Code level 의 always include: 매 outdated.
• Stale diagram: 매 living doc X.
• No audience differentiation: 매 single doc 의 모두 의 fail.
• UML 의 heavy 의 mistake: 매 C4 의 simplicity 의 lose.
• No tool / pure manual: 매 sync drift.

🧪 검증 / 중복

• Verified (Simon Brown's c4model.com, Structurizr docs).
• 신뢰도 A.
• Related: Software Architecture Styles · ADR · Bounded Contexts (DDD) · Architecture-as-Code.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — 4 level + tool + 매 Structurizr / PlantUML / Mermaid code