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

---
id: wiki-2026-0508-structurizr
title: Structurizr
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Structurizr DSL, C4 Tooling]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, c4-model, diagrams-as-code, documentation]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: dsl
  framework: structurizr
---

# Structurizr

## 매 한 줄
> **"매 architecture-as-code 의 reference impl"**. Simon Brown 의 C4 model 을 textual DSL 로 표현 → 다양한 view (Context, Container, Component, Code) 의 자동 generation. 2026 의 AI-aided (Claude, Cursor) 의 architectural diagram 생성 의 default tooling 중 하나.

## 매 핵심

### 매 C4 model recap
- **Level 1 — Context**: System 의 user, external system 과 의 관계.
- **Level 2 — Container**: Application, datastore, microservice 의 deployment unit.
- **Level 3 — Component**: Container 내부 의 logical group.
- **Level 4 — Code**: 매 class diagram (rarely needed).

### 매 Structurizr 형태
- **Structurizr DSL**: text-based, 매 single source of truth.
- **Structurizr CLI**: DSL → JSON workspace, export to PlantUML, Mermaid, D2.
- **Structurizr Lite**: 매 self-hosted preview (Docker).
- **Structurizr Cloud**: 매 hosted SaaS.

### 매 응용
1. Onboarding documentation (engineer hire 의 first-day reading).
2. ADR companion (decision record 의 visual context).
3. AI-aided refactoring planning (Claude 가 DSL 생성).
4. Compliance / audit (SOC2, ISO27001 의 system diagram).

## 💻 패턴

### Basic workspace (DSL)
```dsl
workspace "PaymentSystem" {
  model {
    user = person "Customer"
    paymentSystem = softwareSystem "Payment System" {
      webApp = container "Web App" "Next.js" "TypeScript"
      api = container "API" "Hono on Bun" "TypeScript"
      db = container "Database" "PostgreSQL" "Database"
    }
    stripe = softwareSystem "Stripe" "External payment provider" "External"

    user -> webApp "Uses"
    webApp -> api "Calls" "HTTPS/JSON"
    api -> db "Reads/Writes" "SQL"
    api -> stripe "Charges" "HTTPS"
  }
  views {
    systemContext paymentSystem { include * autolayout lr }
    container paymentSystem { include * autolayout lr }
    theme default
  }
}
```

### Component view (Level 3)
```dsl
component api {
  authController = component "AuthController" "JWT validation"
  paymentService = component "PaymentService" "Charge orchestration"
  stripeClient = component "StripeClient" "Stripe SDK wrapper"

  authController -> paymentService "Delegates"
  paymentService -> stripeClient "Uses"
}
```

### Export to other formats
```bash
docker run --rm -v $PWD:/usr/local/structurizr structurizr/cli \
  export -workspace workspace.dsl -format plantuml
docker run --rm -v $PWD:/usr/local/structurizr structurizr/cli \
  export -workspace workspace.dsl -format mermaid
```

### Structurizr Lite (local preview)
```bash
docker run -it --rm -p 8080:8080 \
  -v $PWD:/usr/local/structurizr \
  structurizr/lite
# open http://localhost:8080
```

### AI-aided generation (Claude prompt)
```
Given this codebase tree and key file imports, generate a Structurizr DSL
workspace covering Context + Container views. Use:
- person for end users
- softwareSystem for our system
- container for each deployable unit (web, api, worker, db, queue)
- explicit relationships with technology labels
Return only the DSL block.
```

### Deployment view
```dsl
deploymentEnvironment "Production" {
  deploymentNode "AWS us-east-1" {
    deploymentNode "ECS Cluster" {
      containerInstance api
    }
    deploymentNode "RDS" {
      containerInstance db
    }
  }
}
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 single-source-of-truth diagram | Structurizr DSL |
| 매 quick sketch | Mermaid / D2 직접 |
| 매 enterprise architecture | Structurizr Cloud + ADR |
| 매 OSS / public | Structurizr Lite + GitHub |
| 매 ad-hoc one-off | Excalidraw |

**기본값**: 매 production system documentation → Structurizr DSL + Lite.

## 🔗 Graph
- 부모: [[Software-Architecture]]
- 변형: [[Mermaid]] · [[PlantUML]] · [[D2]]
- 응용: [[C4 Model (Architecture Documentation)]] · [[ADR]] · [[Onboarding]]
- Adjacent: [[Diagrams as Code]] · [[Architecture-Decision-Record]]

## 🤖 LLM 활용
**언제**: 매 codebase walk-through 후 architecture diagram 생성 (Claude 가 DSL 작성), 매 refactor plan 의 before/after view, 매 ADR 의 visual context.
**언제 X**: 매 throwaway sketch (overkill), 매 UI component design (use Figma), 매 sequence diagram primary (use Mermaid sequenceDiagram).

## ❌ 안티패턴
- **Level 4 (Code) 의 maintain**: IDE 가 더 잘함. C4 의 Code level 은 rarely worthwhile.
- **DSL 의 stale**: 매 code 와 sync 안 됨 → AI 가 quarterly regenerate.
- **Container 의 too granular**: 매 microservice 50+ 의 single view → split per bounded context.

## 🧪 검증 / 중복
- Verified (Simon Brown C4 model, structurizr.com docs, GitHub structurizr/dsl).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — DSL + CLI + Lite + AI-aided coverage |