diagram-as-code

Diagrama de arquitetura desenhado à mão tem um problema que ninguém percebe no dia da entrega: ele envelhece em silêncio. A infraestrutura muda a cada PR, o PNG no Confluence continua mostrando o NAT Gateway que foi removido há três meses, e a revisão de arquitetura passa a discutir um sistema que não existe mais.

A pergunta que importa não é "como desenho este diagrama?", é "quem atualiza este diagrama quando a infraestrutura mudar?". Quando o diagrama é um arquivo YAML no mesmo repositório do código, a resposta passa a ser: quem abriu o PR. O diff do diagrama aparece na revisão, igual a qualquer outra mudança.

O upstream da awslabs já resolve a parte central: lê YAML legível, segue as diretrizes de ícones da AWS, ajusta posição e tamanho de grupos sozinho e roda num container sem headless browser nem GUI. O que me faltava era o caminho de volta para o draw.io, que é onde a maioria dos times faz o ajuste fino antes de apresentar, e uma forma de usar a ferramenta sem instalar nada. Este fork existe para isso.

O motor lê o YAML, resolve cada recurso contra os definition files, que dizem qual ícone e qual estilo cada tipo de recurso usa, e calcula o layout: grupos como AWS Cloud, região, VPC e subnet crescem e se posicionam para caber o que está dentro. Por isso você descreve a hierarquia, não coordenadas.

As flags revelam o resto do desenho:

• -t, --template: processa o arquivo com text/template do Go antes de desenhar. Útil para gerar variações do mesmo diagrama por ambiente.
• -c, --cfn-template e -d, --dac-file: ambos em beta. O primeiro desenha direto de um template CloudFormation; o segundo converte o template em YAML no formato dac, para você ajustar e versionar.
• --allow-untrusted-definitions: por padrão, definition files só carregam do repositório oficial. A flag libera URLs de terceiros.
• --width e --height: redimensionam a imagem final; 0 mantém o tamanho calculado.

No fork, o export draw.io é um segundo backend sobre o mesmo modelo: em vez de rasterizar, ele grava o XML do draw.io com os assets dos ícones. O editor web chama esse mesmo motor por uma Go Function na Vercel, então o que você vê no navegador é o que o CLI gera.

Eu uso de três formas.

Documentação viva: o YAML mora ao lado do Terraform ou do CloudFormation, e o PNG é gerado no CI. Diagrama desatualizado vira diff visível na revisão, não descoberta em reunião.

Rascunho de proposta: no editor web, parto de um template, ajusto em minutos e exporto .drawio para dar o acabamento visual que a apresentação pede. O .drawio continua editável, o PNG não.

Geração por máquina: o pacote pkg/diagram deixa outra ferramenta Go, ou um agente que já produz YAML, desenhar sem passar por shell. O formato YAML é estruturado o bastante para um modelo de linguagem gerar com poucos erros, e a validação acontece no parse.

O custo que importa aqui não é o de aprender o formato, é o de manter diagramas sincronizados por anos. Esse custo cai quando o diagrama passa a ser revisado como código.