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
-
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.
-
Choisir le niveau —
context: acteurs, services, systèmes externes, courtier en tant quemessage-bus, arêtesrpc/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. -
Écrire la spécification —
<nom>.spec.jsonà côté de l'emplacement du diagramme (par défautdocs/architecture/), en utilisant l'aide-mémoire ci-dessous. Exécuteznode <skill-dir>/scripts/eip_excalidraw.mjs kindspour le catalogue en direct. -
Construire —
node <skill-dir>/scripts/eip_excalidraw.mjs build <nom>.spec.jsonécrit<nom>.excalidrawet<nom>.svg. Corrigez chaqueerror:(code de sortie 2) ; traitezwarning:comme un défaut de disposition (--strictfait que les avertissements retournent 1).--checkvalide 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 (CHROMEremplace la recherche) et l'accès réseau à esm.sh ; il pilote le navigateur viascripts/export_png.mjs. Un export échoué quitte avec le code 3 et la scène est toujours écrite. -
Regarder —
read <nom>.pngsi vous en avez construit un, sinonread <nom>.svg:img; puis parcourez la liste de révision. -
Corriger — reconstruire après chaque modification de spécification :
Symptôme Modification de spécification une flèche croise un nœud route: "ortho"ou"below", ou fixerrowun libellé chevauche un nœud raccourcir message/label, ou éloigner lerowdu nœud de la flèchela pointe de flèche rétrécit trop de flèches tournent dans cet espace de colonne : router l'une below/above, ou fixer lesrowpour que moins de verticales la partagentencombrement de flèches arrière route: "above"la flèche de réponse boucle sous tout le diagramme route: "ortho", ou placer le canal de réponse à côté du canal de requêtecolonne surchargée ajouter des lanes, ou diviser le diagrammelibellé de nœud long déplacer les détails dans submembres de groupe dispersés fixer col/rowpour que les membres soient adjacentsun cadre englobe un non-membre fixer col/rowou utiliserlanespour que les membres du groupe forment un bloc contigu -
Livrer — le
.spec.json,.excalidrawet.svg(ainsi que le.pngsi 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 danssub(dedupe by orderId). - Chaque canal dont le consommateur peut échouer a une
shadowdead-letter-channel; les échecs de validation obtiennent uninvalid-message-channel. Une DLQ qui n'est pas dessinée, ou volontairement absente, est indiquée dans lesubdu canal ou dans unenote. - Requête-réponse = une arête de commande avec
reply_toetcorrelation, plus une arête de réponse en pointillés en retour. - Les nœuds agrégateur, scatter-gather et saga portent un
subavec la règle d'achèvement (nombre/délai). - Publication dans une transaction = un badge
outboxou un nœudoutbox, 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 portentdurable. - Les écoutes sont des arêtes
tapvers unmessage-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
rpcet sont l'exception, pas le défaut. - Les enregistrements internes franchissant une frontière obtiennent un
content-filter, ou une référenceclaim-check.
Aide-mémoire de spécification
Nœuds par chapitre EIP — la table complète par type se trouve dans references/spec.md :
| Chapitre | Types | Quand l'utiliser |
|---|---|---|
| Canaux | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | Un message se déplace entre participants ; choisir p2p vs pub-sub, puis le canal d'échec. |
| Messages | message command-message document-message event-message | Le message lui-même est le sujet, pas le point de terminaison. |
| Routage | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | Un message, plusieurs destinations possibles, ou des parties à réassembler. |
| Transformation | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | La charge utile ou son enveloppe change entre les sauts. |
| Points de terminaison | 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 | Comment un service se connecte à un canal et le consomme. |
| Gestion système | wire-tap detour message-history smart-proxy test-message channel-purger | Observabilité, sondes et opérations. |
| Infrastructure | message-broker messaging-bridge outbox inbox | Le courtier lui-même, les liaisons courtier-à-courtier, publication/consommation transactionnelle. |
| Participants et magasins | service external-system actor datastore message-store schema-registry note | Qui 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) :
| Groupe | Badges |
|---|---|
| Point de terminaison | gateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter) |
| Consommation | polling (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) |
| Transaction | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| Résilience | bulkhead, retry, circuit-breaker — motifs de résilience, pas EIP |
Arêtes :
| Type d'arête | Trait | Largeur | Têtes | Marqueur |
|---|---|---|---|---|
message (sans type) | continu #1e1e1e | 2 | → arrow | aucun |
message type: command | continu | 2 | → triangle | «C» |
message type: event | continu | 2 | → arrow | «E» |
message type: document | continu | 2 | → arrow | «D» |
message type: reply | pointillé | 2 | → arrow | «R» |
rpc | continu | 1 | → arrow | aucun |
data | pointillé | 1 | → arrow | aucun |
tap | pointillé | 1 | circle → arrow | aucun |
dlq | pointillé #c92a2a | 1 | → arrow | aucun |
control | pointillé #868e96 | 1 | ┤ bar | aucun |
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
| Pile | Dessiner comme |
|---|---|
| Sujet Kafka | pubsub-channel ; groupe de consommateurs → competing:N ; abonnement durable → durable |
| File RabbitMQ | p2p-channel ; échange → message-broker ou content-based-router ; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| Règle EventBridge | content-based-router |
| Step Functions | process-manager ou saga |
| Consommateur Lambda | service avec event-driven |
| Base de données | datastore ; copies d'audit/rejeu → message-store |
| API partenaire | external-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.