Community이미지github.com

Excalidraw 아키텍처 다이어그램 (EIP 표기법)

소프트웨어 아키텍처, 메시지 흐름, 이벤트 기반 시스템 또는 마이크로서비스를 Excalidraw로 다이어그램, 그림, 스케치 또는 시각화할 때 사용합니다. 채널, 라우터, 트랜스레이터, 엔드포인트, DLQ, 사가 등 Enterprise Integration Patterns 표기법으로 .excalidraw 파일을 생성합니다. UI 목업, 슬라이드 데크, 자유형 화이트보딩에는 적합하지 않습니다.

Excalidraw 아키텍처 다이어그램 (EIP 표기법)란 무엇인가요?

이 스킬은 Hohpe & Woolf의 Enterprise Integration Patterns (EIP) 표기법을 사용하여 소프트웨어 아키텍처 다이어그램을 생성하는 전문 도구입니다. 사용자는 작은 JSON 스펙 파일에 노드, 엣지, 그룹을 정의하고, 제공된 `eip_excalidraw.mjs` 스크립트를 통해 Excalidraw 파일(.excalidraw)과 미리보기 SVG(.svg)를 자동으로 생성합니다. 또한 PNG 내보내기를 지원하여 문서에 바로 포함할 수 있습니다. 이 스킬은 메시지 흐름 설계, 마이크로서비스 통합, 이벤트 기반 아키텍처 문서화에 특히 유용합니다. 각 다이어그램은 채널 종류, DLQ(Dead Letter Queue) 유무, 멱등성 보장, 상관관계 ID 등 메시징 아키텍처의 핵심 속성을 시각적으로 드러내도록 설계되었습니다. 사가, 집계기, 경쟁 소비자 등 패턴별로 전용 노드 종류를 제공하며, 바운디드 컨텍스트 경계에 트랜스레이터를 배치하고, 프레임을 통해 그룹을 시각화합니다. 지원되는 플랫폼은 Claude Code, Cursor, Codex 등 AI 에이전트 환경이며, 명령줄에서 스크립트를 실행하여 작동합니다. 스펙 파일이 단일 진실 공급원(source of truth)이므로, 빌드 후 Excalidraw에서 수동 편집이 가능하지만 재빌드 시 덮어쓰기됩니다. 빌드 시 오류는 종료 코드 2로, 경고는 레이아웃 결함으로 처리되며 `--strict` 옵션으로 경고를 오류로 승격할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jamescarr/diagram-skill/tree/HEAD/skills/excalidraw-architecture

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 파일이 아닌 모든 경우

워크플로우

  1. 인벤토리 — 그리기 전에 목록을 작성하세요:

    • 참여자: 서비스, 외부 시스템, 액터, 저장소
    • 채널: 이름, 점대점 대 게시-구독, 키/파티션/순서, 지속성, DLQ
    • 메시지: 이름 (명령어 = 명령형, 이벤트 = 과거형, 문서 = 명사) 및 유형
    • 서비스별 엔드포인트: 게이트웨이, 아웃박스/트랜잭션, 소비자 스타일, 경쟁 수, 멱등성, 지속성, 선택성
    • 라우팅 및 변환 단계
    • 요청-응답 쌍: 응답 채널, 상관관계, TTL
    • 관리: 와이어 탭, 저장소, 제어 버스 패턴 선택이 불분명할 때는 enterprise-integration-patterns 스킬이 설치되어 있다면 참조하세요.
  2. 수준 선택 — context: 액터, 서비스, 외부 시스템, 브로커를 message-bus로, rpc/data 엣지 사용. flow (기본값): 채널과 EIP 구성 요소를 포함한 단일 비즈니스 흐름을 처음부터 끝까지. endpoint: 단일 서비스 내부 — 게이트웨이 → 아웃박스 → 채널, 또는 소비자 → 멱등 수신기 → 활성화기. 다이어그램당 하나의 흐름, 최대 20개 노드; 그렇지 않으면 흐름별로 분할.

  3. 스펙 작성 — <이름>.spec.json 파일을 다이어그램이 위치할 곳(기본값 docs/architecture/)에 아래 치트 시트를 참고하여 작성하세요. 라이브 카탈로그를 보려면 node <skill-dir>/scripts/eip_excalidraw.mjs kinds를 실행하세요.

  4. 빌드 — 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이며 씬은 계속 기록됩니다.

  5. 확인 — PNG를 빌드했다면 read <이름>.png, 그렇지 않으면 read <이름>.svg:img로 확인한 후 검토 목록을 작업하세요.

  6. 수정 — 스펙 변경 후 재빌드하세요:

    증상스펙 변경
    화살표가 노드 위를 가로지름route: "ortho" 또는 "below", 또는 row 고정
    레이블이 노드와 겹침message/label 단축, 또는 노드의 row를 화살표에서 멀리 고정
    화살촉이 작아짐해당 컬럼 간격에 화살표가 너무 많음: 하나를 below/above로 라우팅하거나, row를 고정하여 수직선 공유를 줄임
    역방향 화살표 복잡route: "above"
    응답 화살표가 다이어그램 전체 아래로 루프route: "ortho", 또는 응답 채널을 요청 채널 옆에 배치
    컬럼 혼잡lanes 추가, 또는 다이어그램 분할
    긴 노드 레이블세부 정보를 sub로 이동
    그룹 멤버가 흩어짐col/row를 고정하여 멤버가 인접하도록
    프레임이 비멤버를 포함col/row를 고정하거나 lanes를 사용하여 그룹 멤버가 연속 블록을 형성하도록
  7. 전달 — .spec.json, .excalidraw, .svg (PNG를 빌드했다면 .png 포함)를 전달합니다. 스펙이 단일 진실 공급원임을 명시하세요: 편집 후 재생성 필요. Excalidraw에서 수동 편집은 이후에 가능하지만 재빌드 시 덮어쓰기됩니다.

모델링 규칙

각 규칙은 다이어그램이 반드시 시각적으로 드러내야 하는 주장입니다; 주장이 참일 수 없을 때는 예외를 명시적으로 그리세요.

  • 모든 채널은 종류 태그와 키/파티션/순서 태그를 표시합니다 (tags).
  • 적어도 한 번 이상(at-least-once) 채널의 모든 소비자는 idempotent 배지를 착용해야 합니다. 그렇지 않은 이유를 다이어그램에 명시하세요. 배지는 앱 계열 노드에만 존재하므로, 사가, 라우터, 집계기는 sub에 중복 제거 규칙을 명시합니다 (dedupe by orderId).
  • 소비자가 실패할 수 있는 모든 채널에는 dead-letter-channel shadow가 있습니다; 검증 실패는 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 (유형 없음)실선 #1e1e1e2→ 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점선1circle → arrow없음
dlq점선 #c92a2a1→ arrow없음
control점선 #868e961┤ 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 / SNSp2p-channel / pubsub-channel
EventBridge 규칙content-based-router
Step Functionsprocess-manager 또는 saga
Lambda 소비자event-driven 배지가 있는 service
데이터베이스datastore; 감사/재생 복사본 → message-store
파트너 APIexternal-system, 점선

수동 편집

references/excalidraw-format.md에는 수동 편집 후에도 Excalidraw의 바인딩, 텍스트 및 프레임이 유효하도록 유지하는 JSON 불변 조건이 나열되어 있습니다.

관련 스킬