---
id: wiki-2026-0508-c4-model
title: C4 Model (Architecture Documentation)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [C4, C4 model, Simon Brown, system context, container diagram, component diagram, structurizr, architecture diagram]
duplicate_of: none
source_trust_level: A
confidence_score: 0.93
verification_status: applied
tags: [architecture, c4-model, documentation, diagram, structurizr, plantuml, mermaid, system-design]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: documentation
  framework: 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
```plantuml
@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
```mermaid
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)
```python
# 매 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)
```js
// 매 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)
```yaml
# 매 .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 |