118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
---
|
|
id: wiki-2026-0508-architecture-diagramming-standar
|
|
title: Architecture Diagramming Standards
|
|
category: 10_Wiki/Topics
|
|
status: verified
|
|
canonical_id: self
|
|
aliases: [P-REINFORCE-WIKI-ARCH-DIAGRAMS, 아키텍처 다이어그램, Architecture Diagram, 시스템 청사진]
|
|
duplicate_of: none
|
|
source_trust_level: A
|
|
confidence_score: 1.0
|
|
tags: [Architecture, Visualization, C4_Model, Documentation, Communication]
|
|
raw_sources: [Datacollector_Export_2026-05-02]
|
|
last_reinforced: 2026-05-02
|
|
github_commit: pending
|
|
tech_stack:
|
|
language: unspecified
|
|
framework: unspecified
|
|
---
|
|
|
|
# [[아키텍처 다이어그램 작성 표준 (Architecture Diagramming Standards)]]
|
|
|
|
## 1. 개요
|
|
아키텍처 다이어그램은 소프트웨어 시스템의 구조, 컴포넌트 간의 관계, 통신 채널을 시각적으로 표현한 청사진이다. 복잡한 시스템을 추상화하여 이해관계자 간의 정렬을 돕고, 설계 의도를 명확히 전달하며, 유지보수 및 온보딩의 가이드라인 역할을 수행한다.
|
|
|
|
## 2. 주요 다이어그램 유형 및 용도
|
|
- **시스템 컨텍스트 다이어그램**: 시스템과 외부 액터(사용자, 외부 시스템) 간의 경계 정의.
|
|
- **컨테이너 다이어그램**: 배포 가능한 기술 단위(웹 앱, DB 등)와 주요 통신 프로토콜 명시.
|
|
- **컴포넌트 다이어그램**: 특정 컨테이너 내부의 논리적 모듈 구조와 의존성 표현.
|
|
- **배포 다이어그램**: 소프트웨어가 실제 물리적/논리적 인프라에 매핑되는 방식 시각화.
|
|
- **시퀀스 다이어그램**: 특정 유즈케이스 시나리오에 따른 객체/서비스 간의 시간적 상호작용 흐름 표현.
|
|
|
|
## 3. 작성 모범 사례 (Best Practices)
|
|
- **독자 중심 설계**: 독자의 지식 수준(경영진 vs 엔지니어)에 맞춰 추상화 깊이 조절. (C4 모델 활용 권장)
|
|
- **일관된 표기법 및 범례**: 모양, 색상, 선 스타일의 의미를 통일하고 반드시 범례(Legend) 포함.
|
|
- **명확한 라벨링**: 컴포넌트 이름뿐만 아니라 기술 스택, 통신 프로토콜(HTTP, gRPC 등)을 명확히 기재.
|
|
- **Diagrams as Code**: 이미지 파일 대신 PlantUML, Mermaid 등을 사용하여 코드와 함께 버전 관리.
|
|
|
|
## 4. 트레이드오프 및 주의사항
|
|
- **아키텍처 드리프트 (Architectural Drift)**: 코드가 변경됨에 따라 다이어그램이 구식이 되지 않도록 자동화 또는 정기적 업데이트 필요.
|
|
- **과도한 복잡성 방지**: 하나의 다이어그램에 모든 정보를 담으려 하지 말고, 단일 목적성에 집중하여 분리 작성.
|
|
- **기술 숭배 지양**: 논리적 구조보다 특정 라이브러리 명칭 기재에 집착하면 시스템의 개념적 이해를 방해함.
|
|
|
|
## 5. 지식 연결 (Related)
|
|
- [[C4_Modeling_Framework]]: 다이어그램의 추상화 수준을 관리하는 실용적 프레임워크.
|
|
- [[UML_Unified_Modeling_Language]]: 정밀한 기술 명세를 위한 표준 모델링 언어.
|
|
- [[Architectural_Drift_Prevention]]: 다이어그램과 실제 코드 간의 불일치를 관리하는 전략.
|
|
|
|
## 🧪 검증 상태 (Validation)
|
|
- **정보 상태**: 검증 완료 (Verified)
|
|
- **출처 신뢰도**: A
|
|
- **검토 이유**: 시스템 설계의 투명성을 확보하고 기술적 의사소통의 효율성을 높이기 위한 시각화 표준 확립.
|
|
|
|
## 📌 한 줄 통찰 (The Karpathy Summary)
|
|
|
|
> *(TODO: 한 문장으로 핵심 통찰을 작성. "X는 Y 조건에서 Z 효과를 낸다" 구조 권장.)*
|
|
|
|
## 📖 구조화된 지식 (Synthesized Content)
|
|
|
|
**추출된 패턴:**
|
|
> *(TODO)*
|
|
|
|
**세부 내용:**
|
|
- *(TODO)*
|
|
|
|
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
|
|
|
**언제 이 지식을 쓰는가:**
|
|
- *(TODO)*
|
|
|
|
**언제 쓰면 안 되는가:**
|
|
- *(TODO)*
|
|
|
|
## 🧬 중복 검사 (Duplicate Check)
|
|
|
|
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
|
- **처리 방식:** UPDATE (자동 정규화)
|
|
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
|
|
|
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
|
|
|
- **과거 데이터와의 충돌:** 없음
|
|
- **정책 변화:** 없음
|
|
|
|
## 🔗 지식 연결 (Graph)
|
|
|
|
- **Parent:** [[10_Wiki/Topics]]
|
|
- **Related:** *(TODO: 최소 2개)*
|
|
- **Opposite / Trade-off:** *(TODO)*
|
|
- **Raw Source:** 직접 입력
|
|
|
|
## 🕓 변경 이력 (Changelog)
|
|
|
|
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
|
|------|-----------|-----------|--------|
|
|
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
|
|
|
## 💻 코드 패턴 (Code Patterns)
|
|
|
|
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
|
|
|
```text
|
|
# TODO
|
|
```
|
|
|
|
## 🤔 의사결정 기준 (Decision Criteria)
|
|
|
|
**선택 A를 써야 할 때:**
|
|
- *(TODO)*
|
|
|
|
**선택 B를 써야 할 때:**
|
|
- *(TODO)*
|
|
|
|
**기본값:**
|
|
> *(TODO)*
|
|
|
|
## ❌ 안티패턴 (Anti-Patterns)
|
|
|
|
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)* |