CommunityImagengithub.com

diagramas-excalidraw-architecture

Se usa cuando se pide diagramar, dibujar, bosquejar o visualizar una arquitectura de software, flujo de mensajes, sistemas basados en eventos o microservicios en Excalidraw. Produce archivos .excalidraw en notación de Patrones de Integración Empresarial (canales, enrutadores, traductores, puntos finales, DLQ, sagas) a partir de una especificación JSON pequeña mediante scripts/eip_excalidraw.mjs, con un SVG de vista previa y una verificación de renderizado. No sirve para maquetas de UI, presentaciones de diapositivas ni pizarra libre.

¿Qué es diagramas-excalidraw-architecture?

Esta habilidad permite a un agente de IA generar diagramas de arquitectura de software en formato Excalidraw utilizando la notación de Patrones de Integración Empresarial (EIP) de Hohpe & Woolf, a partir de una especificación JSON simple. Está diseñada para documentar flujos de mensajes, canales, enrutadores, transformadores, puntos finales y otros componentes de sistemas distribuidos, y produce archivos `.excalidraw` y `.svg` (y opcionalmente `.png`) como artefactos de compilación. La habilidad se ejecuta mediante un script Node.js (`eip_excalidraw.mjs`) que lee el archivo de especificación, valida el diseño y genera el diagrama con posicionamiento automático de nodos y rutas de flechas. Incluye reglas de modelado explícitas (por ejemplo, que todo canal muestre su tipo y claves, que todo consumidor de un canal 'al menos una vez' sea idempotente) y una lista de verificación de revisión. Funciona en agentes como Claude Code, Cursor y Codex, así como en cualquier entorno que soporte la instalación de skills. Es útil para arquitectos y desarrolladores que necesitan comunicar visualmente diseños de mensajería, integraciones y sistemas basados en eventos de manera precisa y consistente.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

  1. 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.
  2. Elegir el nivel — context: actores, servicios, sistemas externos, broker como message-bus, aristas rpc/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.

  3. Escribir la especificación — <nombre>.spec.json junto a donde vivirá el diagrama (por defecto docs/architecture/), usando la chuleta a continuación. Ejecutar node <skill-dir>/scripts/eip_excalidraw.mjs kinds para el catálogo en vivo.

  4. Compilar — node <skill-dir>/scripts/eip_excalidraw.mjs build <nombre>.spec.json escribe <nombre>.excalidraw y <nombre>.svg. Corregir cada error: (salida 2); tratar warning: como un defecto de diseño (--strict hace que las advertencias salgan con 1). --check valida 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 (CHROME anula la búsqueda) y acceso de red a esm.sh; controla el navegador mediante scripts/export_png.mjs. Una exportación fallida sale con 3 y la escena aún se escribe.

  5. Mirar — read <nombre>.png si has compilado uno, si no read <nombre>.svg:img; luego repasar la lista de revisión.

  6. Corregir — recompilar después de cada cambio en la especificación:

    SíntomaCambio en la especificación
    flecha cruza un nodoroute: "ortho" o "below", o fijar row
    etiqueta se superpone a un nodoacortar message/label, o fijar la row del nodo lejos de la flecha
    punta de flecha se encogedemasiadas flechas giran en ese espacio de columna: enrutar una below/above, o fijar rows para que menos verticales la compartan
    desorden de flechas hacia atrásroute: "above"
    flecha de respuesta hace un bucle bajo todo el diagramaroute: "ortho", o poner el canal de respuesta junto al canal de solicitud
    columna abarrotadaañadir lanes, o dividir el diagrama
    etiqueta de nodo largamover el detalle a sub
    miembros del grupo dispersosfijar col/row para que los miembros sean adyacentes
    marco encierra a un no miembrofijar col/row o usar lanes para que los miembros del grupo formen un bloque contiguo
  7. Entregar — el .spec.json, .excalidraw y .svg (más el .png si 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 en sub (dedupe by orderId).
  • Cada canal cuyo consumidor puede fallar tiene una shadow dead-letter-channel; las fallas de validación tienen un invalid-message-channel. Una DLQ que no se dibuja, o que está deliberadamente ausente, se indica en el sub del canal o en un note.
  • Solicitud-respuesta = una arista de comando con reply_to y correlation, más una arista de respuesta discontinua de vuelta.
  • Los nodos Agregador, Scatter-Gather y Saga llevan un sub con la regla de finalización (cantidad/tiempo de espera).
  • Publicar dentro de una transacción = una insignia outbox o un nodo outbox, 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 llevan durable.
  • Las escuchas (wire taps) son aristas tap hacia un message-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 rpc y son la excepción, no el valor predeterminado.
  • Los registros internos que cruzan un límite obtienen un content-filter, o una referencia claim-check.

Chuleta de la especificación

Nodos por capítulo de EIP — la tabla completa tipo por tipo está en references/spec.md:

CapítuloTiposCuándo usarlos
Canaleschannel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-busUn mensaje se mueve entre participantes; elegir p2p vs pub-sub, luego el canal de fallo.
Mensajesmessage command-message document-message event-messageEl mensaje mismo es el sujeto, no el punto final.
Enrutamientocontent-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager sagaUn mensaje, varios destinos posibles, o partes para reensamblar.
Transformaciónmessage-translator envelope-wrapper content-enricher content-filter claim-check normalizerLa carga útil o su envoltura cambia entre saltos.
Puntos finalesmessage-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-adapterCómo un servicio se conecta a un canal y lo consume.
Gestión del sistemawire-tap detour message-history smart-proxy test-message channel-purgerObservabilidad, sondas y operaciones.
Infraestructuramessage-broker messaging-bridge outbox inboxEl propio broker, enlaces broker-a-broker, publicación/consumo transaccional.
Participantes y almacenesservice external-system actor datastore message-store schema-registry noteQuié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):

GrupoInsignias
Punto finalgateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter)
Consumopolling (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óntx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver)
Resilienciabulkhead, retry, circuit-breaker — patrones de resiliencia, no EIP

Aristas:

Tipo de aristaTrazoAnchoCabezasMarcador
message (sin tipo)sólido #1e1e1e2→ arrowninguno
message type: commandsólido2→ triangle«C»
message type: eventsólido2→ arrow«E»
message type: documentsólido2→ arrow«D»
message type: replydiscontinuo2→ arrow«R»
rpcsólido1→ arrowninguno
datapunteado1→ arrowninguno
tappunteado1circle → arrowninguno
dlqdiscontinuo #c92a2a1→ arrowninguno
controldiscontinuo #868e961┤ barninguno

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

PilaDibujar como
Tópico Kafkapubsub-channel; grupo de consumidores → competing:N; suscripción duradera → durable
Cola RabbitMQp2p-channel; exchange → message-broker o content-based-router; DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
Regla de EventBridgecontent-based-router
Step Functionsprocess-manager o saga
Consumidor Lambdaservice con event-driven
Base de datosdatastore; copias de auditoría/reproducción → message-store
API de socioexternal-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.

Skills relacionados