diagram-as-code

Diagrama de arquitetura desenhado à mão tem um problema que ninguém orça: ele envelhece no dia seguinte à revisão. O custo dele não é desenhar, é manter o desenho fiel ao que está em produção a cada mudança de VPC, de subnet ou de balanceador. Depois de anos revisando arquitetura, o padrão que vejo se repetir é o mesmo: o PNG no Confluence descreve o sistema de seis meses atrás e ninguém sabe dizer quando ele deixou de ser verdade.

O projeto original da awslabs resolve a parte central disso. Você descreve recursos e ligações em YAML legível, o arquivo vai para o Git junto do código, e o CLI awsdac gera a imagem seguindo as diretrizes de ícones da AWS. O diagrama passa a ter diff, revisão em pull request e histórico.

O fork nasceu de duas lacunas que eu tinha no dia a dia. PNG não se edita: quando alguém precisa ajustar uma seta para uma apresentação, o PNG obriga a regenerar ou redesenhar. Por isso acrescentei a exportação .drawio, que vira a fonte editável. Nem todo mundo instala um CLI: para quem só quer testar um YAML, o editor web em dac.moretes.com gera o diagrama no navegador, sem instalação local.

O YAML descreve três coisas: os definition files, que dizem quais ícones e estilos existem; os recursos, organizados em hierarquia (canvas, nuvem, região, VPC, subnet, serviço); e os links entre eles. O CLI lê a hierarquia, calcula o tamanho de cada grupo a partir dos filhos e posiciona tudo sem que você informe coordenada. É isso que torna o arquivo revisável em pull request: o diff mostra "entrou um NAT Gateway na subnet pública", não "o retângulo andou 40 pixels".

Definition files: por padrão vêm do repositório oficial. Carregar de outra URL exige --allow-untrusted-definitions, e a trava existe por um motivo concreto: o arquivo de definição decide o que é desenhado, então uma URL qualquer é entrada não confiável no seu pipeline. O mesmo mecanismo permite diagramas fora da AWS, basta escrever outro arquivo de definição.

Templates: com -t, o YAML é processado pelo text/template do Go antes do render. Na prática, isso deixa um único arquivo gerar o diagrama de dev, hml e prod variando contas, regiões ou número de instâncias.

draw.io como fonte: no fork, o .drawio gerado é o artefato de referência. PNG e PDF podem ser exportados a partir dele quando o binário drawio está instalado, o que vale para CLI local e ambientes que não são serverless. No editor web, o backend roda como Vercel Function em Go, e o cmd/api-dev sobe o mesmo handler localmente para testar sem a Vercel CLI.

O uso que mais rende não é gerar um diagrama bonito uma vez, é gerar o mesmo diagrama em todo merge. Como o binário não depende de navegador headless, ele roda num container de CI em segundos: o pipeline chama awsdac arquitetura.yaml -o docs/arquitetura.png -f e publica a imagem junto da documentação. Se o YAML mudou e a imagem não, o build mostra.

Junto do IaC: o YAML do diagrama mora no mesmo repositório do Terraform ou do CloudFormation. Quem altera a rede na mesma PR altera o desenho, e o revisor vê as duas coisas lado a lado.

Para apresentação: gere o .drawio, abra no draw.io e faça o acabamento visual ali. O YAML continua sendo a verdade estrutural; o .drawio é a camada editável para quem não vai abrir um terminal.

Como biblioteca: se você tem uma ferramenta própria, um agente de IA que propõe arquitetura, por exemplo, o pkg/diagram permite gerar o desenho sem chamar o CLI como processo externo.