---
id: wiki-2026-0508-소프트웨어-아키텍처-다이어그램-software-archit
title: 소프트웨어 아키텍처 다이어그램 (Software Architecture Diagrams)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Architecture Diagrams, C4 Diagrams, Software Architecture Visualization]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, diagrams, c4, mermaid, documentation]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: markdown
  framework: Mermaid/Structurizr/PlantUML
---

# 소프트웨어 아키텍처 다이어그램 (Software Architecture Diagrams)

## 매 한 줄
> **"매 다이어그램은 한 명의 viewer 의 한 가지 질문 에 답한다"**. 매 2026 standard 는 Simon Brown 의 C4 model + diagrams-as-code (Mermaid, Structurizr DSL) 의 결합 — Confluence 에 박힌 dead PNG 의 시대 는 끝났고, repo 안에 versioned source 로 살아 movement 하는 architecture artifact 의 시대.

## 매 핵심

### 매 C4 model (4 abstraction levels)
- **Level 1 — System Context**: System + actors + external systems. 매 비기술 stakeholder 용.
- **Level 2 — Containers**: Deployable/runnable units (web app, API, DB, queue). 매 high-level tech choice 가 보임.
- **Level 3 — Components**: Container 내부의 logical grouping (controller, service, repo). 매 dev 용.
- **Level 4 — Code**: 매 class diagram. 거의 안 그림 — IDE 가 자동 생성.

### 매 diagrams-as-code 의 우위
- Git diff 가능 → review 가능 → versioning 가능.
- CI 에서 render 가능 → docs 와 code 의 drift 방지.
- Plain text → AI assistant (Claude, Copilot) 가 read/write 가능.

### 매 도구 (2026 state)
- **Mermaid**: 매 GitHub/GitLab native render. 매 sequence/flowchart/state 의 sweet spot.
- **Structurizr DSL**: 매 C4 model first-class. 매 single source of truth → multi-view export.
- **PlantUML**: 매 legacy 에서 살아남음. UML 전체 의 cover.
- **D2 / Excalidraw**: 매 modern alternatives — D2 는 declarative, Excalidraw 는 sketch feel.
- **Diagrams.net (drawio)**: 매 GUI 의 마지막 선택지 — 매 export 는 PNG 가 아닌 .drawio (XML) 로.

### 매 응용
1. ADR 첨부 — 결정 의 visual context.
2. Onboarding — new dev 가 30분 안에 system overview 흡수.
3. Incident review — blast radius 의 explanation.
4. Compliance — auditor 용 trust boundary diagram.

## 💻 패턴

### C4 Level 1 (Mermaid)
```mermaid
C4Context
  title System Context — Order Service
  Person(customer, "Customer", "Places orders via web")
  System(order, "Order System", "Handles order lifecycle")
  System_Ext(payment, "Stripe", "Payment processor")
  System_Ext(email, "SendGrid", "Transactional email")
  Rel(customer, order, "Places orders", "HTTPS")
  Rel(order, payment, "Charges card", "REST/JSON")
  Rel(order, email, "Sends receipts", "SMTP API")
```

### C4 Level 2 — Containers
```mermaid
C4Container
  title Containers — Order System
  Person(customer, "Customer")
  System_Boundary(order, "Order System") {
    Container(web, "Web App", "Next.js 15", "Server components + RSC")
    Container(api, "Order API", "Go 1.24", "REST + gRPC")
    Container(worker, "Worker", "Go", "Async job processor")
    ContainerDb(db, "Postgres 17", "Orders, customers")
    ContainerDb(cache, "Redis 8", "Session, rate-limit")
    ContainerQueue(mq, "NATS JetStream", "Event bus")
  }
  Rel(customer, web, "HTTPS")
  Rel(web, api, "gRPC")
  Rel(api, db, "SQL/TLS")
  Rel(api, mq, "Publish events")
  Rel(worker, mq, "Consume events")
  Rel(api, cache, "Read/Write")
```

### Sequence diagram (Mermaid)
```mermaid
sequenceDiagram
  autonumber
  participant C as Client
  participant G as API Gateway
  participant O as Order Service
  participant P as Payment Service
  participant Q as Event Bus

  C->>G: POST /orders
  G->>O: createOrder(payload)
  O->>P: chargeCard(amount)
  P-->>O: paymentId
  O->>Q: publish OrderCreated
  O-->>G: 201 Created
  G-->>C: { orderId }
  Note over Q: Async: shipping, email, analytics
```

### Structurizr DSL (single source of truth)
```dsl
workspace "Order System" {
  model {
    customer = person "Customer"
    orderSystem = softwareSystem "Order System" {
      web = container "Web App" "Next.js 15"
      api = container "Order API" "Go 1.24"
      db = container "Postgres" "RDBMS" "Database"
    }
    customer -> web "Uses"
    web -> api "gRPC"
    api -> db "SQL"
  }
  views {
    systemContext orderSystem { include * autolayout }
    container    orderSystem { include * autolayout }
    theme default
  }
}
```

### Deployment diagram
```mermaid
flowchart TB
  subgraph AWS["AWS us-east-1"]
    subgraph VPC["VPC 10.0.0.0/16"]
      ALB[Application Load Balancer]
      subgraph EKS["EKS Cluster"]
        WEB[web-app pods x3]
        API[order-api pods x6]
      end
      RDS[(RDS Postgres 17 Multi-AZ)]
      EC[(ElastiCache Redis 8)]
    end
  end
  Client[Client Browsers] -->|HTTPS 443| ALB
  ALB --> WEB
  WEB --> API
  API --> RDS
  API --> EC
```

### State machine (order lifecycle)
```mermaid
stateDiagram-v2
  [*] --> Pending
  Pending --> Paid: payment_succeeded
  Pending --> Cancelled: timeout / user_cancel
  Paid --> Shipped: warehouse_dispatch
  Paid --> Refunded: refund_requested
  Shipped --> Delivered: carrier_confirm
  Shipped --> Lost: sla_exceeded
  Delivered --> [*]
  Cancelled --> [*]
  Refunded --> [*]
  Lost --> Refunded
```

### CI render (docs drift 방지)
```yaml
# .github/workflows/diagrams.yml
name: Render diagrams
on: [pull_request]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mermaid-js/mermaid-cli@v11
      - run: |
          for f in docs/diagrams/*.mmd; do
            mmdc -i "$f" -o "${f%.mmd}.svg"
          done
      - run: git diff --exit-code docs/diagrams/
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Stakeholder 1명 + 1 view | Mermaid in markdown |
| Multi-view, single model | Structurizr DSL |
| UML 전 영역 (class/activity) | PlantUML |
| Sketch / brainstorm | Excalidraw |
| Cloud topology (AWS/GCP) | Diagrams.net + provider icons or D2 |

**기본값**: 매 README/ADR 안의 inline Mermaid. 매 system 이 4 view 이상 필요 → Structurizr.

## 🔗 Graph
- 부모: [[Architecture Description (아키텍처 명세)]] · [[ADR (Architecture Decision Record)]]
- 변형: [[C4_Model]] · [[UML]] · [[Mermaid]]
- 응용: [[Onboarding Documentation]] · [[Incident Postmortem]]
- Adjacent: [[Diagrams as Code]] · [[Documentation as Code]]

## 🤖 LLM 활용
**언제**: 매 LLM 에 system spec 을 주고 Mermaid/DSL diagram 의 generate 요청. 매 verbal description → diagram 의 변환 빠름.
**언제 X**: 매 pixel-perfect marketing 그림 — 매 designer 의 작업.

## ❌ 안티패턴
- **PNG-only diagram**: 매 source 없음 → 매 update 불가능 → 매 6개월 후 stale.
- **Everything-in-one diagram**: 매 50개 box + 200개 화살표 → 매 아무도 안 봄.
- **No legend**: 매 화살표 색깔의 의미 의 unknown.
- **Missing trust boundaries**: 매 security review 시 데이터 흐름 의 gap.

## 🧪 검증 / 중복
- Verified (Simon Brown C4 model, c4model.com; Mermaid v11 docs).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — C4 + Mermaid + Structurizr 의 modern stack 정리 |
