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

Root SSOT: rules/diagram-standards.md §7~§11 parent: 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 §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 를 욱여넣지 말 것.

![[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]]

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

3.3 KiB Raw Blame History