2nd/10_Wiki/Topics/AI_and_ML/Structurizr.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-structurizr	Structurizr	10_Wiki/Topics	verified	self	Structurizr DSL C4 Tooling	none	A	0.9	applied	architecture c4-model diagrams-as-code documentation		2026-05-10	pending	language framework dsl 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)

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)

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

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)

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

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 · 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