96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# Diagram Elements — Budget + Component / Edge Labels + Visual Hierarchy
|
|
|
|
Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §3~§6
|
|
parent: [`README.md`](README.md)
|
|
|
|
## §3. Element Budget — 요소 수 상한 (HARD LIMITS)
|
|
|
|
| 요소 | 권장 | 상한 | 초과 시 |
|
|
|---|---|---|---|
|
|
| **Vertex (박스)** | 5~7개 | **10개** | 분할 또는 비핵심 제거 |
|
|
| **Edge (화살표)** | 4~6개 | **8개** | 시퀀스 다이어그램으로 분리 |
|
|
| **Callout (주석 박스)** | 0~1개 | **1개** | 본문 텍스트로 옮김 |
|
|
| **Boundary group** | 1~2개 | **3개** | 중첩 단계 축소 |
|
|
| **Legend 항목** | 3~4개 | **6개** | 표준 컨벤션 사용 (legend 생략) |
|
|
| **색상** | 2~3 가지 (회색/흑백 + 강조 1) | **4 가지** | 색 분류 축소 |
|
|
|
|
상한을 초과하면 다이어그램이 잘못된 단위에 있다. 분할 또는 추상화 레벨 올리기.
|
|
|
|
## §4. Component Label — 박스 안 텍스트 ≤ 2줄
|
|
|
|
```
|
|
┌─────────────────────────┐
|
|
│ <Name> │ ← 1줄: 시스템 이름 (Bold)
|
|
│ <Context 1줄> │ ← 1줄: 역할 OR 기술. 둘 중 핵심만.
|
|
└─────────────────────────┘
|
|
```
|
|
|
|
### 예시
|
|
|
|
| Bad (v2 이전 스타일) | Good |
|
|
|---|---|
|
|
| `Spring Boot Resource Server`<br/>`Role: JWT 검증 + 비즈니스 API`<br/>`Stack: Spring Boot 3.4 / Java 21`<br/>`+ Spring Security 6.x`<br/>`Endpoint: localhost:8080`<br/>`Capacity: 1 instance`<br/>`Owner: 본인` (7줄) | `**Spring Boot RS**`<br/>`Spring Boot 3.4 · :8080` (2줄) |
|
|
|
|
### 다이어그램에 안 들어가는 정보는 본문에
|
|
|
|
- 컴포넌트 상세 (역할, 책임, owner, capacity) → project-note 의 §"컴포넌트 책임 분담" 표
|
|
- 의존성 매트릭스 → 별도 §"외부 의존성" 표
|
|
- 운영 SLO → 별도 §"비기능 요구사항"
|
|
|
|
## §5. Edge Label — 화살표 라벨 ≤ 5단어
|
|
|
|
```
|
|
<step?> <verb/protocol> <object>
|
|
```
|
|
|
|
### 예시
|
|
|
|
| Bad (v2 이전 스타일) | Good |
|
|
|---|---|
|
|
| `① HTTPS GET / (HTML/JS)`<br/>` payload: ~50KB (initial SPA bundle)`<br/>` p99: ~80ms (cold) / ~10ms (cache)` (3줄) | `① GET /` (1줄) |
|
|
| `⑥ proxy_pass http://localhost:8080`<br/>` Authorization header forward`<br/>` (timeout: 30s, keepalive: 60s)` | `proxy_pass :8080` |
|
|
|
|
### 스케일 어노테이션 (QPS, latency, payload size) — 다이어그램의 질문이 *그것* 일 때만
|
|
|
|
- 일반 아키텍처 다이어그램: 화살표는 prototype + endpoint 만
|
|
- 성능 다이어그램: QPS / latency 가 핵심 → 그 때만 라벨에
|
|
|
|
번호 (①②③) 는 **순서가 중요할 때만**. 정적 토폴로지 다이어그램은 번호 불필요.
|
|
|
|
## §6. Visual Hierarchy Through Restraint — 색은 강조용
|
|
|
|
### 색 사용 비율
|
|
|
|
- **80% 회색/흑백** — 본문 박스의 기본 fill / stroke
|
|
- **15% 강조색 1개** — 다이어그램의 critical path 또는 primary system
|
|
- **5% 위험 / 경고색 (빨강)** — error path, SPoF, 보안 위협 — 있을 때만
|
|
|
|
### 표준 팔레트 (Minimal)
|
|
|
|
| 용도 | Fill | Stroke | 비고 |
|
|
|---|---|---|---|
|
|
| 일반 컴포넌트 (기본) | `#FFFFFF` | `#57606A` (회색) | 80% 의 박스가 여기 |
|
|
| **Critical path / 주인공** | `#FFFFFF` 또는 옅은 강조색 | **굵은 강조색** (`#1F6FEB` 파랑 또는 `#FB923C` 주황) | 다이어그램에서 가장 중요한 1~2개 박스만 |
|
|
| Data store (DB) | `#FFFFFF` | `#57606A` + cylinder shape | 모양으로 구분 |
|
|
| **External (점선)** | `#F6F8FA` | `#D0D7DE` (회색 점선) | 외부 시스템·3rd party |
|
|
| **Warning / Error path** | `#FEF2F2` (옅은 빨강) | `#DC2626` (빨강) | 있을 때만, 1~2 요소 한정 |
|
|
|
|
**금지**: 모든 박스에 색 칠하기. 색이 의미를 잃음 (color salad).
|
|
|
|
### Stroke 굵기
|
|
|
|
- 일반: 1~1.5px
|
|
- Critical path / Primary: 2~3px (강조용)
|
|
- Boundary: 1.5~2px
|
|
|
|
### 화살표 종류
|
|
|
|
| 종류 | 의미 |
|
|
|---|---|
|
|
| 실선 + 화살촉 | 동기 호출 (HTTP, RPC, JDBC) |
|
|
| 점선 + 화살촉 | 비동기 / fire-and-forget (Kafka publish, async event) |
|
|
| 굵은 실선 (2~3px, 강조색) | Critical path / hot path |
|
|
| 빨간 점선 | Error path |
|
|
|
|
화살표 종류는 **다이어그램 내 일관성** 이 핵심. 4종류 이상 섞지 말 것.
|