Excalidraw 아키텍처 다이어그램 (EIP 표기법)은(는) 무엇을 하나요?
다이어그램은 작은 JSON 스펙(노드, 엣지, 그룹)과 Hohpe & Woolf 표기법으로 레이아웃을 생성하는 생성기로 구성됩니다. 스펙이 단일 진실 공급원이며, .excalidraw 파일과 미리보기 .svg는 빌드 산출물입니다.
<skill-dir>는 이 스킬이 설치된 디렉터리입니다 (예: ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture 또는 .agents/skills/excalidraw-architecture). GitHub 저장소 https://github.com/jamescarr/diagram-skill 에서는 skills/excalidraw-architecture 경로입니다.
사용 시점
- 서비스, 이벤트 또는 메시징 아키텍처를 다이어그램, 그림, 스케치 또는 시각화하라는 요청을 받았을 때
- 메시지가 이동하는 방식을 설명할 때: 어떤 채널, 어떤 엔드포인트, 실패 시 어떤 일이 발생하는지
- 바운디드 컨텍스트의 통합 표면을 컨텍스트, 흐름 또는 엔드포인트 수준에서 문서화할 때
- 메시지 지향 설계를 검토할 때, 그림이 누락된 DLQ, 상관관계 ID 또는 멱등성을 드러내야 하는 경우
사용하지 말아야 할 경우
- UI 목업, 와이어프레임, 슬라이드 데크, 자유형 화이트보딩
- 단일 프로세스 내 호출에 대한 시퀀스 다이어그램
- 결과물이
.excalidraw파일이 아닌 모든 경우
워크플로우
-
인벤토리 — 그리기 전에 목록을 작성하세요:
- 참여자: 서비스, 외부 시스템, 액터, 저장소
- 채널: 이름, 점대점 대 게시-구독, 키/파티션/순서, 지속성, DLQ
- 메시지: 이름 (명령어 = 명령형, 이벤트 = 과거형, 문서 = 명사) 및 유형
- 서비스별 엔드포인트: 게이트웨이, 아웃박스/트랜잭션, 소비자 스타일, 경쟁 수, 멱등성, 지속성, 선택성
- 라우팅 및 변환 단계
- 요청-응답 쌍: 응답 채널, 상관관계, TTL
- 관리: 와이어 탭, 저장소, 제어 버스
패턴 선택이 불분명할 때는
enterprise-integration-patterns스킬이 설치되어 있다면 참조하세요.
-
수준 선택 —
context: 액터, 서비스, 외부 시스템, 브로커를message-bus로,rpc/data엣지 사용.flow(기본값): 채널과 EIP 구성 요소를 포함한 단일 비즈니스 흐름을 처음부터 끝까지.endpoint: 단일 서비스 내부 — 게이트웨이 → 아웃박스 → 채널, 또는 소비자 → 멱등 수신기 → 활성화기. 다이어그램당 하나의 흐름, 최대 20개 노드; 그렇지 않으면 흐름별로 분할. -
스펙 작성 —
<이름>.spec.json파일을 다이어그램이 위치할 곳(기본값docs/architecture/)에 아래 치트 시트를 참고하여 작성하세요. 라이브 카탈로그를 보려면node <skill-dir>/scripts/eip_excalidraw.mjs kinds를 실행하세요. -
빌드 —
node <skill-dir>/scripts/eip_excalidraw.mjs build <이름>.spec.json명령으로<이름>.excalidraw와<이름>.svg파일을 생성합니다. 모든error:를 수정하세요 (종료 코드 2);warning:은 레이아웃 결함으로 처리하세요 (--strict는 경고를 종료 코드 1로 처리).--check는 쓰기 없이 검증하고 레이아웃을 생성합니다.--png [OUT.png]를 추가하면 Excalidraw 자체에서 렌더링한 PNG도 내보냅니다 (손그림 스타일, Excalifont, 파일 내에 씬이 포함되어 excalidraw.com에 다시 드롭 가능). README, 문서 또는 블로그 포스트에 포함하기 적합합니다. Chrome 또는 Chromium이 필요하며 (CHROME환경 변수로 경로 재정의 가능), esm.sh에 네트워크 접근이 필요합니다.scripts/export_png.mjs를 통해 브라우저를 구동합니다. 내보내기 실패 시 종료 코드 3이며 씬은 계속 기록됩니다. -
확인 — PNG를 빌드했다면
read <이름>.png, 그렇지 않으면read <이름>.svg:img로 확인한 후 검토 목록을 작업하세요. -
수정 — 스펙 변경 후 재빌드하세요:
증상 스펙 변경 화살표가 노드 위를 가로지름 route: "ortho"또는"below", 또는row고정레이블이 노드와 겹침 message/label단축, 또는 노드의row를 화살표에서 멀리 고정화살촉이 작아짐 해당 컬럼 간격에 화살표가 너무 많음: 하나를 below/above로 라우팅하거나,row를 고정하여 수직선 공유를 줄임역방향 화살표 복잡 route: "above"응답 화살표가 다이어그램 전체 아래로 루프 route: "ortho", 또는 응답 채널을 요청 채널 옆에 배치컬럼 혼잡 lanes추가, 또는 다이어그램 분할긴 노드 레이블 세부 정보를 sub로 이동그룹 멤버가 흩어짐 col/row를 고정하여 멤버가 인접하도록프레임이 비멤버를 포함 col/row를 고정하거나lanes를 사용하여 그룹 멤버가 연속 블록을 형성하도록 -
전달 —
.spec.json,.excalidraw,.svg(PNG를 빌드했다면.png포함)를 전달합니다. 스펙이 단일 진실 공급원임을 명시하세요: 편집 후 재생성 필요. Excalidraw에서 수동 편집은 이후에 가능하지만 재빌드 시 덮어쓰기됩니다.
모델링 규칙
각 규칙은 다이어그램이 반드시 시각적으로 드러내야 하는 주장입니다; 주장이 참일 수 없을 때는 예외를 명시적으로 그리세요.
- 모든 채널은 종류 태그와 키/파티션/순서 태그를 표시합니다 (
tags). - 적어도 한 번 이상(at-least-once) 채널의 모든 소비자는
idempotent배지를 착용해야 합니다. 그렇지 않은 이유를 다이어그램에 명시하세요. 배지는 앱 계열 노드에만 존재하므로, 사가, 라우터, 집계기는sub에 중복 제거 규칙을 명시합니다 (dedupe by orderId). - 소비자가 실패할 수 있는 모든 채널에는
dead-letter-channelshadow가 있습니다; 검증 실패는invalid-message-channel을 사용합니다. 그려지지 않았거나 의도적으로 없는 DLQ는 채널의sub또는note에 명시합니다. - 요청-응답 =
reply_to및correlation이 있는 명령 엣지와 점선 응답 엣지로 구성됩니다. - 집계기, 산포-수집 및 사가 노드는 완료 규칙(횟수/타임아웃)이 포함된
sub를 가집니다. - 트랜잭션 내 게시 =
outbox배지 또는outbox노드로, 커밋 후 맨 게시(bare publish)는 허용되지 않습니다. - 트랜스레이터는 바운디드 컨텍스트 경계(프레임)에 위치합니다.
- 경쟁 소비자는
competing:N으로 표시합니다; 지속적 구독은durable을 착용합니다. - 와이어 탭은
message-store로 향하는tap엣지입니다. - 스마트 엔드포인트, 덤프 파이프: 라우팅 로직은 라우터 노드에 있으며, 채널 내에 암시되지 않습니다.
- 동기 호출은
rpc엣지이며 기본값이 아닌 예외입니다. - 경계를 넘는 내부 기록은
content-filter또는claim-check참조를 사용합니다.
스펙 치트 시트
EIP 장별 노드 — 전체 종류별 표는 references/spec.md에 있습니다:
| 장 | 종류 | 사용 시점 |
|---|---|---|
| 채널 | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | 메시지가 참여자 간 이동; p2p 대 pub-sub 선택 후 실패 채널 선택 |
| 메시지 | message command-message document-message event-message | 메시지 자체가 주제이며 엔드포인트가 아님 |
| 라우팅 | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | 하나의 메시지, 여러 가능한 대상, 또는 재조립할 부분 |
| 변환 | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | 페이로드 또는 엔벨로프가 홉 사이에서 변경됨 |
| 엔드포인트 | message-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapter | 서비스가 채널에 연결하고 소비하는 방식 |
| 시스템 관리 | wire-tap detour message-history smart-proxy test-message channel-purger | 관측 가능성, 프로브 및 운영 |
| 인프라 | message-broker messaging-bridge outbox inbox | 브로커 자체, 브로커 간 링크, 트랜잭션 게시/소비 |
| 참여자 및 저장소 | service external-system actor datastore message-store schema-registry note | 채널 끝을 소유하는 주체; 상태, 스키마 및 주석이 있는 위치 |
배지 (앱 계열 노드 전용; 짧은 텍스트를 표시하는 알약):
| 그룹 | 배지 |
|---|---|
| 엔드포인트 | gateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter) |
| 소비 | polling (Polling Consumer), event-driven (Event-Driven Consumer), competing / competing:N (Competing Consumers, 최대 3개 상자 스택에 competing ×N으로 렌더링), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber) |
| 트랜잭션 | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| 복원력 | bulkhead, retry, circuit-breaker — EIP가 아닌 복원력 패턴 |
엣지:
| 엣지 종류 | 선 스타일 | 너비 | 화살촉 | 마커 |
|---|---|---|---|---|
message (유형 없음) | 실선 #1e1e1e | 2 | → arrow | 없음 |
message type: command | 실선 | 2 | → triangle | «C» |
message type: event | 실선 | 2 | → arrow | «E» |
message type: document | 실선 | 2 | → arrow | «D» |
message type: reply | 점선 | 2 | → arrow | «R» |
rpc | 실선 | 1 | → arrow | 없음 |
data | 점선 | 1 | → arrow | 없음 |
tap | 점선 | 1 | circle → arrow | 없음 |
dlq | 점선 #c92a2a | 1 | → arrow | 없음 |
control | 점선 #868e96 | 1 | ┤ bar | 없음 |
엣지 필드: from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. 노드 필드: id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.
검토 체크리스트
- 제목이 존재하며, 전체 시스템이 아닌 흐름의 이름을 지정합니다.
- 모든 화살표에 메시지 또는 호출 레이블이 있습니다.
- 모든 채널에 종류 태그와 키/파티션 태그가 있습니다.
- DLQ 결정이 모든 채널에 대해 표시됩니다.
- 6개 이상의 종류가 나타날 때 범례가 있습니다.
- 빌드에서
warning:이 남지 않았습니다. - 그룹 프레임에 해당 멤버만 포함됩니다.
- 최대 20개 노드.
스택 매핑
| 스택 | 그리기 방식 |
|---|---|
| Kafka 토픽 | pubsub-channel; 소비자 그룹 → competing:N; 지속적 구독 → durable |
| RabbitMQ 큐 | p2p-channel; 익스체인지 → message-broker 또는 content-based-router; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| EventBridge 규칙 | content-based-router |
| Step Functions | process-manager 또는 saga |
| Lambda 소비자 | event-driven 배지가 있는 service |
| 데이터베이스 | datastore; 감사/재생 복사본 → message-store |
| 파트너 API | external-system, 점선 |
수동 편집
references/excalidraw-format.md에는 수동 편집 후에도 Excalidraw의 바인딩, 텍스트 및 프레임이 유효하도록 유지하는 JSON 불변 조건이 나열되어 있습니다.