# Diagram Structure — Boundary / Callout / Legend / Header-Footer / Source

Root SSOT: [`rules/diagram-standards.md`](../../../../../rules/diagram-standards.md) §7~§11
parent: [`README.md`](README.md)

## §7. Boundary — 정보 있을 때만 사용

Boundary 는 **시각 장식이 아님.** 다음 중 하나일 때만 사용:

- **Trust Boundary**: 인증·인가 영역 분리 (파란 실선, 옅은 파란 배경)
- **Network Boundary**: VPC / 서브넷 / public-private (회색 점선)
- **External**: 외부 시스템 영역 (회색 점선)

### 금지

- 모든 컴포넌트가 1개 boundary 안에 있음 → boundary 가 정보 0. 제거.
- 3 단계 이상 중첩 boundary → 시각 복잡도 폭증
- "팀 소유권" 같은 다이어그램 핵심이 아닌 분류 → 다이어그램 외부 본문 표로

## §8. Callout — 1개만, 진짜 비자명한 것에만

Callout 박스는 **다이어그램의 시각 요소로 표현 불가능한 핵심 1가지** 에만 사용.

### 좋은 callout

- 비자명한 함정 (e.g., "KC_HOSTNAME 미설정 시 JWT iss mismatch")
- 핵심 결정의 이유 (e.g., "왜 BFF 대신 SPA-direct? — 학습 환경 단순성")
- 보안 위협 영역 (e.g., "JWKS unknown kid → DoS 벡터")

### 나쁜 callout (제거 대상)

- 단순 부가 정보 (capacity, version 등) → 박스 라벨로
- 컴포넌트 설명 → 본문 텍스트로
- "참고로..." 식 비핵심 메모 → 본문으로

**1개 이상의 callout → 다이어그램이 너무 많은 것을 말하려는 것. 분할.**

## §9. Legend — 표준 컨벤션이면 생략

Legend 는 **다이어그램 내 비표준 색·기호** 가 있을 때만.

### 표준 컨벤션 (Legend 불필요)

- 점선 = 외부 / 비동기
- Cylinder = DB
- Solid arrow = 동기 호출
- Dashed arrow = 비동기 / 점선 응답

### Legend 가 필요한 경우

- 다이어그램 내 색이 [`elements.md`](elements.md) §6 표준 팔레트 **외** 인 경우
- 특수 기호 사용 (예: ⚡ for circuit breaker)

### Legend 작성 표준

- ≤ 6 항목 (가능하면 ≤ 4)
- 다이어그램 우하단 또는 본문 캡션
- 표준 컨벤션 (점선=외부, cylinder=DB) 은 legend 에 안 적음

## §10. Header / Footer — 미니멀

### Header (다이어그램 상단)

```
<Title>
<답하는 질문 1줄>  ← 옵션
```

`Project / branch / status` 같은 메타 정보는 **다이어그램에 안 들어감**. project-note frontmatter 와 §3 본문에 이미 있음.

### Footer (다이어그램 하단)

```
v2 · 2026-05-26
```

작성자 / source wikilink / standard reference 같은 메타는 **다이어그램 외부**. project-note 의 frontmatter `diagrams:` 필드와 본문에서 참조.

## §11. Source 인용 — 본문에서, 다이어그램 안 X

핵심 사실의 출처 wikilink (`[[raw/official-docs/...]]`) 는 **다이어그램 옆 본문 또는 callout** 에 둔다. 화살표 라벨이나 박스 안에 wikilink 를 욱여넣지 말 것.

```markdown
![[architecture-p3a-...drawio]]

> **출처**:
> - KC_HOSTNAME 함정: [[raw/branch-notes/feature-keycloak-iss-claim-hostname-mismatch]]
> - redirect_uri 함정: [[raw/branch-notes/feature-keycloak-docker-compose-stack]]
> - OIDC PKCE: [[raw/official-docs/oauth2-rfc-7636-pkce]]
```

본문이 다이어그램을 보강한다. 다이어그램이 본문 역할까지 떠안지 말 것.