c4-container-diagram

name

c4-container-diagram

description

Gera e valida diagramas de containers C4 production-ready em PT-BR, seguindo o modelo oficial de Simon Brown, com elementos obrigatorios, notacao padrao, regras de seguranca, eficiencia e escalabilidade. Use quando for criar, revisar ou converter descricoes/infraestrutura em diagrama de containers C4 valido. Nao use para diagramas de contexto, componentes, codigo, deployment, brainstorming sem infraestrutura real ou documentacao generica sem validacao.

Diagrama de Containers C4 Production-Ready

Esta skill aplica o modelo C4 oficial de Simon Brown sem adaptacoes, abreviacoes ou flexibilidade. Toda regra de elements, relacionamentos, escopo e notacao e obrigatoria. O diagrama de containers DEVE mostrar exatamente UM sistema de software por diagrama, os containers dentro desse sistema, pessoas e sistemas externos diretamente conectados, e NADA mais. Todo container DEVE ser uma unidade executavel ou armazenavel separadamente (processo, aplicacao, schema de banco, bucket, fila, etc.). Nao representar modulos, classes, bibliotecas, funcoes, microsservicos invisiveis ou decisoes de deployment. Todo relacionamento DEVE ter rotulo descritivo e, quando relevante, protocolo/tecnologia. Relacionamentos sem rotulo ou sem direcao sao invalidos. A tecnologia de cada container DEVE ser declarada explicitamente. Nao e permitido tecnologia vaga como "backend", "servico" ou "aplicacao". Esta skill NAO gera diagrama quando faltar: nome do sistema, proposito do diagrama, lista minima de containers, ou fonte de verdade da arquitetura (codigo, docs, descricao estruturada, manifests, API specs). Todo artefato gerado DEVE ser validado por python3 scripts/validate-c4-container.py antes de ser entregue. Saida so e considerada pronta quando o validador retornar SUCCESS. Diagramas, descricoes e registros de decisao DEVEM ficar em PT-BR. Nomes proprios de sistemas, produtos ou tecnologias mantem sua grafia original. Usar estados finais explicitos: done, needs_input, blocked ou failed.

Entrada Obrigatoria

• Nome do sistema de software em escopo (um unico sistema).
• Proposito do diagrama: novo desenho, revisao, migracao, onboarding ou alinhamento.
• Fonte de verdade da arquitetura em ordem de preferencia:
  1. Codigo-fonte, manifests (Docker, K8s, Terraform, serverless), API specs ou configs;
  2. Documentacao tecnica estruturada, ADRs, runbooks ou diagramas anteriores;
  3. Descricao textual detalhada com responsabilidades, tecnologias e protocolos.
• Pelo menos dois containers candidatos ou a evidencia de que o sistema e trivial (um unico container).

Entrada Recomendavel

• Personas/usuarios que interagem com o sistema.
• Sistemas externos diretamente conectados aos containers.
• Restricoes de seguranca (autenticacao, autorizacao, TLS, rede privada, secrets).
• Restricoes de eficiencia (latencia, throughput, cache, batch vs real-time).
• Restricoes de escalabilidade (stateless, replicas, filas, particionamento).
• Padrao de notacao preferido: mermaid, plantuml, drawio ou texto-estruturado.

Saida Obrigatoria

• Bundle em ./discoveries/c4-container-<slug>/ contendo:
  • bundle.json - indice com status, titulo, sistema, prontidao e blockers.
  • container-diagram.<ext> - diagrama no formato escolhido (.mmd, .puml, .drawio ou .md).
  • containers.md - descricao canonica de cada container: nome, tecnologia, responsabilidade, interfaces e dependencias.
  • decisions.md - decisoes arquiteturais, trade-offs e rejeicoes explicitas.
  • transcript.md - historico auditavel de coleta, validacoes e correcoes.
• Resultado da execucao de python3 scripts/validate-c4-container.py <bundle_dir>.

Contrato de Compatibilidade

• O comportamento deve ser identico entre agentes: a mesma entrada deve produzir o mesmo conjunto de artefatos e o mesmo status final.
• done: bundle completo, validador executado com SUCCESS, sem blockers.
• needs_input: falta evidencia material para continuar com seguranca.
• blocked: ha impedimento externo ou dependencia ausente fora do controle da skill.
• failed: o bundle ficou estruturalmente invalido ou o validador nao passou apos correcao.

Procedimentos

Etapa 1: Validar entrada e inicializar bundle

1. Identificar o titulo a partir do nome do sistema fornecido.
2. Executar python3 scripts/slugify.py "<titulo>" para normalizar o slug.
3. Verificar se ./discoveries/c4-container-<slug>/ ja existe. Se existir, perguntar em multipla escolha se deve reaproveitar, criar novo com sufixo ou cancelar.
4. Executar python3 scripts/init-bundle.py <slug> --format <formato> para criar bundle.json, containers.md, decisions.md, transcript.md e container-diagram.<ext>.
5. Preencher bundle.json com:
   • title: titulo do diagrama;
   • system_name: nome exato do sistema em escopo;
   • status: draft ate a validacao final;
   • readiness.status: mesmo valor de status;
   • readiness.blockers: lista vazia ou lista de impedimentos.
6. Encerrar com blocked se o script falhar por conflito de diretorio, permissao ou slug invalido.
7. Registrar a fonte de verdade e o proposito no transcript.md.

Etapa 2: Carregar regras obrigatorias

1. Ler references/c4-rules.md e aplicar cada regra como obrigatoria.
2. Ler references/container-checklist.md e usa-lo como gate em todas as etapas.
3. Ler references/notation-mapping.md para o formato de saida escolhido (mermaid, plantuml, drawio ou texto-estruturado).

Etapa 3: Coletar e normalizar evidencias

1. Extrair do contexto:
   • pessoas/usuarios que interagem com o sistema;
   • sistemas externos diretamente conectados;
   • containers candidatos com nome, tecnologia e responsabilidade;
   • relacionamentos com rotulo e protocolo/tecnologia;
   • restricoes de seguranca, eficiencia e escalabilidade.
2. Confrontar a evidencia com references/evidence-classification.md:
   • classificar cada achado como confirmado, suspeito, ausente ou refutado;
   • confirmado exige evidencia em codigo, manifest ou spec com path:linha ou link direto.
3. Registrar o resultado da classificacao no transcript.md.
4. Se faltar evidencia para qualquer container ou relacionamento essencial, parar e solicitar o dado faltante.

Etapa 4: Validar o escopo e os elementos

1. Confirmar que existe exatamente um sistema de software em escopo.
2. Confirmar que cada elemento dentro do limite do sistema e um container valido (aplicacao executavel ou armazenamento de dados).
3. Confirmar que nenhum elemento e componente, classe, funcao, biblioteca, modulo ou detalhe de deployment.
4. Confirmar que cada container tem:
   • nome unico no diagrama;
   • tecnologia explicita (ex: "ASP.NET Core 8", "PostgreSQL 16", "React 18", "RabbitMQ 3.13");
   • responsabilidade clara em uma frase.
5. Confirmar que pessoas e sistemas externos fora do limite do sistema aparecem como elementos de suporte.
6. Se qualquer validacao falhar, corrigir a evidencia ou parar com needs_input.

Etapa 5: Validar relacionamentos

1. Confirmar que cada relacionamento:
   • conecta dois elementos do diagrama;
   • possui rotulo descritivo (ex: "Autentica", "Consulta pedidos", "Publica evento");
   • declara protocolo/tecnologia quando houver comunicacao (ex: "HTTPS/JSON", "gRPC", "AMQP", "SQL/TLS");
   • possui direcao clara (origem -> destino).
2. Confirmar que nao ha relacionamentos cruzando o limite do sistema sem que o elemento externo esteja representado.
3. Confirmar que cada container nao isolado tem pelo menos um relacionamento.
4. Se houver relacionamento invalido, corrigir ou parar com needs_input.

Etapa 6: Aplicar regras de seguranca, eficiencia e escalabilidade

1. Ler references/security-rules.md e aplicar:
   • autenticacao/autorizacao representada nos relacionamentos externos;
   • TLS/SSL indicado em toda comunicacao exposta;
   • rede privada ou segmentacao indicada quando aplicavel;
   • secrets e credenciais NUNCA aparecem no diagrama.
2. Ler references/efficiency-rules.md e aplicar:
   • cache, fila ou batch explicitados quando forem decisoes arquiteturais;
   • sincrono vs assincrono indicado nos relacionamentos relevantes.
3. Ler references/scalability-rules.md e aplicar:
   • stateless vs stateful indicado para cada container aplicacional;
   • replicacao ou particionamento indicados quando forem decisoes arquiteturais.
4. Registrar as decisoes aplicadas e as rejeitadas em decisions.md.

Etapa 7: Gerar o diagrama

1. Ler assets/diagram-template.<ext> correspondente ao formato escolhido, onde <ext> e:
   • mermaid -> diagram-template.mmd;
   • plantuml -> diagram-template.puml;
   • drawio -> diagram-template.drawio;
   • texto-estruturado -> diagram-template-text.md.
2. Substituir TODOS os placeholders do template por valores concretos. Nao deixar nenhum [PLACEHOLDER] no arquivo final.
3. Preencher o template com os elementos validados:
   • titulo no formato "Diagrama de Containers - ";
   • sistema de software como fronteira (System_Boundary ou equivalente);
   • containers dentro da fronteira;
   • pessoas e sistemas externos fora da fronteira;
   • relacionamentos com rotulo e protocolo.
4. Garantir que a notacao segue references/notation-mapping.md.
5. Garantir que o diagrama inclui legenda ou chave explicativa:
   • Mermaid: usar SHOW_LEGEND();
   • PlantUML: usar LAYOUT_WITH_LEGEND();
   • draw.io: incluir uma caixa de legenda com os tipos de elemento;
   • Texto estruturado: manter a secao ## Legenda.
6. Salvar o diagrama em container-diagram.<ext> no bundle.

Etapa 8: Gerar descricao canonica dos containers

1. Preencher containers.md com uma secao por container, substituindo todos os placeholders do template.
2. Cada secao deve conter:
   • Nome;
   • Tipo (Web App, API, Mobile App, Database, Message Queue, File System, etc.);
   • Tecnologia com versao ou major version;
   • Responsabilidade em uma frase;
   • Interfaces (APIs, eventos, filas, queries) com protocolo;
   • Dependencias para outros containers ou sistemas externos;
   • Notas de seguranca, eficiencia ou escalabilidade quando relevantes.
3. Garantir que nenhum container depende de elemento nao representado no diagrama.
4. Remover a secao ## Itens em Aberto se nao houver itens pendentes; caso contrario, lista-los explicitamente.

Etapa 9: Validar o bundle

1. Executar python3 scripts/validate-c4-container.py ./discoveries/c4-container-<slug>.
2. O validador verifica: estrutura do bundle, preenchimento dos JSON, placeholders, secoes obrigatorias, tipos de container, tecnologias vagas, relacionamentos, aliases, fronteira do sistema, legenda e consistencia entre arquivos.
3. Se o validador reportar falhas, ler o stderr, identificar a regra violada em references/c4-rules.md ou references/container-checklist.md, corrigir o artefato e reexecutar.
4. Repetir ate obter SUCCESS.
5. Se apos uma rodada honesta de correcao o validador ainda falhar, encerrar com blocked.
6. Ao obter SUCCESS, atualizar bundle.json para status: done e readiness.status: done.

Etapa 10: Relatar a saida

1. Informar o caminho do bundle gerado.
2. Resumir em ate 6 bullets: sistema em escopo, numero de containers, elementos externos, principais decisoes, riscos residuais e prontidao.
3. Indicar o status final: done, needs_input, blocked ou failed.
4. Nao executar outra skill automaticamente.

Decisoes Operacionais

1. Preferir diagramas pequenos e legiveis a diagramas monoliticos. Se um sistema tiver mais de 12 containers, considerar dividir em sub-sistemas e gerar diagramas separados, mantendo um indice em containers.md.
2. Representar tecnologias reais e verificaveis. Nao usar termos genericos para mascarar incerteza.
3. Nao colocar detalhes de deployment (cluster, load balancer, replica, failover) no diagrama de containers. Esses detalhes pertencem ao diagrama de deployment.
4. Nao representar componentes internos de um container. Esses detalhes pertencem ao diagrama de componentes.
5. Nao representar codigo ou classes. Esses detalhes pertencem ao diagrama de codigo.
6. Preservar os nomes de sistemas e produtos informados pelo usuario. Nao traduzir nomes proprios.
7. Registrar toda decisao arquitetural com trade-off explicito em decisions.md.
8. Tratar seguranca, eficiencia e escalabilidade como restricoes de primeira classe, nao como anotacoes opcionais.
9. Se houver confito entre a vontade do usuario e as regras do C4, aplicar as regras do C4 e explicar o motivo no decisions.md.
10. Usar multipla escolha em texto puro quando nao houver ferramenta de pergunta estruturada, aguardando resposta inequivoca antes de prosseguir.

Estados Finais

• done: bundle completo, diagrama gerado, validador SUCCESS, sem blockers.
• needs_input: falta resposta do usuario para evidencia material ou insumo indispensavel.
• blocked: erro de I/O, conflito de diretorio, falha persistente de validacao ou impossibilidade de materializar o bundle.
• failed: erro inesperado de execucao apos tentativa de recuperacao.

Tratamento de Erros

• Entrada insuficiente: Se faltar nome do sistema, proposito ou fonte de verdade, interromper e pedir apenas os dados faltantes em vez de inventar containers.
• Container invalido: Se um elemento proposto nao for uma unidade executavel ou armazenavel separada, rejeitar e pedir o nivel correto de abstracao.
• Relacionamento invalido: Se um relacionamento estiver sem rotulo, sem direcao ou conectar elementos nao representados, corrigir ou pedir esclarecimento.
• Falha de validacao: Se scripts/validate-c4-container.py reportar erro, ler o stderr, consultar references/c4-rules.md, aplicar a correcao e reexecutar ate SUCCESS.
• Ambiguidade material: Se houver duas interpretacoes plausiveis para o mesmo elemento ou relacionamento, parar com needs_input e apresentar opcoes A, B, C, D.
• Formato nao suportado: Se o formato solicitado nao estiver em mermaid, plantuml, drawio ou texto-estruturado, padronizar para mermaid e registrar a decisao em decisions.md.