Excalidraw-Architekturdiagramme (EIP-Notation)
Ein Diagramm ist eine kleine JSON-Spezifikation – Knoten, Kanten, Gruppen – plus ein Generator, der sie in der Notation von Hohpe & Woolf anordnet. Die Spezifikation ist die Quelle der Wahrheit; die .excalidraw-Datei und die Vorschau-.svg sind Build-Artefakte.
<skill-dir> unten ist das Verzeichnis, in dem dieses Skill installiert ist – z. B. ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture oder .agents/skills/excalidraw-architecture – und skills/excalidraw-architecture im https://github.com/jamescarr/diagram-skill-Repository.
Wann verwenden
- Gefragt, einen Dienst, ein Ereignis oder eine Messaging-Architektur zu diagrammieren, zu zeichnen, zu skizzieren oder zu visualisieren.
- Zu erklären, wie eine Nachricht reist: welcher Kanal, welcher Endpunkt, was passiert, wenn sie fehlschlägt.
- Die Integrationsoberfläche eines begrenzten Kontexts auf Kontext-, Fluss- oder Endpunktebene zu dokumentieren.
- Ein nachrichtenorientiertes Design zu überprüfen, bei dem das Bild eine fehlende DLQ, Korrelations-ID oder Idempotenz aufdecken muss.
Nicht verwenden
- UI-Mockups, Wireframes, Präsentationsfolien, freies Whiteboarding.
- Sequenzdiagramme von Aufrufen innerhalb eines Prozesses.
- Alles, dessen Ergebnis keine
.excalidraw-Datei ist.
Arbeitsablauf
-
Inventar – vor dem Zeichnen auflisten:
- Teilnehmer: Dienste, externe Systeme, Akteure, Speicher;
- Kanäle: Name, Point-to-Point vs. Publish-Subscribe, Schlüssel/Partitionen/Reihenfolge, Haltbarkeit, DLQ;
- Nachrichten: Name (Befehl = Imperativ, Ereignis = Vergangenheitsform, Dokument = Nomen) und Typ;
- Endpunkte pro Dienst: Gateway, Outbox/Transaktion, Consumer-Stil, Wettbewerbsanzahl, Idempotenz, Haltbarkeit, Selektivität;
- Routing- und Transformationsschritte;
- Request-Reply-Paare: Reply-Kanal, Korrelation, TTL;
- Verwaltung: Wire Tap, Store, Control Bus.
Lesen Sie das Skill
enterprise-integration-patterns, falls es installiert ist, wenn eine Musterwahl unklar ist.
-
Die Ebene wählen –
context: Akteure, Dienste, externe Systeme, Broker alsmessage-bus,rpc/data-Kanten.flow(Standard): ein Geschäftsfluss Ende-zu-Ende mit Kanälen und EIP-Komponenten.endpoint: innerhalb eines Dienstes – Gateway → Outbox → Kanal oder Consumer → Idempotent Receiver → Activator. Ein Fluss pro Diagramm, maximal 20 Knoten; andernfalls nach Fluss aufteilen. -
Die Spezifikation schreiben –
<name>.spec.jsonneben dem Ort, an dem das Diagramm leben wird (Standard:docs/architecture/), unter Verwendung des Spickzettels unten. Führen Sienode <skill-dir>/scripts/eip_excalidraw.mjs kindsfür den Live-Katalog aus. -
Erstellen –
node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.jsonschreibt<name>.excalidrawund<name>.svg. Beheben Sie jedenerror:(Exit 2); behandeln Siewarning:als Layout-Fehler (--strictlässt Warnungen mit Exit 1 beenden).--checkvalidiert und layoutet ohne zu schreiben. Fügen Sie--png [OUT.png]hinzu, um auch ein von Excalidraw selbst gerendertes PNG zu exportieren (handgezeichnet, Excalifont, die Szene in die Datei eingebettet, sodass sie wieder auf excalidraw.com abgelegt werden kann) – was in eine README, ein Dokument oder einen Blogbeitrag eingebettet werden sollte. Es benötigt Chrome oder Chromium (CHROMEüberschreibt die Suche) und Netzwerkzugriff auf esm.sh; es steuert den Browser überscripts/export_png.mjs. Ein fehlgeschlagener Export beendet das Programm mit Exit 3, und die Szene wird trotzdem geschrieben. -
Anschauen –
read <name>.pngwenn Sie eines erstellt haben, sonstread <name>.svg:img; dann die Überprüfungsliste durchgehen. -
Beheben – nach jeder Spezifikationsänderung neu erstellen:
Symptom Spezifikationsänderung Pfeil kreuzt einen Knoten route: "ortho"oder"below", oderrowfestlegenBeschriftung überlappt einen Knoten message/labelkürzen oder dierowdes Knotens vom Pfeil weg festlegenPfeilspitze schrumpft zu viele Pfeile drehen in diesem Spaltenabstand: einen below/aboverouten oderrows festlegen, sodass weniger Vertikale ihn teilenRückwärtspfeil-Unordnung route: "above"Reply-Pfeil schleift unter dem gesamten Diagramm route: "ortho"oder den Reply-Kanal neben den Request-Kanal legenÜberfüllte Spalte laneshinzufügen oder das Diagramm aufteilenLange Knotenbeschriftung Detail in subverschiebenGruppenmitglieder verstreut col/rowfestlegen, sodass Mitglieder benachbart sindRahmen umschließt ein Nicht-Mitglied col/rowfestlegen oderlanesverwenden, sodass die Mitglieder der Gruppe einen zusammenhängenden Block bilden -
Ausliefern – die
.spec.json,.excalidrawund.svg(plus das.png, wenn Sie eines erstellt haben). Sagen Sie, dass die Spezifikation die Quelle der Wahrheit ist: nach Bearbeitungen neu generieren. Manuelle Bearbeitungen in Excalidraw sind danach in Ordnung, aber ein Neubuild überschreibt sie.
Modellierungsregeln
Jede Regel ist eine Behauptung, die das Diagramm sichtbar machen muss; wenn sie nicht wahr sein kann, zeichnen Sie die Ausnahme explizit.
- Jeder Kanal zeigt seinen Art-Tag und seine Schlüssel/Partition/Reihenfolge-Tags (
tags). - Jeder Consumer eines At-Least-Once-Kanals trägt
idempotent– oder das Diagramm sagt, warum nicht. Badges existieren nur auf App-Familien-Knoten, daher gibt ein Saga, Router oder Aggregator seine Deduplizierungsregel insuban (dedupe by orderId). - Jeder Kanal, dessen Consumer ausfallen kann, hat einen
dead-letter-channelshadow; Validierungsfehler erhalten eineninvalid-message-channel. Ein DLQ, der nicht gezeichnet oder bewusst weggelassen wird, wird imsubdes Kanals oder in einernoteangegeben. - Request-Reply = eine Kommando-Kante mit
reply_toundcorrelation, plus eine gestrichelte Reply-Kante zurück. - Aggregator-, Scatter-Gather- und Saga-Knoten tragen ein
submit der Vervollständigungsregel (Anzahl/Timeout). - Veröffentlichen innerhalb einer Transaktion = ein
outbox-Badge oderoutbox-Knoten, niemals ein bloßes Veröffentlichen nach dem Commit. - Übersetzer sitzen auf Bounded-Context-Grenzen (Rahmen).
- Konkurrierende Consumer zeigen
competing:N; dauerhafte Abonnements tragendurable. - Wire Taps sind
tap-Kanten zu einemmessage-store. - Intelligente Endpunkte, dumme Leitungen: Routing-Logik lebt in Router-Knoten, niemals implizit innerhalb eines Kanals.
- Synchrone Aufrufe sind
rpc-Kanten und die Ausnahme, nicht der Standard. - Interne Datensätze, die eine Grenze überschreiten, erhalten einen
content-filteroder einenclaim-check-Verweis.
Spezifikations-Spickzettel
Knoten nach EIP-Kapitel – die vollständige kind-by-kind-Tabelle befindet sich in references/spec.md:
| Kapitel | Arten | Verwenden, wenn |
|---|---|---|
| Kanäle | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | Eine Nachricht bewegt sich zwischen Teilnehmern; wählen Sie p2p vs. pub-sub, dann den Fehlerkanal. |
| Nachrichten | message command-message document-message event-message | Die Nachricht selbst ist das Subjekt, nicht der Endpunkt. |
| Routing | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | Eine Nachricht, mehrere mögliche Ziele oder Teile, die wieder zusammengesetzt werden müssen. |
| Transformation | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | Die Nutzlast oder ihr Umschlag ändert sich zwischen den Sprüngen. |
| Endpunkte | 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 | Wie ein Dienst an einen Kanal anbindet und ihn konsumiert. |
| Systemverwaltung | wire-tap detour message-history smart-proxy test-message channel-purger | Beobachtbarkeit, Sonden und Betrieb. |
| Infrastruktur | message-broker messaging-bridge outbox inbox | Der Broker selbst, Broker-zu-Broker-Verbindungen, transaktionales Veröffentlichen/Konsumieren. |
| Teilnehmer und Speicher | service external-system actor datastore message-store schema-registry note | Wem gehört ein Kanalende; wo Zustand, Schemata und Anmerkungen leben. |
Badges (nur App-Familien-Knoten; die Pille rendert den kurzen Text):
| Gruppe | Badges |
|---|---|
| Endpunkt | gateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter) |
| Konsum | polling (Polling Consumer), event-driven (Event-Driven Consumer), competing / competing:N (Competing Consumers, rendert competing ×N auf einem Stapel von bis zu drei Kästchen), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber) |
| Transaktion | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| Resilienz | bulkhead, retry, circuit-breaker – Resilienz-Muster, nicht EIP |
Kanten:
| Kantenart | Strich | Breite | Köpfe | Marker |
|---|---|---|---|---|
message (kein Typ) | durchgehend #1e1e1e | 2 | → arrow | keiner |
message type: command | durchgehend | 2 | → triangle | «C» |
message type: event | durchgehend | 2 | → arrow | «E» |
message type: document | durchgehend | 2 | → arrow | «D» |
message type: reply | gestrichelt | 2 | → arrow | «R» |
rpc | durchgehend | 1 | → arrow | keiner |
data | gepunktet | 1 | → arrow | keiner |
tap | gepunktet | 1 | circle → arrow | keiner |
dlq | gestrichelt #c92a2a | 1 | → arrow | keiner |
control | gestrichelt #868e96 | 1 | ┤ bar | keiner |
Kantenfelder: from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. Knotenfelder: id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.
Überprüfungs-Checkliste
- Titel vorhanden; er benennt den Fluss, nicht das gesamte System.
- Jeder Pfeil ist mit einer Nachricht oder einem Aufruf beschriftet.
- Jeder Kanal trägt seinen Art-Tag und seine Schlüssel/Partition-Tags.
- Die DLQ-Entscheidung ist für jeden Kanal sichtbar.
- Legende vorhanden, wenn mehr als 6 Arten vorkommen.
- Keine
warning:vom Build übrig. - Gruppenrahmen enthalten nur ihre Mitglieder.
- Maximal 20 Knoten.
Stack-Zuordnung
| Stack | Zeichnen als |
|---|---|
| Kafka-Thema | pubsub-channel; Consumer-Gruppe → competing:N; dauerhaftes Abonnement → durable |
| RabbitMQ-Warteschlange | p2p-channel; Exchange → message-broker oder content-based-router; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| EventBridge-Regel | content-based-router |
| Step Functions | process-manager oder saga |
| Lambda-Consumer | service mit event-driven |
| Datenbank | datastore; Audit-/Wiederholungskopien → message-store |
| Partner-API | external-system, gestrichelt |
Manuelle Bearbeitungen
references/excalidraw-format.md listet die JSON-Invarianten auf, die Excalidraws Bindungen, Texte und Rahmen nach einer manuellen Bearbeitung gültig halten.