---
id: wiki-2026-0508-architecture-description-아키텍처-명세
title: Architecture Description (아키텍처 명세)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Architecture Description, 아키텍처 명세, AD, Software Architecture Document, SAD]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [architecture, documentation, c4, 4plus1-view, iso-42010]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: markdown
  framework: Structurizr / C4 / arc42
---

# Architecture Description (아키텍처 명세)

## 매 한 줄
> **"매 architecture description 은 system 의 multiple stakeholder concern 을 multiple view 로 documenting"**. ISO/IEC/IEEE 42010 standard 기반 — 매 stakeholder, concern, viewpoint, view, model 의 conceptual chain. 매 modern practice 는 4+1 (Kruchten) → C4 (Brown) → arc42 (Starke) → DAR (Decision Records) 의 layered combination.

## 매 핵심

### 매 ISO/IEC/IEEE 42010 framework
- **Stakeholder**: dev, ops, security, PM, customer — 매 다른 concern.
- **Concern**: performance, security, deployability, cost, regulatory.
- **Viewpoint**: concern 의 lens (e.g., "security viewpoint", "deployment viewpoint").
- **View**: viewpoint 적용 결과의 specific artifact.
- **Model**: view 안의 box-and-line / sequence / state diagram.

### 매 4+1 view (Kruchten 1995, still relevant)
- **Logical view**: domain model, class, package — dev concern.
- **Process view**: runtime behavior, threading, concurrency — perf concern.
- **Development view**: module, layer, build — dev productivity.
- **Physical view**: deployment topology — ops concern.
- **+1 Scenario**: use cases tying 4 views together.

### 매 C4 model (Simon Brown, modern default)
1. **Context (L1)**: system + external actor/system — non-technical stakeholder 용.
2. **Container (L2)**: deployable unit (web app, API, DB) — tech overview.
3. **Component (L3)**: container 내부 module — dev 용.
4. **Code (L4, optional)**: class diagram — auto-gen, rarely manual.

## 💻 패턴

### Structurizr DSL (modern C4 standard, 2026)
```dsl
workspace "BankingApp" {
    model {
        customer = person "Customer" "A bank customer"
        bankingSystem = softwareSystem "Internet Banking" {
            webApp = container "Web App" "React SPA" "TypeScript/React"
            api = container "API" "REST backend" "Kotlin/Spring"
            db = container "Database" "Customer + tx data" "PostgreSQL 16"
            webApp -> api "Calls" "HTTPS/JSON"
            api -> db "Reads/writes" "JDBC"
        }
        customer -> webApp "Uses" "HTTPS"
    }
    views {
        systemContext bankingSystem { include * autoLayout }
        container bankingSystem { include * autoLayout }
        theme default
    }
}
```

### arc42 template skeleton (Markdown, 12 sections)
```markdown
# 1. Introduction & Goals
## 1.1 Requirements Overview
## 1.2 Quality Goals (top 3-5)
## 1.3 Stakeholders

# 2. Architecture Constraints
# 3. Context & Scope (C4 L1 here)
# 4. Solution Strategy
# 5. Building Block View (C4 L2/L3)
# 6. Runtime View (sequence / activity)
# 7. Deployment View
# 8. Crosscutting Concepts (security, logging, i18n)
# 9. Architecture Decisions (link to ADRs)
# 10. Quality Requirements (scenarios)
# 11. Risks & Technical Debt
# 12. Glossary
```

### ADR (Architecture Decision Record, Michael Nygard format)
```markdown
# ADR-0042: Use PostgreSQL over MongoDB for tx store

## Status
Accepted (2026-04-15) — supersedes ADR-0021.

## Context
Transactional integrity 의 critical. Document flexibility 의 secondary.
PostgreSQL 16 의 JSONB columns 의 hybrid 의 enable.

## Decision
PostgreSQL 16 with JSONB for flexible attributes.

## Consequences
+ ACID guarantees, mature tooling, strong ecosystem.
- Schema migrations more rigid than Mongo.
- Team needs PG expertise (training budget allocated).
```

### Mermaid C4 diagram (lightweight, GitHub-native)
```mermaid
C4Context
  title System Context — Banking
  Person(customer, "Customer")
  System(banking, "Banking System", "Online banking")
  System_Ext(email, "Email System", "SMTP")
  Rel(customer, banking, "Uses", "HTTPS")
  Rel(banking, email, "Sends notifications", "SMTP")
```

### Architecture-as-code: PlantUML C4 macro
```plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(c1, "App") {
  Container(spa, "SPA", "React 19")
  Container(api, "API", "Kotlin/Ktor")
  ContainerDb(db, "DB", "PostgreSQL 16")
}
Rel(user, spa, "Uses", "HTTPS")
Rel(spa, api, "JSON/REST")
Rel(api, db, "JDBC")
@enduml
```

### Quality scenario (ATAM-style, embeddable in AD)
```yaml
scenario: "API survives 10x traffic spike"
source: External users
stimulus: Sudden 10x request burst
artifact: API container
environment: Production, normal ops
response: Auto-scale, no errors >0.1%
response_measure:
  - p99 latency < 800ms
  - error_rate < 0.1%
  - autoscale_lag < 60s
```

### Living docs — auto-extract from code (jQAssistant + Structurizr)
```bash
# Generate Structurizr workspace from code annotations
./gradlew structurizrExport
structurizr-cli push -workspace workspace.dsl \
  -id $WORKSPACE_ID -key $API_KEY -secret $API_SECRET
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Greenfield, small-mid team | C4 + arc42 + ADR |
| Enterprise, regulatory | ISO 42010 strict + 4+1 |
| OSS project | Mermaid C4 in README |
| Microservices, many teams | Structurizr DSL + ADR per service |
| Legacy reverse-engineered | Auto-gen (jQAssistant) + manual context |

**기본값**: C4 (Structurizr DSL) + arc42 sections + ADR — 매 modern combination.

## 🔗 Graph
- 부모: [[Software Architecture]]
- 변형: [[C4 Model (Architecture Documentation)]] · [[arc42]]
- 응용: [[Architecture_Diagramming_Standards]] · [[Architecture Review (아키텍처 및 설계 리뷰)]]

## 🤖 LLM 활용
**언제**: bootstrap arc42 template from a codebase scan, generate C4 Container diagrams from package structure, draft ADR Context/Consequences from PR descriptions.
**언제 X**: do not let an LLM author quality scenarios without measurable response criteria — vague AI-generated "should be fast" fails ATAM review.

## ❌ 안티패턴
- **Diagram-only AD**: pictures without prose context — stakeholder cannot infer intent.
- **One-view-fits-all**: single deployment diagram trying to satisfy security, perf, dev concerns simultaneously.
- **Stale Visio**: AD frozen on day 1, drifts from implementation within 6 months.
- **Pseudo-UML**: ad-hoc boxes labeled "UML" with no notation discipline.
- **Decision-less AD**: structures documented without WHY — readers cannot evaluate tradeoffs.

## 🧪 검증 / 중복
- Verified (ISO/IEC/IEEE 42010:2022, Kruchten 1995, Brown C4 spec, Starke arc42 v8.2).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — full AD spec with C4/4+1/arc42/ADR patterns |