Diagramas de arquitectura Excalidraw (notación EIP)
Un diagrama es una especificación JSON pequeña (nodos, aristas, grupos) más un generador que la distribuye en notación de Hohpe & Woolf. La especificación es la fuente de verdad; el archivo .excalidraw y el .svg de vista previa son artefactos de compilación.
<skill-dir> a continuación es el directorio donde está instalada esta skill — p. ej. ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture o .agents/skills/excalidraw-architecture— y skills/excalidraw-architecture en el repositorio https://github.com/jamescarr/diagram-skill.
Cuándo usarla
- Se pide diagramar, dibujar, bosquejar o visualizar una arquitectura de servicio, evento o mensajería.
- Explicar cómo viaja un mensaje: qué canal, qué punto final, qué sucede cuando falla.
- Documentar la superficie de integración de un contexto delimitado a nivel de contexto, flujo o punto final.
- Revisar un diseño orientado a mensajes donde la imagen debe revelar una DLQ faltante, un ID de correlación o idempotencia.
No usar para
- Maquetas de UI, wireframes, presentaciones de diapositivas, pizarra libre.
- Diagramas de secuencia de llamadas dentro de un solo proceso.
- Cualquier cosa cuyo entregable no sea un archivo
.excalidraw.
Flujo de trabajo
-
Inventario — enumerar antes de dibujar:
- participantes: servicios, sistemas externos, actores, almacenes;
- canales: nombre, punto a punto vs publicación-suscripción, clave/particiones/ordenamiento, durabilidad, DLQ;
- mensajes: nombre (comando = imperativo, evento = tiempo pasado, documento = sustantivo) y tipo;
- puntos finales por servicio: puerta de enlace, bandeja de salida/transacción, estilo de consumidor, número de competidores, idempotencia, durabilidad, selectividad;
- pasos de enrutamiento y transformación;
- pares solicitud-respuesta: canal de respuesta, correlación, TTL;
- gestión: escucha, almacén, bus de control.
Lee la skill
enterprise-integration-patterns, si la tienes instalada, cuando una elección de patrón no esté clara.
-
Elegir el nivel —
context: actores, servicios, sistemas externos, broker comomessage-bus, aristasrpc/data.flow(el predeterminado): un flujo de negocio de extremo a extremo con canales y componentes EIP.endpoint: dentro de un servicio — puerta de enlace → bandeja de salida → canal, o consumidor → receptor idempotente → activador. Un flujo por diagrama, como máximo 20 nodos; dividir por flujo en caso contrario. -
Escribir la especificación —
<nombre>.spec.jsonjunto a donde vivirá el diagrama (por defectodocs/architecture/), usando la chuleta a continuación. Ejecutarnode <skill-dir>/scripts/eip_excalidraw.mjs kindspara el catálogo en vivo. -
Compilar —
node <skill-dir>/scripts/eip_excalidraw.mjs build <nombre>.spec.jsonescribe<nombre>.excalidrawy<nombre>.svg. Corregir cadaerror:(salida 2); tratarwarning:como un defecto de diseño (--stricthace que las advertencias salgan con 1).--checkvalida y diseña sin escribir. Añadir--png [SALIDA.png]para exportar también un PNG renderizado por el propio Excalidraw (dibujado a mano, Excalifont, la escena incrustada en el archivo para poder arrastrarla de vuelta a excalidraw.com) — lo que un README, un documento o una entrada de blog debería incrustar. Necesita Chrome o Chromium (CHROMEanula la búsqueda) y acceso de red a esm.sh; controla el navegador mediantescripts/export_png.mjs. Una exportación fallida sale con 3 y la escena aún se escribe. -
Mirar —
read <nombre>.pngsi has compilado uno, si noread <nombre>.svg:img; luego repasar la lista de revisión. -
Corregir — recompilar después de cada cambio en la especificación:
Síntoma Cambio en la especificación flecha cruza un nodo route: "ortho"o"below", o fijarrowetiqueta se superpone a un nodo acortar message/label, o fijar larowdel nodo lejos de la flechapunta de flecha se encoge demasiadas flechas giran en ese espacio de columna: enrutar una below/above, o fijarrows para que menos verticales la compartandesorden de flechas hacia atrás route: "above"flecha de respuesta hace un bucle bajo todo el diagrama route: "ortho", o poner el canal de respuesta junto al canal de solicitudcolumna abarrotada añadir lanes, o dividir el diagramaetiqueta de nodo larga mover el detalle a submiembros del grupo dispersos fijar col/rowpara que los miembros sean adyacentesmarco encierra a un no miembro fijar col/rowo usarlanespara que los miembros del grupo formen un bloque contiguo -
Entregar — el
.spec.json,.excalidrawy.svg(más el.pngsi has compilado uno). Decir que la especificación es la fuente de verdad: regenerar después de ediciones. Las ediciones manuales en Excalidraw están bien después, pero una recompilación las sobrescribe.
Reglas de modelado
Cada regla es una afirmación que el diagrama debe hacer visible; cuando no pueda ser cierta, dibujar la excepción explícitamente.
- Cada canal muestra su etiqueta de tipo y sus etiquetas de clave/partición/ordenamiento (
tags). - Cada consumidor de un canal "al menos una vez" lleva
idempotent— o el diagrama dice por qué no. Las insignias existen solo en nodos de tipo aplicación, así que un saga, enrutador o agregador indica su regla de deduplicación ensub(dedupe by orderId). - Cada canal cuyo consumidor puede fallar tiene una
shadowdead-letter-channel; las fallas de validación tienen uninvalid-message-channel. Una DLQ que no se dibuja, o que está deliberadamente ausente, se indica en elsubdel canal o en unnote. - Solicitud-respuesta = una arista de comando con
reply_toycorrelation, más una arista de respuesta discontinua de vuelta. - Los nodos Agregador, Scatter-Gather y Saga llevan un
subcon la regla de finalización (cantidad/tiempo de espera). - Publicar dentro de una transacción = una insignia
outboxo un nodooutbox, nunca una publicación desnuda después del commit. - Los traductores se sientan en los bordes del contexto delimitado (marcos).
- Los consumidores competidores muestran
competing:N; las suscripciones duraderas llevandurable. - Las escuchas (wire taps) son aristas
taphacia unmessage-store. - Puntos finales inteligentes, tuberías tontas: la lógica de enrutamiento vive en nodos enrutadores, nunca implícita dentro de un canal.
- Las llamadas síncronas son aristas
rpcy son la excepción, no el valor predeterminado. - Los registros internos que cruzan un límite obtienen un
content-filter, o una referenciaclaim-check.
Chuleta de la especificación
Nodos por capítulo de EIP — la tabla completa tipo por tipo está en references/spec.md:
| Capítulo | Tipos | Cuándo usarlos |
|---|---|---|
| Canales | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | Un mensaje se mueve entre participantes; elegir p2p vs pub-sub, luego el canal de fallo. |
| Mensajes | message command-message document-message event-message | El mensaje mismo es el sujeto, no el punto final. |
| Enrutamiento | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | Un mensaje, varios destinos posibles, o partes para reensamblar. |
| Transformación | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | La carga útil o su envoltura cambia entre saltos. |
| Puntos finales | 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 | Cómo un servicio se conecta a un canal y lo consume. |
| Gestión del sistema | wire-tap detour message-history smart-proxy test-message channel-purger | Observabilidad, sondas y operaciones. |
| Infraestructura | message-broker messaging-bridge outbox inbox | El propio broker, enlaces broker-a-broker, publicación/consumo transaccional. |
| Participantes y almacenes | service external-system actor datastore message-store schema-registry note | Quién posee un extremo de canal; dónde viven el estado, los esquemas y las anotaciones. |
Insignias (solo nodos de tipo aplicación; la píldora muestra el texto corto):
| Grupo | Insignias |
|---|---|
| Punto final | gateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter) |
| Consumo | polling (Polling Consumer), event-driven (Event-Driven Consumer), competing / competing:N (Competing Consumers, muestra competing ×N en una pila de hasta tres cajas), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber) |
| Transacción | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| Resiliencia | bulkhead, retry, circuit-breaker — patrones de resiliencia, no EIP |
Aristas:
| Tipo de arista | Trazo | Ancho | Cabezas | Marcador |
|---|---|---|---|---|
message (sin tipo) | sólido #1e1e1e | 2 | → arrow | ninguno |
message type: command | sólido | 2 | → triangle | «C» |
message type: event | sólido | 2 | → arrow | «E» |
message type: document | sólido | 2 | → arrow | «D» |
message type: reply | discontinuo | 2 | → arrow | «R» |
rpc | sólido | 1 | → arrow | ninguno |
data | punteado | 1 | → arrow | ninguno |
tap | punteado | 1 | circle → arrow | ninguno |
dlq | discontinuo #c92a2a | 1 | → arrow | ninguno |
control | discontinuo #868e96 | 1 | ┤ bar | ninguno |
Campos de arista: from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. Campos de nodo: id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.
Lista de verificación de revisión
- Título presente; nombra el flujo, no todo el sistema.
- Cada flecha está etiquetada con un mensaje o una llamada.
- Cada canal lleva su etiqueta de tipo y sus etiquetas de clave/partición.
- La decisión de DLQ es visible para cada canal.
- Leyenda presente cuando aparecen más de 6 tipos.
- No queda ningún
warning:de la compilación. - Los marcos de grupo contienen solo a sus miembros.
- Como máximo 20 nodos.
Mapeo de pilas
| Pila | Dibujar como |
|---|---|
| Tópico Kafka | pubsub-channel; grupo de consumidores → competing:N; suscripción duradera → durable |
| Cola RabbitMQ | p2p-channel; exchange → message-broker o content-based-router; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| Regla de EventBridge | content-based-router |
| Step Functions | process-manager o saga |
| Consumidor Lambda | service con event-driven |
| Base de datos | datastore; copias de auditoría/reproducción → message-store |
| API de socio | external-system, discontinuo |
Ediciones manuales
references/excalidraw-format.md enumera los invariantes JSON que mantienen válidos los enlaces, texto y marcos de Excalidraw después de una edición manual.