Excalidraw アーキテクチャ図 (EIP 記法)
図は小さな JSON スペック(ノード、エッジ、グループ)と、それを Hohpe & Woolf 記法でレイアウトするジェネレータで構成されます。スペックが真実の源泉であり、.excalidraw ファイルとプレビュー .svg はビルド成果物です。
<skill-dir> は、このスキルがインストールされているディレクトリです(例: ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture、.agents/skills/excalidraw-architecture、または https://github.com/jamescarr/diagram-skill リポジトリ内の skills/excalidraw-architecture)。
使用するタイミング
- サービス、イベント、メッセージングアーキテクチャの図示、描画、スケッチ、可視化を依頼された場合。
- メッセージの経路(どのチャネル、どのエンドポイント、失敗時に何が起こるか)を説明する場合。
- 境界付けられたコンテキストの統合面をコンテキスト、フロー、エンドポイントレベルで文書化する場合。
- メッセージ指向の設計をレビューし、図が欠落している DLQ、相関 ID、または冪等性を明らかにする必要がある場合。
使用しないタイミング
- UI モックアップ、ワイヤーフレーム、スライドデッキ、自由形式のホワイトボーディング。
- 単一プロセス内の呼び出しのシーケンス図。
- 成果物が
.excalidrawファイルではないもの。
ワークフロー
-
インベントリ — 描画前に以下をリストアップ:
- 参加者: サービス、外部システム、アクター、ストア;
- チャネル: 名前、ポイントツーポイント vs パブリッシュ-サブスクライブ、キー/パーティション/順序付け、持続性、DLQ;
- メッセージ: 名前(コマンド = 命令形、イベント = 過去形、ドキュメント = 名詞)とタイプ;
- サービスごとのエンドポイント: ゲートウェイ、アウトボックス/トランザクション、コンシューマスタイル、競合数、冪等性、持続性、選択性;
- ルーティングと変換ステップ;
- リクエスト-リプライペア: リプライチャネル、相関、TTL;
- 管理: ワイヤータップ、ストア、コントロールバス。
パターンの選択が不明な場合は、インストールされていれば
enterprise-integration-patternsスキルを読んでください。
-
レベルを選択 —
context: アクター、サービス、外部システム、ブローカーはmessage-bus、rpc/dataエッジ。flow(デフォルト): チャネルと EIP コンポーネントを含む、エンドツーエンドの1つのビジネスフロー。endpoint: 1つのサービス内部 — ゲートウェイ→アウトボックス→チャネル、またはコンシューマ→冪等レシーバ→アクティベータ。図1つにつき1フロー、最大20ノード。それ以外の場合はフローごとに分割。 -
スペックを記述 — 図を配置する場所(デフォルトは
docs/architecture/)に<name>.spec.jsonを作成し、以下のチートシートを使用します。node <skill-dir>/scripts/eip_excalidraw.mjs kindsを実行すると、ライブカタログが表示されます。 -
ビルド —
node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.jsonを実行すると、<name>.excalidrawと<name>.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 <name>.png、それ以外の場合はread <name>.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 をビルドした場合はそれも含む)。スペックが真実の源泉であると明記し、編集後は再生成すること。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ノード。コミット後にベアでパブリッシュしてはならない。 - トランスレーターは境界付けられたコンテキストの境界(フレーム)上に配置する。
- 競合コンシューマは
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 | 1つのメッセージに複数の宛先がある、または再構成する必要のある部分がある。 |
| 変換 | 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 コンシューマ | service with event-driven |
| データベース | datastore; 監査/リプレイコピー → message-store |
| パートナー API | external-system、破線 |
手動編集
references/excalidraw-format.md には、手動編集後も Excalidraw のバインディング、テキスト、フレームを有効に保つための JSON 不変条件がリストされています。