ANcpLua/ancplua-skills

Gerador de Diagramas C4 de Contêiner

Gere diagramas C4 de contêiner seguindo as convenções do modelo C4, exportados como arquivos XML .drawio editáveis que abrem diretamente no draw.io (desktop ou web).

Quando Usar

Gatilhos explícitos:

• O usuário pede um diagrama C4, diagrama de contêiner ou diagrama de arquitetura
• O usuário diz "desenhe a arquitetura", "diagrama do sistema", "mostre os componentes"
• O usuário precisa visualizar a arquitetura do sistema para documentação ou apresentação
• O usuário menciona draw.io, drawio ou quer um diagrama editável

Gatilhos proativos:

• Explicando um sistema com 3+ componentes interagentes
• Discutindo microsserviços, APIs, bancos de dados e seus relacionamentos
• Revisando ou projetando arquitetura de sistemas

Pule quando:

• O usuário quer um fluxograma simples (use Mermaid)
• O usuário quer wireframes ou mockups de UI
• O sistema tem menos de 3 componentes

Processo

Passo 1: Coletar Requisitos

Identifique a partir da conversa ou pergunte ao usuário:

• Qual sistema estamos diagramando?
• Quem são os usuários/atores (Pessoa)?
• Quais contêineres existem (apps, serviços, bancos de dados, filas, armazenamento de arquivos)?
• Quais sistemas externos interagem com ele?
• Quais são os fluxos de dados e protocolos principais?

Se o usuário fornecer uma especificação, descrição da base de código ou visão geral da arquitetura, extraia os elementos automaticamente e confirme antes de gerar.

Passo 2: Classificar Elementos

Mapeie cada elemento para uma categoria C4:

Categoria	Cor	Forma	Descrição
Pessoa	#08427B (azul escuro)	shape=actor + rótulo de texto	Usuários, atores, papéis
Contêiner	#438DD5 (azul)	Retângulo arredondado	Aplicações, serviços, APIs
Banco de Dados	#438DD5 (azul)	Cilindro	Qualquer armazenamento de dados (SQL, NoSQL, arquivos)
Fila/Broker	#438DD5 (azul)	Retângulo arredondado com rótulo	Filas de mensagens, barramentos de eventos
Sistema Externo	#999999 (cinza)	Retângulo arredondado	Serviços de terceiros, APIs
Fronteira do Sistema	nenhuma (transparente)	Retângulo tracejado	Agrupa contêineres internos

Referência: references/element-templates.md para modelos exatos de XML draw.io.

Passo 3: Planejar Layout

Aplique layout estrito em camadas (de cima para baixo):

Camada 1 (y ~= 20):     Elementos Pessoa (atores)
Camada 2 (y ~= 250):    Fronteira do Sistema contendo Contêineres internos
Camada 3 (y ~= 700+):   Sistemas Externos

Regras de layout:

• Cada elemento recebe coordenadas x, y explícitas (sem auto-layout)
• Mínimo de 200px de espaçamento horizontal entre elementos na mesma camada
• Mínimo de 200px de espaçamento vertical entre camadas
• Fronteira do sistema = retângulo tracejado envolvendo todos os contêineres internos com 40px de preenchimento
• Ordene os elementos da esquerda para a direita seguindo a direção do fluxo de dados principal
• Agrupe contêineres relacionados dentro de subfronteiras se o sistema tiver subsistemas distintos
• Mantenha a largura do diagrama abaixo de 1600px para legibilidade
• Centralize os elementos horizontalmente dentro de sua camada

Minimizando cruzamentos de linhas:

• Coloque elementos que se comunicam frequentemente adjacentes uns aos outros
• Roteie conexões verticalmente quando possível
• Evite linhas diagonais que cruzam outros elementos
• Sem setas através de contêineres não relacionados: se A conecta-se a C, a seta NÃO deve passar por B. Corrija: (a) colocando A e C adjacentes, (b) usando pontos de saída/entrada explícitos, ou (c) reorganizando o layout
• Rótulos de seta não devem sobrepor texto de contêiner: use labelBackgroundColor=#ffffff em todas as arestas e use deslocamento perpendicular (y no mxGeometry) para empurrar rótulos para longe de contêineres

Passo 4: Definir Conexões

Para cada conexão, especifique:

• Elemento de origem e destino
• Rótulo: ação + protocolo (ex.: "Lê/escreve [SQL/TCP]", "Envia eventos [AMQP]")
• Estilo: linha sólida = chamada síncrona, linha tracejada = assíncrona (eventos, filas, webhooks)
• Direção: sempre origem -> destino (siga o fluxo de dados)

Regras de conexão:

• Cada seta deve ter um rótulo (sem conexões não rotuladas) - se um rótulo sobrepor, corrija o layout ou desloque-o, nunca remova o rótulo
• Sempre inclua labelBackgroundColor=#ffffff nos estilos de conexão
• Use o sufixo [Protocolo]: [REST/JSON], [gRPC], [SQL], [AMQP], [WebSocket]
• Fluxos bidirecionais: use duas setas separadas com rótulos distintos
• Auto-referência: evite (reestruture o diagrama)

Passo 5: Gerar XML .drawio

Use a estrutura XML de references/drawio-template.md como base.

Construa o XML seguindo estas regras:

1. Comece com o wrapper <mxfile> e <mxGraphModel> com dimensões adequadas
2. Adicione as células raiz (id="0" e id="1")
3. Adicione primeiro os retângulos da fronteira do sistema (são pais dos elementos contidos)
4. Adicione todos os elementos com geometria explícita (x, y, largura, altura)
5. Adicione todas as conexões com referências de origem/destino
6. Adicione a legenda no canto inferior direito

Dimensionamento de elementos:

• Pessoa: 40 x 60px ator + 220 x 60px rótulo de texto abaixo
• Contêiner: 240 x 120px
• Banco de Dados (cilindro): 240 x 120px
• Sistema Externo: 240 x 120px
• Fronteira do Sistema: calculada para envolver os filhos + 40px de preenchimento em cada lado

Passo 6: Adicionar Legenda

Cada diagrama deve incluir uma legenda. Coloque-a no canto inferior direito.

A legenda deve mostrar:

• Pessoa = boneco azul escuro (#08427B)
• Contêiner = retângulo arredondado azul (#438DD5)
• Banco de Dados = cilindro azul (#438DD5)
• Sistema Externo = retângulo arredondado cinza (#999999)
• Seta sólida = fluxo síncrono
• Seta tracejada = fluxo assíncrono

Referência: references/legend-template.md para o XML exato.

Passo 7: Salvar e Validar

Salve no caminho solicitado pelo usuário, ou como padrão ./c4_[nome_do_sistema].drawio.

Checklist de validação:

• Todos os elementos têm coordenadas x, y explícitas
• As camadas estão de cima para baixo: Pessoa -> Fronteira do Sistema -> Externo
• A fronteira do sistema envolve todos os contêineres internos
• A legenda está presente no canto inferior direito
• Nenhum elemento sobreposto (verifique coordenadas + dimensões)
• Cruzamentos de linhas mínimos
• Cada conexão tem um rótulo com protocolo
• Linhas sólidas = síncronas, linhas tracejadas = assíncronas
• Cores de fonte são brancas (#ffffff) em fundos coloridos
• O arquivo abre corretamente no draw.io (estrutura XML válida)

Regras do Modelo C4

Siga as restrições do diagrama C4 de contêiner:

• Diagrama de contêiner mostra as escolhas de tecnologia de alto nível e como os contêineres se comunicam
• Cada contêiner é uma unidade implantável/executável separadamente (não uma classe ou módulo)
• Não misture níveis C4: esta habilidade gera apenas o nível de Contêiner
• Para detalhes de nível de Componente dentro de um contêiner, crie um diagrama separado
• Elementos Pessoa representam papéis, não pessoas individuais
• Sistemas externos são qualquer coisa fora da fronteira do sistema que a equipe não possui

Anti-padrões

• SEM auto-layout - sempre use coordenadas x, y explícitas para resultados previsíveis
• SEM setas não rotuladas - cada conexão precisa de uma ação e protocolo
• SEM legenda ausente - a legenda é obrigatória em cada diagrama
• SEM layout apertado - mantenha espaçamentos mínimos entre elementos
• SEM níveis C4 misturados - apenas nível de Contêiner (sem classes, sem infraestrutura)
• SEM texto invisível - garanta que a cor da fonte contraste com o fundo
• SEM dimensões fixas - calcule o tamanho da fronteira do sistema a partir dos filhos
• SEM formas mxgraph.c4.* - elas exigem a biblioteca de formas C4 que NÃO é carregada por padrão no draw.io. Use formas nativas: shape=actor para pessoas, shape=cylinder3 para bancos de dados
• SEM setas cruzando contêineres não relacionados - reorganize o layout para que cada seta tenha um caminho claro entre origem e destino
• SEM rótulos sem labelBackgroundColor=#ffffff - rótulos nus tornam-se ilegíveis ao cruzar outros elementos
• SEM remover rótulos para corrigir sobreposição - se um rótulo sobrepor um contêiner, corrija o layout ou desloque-o, nunca remova informações