2nd/10_Wiki/Topics/Architecture/Software Architecture Documentation.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-software-architecture-documentat	Software Architecture Documentation	10_Wiki/Topics	verified	self	SAD Architecture Documentation arc42 C4 Model	none	A	0.9	applied	architecture documentation arc42 c4 adr		2026-05-10	pending	language framework markdown structurizr

Software Architecture Documentation

매 한 줄

"매 architecture 의 communicate 가능 form 의 capture — 매 stakeholder 의 different view 의 serve.". 매 arc42 (12-section template), C4 (4-level zoom), 4+1 view (logical/process/dev/physical+scenario), ADR (decision log) 의 4 매 dominant frameworks. 매 2026 modern: Structurizr DSL 의 diagrams-as-code, AsyncAPI 의 event arch documentation.

매 핵심

매 frameworks

• arc42 — 12 sections (introduction → goals → context → solution strategy → blocks → runtime → deployment → concepts → decisions → quality → risks → glossary).
• C4 Model (Brown) — Context / Containers / Components / Code (zoom levels).
• 4+1 View (Kruchten) — Logical, Process, Development, Physical, +Scenarios.
• ADR (Nygard) — decision log per technical choice.

매 audiences

• Executives → context view (C4 L1).
• Developers → containers + components.
• Ops → deployment view + runbook.
• Auditors → cross-cutting concerns + decisions.

매 응용

1. New service onboarding doc.
2. M&A architecture due diligence.
3. SOC2 / ISO27001 audit evidence.
4. Pre-rewrite reverse-architecting.
5. Onboarding new engineer (1-week ramp).

💻 패턴

arc42 skeleton (markdown)

# Architecture Documentation — Service X

## 1. Introduction & Goals
## 2. Constraints
## 3. Context & Scope
## 4. Solution Strategy
## 5. Building Block View
## 6. Runtime View
## 7. Deployment View
## 8. Crosscutting Concepts
## 9. Architecture Decisions (ADRs)
## 10. Quality Requirements
## 11. Risks & Technical Debt
## 12. Glossary

C4 with Structurizr DSL

workspace "Skybound" {
  model {
    user = person "Customer"
    api = softwareSystem "API" {
      web = container "Web App" "React"
      svc = container "Backend" "Node.js"
      db = container "Database" "Postgres"
    }
    user -> web "uses"
    web -> svc "JSON/HTTPS"
    svc -> db "SQL"
  }
  views {
    systemContext api { include * autolayout }
    container api { include * autolayout }
  }
}

ADR template (MADR)

# ADR-0042: Use Postgres as Primary Store

## Status
Accepted (2026-05-10)

## Context
Need transactional store with strong consistency, JSON support.

## Decision
Use Postgres 16 with logical replication for read-replicas.

## Consequences
+ ACID, mature ecosystem, JSONB
- Vertical scaling ceiling — sharding plan needed by 2027

## Alternatives
- DynamoDB: rejected (relational queries)
- Mongo: rejected (consistency tradeoffs)

Diagrams-as-code (Mermaid)

```mermaid
C4Container
  title Container Diagram for Skybound
  Person(user, "User")
  System_Boundary(api, "Skybound") {
    Container(web, "Web App", "React")
    Container(svc, "Backend", "Node.js")
    ContainerDb(db, "Database", "Postgres")
  }
  Rel(user, web, "uses")
  Rel(web, svc, "JSON/HTTPS")
  Rel(svc, db, "SQL")

### AsyncAPI (event arch)
```yaml
asyncapi: 3.0.0
info: { title: Orders, version: 1.0.0 }
channels:
  orderPlaced:
    address: orders.placed
    messages:
      OrderPlaced:
        payload:
          type: object
          properties:
            id: { type: string }
            amount: { type: number }

Quality attribute scenarios

## Performance Scenario
- Source: 10k concurrent users
- Stimulus: checkout submit
- Environment: peak load
- Response: order created, confirmation email queued
- Measure: p99 < 800ms, error rate < 0.1%

Documentation in repo (docs-as-code)

/docs
  /architecture
    arc42.md
    /adr
      0001-postgres.md
      0002-event-bus.md
    /diagrams
      workspace.dsl

매 결정 기준

상황	Approach
Quick visual onboarding	C4 Context + Container
Comprehensive system doc	arc42 full template
Per-decision rationale	ADR (MADR)
Event-driven system	AsyncAPI + arc42 ch.6
Audit evidence	arc42 ch.8 + ADRs

기본값: arc42 + C4 (L1-L2) + ADR repo + Structurizr DSL + docs-as-code in monorepo.

🔗 Graph

• 부모: Software-Architecture · Documentation
• 변형: arc42 · C4-Model · 4+1-View
• 응용: ADR · Structurizr · AsyncAPI · Mermaid-Diagrams
• Adjacent: Architecture Decision Record · Software-Architecture-Erosion

🤖 LLM 활용

언제: doc gap analysis, ADR drafting, view-completeness review. 언제 X: 매 architecture 의 yet 결정 X — 매 decision-making 의 first.

❌ 안티패턴

• Stale Visio: 매 PDF/image 의 versioned X — diagrams-as-code 사용.
• Doc-only, no view: 매 1 PDF 의 dump — view-per-audience 분리.
• No ADR: 매 6개월 후 매 "왜 X 선택?" 답 X.

🧪 검증 / 중복

• Verified (arc42.org, C4model.com, Brown "Software Architecture for Developers", Nygard ADR).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — arc42, C4, ADR, AsyncAPI, docs-as-code patterns