CommunityImagemgithub.com

excalidraw-architecture

Use para diagramar, desenhar, esboçar ou visualizar arquiteturas de software, fluxos de mensagens, sistemas orientados a eventos ou microsserviços no Excalidraw. Produz arquivos .excalidraw na notação Enterprise Integration Patterns (canais, roteadores, tradutores, endpoints, DLQs, sagas) a partir de uma especificação JSON via scripts/eip_excalidraw.mjs, com uma pré-visualização SVG e verificação de renderização. Não para mockups de UI, apresentações de slides ou quadros brancos livres.

O que é excalidraw-architecture?

Este skill permite que você crie diagramas de arquitetura precisos no Excalidraw usando a notação Enterprise Integration Patterns (EIP). Em vez de arrastar elementos manualmente, você define um arquivo de especificação JSON contendo nós, arestas e grupos, e uma ferramenta de geração de código produz os arquivos .excalidraw e .svg automaticamente. O skill é útil para engenheiros de software que precisam documentar fluxos de mensagens, sistemas orientados a eventos, microsserviços e integrações. Ele oferece suporte a uma ampla variedade de padrões EIP, incluindo canais point-to-point e publish-subscribe, roteadores, tradutores, endpoints e padrões de gerenciamento de sistema. Além disso, você pode exportar uma imagem PNG renderizada pelo Excalidraw, ideal para incluir em READMEs, documentação ou postagens de blog. O skill inclui um fluxo de trabalho passo a passo: fazer um inventário dos participantes e canais, escolher o nível de detalhe (contexto, fluxo ou endpoint), escrever a especificação JSON, construir o diagrama, inspecioná-lo e corrigir problemas usando uma tabela de sintomas e soluções comuns. Uma lista de verificação de revisão garante que o diagrama final seja completo e claro.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. 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.
  2. Escolha o nível — context: atores, serviços, sistemas externos, broker como message-bus, arestas rpc/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.

  3. Escreva a especificação — <nome>.spec.json ao lado de onde o diagrama ficará (padrão docs/architecture/), usando a cola abaixo. Execute node <skill-dir>/scripts/eip_excalidraw.mjs kinds para o catálogo ao vivo.

  4. Construa — node <skill-dir>/scripts/eip_excalidraw.mjs build <nome>.spec.json escreve <nome>.excalidraw e <nome>.svg. Corrija todo error: (saída 2); trate warning: como um defeito de layout (--strict faz warnings saírem com 1). --check valida 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 (CHROME substitui a busca) e acesso de rede ao esm.sh; ele dirige o navegador através de scripts/export_png.mjs. Uma exportação falha sai com 3 e a cena ainda é escrita.

  5. Observe — read <nome>.png quando você construiu um, caso contrário read <nome>.svg:img; então percorra a lista de revisão.

  6. Corrija — reconstrua após cada alteração na especificação:

    SintomaMudança na especificação
    seta cruza um nóroute: "ortho" ou "below", ou fixe row
    rótulo sobrepõe um nóencurte message/label, ou fixe a row do nó para longe da seta
    ponta de seta encolhemuitas setas na mesma lacuna de coluna: roteie uma below/above, ou fixe rows para que menos verticais compartilhem
    desordem de setas para trásroute: "above"
    seta de resposta faz um loop sob todo o diagramaroute: "ortho", ou coloque o canal de resposta próximo ao canal de requisição
    coluna lotadaadicione lanes, ou divida o diagrama
    rótulo longo do nómova detalhes para sub
    membros do grupo espalhadosfixe col/row para que os membros fiquem adjacentes
    moldura envolve um não-membrofixe col/row ou use lanes para que os membros do grupo formem um bloco contíguo
  7. Entregue — o .spec.json, .excalidraw e .svg (mais o .png quando 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 em sub (dedupe by orderId).
  • Todo canal cujo consumidor pode falhar tem um shadow dead-letter-channel; falhas de validação recebem um invalid-message-channel. Uma DLQ que não é desenhada, ou deliberadamente ausente, é declarada no sub do canal ou em um note.
  • Requisição-resposta = uma aresta de comando com reply_to e correlation, mais uma aresta de resposta tracejada de volta.
  • Agregador, scatter-gather e saga carregam um sub com a regra de conclusão (contagem/timeout).
  • Publicar dentro de uma transação = um emblema outbox ou 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 usam durable.
  • Wire taps são arestas tap para um message-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 rpc e são a exceção, não o padrão.
  • Registros internos que cruzam um limite recebem um content-filter, ou uma referência claim-check.

Cola da especificação

Nós por capítulo EIP — a tabela completa tipo por tipo está em references/spec.md:

CapítuloTiposUse quando
Canaischannel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-busUma mensagem se move entre participantes; escolha p2p vs pub-sub, depois o canal de falha.
Mensagensmessage command-message document-message event-messageA própria mensagem é o assunto, não o endpoint.
Roteamentocontent-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager sagaUma mensagem, vários destinos possíveis, ou partes para remontar.
Transformaçãomessage-translator envelope-wrapper content-enricher content-filter claim-check normalizerA carga ou seu envelope muda entre saltos.
Endpointsmessage-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-adapterComo um serviço se conecta a um canal e o consome.
Gerenciamento de sistemawire-tap detour message-history smart-proxy test-message channel-purgerObservabilidade, sondas e operações.
Infraestruturamessage-broker messaging-bridge outbox inboxO próprio broker, links entre brokers, publicação/consumo transacional.
Participantes e armazenamentosservice external-system actor datastore message-store schema-registry noteQuem 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):

GrupoEmblemas
Endpointgateway (Messaging Gateway), mapper (Messaging Mapper), activator (Service Activator), adapter (Channel Adapter)
Consumopolling (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çãotx (Transactional Client), outbox (Transactional Outbox), inbox (Transactional Inbox), idempotent (Idempotent Receiver)
Resiliênciabulkhead, retry, circuit-breaker — padrões de resiliência, não EIP

Arestas:

Tipo de arestaTraçoLarguraPontasMarcador
message (sem tipo)sólida #1e1e1e2→ arrownenhum
message type: commandsólida2→ triangle«C»
message type: eventsólida2→ arrow«E»
message type: documentsólida2→ arrow«D»
message type: replytracejada2→ arrow«R»
rpcsólida1→ arrownenhum
datapontilhada1→ arrownenhum
tappontilhada1circle → arrownenhum
dlqtracejada #c92a2a1→ arrownenhum
controltracejada #868e961┤ barnenhum

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

PilhaDesenhe como
Tópico Kafkapubsub-channel; grupo de consumidores → competing:N; assinatura durável → durable
Fila RabbitMQp2p-channel; exchange → message-broker ou content-based-router; DLX → dead-letter-channel
SQS / SNSp2p-channel / pubsub-channel
Regra EventBridgecontent-based-router
Step Functionsprocess-manager ou saga
Consumidor Lambdaservice com event-driven
Banco de dadosdatastore; cópias de auditoria/reprodução → message-store
API de parceiroexternal-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.

Habilidades Relacionadas