Diagramas de arquitetura no Excalidraw (notação EIP)
Um diagrama é uma pequena especificação JSON — nós, arestas, grupos — mais um gerador que a organiza na notação Hohpe & Woolf. A especificação é a fonte da verdade; o arquivo .excalidraw e a pré-visualização .svg são artefatos de build.
<skill-dir> abaixo é o diretório onde este skill está instalado — por exemplo, ~/.omp/agent/skills/excalidraw-architecture, ~/.claude/skills/excalidraw-architecture ou .agents/skills/excalidraw-architecture — e skills/excalidraw-architecture no repositório https://github.com/jamescarr/diagram-skill.
Quando usar
- Quando solicitado a diagramar, desenhar, esboçar ou visualizar uma arquitetura de serviço, evento ou mensageria.
- Explicando como uma mensagem viaja: qual canal, qual endpoint, o que acontece quando falha.
- Documentando a superfície de integração de um contexto limitado nos níveis de contexto, fluxo ou endpoint.
- Revisando um design orientado a mensagens onde a imagem deve expor uma DLQ, correlation id ou idempotência ausentes.
Não use
- Mockups de UI, wireframes, apresentações de slides, quadros brancos livres.
- Diagramas de sequência de chamadas dentro de um processo.
- Qualquer coisa cuja entrega não seja um arquivo
.excalidraw.
Fluxo de trabalho
-
Inventário — liste antes de desenhar:
- participantes: serviços, sistemas externos, atores, armazenamentos;
- canais: nome, ponto-a-ponto vs publish-subscribe, chave/partições/ordenação, durabilidade, DLQ;
- mensagens: nome (comando = imperativo, evento = passado, documento = substantivo) e tipo;
- endpoints por serviço: gateway, outbox/transação, estilo de consumidor, contagem de concorrência, idempotência, durabilidade, seletividade;
- etapas de roteamento e transformação;
- pares requisição-resposta: canal de resposta, correlação, TTL;
- gerenciamento: wire tap, armazenamento, barramento de controle.
Leia o skill
enterprise-integration-patterns, se estiver instalado, quando uma escolha de padrão não estiver clara.
-
Escolha o nível —
context: atores, serviços, sistemas externos, broker comomessage-bus, arestasrpc/data.flow(o padrão): um fluxo de negócio completo com canais e componentes EIP.endpoint: dentro de um serviço — gateway → outbox → canal, ou consumidor → receptor idempotente → ativador. Um fluxo por diagrama, no máximo 20 nós; divida por fluxo caso contrário. -
Escreva a especificação —
<nome>.spec.jsonao lado de onde o diagrama ficará (padrãodocs/architecture/), usando a cola abaixo. Executenode <skill-dir>/scripts/eip_excalidraw.mjs kindspara o catálogo ao vivo. -
Construa —
node <skill-dir>/scripts/eip_excalidraw.mjs build <nome>.spec.jsonescreve<nome>.excalidrawe<nome>.svg. Corrija todoerror:(saída 2); tratewarning:como um defeito de layout (--strictfaz warnings saírem com 1).--checkvalida e organiza sem escrever. Adicione--png [SAIDA.png]para também exportar um PNG renderizado pelo próprio Excalidraw (desenhado à mão, Excalifont, a cena incorporada no arquivo para que possa ser colocada de volta no excalidraw.com) — o que um README, um documento ou uma postagem de blog devem incorporar. Precisa do Chrome ou Chromium (CHROMEsubstitui a busca) e acesso de rede ao esm.sh; ele dirige o navegador através descripts/export_png.mjs. Uma exportação falha sai com 3 e a cena ainda é escrita. -
Observe —
read <nome>.pngquando você construiu um, caso contrárioread <nome>.svg:img; então percorra a lista de revisão. -
Corrija — reconstrua após cada alteração na especificação:
Sintoma Mudança na especificação seta cruza um nó route: "ortho"ou"below", ou fixerowrótulo sobrepõe um nó encurte message/label, ou fixe arowdo nó para longe da setaponta de seta encolhe muitas setas na mesma lacuna de coluna: roteie uma below/above, ou fixerows para que menos verticais compartilhemdesordem de setas para trás route: "above"seta de resposta faz um loop sob todo o diagrama route: "ortho", ou coloque o canal de resposta próximo ao canal de requisiçãocoluna lotada adicione lanes, ou divida o diagramarótulo longo do nó mova detalhes para submembros do grupo espalhados fixe col/rowpara que os membros fiquem adjacentesmoldura envolve um não-membro fixe col/rowou uselanespara que os membros do grupo formem um bloco contíguo -
Entregue — o
.spec.json,.excalidrawe.svg(mais o.pngquando você construiu um). Diga que a especificação é a fonte da verdade: regenere após edições. Edições manuais no Excalidraw são aceitáveis depois, mas uma reconstrução as substitui.
Regras de modelagem
Cada regra é uma afirmação que o diagrama deve tornar visível; quando não puder ser verdadeira, desenhe a exceção explicitamente.
- Todo canal mostra sua tag de tipo e suas tags de chave/partição/ordenação (
tags). - Todo consumidor de um canal pelo menos uma vez usa
idempotent— ou o diagrama diz por que não. Emblemas existem apenas em nós da família de aplicação, então uma saga, roteador ou agregador declara sua regra de deduplicação emsub(dedupe by orderId). - Todo canal cujo consumidor pode falhar tem um
shadowdead-letter-channel; falhas de validação recebem uminvalid-message-channel. Uma DLQ que não é desenhada, ou deliberadamente ausente, é declarada nosubdo canal ou em umnote. - Requisição-resposta = uma aresta de comando com
reply_toecorrelation, mais uma aresta de resposta tracejada de volta. - Agregador, scatter-gather e saga carregam um
subcom a regra de conclusão (contagem/timeout). - Publicar dentro de uma transação = um emblema
outboxou nóoutbox, nunca uma publicação pura após o commit. - Tradutores ficam nas bordas dos contextos limitados (molduras).
- Consumidores concorrentes mostram
competing:N; assinaturas duráveis usamdurable. - Wire taps são arestas
tappara ummessage-store. - Endpoints inteligentes, pipes burros: a lógica de roteamento vive em nós de roteador, nunca implícita dentro de um canal.
- Chamadas síncronas são arestas
rpce são a exceção, não o padrão. - Registros internos que cruzam um limite recebem um
content-filter, ou uma referênciaclaim-check.
Cola da especificação
Nós por capítulo EIP — a tabela completa tipo por tipo está em references/spec.md:
| Capítulo | Tipos | Use quando |
|---|---|---|
| Canais | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | Uma mensagem se move entre participantes; escolha p2p vs pub-sub, depois o canal de falha. |
| Mensagens | message command-message document-message event-message | A própria mensagem é o assunto, não o endpoint. |
| Roteamento | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | Uma mensagem, vários destinos possíveis, ou partes para remontar. |
| Transformação | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | A carga ou seu envelope muda entre saltos. |
| Endpoints | 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 | Como um serviço se conecta a um canal e o consome. |
| Gerenciamento de sistema | wire-tap detour message-history smart-proxy test-message channel-purger | Observabilidade, sondas e operações. |
| Infraestrutura | message-broker messaging-bridge outbox inbox | O próprio broker, links entre brokers, publicação/consumo transacional. |
| Participantes e armazenamentos | service external-system actor datastore message-store schema-registry note | Quem possui uma extremidade de canal; onde estado, esquemas e anotações vivem. |
Emblemas (apenas nós da família de aplicação; a pílula renderiza o texto curto):
| Grupo | Emblemas |
|---|---|
| Endpoint | 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, renderiza competing ×N em uma pilha de até três caixas), dispatcher (Message Dispatcher), selective (Selective Consumer), durable (Durable Subscriber) |
| Transação | tx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver) |
| Resiliência | bulkhead, retry, circuit-breaker — padrões de resiliência, não EIP |
Arestas:
| Tipo de aresta | Traço | Largura | Pontas | Marcador |
|---|---|---|---|---|
message (sem tipo) | sólida #1e1e1e | 2 | → arrow | nenhum |
message type: command | sólida | 2 | → triangle | «C» |
message type: event | sólida | 2 | → arrow | «E» |
message type: document | sólida | 2 | → arrow | «D» |
message type: reply | tracejada | 2 | → arrow | «R» |
rpc | sólida | 1 | → arrow | nenhum |
data | pontilhada | 1 | → arrow | nenhum |
tap | pontilhada | 1 | circle → arrow | nenhum |
dlq | tracejada #c92a2a | 1 | → arrow | nenhum |
control | tracejada #868e96 | 1 | ┤ bar | nenhum |
Campos da aresta: from, to, kind, type, message, label, seq, route, correlation, reply_to, ttl, sequence, style, color. Campos do nó: id, kind, label, sub, badges, tags, group, lane, col, row, shadow, attach, link.
Lista de verificação de revisão
- Título presente; nomeia o fluxo, não todo o sistema.
- Toda seta está rotulada com uma mensagem ou uma chamada.
- Todo canal carrega sua tag de tipo e suas tags de chave/partição.
- A decisão de DLQ está visível para cada canal.
- Legenda presente quando mais de 6 tipos aparecem.
- Nenhum
warning:restante do build. - Molduras de grupo contêm apenas seus membros.
- No máximo 20 nós.
Mapeamento de pilhas
| Pilha | Desenhe como |
|---|---|
| Tópico Kafka | pubsub-channel; grupo de consumidores → competing:N; assinatura durável → durable |
| Fila RabbitMQ | p2p-channel; exchange → message-broker ou content-based-router; DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| Regra EventBridge | content-based-router |
| Step Functions | process-manager ou saga |
| Consumidor Lambda | service com event-driven |
| Banco de dados | datastore; cópias de auditoria/reprodução → message-store |
| API de parceiro | external-system, tracejada |
Edições manuais
references/excalidraw-format.md lista os invariantes JSON que mantêm as ligações, texto e molduras do Excalidraw válidos após uma edição manual.