Excalidraw architecture diagrams (EIP notation)
A diagram is a small JSON spec — nodes, edges, groups — plus a generator that lays it out in Hohpe & Woolf notation. The spec is the source of truth; the .excalidraw file and the preview .svg are build artefacts.
<skill-dir> below is the directory this skill is installed in — e.g. ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture or .agents/skills/excalidraw-architecture — and skills/excalidraw-architecture in the https://github.com/jamescarr/diagram-skill repo.
When to use
- Asked to diagram, draw, sketch or visualise a service, event or messaging architecture.
- Explaining how a message travels: which channel, which endpoint, what happens when it fails.
- Documenting the integration surface of a bounded context at context, flow or endpoint level.
- Reviewing a message-oriented design where the picture must expose a missing DLQ, correlation id or idempotency.
Don't use
- UI mockups, wireframes, slide decks, freeform whiteboarding.
- Sequence diagrams of calls inside one process.
- Anything whose deliverable is not an
.excalidrawfile.
Workflow
-
Inventory — list before drawing:
- participants: services, external systems, actors, stores;
- channels: name, point-to-point vs publish-subscribe, key/partitions/ordering, durability, DLQ;
- messages: name (command = imperative, event = past tense, document = noun) and type;
- endpoints per service: gateway, outbox/transaction, consumer style, competing count, idempotency, durability, selectivity;
- routing and transformation steps;
- request-reply pairs: reply channel, correlation, TTL;
- management: wire tap, store, control bus.
Read the
enterprise-integration-patternsskill, if you have it installed, when a pattern choice is unclear.
-
Pick the level —
context: actors, services, external systems, broker asmessage-bus,rpc/dataedges.flow(the default): one business flow end to end with channels and EIP components.endpoint: inside one service — gateway → outbox → channel, or consumer → idempotent receiver → activator. One flow per diagram, at most 20 nodes; split by flow otherwise. -
Write the spec —
<name>.spec.jsonnext to where the diagram will live (defaultdocs/architecture/), using the cheat-sheet below. Runnode <skill-dir>/scripts/eip_excalidraw.mjs kindsfor the live catalogue. -
Build —
node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.jsonwrites<name>.excalidrawand<name>.svg. Fix everyerror:(exit 2); treatwarning:as a layout defect (--strictmakes warnings exit 1).--checkvalidates and lays out without writing. Add--png [OUT.png]to also export a PNG rendered by Excalidraw itself (hand-drawn, Excalifont, the scene embedded in the file so it can be dropped back onto excalidraw.com) — what a README, a doc or a blog post should embed. It needs Chrome or Chromium (CHROMEoverrides the lookup) and network access to esm.sh; it drives the browser throughscripts/export_png.mjs. A failed export exits 3 and the scene is still written. -
Look —
read <name>.pngwhen you built one, otherwiseread <name>.svg:img; then work the review list. -
Fix — rebuild after each spec change:
Symptom Spec change arrow crosses a node route: "ortho"or"below", or pinrowlabel overlaps a node shorten message/label, or pin the node'srowaway from the arrowarrowhead shrinks too many arrows turn in that column gap: route one below/above, or pinrows so fewer verticals share itbackward arrow clutter route: "above"reply arrow loops under the whole diagram route: "ortho", or put the reply channel next to the request channelcrowded column add lanes, or split the diagramlong node label move detail to subgroup members scattered pin col/rowso members are adjacentframe encloses a non-member pin col/rowor uselanesso the group's members form a contiguous block -
Deliver — the
.spec.json,.excalidrawand.svg(plus the.pngwhen you built one). Say the spec is the source of truth: regenerate after edits. Hand edits in Excalidraw are fine afterwards, but a rebuild overwrites them.
Modelling rules
Each rule is a claim the diagram must make visible; when it cannot be true, draw the exception explicitly.
- Every channel shows its kind tag and its key/partition/ordering tags (
tags). - Every consumer of an at-least-once channel wears
idempotent— or the diagram says why not. Badges exist only on app-family nodes, so a saga, router or aggregator states its dedupe rule insub(dedupe by orderId). - Every channel whose consumer can fail has a
dead-letter-channelshadow; validation failures get aninvalid-message-channel. A DLQ that is left undrawn, or deliberately absent, is stated in the channel'ssubor in anote. - Request-reply = a command edge with
reply_toandcorrelation, plus a dashed reply edge back. - Aggregator, scatter-gather and saga nodes carry a
subwith the completion rule (count/timeout). - Publish inside a transaction = an
outboxbadge oroutboxnode, never a bare publish after commit. - Translators sit on bounded-context borders (frames).
- Competing consumers show
competing:N; durable subscriptions weardurable. - Wire taps are
tapedges into amessage-store. - Smart endpoints, dumb pipes: routing logic lives in router nodes, never implied inside a channel.
- Sync calls are
rpcedges and are the exception, not the default. - Internal records crossing a boundary get a
content-filter, or aclaim-checkreference.
Spec cheat-sheet
Nodes by EIP chapter — the full kind-by-kind table is in references/spec.md:
| Chapter | Kinds | Use when |
|---|---|---|
| Channels | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | A message moves between participants; pick p2p vs pub-sub, then the failure channel. |
| Messages | message command-message document-message event-message | The message itself is the subject, not the endpoint. |
| Routing | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | One message, several possible destinations, or parts to reassemble. |
| Transformation | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | The payload or its envelope changes between hops. |
| Endpoints | 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 | How a service attaches to a channel and consumes it. |
| System management | wire-tap detour message-history smart-proxy test-message channel-purger | Observability, probes and operations. |
| Infrastructure | message-broker messaging-bridge outbox inbox | The broker itself, broker-to-broker links, transactional publish/consume. |
| Participants and stores | service external-system actor datastore message-store schema-registry note | Who owns a channel end; where state, schemas and annotations live. |
Badges (app-family nodes only; the pill renders the short text):
| Group | Badges |
|---|---|
| Endpoint | gateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter) |
| Consumption | polling (Polling Consumer), event-driven (Event-Driven Consumer), competing / competing:N (Competing Consumers, renders competing ×N on a stack of up to three boxes), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber) |
| Transaction | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| Resilience | bulkhead, retry, circuit-breaker — resilience patterns, not EIP |
Edges:
| Edge kind | Stroke | Width | Heads | Marker |
|---|---|---|---|---|
message (no type) | solid #1e1e1e | 2 | → arrow | none |
message type: command | solid | 2 | → triangle | «C» |
message type: event | solid | 2 | → arrow | «E» |
message type: document | solid | 2 | → arrow | «D» |
message type: reply | dashed | 2 | → arrow | «R» |
rpc | solid | 1 | → arrow | none |
data | dotted | 1 | → arrow | none |
tap | dotted | 1 | circle → arrow | none |
dlq | dashed #c92a2a | 1 | → arrow | none |
control | dashed #868e96 | 1 | ┤ bar | none |
Edge fields: from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. Node fields: id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.
Review checklist
- Title present; it names the flow, not the whole system.
- Every arrow is labelled with a message or a call.
- Every channel carries its kind tag and its key/partition tags.
- The DLQ decision is visible for every channel.
- Legend present when more than 6 kinds appear.
- No
warning:left from the build. - Group frames contain only their members.
- At most 20 nodes.
Stack mapping
| Stack | Draw as |
|---|---|
| Kafka topic | pubsub-channel; consumer group → competing:N; durable subscription → durable |
| RabbitMQ queue | p2p-channel; exchange → message-broker or content-based-router; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| EventBridge rule | content-based-router |
| Step Functions | process-manager or saga |
| Lambda consumer | service with event-driven |
| Database | datastore; audit/replay copies → message-store |
| Partner API | external-system, dashed |
Hand edits
references/excalidraw-format.md lists the JSON invariants that keep Excalidraw's bindings, text and frames valid after a hand edit.