CommunityImagegithub.com

excalidraw-architecture

Utilisez pour schématiser, dessiner, croquer ou visualiser une architecture logicielle, un flux de messages, un système événementiel ou de microservices dans Excalidraw. Produit des fichiers .excalidraw en notation Enterprise Integration Patterns (canaux, routeurs, traducteurs, points de terminaison, DLQs, sagas) à partir d'une petite spécification JSON via scripts/eip_excalidraw.mjs, avec un SVG de prévisualisation et une vérification du rendu. Ne convient pas aux maquettes UI, présentations ou tableaux blancs libres.

Qu'est-ce que excalidraw-architecture ?

Cette compétence permet aux agents LLM (comme Claude Code, Cursor, Codex) de générer des diagrammes d'architecture technique dans Excalidraw en utilisant la notation des Enterprise Integration Patterns (EIP) de Hohpe & Woolf. L'utilisateur fournit une spécification JSON compacte (nœuds, arêtes, groupes) et la compétence produit automatiquement un fichier `.excalidraw` éditable et un SVG de prévisualisation. Elle est spécialisée pour les schémas d'architecture orientés messages et événements : flux entre services, canaux point-à-point ou pub/sub, routeurs, traducteurs, gestion des erreurs (DLQ), sagas, et patterns de résilience. La compétence guide l'utilisateur via un workflow structuré : inventaire des participants et des messages, choix du niveau de détail (contexte, flux, point de terminaison), rédaction de la spécification, génération, relecture et corrections des défauts de disposition (chemins d'arêtes, étiquettes superposées). Elle inclut une checklist de révision, une table de correspondance avec les technologies courantes (Kafka, RabbitMQ, SQS, Step Functions) et un cheat-sheet complet des types de nœuds par chapitre EIP. La sortie est un artefact de build : la spécification reste la source de vérité ; des modifications manuelles dans Excalidraw sont possibles mais seront écrasées à la prochaine régénération.

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

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Diagrammes d'architecture Excalidraw (notation EIP)

Un diagramme est une petite spécification JSON — nœuds, arêtes, groupes — ainsi qu'un générateur qui la dispose dans la notation Hohpe & Woolf. La spécification est la source de vérité ; le fichier .excalidraw et le SVG de prévisualisation .svg sont des artefacts de build.

<skill-dir> ci-dessous est le répertoire dans lequel cette compétence est installée — par ex. ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture ou .agents/skills/excalidraw-architecture — et skills/excalidraw-architecture dans le dépôt https://github.com/jamescarr/diagram-skill.

Quand l'utiliser

  • Demander de schématiser, dessiner, croquer ou visualiser une architecture de service, d'événements ou de messagerie.
  • Expliquer comment un message se déplace : quel canal, quel point de terminaison, ce qui se passe en cas d'échec.
  • Documenter la surface d'intégration d'un contexte borné aux niveaux contexte, flux ou point de terminaison.
  • Examiner une conception orientée message où l'image doit révéler une DLQ manquante, un identifiant de corrélation ou une idempotence.

Ne pas utiliser

  • Maquettes UI, wireframes, présentations, tableaux blancs libres.
  • Diagrammes de séquence d'appels à l'intérieur d'un seul processus.
  • Tout ce dont le livrable n'est pas un fichier .excalidraw.

Workflow

  1. Inventaire — lister avant de dessiner :

    • participants : services, systèmes externes, acteurs, magasins ;
    • canaux : nom, point-à-point vs publication-abonnement, clé/partitions/ordonnancement, durabilité, DLQ ;
    • messages : nom (commande = impératif, événement = passé, document = nom) et type ;
    • points de terminaison par service : passerelle, boîte d'envoi/transaction, style de consommateur, nombre de concurrents, idempotence, durabilité, sélectivité ;
    • étapes de routage et de transformation ;
    • paires requête-réponse : canal de réponse, corrélation, TTL ;
    • gestion : écoute, magasin de messages, bus de contrôle. Lisez la compétence enterprise-integration-patterns, si elle est installée, lorsqu'un choix de motif n'est pas clair.
  2. Choisir le niveau — context : acteurs, services, systèmes externes, courtier en tant que message-bus, arêtes rpc/data. flow (par défaut) : un flux métier de bout en bout avec canaux et composants EIP. endpoint : à l'intérieur d'un service — passerelle → boîte d'envoi → canal, ou consommateur → récepteur idempotent → activateur. Un flux par diagramme, au plus 20 nœuds ; sinon, diviser par flux.

  3. Écrire la spécification — <nom>.spec.json à côté de l'emplacement du diagramme (par défaut docs/architecture/), en utilisant l'aide-mémoire ci-dessous. Exécutez node <skill-dir>/scripts/eip_excalidraw.mjs kinds pour le catalogue en direct.

  4. Construire — node <skill-dir>/scripts/eip_excalidraw.mjs build <nom>.spec.json écrit <nom>.excalidraw et <nom>.svg. Corrigez chaque error: (code de sortie 2) ; traitez warning: comme un défaut de disposition (--strict fait que les avertissements retournent 1). --check valide et dispose sans écrire. Ajoutez --png [SORTIE.png] pour également exporter un PNG rendu par Excalidraw lui-même (dessiné à la main, Excalifont, la scène intégrée dans le fichier pour pouvoir être déposée à nouveau sur excalidraw.com) — ce qu'un README, un document ou un article de blog devrait intégrer. Cela nécessite Chrome ou Chromium (CHROME remplace la recherche) et l'accès réseau à esm.sh ; il pilote le navigateur via scripts/export_png.mjs. Un export échoué quitte avec le code 3 et la scène est toujours écrite.

  5. Regarder — read <nom>.png si vous en avez construit un, sinon read <nom>.svg:img ; puis parcourez la liste de révision.

  6. Corriger — reconstruire après chaque modification de spécification :

    SymptômeModification de spécification
    une flèche croise un nœudroute: "ortho" ou "below", ou fixer row
    un libellé chevauche un nœudraccourcir message/label, ou éloigner le row du nœud de la flèche
    la pointe de flèche rétrécittrop de flèches tournent dans cet espace de colonne : router l'une below/above, ou fixer les row pour que moins de verticales la partagent
    encombrement de flèches arrièreroute: "above"
    la flèche de réponse boucle sous tout le diagrammeroute: "ortho", ou placer le canal de réponse à côté du canal de requête
    colonne surchargéeajouter des lanes, ou diviser le diagramme
    libellé de nœud longdéplacer les détails dans sub
    membres de groupe dispersésfixer col/row pour que les membres soient adjacents
    un cadre englobe un non-membrefixer col/row ou utiliser lanes pour que les membres du groupe forment un bloc contigu
  7. Livrer — le .spec.json, .excalidraw et .svg (ainsi que le .png si vous en avez construit un). Dites que la spécification est la source de vérité : régénérer après des modifications. Les modifications manuelles dans Excalidraw sont acceptables par la suite, mais une reconstruction les écrase.

Règles de modélisation

Chaque règle est une affirmation que le diagramme doit rendre visible ; lorsqu'elle ne peut pas être vraie, dessiner l'exception explicitement.

  • Chaque canal affiche son étiquette de type et ses étiquettes de clé/partition/ordonnancement (tags).
  • Chaque consommateur d'un canal au-moins-une-fois porte idempotent — ou le diagramme explique pourquoi pas. Les badges n'existent que sur les nœuds de type application, donc une saga, un routeur ou un agrégateur indique sa règle de déduplication dans sub (dedupe by orderId).
  • Chaque canal dont le consommateur peut échouer a une shadow dead-letter-channel ; les échecs de validation obtiennent un invalid-message-channel. Une DLQ qui n'est pas dessinée, ou volontairement absente, est indiquée dans le sub du canal ou dans une note.
  • Requête-réponse = une arête de commande avec reply_to et correlation, plus une arête de réponse en pointillés en retour.
  • Les nœuds agrégateur, scatter-gather et saga portent un sub avec la règle d'achèvement (nombre/délai).
  • Publication dans une transaction = un badge outbox ou un nœud outbox, jamais une publication nue après validation.
  • Les traducteurs se situent sur les frontières des contextes bornés (cadres).
  • Les consommateurs concurrents montrent competing:N ; les abonnements durables portent durable.
  • Les écoutes sont des arêtes tap vers un message-store.
  • Points de terminaison intelligents, canaux stupides : la logique de routage vit dans des nœuds routeur, jamais implicite dans un canal.
  • Les appels synchrones sont des arêtes rpc et sont l'exception, pas le défaut.
  • Les enregistrements internes franchissant une frontière obtiennent un content-filter, ou une référence claim-check.

Aide-mémoire de spécification

Nœuds par chapitre EIP — la table complète par type se trouve dans references/spec.md :

ChapitreTypesQuand l'utiliser
Canauxchannel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-busUn message se déplace entre participants ; choisir p2p vs pub-sub, puis le canal d'échec.
Messagesmessage command-message document-message event-messageLe message lui-même est le sujet, pas le point de terminaison.
Routagecontent-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager sagaUn message, plusieurs destinations possibles, ou des parties à réassembler.
Transformationmessage-translator envelope-wrapper content-enricher content-filter claim-check normalizerLa charge utile ou son enveloppe change entre les sauts.
Points de terminaisonmessage-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-adapterComment un service se connecte à un canal et le consomme.
Gestion systèmewire-tap detour message-history smart-proxy test-message channel-purgerObservabilité, sondes et opérations.
Infrastructuremessage-broker messaging-bridge outbox inboxLe courtier lui-même, les liaisons courtier-à-courtier, publication/consommation transactionnelle.
Participants et magasinsservice external-system actor datastore message-store schema-registry noteQui possède une extrémité de canal ; où vivent l'état, les schémas et les annotations.

Badges (nœuds de type application uniquement ; la pilule affiche le texte court) :

GroupeBadges
Point de terminaisongateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter)
Consommationpolling (Polling Consumer), event-driven (Event-Driven Consumer), competing / competing:N (Competing Consumers, affiche competing ×N sur une pile de jusqu'à trois boîtes), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber)
Transactiontx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver)
Résiliencebulkhead, retry, circuit-breaker — motifs de résilience, pas EIP

Arêtes :

Type d'arêteTraitLargeurTêtesMarqueur
message (sans type)continu #1e1e1e2→ arrowaucun
message type: commandcontinu2→ triangle«C»
message type: eventcontinu2→ arrow«E»
message type: documentcontinu2→ arrow«D»
message type: replypointillé2→ arrow«R»
rpccontinu1→ arrowaucun
datapointillé1→ arrowaucun
tappointillé1circle → arrowaucun
dlqpointillé #c92a2a1→ arrowaucun
controlpointillé #868e961┤ baraucun

Champs d'arête : from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. Champs de nœud : id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.

Liste de vérification de révision

  • Titre présent ; il nomme le flux, pas tout le système.
  • Chaque flèche est étiquetée avec un message ou un appel.
  • Chaque canal porte son étiquette de type et ses étiquettes de clé/partition.
  • La décision DLQ est visible pour chaque canal.
  • Légende présente lorsque plus de 6 types apparaissent.
  • Aucun warning: restant de la construction.
  • Les cadres de groupe contiennent uniquement leurs membres.
  • Au plus 20 nœuds.

Mappage de pile

PileDessiner comme
Sujet Kafkapubsub-channel ; groupe de consommateurs → competing:N ; abonnement durable → durable
File RabbitMQp2p-channel ; échange → message-broker ou content-based-router ; DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
Règle EventBridgecontent-based-router
Step Functionsprocess-manager ou saga
Consommateur Lambdaservice avec event-driven
Base de donnéesdatastore ; copies d'audit/rejeu → message-store
API partenaireexternal-system, pointillé

Modifications manuelles

references/excalidraw-format.md liste les invariants JSON qui maintiennent les liaisons, le texte et les cadres d'Excalidraw valides après une modification manuelle.

Skills associés