Files

T

koriweb d8a80f6272 chore(wiki): dangling 링크 canonical 정규화 (768파일/1200건)

이름만 다른(표기 변형) [[위키링크]]를 대상 문서의 canonical 제목으로 치환해
끊겼던 1,200개 링크를 연결. 제목/파일명 정규화 일치만 적용하고 별칭 매칭은
과병합 위험으로 제외(애매성 가드). 원본은 _link_reconcile_backup/ 에 백업.
도구: Datacollect/scripts/link_reconcile_apply.mjs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-08 12:24:15 +09:00

5.4 KiB

Raw Blame History

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

title

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.

매 응용

New service onboarding doc.
M&A architecture due diligence.
SOC2 / ISO27001 audit evidence.
Pre-rewrite reverse-architecting.
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
변형: arc42 · C4 Model (Architecture Documentation)
응용: ADR · Structurizr · 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

5.4 KiB Raw Blame History