CommunityBildgithub.com

Excalidraw-Architektur

Verwenden, wenn ein Diagramm, eine Skizze oder eine Visualisierung einer Softwarearchitektur, eines Nachrichtenflusses, eines ereignisgesteuerten Systems oder einer Microservices-Architektur in Excalidraw erstellt werden soll. Erzeugt .excalidraw-Dateien in Enterprise-Integration-Patterns-Notation (Kanäle, Router, Übersetzer, Endpunkte, DLQs, Sagas) aus einem kleinen JSON-Spezifikationsformat über scripts/eip_excalidraw.mjs, mit einer Vorschau-SVG und einem Rendering-Check.

Was ist Excalidraw-Architektur?

Dieses Skill ermöglicht es KI-Agenten, Architekturdiagramme in Excalidraw unter Verwendung der Enterprise Integration Patterns (EIP)-Notation zu erstellen. Es ist speziell für die Visualisierung von Nachrichtenflüssen, ereignisgesteuerten Systemen und Microservices-Architekturen konzipiert und eignet sich nicht für UI-Mockups oder freies Whiteboarding. Der Workflow umfasst die Erstellung einer kleinen JSON-Spezifikation, die Knoten, Kanten und Gruppen definiert, und die anschließende Generierung einer .excalidraw-Datei sowie optionaler Vorschauformate wie SVG und PNG. Das Skill unterstützt die Plattformen Claude Code, Cursor und Codex sowie andere, die Open-Interpreter-Plugins nutzen. Es basiert auf einem strikten Modellierungsregelwerk, das sicherstellt, dass jedes Diagramm wichtige Architekturkonzepte wie DLQs, Idempotenz und Transaktionsgrenzen sichtbar macht. Es enthält eine umfangreiche Cheat-Sheet für Knoten, Kanten und Badges sowie eine detaillierte Anleitung zur Fehlerbehebung bei Layout-Problemen.

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

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

  1. 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.
  2. Die Ebene wählen – context: Akteure, Dienste, externe Systeme, Broker als message-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.

  3. Die Spezifikation schreiben – <name>.spec.json neben dem Ort, an dem das Diagramm leben wird (Standard: docs/architecture/), unter Verwendung des Spickzettels unten. Führen Sie node <skill-dir>/scripts/eip_excalidraw.mjs kinds für den Live-Katalog aus.

  4. Erstellen – node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json schreibt <name>.excalidraw und <name>.svg. Beheben Sie jeden error: (Exit 2); behandeln Sie warning: als Layout-Fehler (--strict lässt Warnungen mit Exit 1 beenden). --check validiert 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 über scripts/export_png.mjs. Ein fehlgeschlagener Export beendet das Programm mit Exit 3, und die Szene wird trotzdem geschrieben.

  5. Anschauen – read <name>.png wenn Sie eines erstellt haben, sonst read <name>.svg:img; dann die Überprüfungsliste durchgehen.

  6. Beheben – nach jeder Spezifikationsänderung neu erstellen:

    SymptomSpezifikationsänderung
    Pfeil kreuzt einen Knotenroute: "ortho" oder "below", oder row festlegen
    Beschriftung überlappt einen Knotenmessage/label kürzen oder die row des Knotens vom Pfeil weg festlegen
    Pfeilspitze schrumpftzu viele Pfeile drehen in diesem Spaltenabstand: einen below/above routen oder rows festlegen, sodass weniger Vertikale ihn teilen
    Rückwärtspfeil-Unordnungroute: "above"
    Reply-Pfeil schleift unter dem gesamten Diagrammroute: "ortho" oder den Reply-Kanal neben den Request-Kanal legen
    Überfüllte Spaltelanes hinzufügen oder das Diagramm aufteilen
    Lange KnotenbeschriftungDetail in sub verschieben
    Gruppenmitglieder verstreutcol/row festlegen, sodass Mitglieder benachbart sind
    Rahmen umschließt ein Nicht-Mitgliedcol/row festlegen oder lanes verwenden, sodass die Mitglieder der Gruppe einen zusammenhängenden Block bilden
  7. Ausliefern – die .spec.json, .excalidraw und .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 in sub an (dedupe by orderId).
  • Jeder Kanal, dessen Consumer ausfallen kann, hat einen dead-letter-channel shadow; Validierungsfehler erhalten einen invalid-message-channel. Ein DLQ, der nicht gezeichnet oder bewusst weggelassen wird, wird im sub des Kanals oder in einer note angegeben.
  • Request-Reply = eine Kommando-Kante mit reply_to und correlation, plus eine gestrichelte Reply-Kante zurück.
  • Aggregator-, Scatter-Gather- und Saga-Knoten tragen ein sub mit der Vervollständigungsregel (Anzahl/Timeout).
  • Veröffentlichen innerhalb einer Transaktion = ein outbox-Badge oder outbox-Knoten, niemals ein bloßes Veröffentlichen nach dem Commit.
  • Übersetzer sitzen auf Bounded-Context-Grenzen (Rahmen).
  • Konkurrierende Consumer zeigen competing:N; dauerhafte Abonnements tragen durable.
  • Wire Taps sind tap-Kanten zu einem message-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-filter oder einen claim-check-Verweis.

Spezifikations-Spickzettel

Knoten nach EIP-Kapitel – die vollständige kind-by-kind-Tabelle befindet sich in references/spec.md:

KapitelArtenVerwenden, wenn
Kanälechannel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-busEine Nachricht bewegt sich zwischen Teilnehmern; wählen Sie p2p vs. pub-sub, dann den Fehlerkanal.
Nachrichtenmessage command-message document-message event-messageDie Nachricht selbst ist das Subjekt, nicht der Endpunkt.
Routingcontent-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager sagaEine Nachricht, mehrere mögliche Ziele oder Teile, die wieder zusammengesetzt werden müssen.
Transformationmessage-translator envelope-wrapper content-enricher content-filter claim-check normalizerDie Nutzlast oder ihr Umschlag ändert sich zwischen den Sprüngen.
Endpunktemessage-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-adapterWie ein Dienst an einen Kanal anbindet und ihn konsumiert.
Systemverwaltungwire-tap detour message-history smart-proxy test-message channel-purgerBeobachtbarkeit, Sonden und Betrieb.
Infrastrukturmessage-broker messaging-bridge outbox inboxDer Broker selbst, Broker-zu-Broker-Verbindungen, transaktionales Veröffentlichen/Konsumieren.
Teilnehmer und Speicherservice external-system actor datastore message-store schema-registry noteWem gehört ein Kanalende; wo Zustand, Schemata und Anmerkungen leben.

Badges (nur App-Familien-Knoten; die Pille rendert den kurzen Text):

GruppeBadges
Endpunktgateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter)
Konsumpolling (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)
Transaktiontx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver)
Resilienzbulkhead, retry, circuit-breaker – Resilienz-Muster, nicht EIP

Kanten:

KantenartStrichBreiteKöpfeMarker
message (kein Typ)durchgehend #1e1e1e2→ arrowkeiner
message type: commanddurchgehend2→ triangle«C»
message type: eventdurchgehend2→ arrow«E»
message type: documentdurchgehend2→ arrow«D»
message type: replygestrichelt2→ arrow«R»
rpcdurchgehend1→ arrowkeiner
datagepunktet1→ arrowkeiner
tapgepunktet1circle → arrowkeiner
dlqgestrichelt #c92a2a1→ arrowkeiner
controlgestrichelt #868e961┤ barkeiner

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

StackZeichnen als
Kafka-Themapubsub-channel; Consumer-Gruppe → competing:N; dauerhaftes Abonnement → durable
RabbitMQ-Warteschlangep2p-channel; Exchange → message-broker oder content-based-router; DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
EventBridge-Regelcontent-based-router
Step Functionsprocess-manager oder saga
Lambda-Consumerservice mit event-driven
Datenbankdatastore; Audit-/Wiederholungskopien → message-store
Partner-APIexternal-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.

Verwandte Skills