koriweb
d8a80f6272
이름만 다른(표기 변형) [[위키링크]]를 대상 문서의 canonical 제목으로 치환해 끊겼던 1,200개 링크를 연결. 제목/파일명 정규화 일치만 적용하고 별칭 매칭은 과병합 위험으로 제외(애매성 가드). 원본은 _link_reconcile_backup/ 에 백업. 도구: Datacollect/scripts/link_reconcile_apply.mjs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
198 lines
6.9 KiB
Markdown
198 lines
6.9 KiB
Markdown
---
|
|
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 |
|