diagram-as-code
Diagramas AWS a partir de YAML versionado no Git, com export nativo para draw.io
git clone https://github.com/fernando-moretes/tool-diagram-as-code.gitcerca de 4 min · áudio gerado ao tocar
O diagram-as-code é meu fork do awslabs/diagram-as-code: uma CLI em Go que transforma YAML em diagramas de arquitetura AWS. Acrescentei export nativo para .drawio, um pacote Go público para embutir em outras ferramentas e um editor web hospedado em dac.moretes.com.
Por que este fork existe
O problema que um diagrama de arquitetura cria não é desenhar a primeira versão, é manter o desenho fiel ao sistema depois do terceiro deploy. Diagrama feito à mão em ferramenta gráfica envelhece em silêncio: ninguém revisa um PNG num pull request, e no dia da auditoria o desenho mostra um NAT Gateway que já saiu da conta faz meses.
O projeto original da awslabs resolve a parte principal: o diagrama vira YAML legível, entra no Git, passa por revisão como qualquer outro código e é gerado por uma CLI sem depender de navegador headless nem de GUI. Isso já o torna utilizável num pipeline de CI dentro de um container.
O que me faltava eram duas coisas. Editar depois de gerar: o PNG é saída final, e em revisão com time de arquitetura alguém sempre quer mover uma caixa ou anotar um fluxo. Por isso o export para .drawio virou a fonte de verdade, e PNG ou PDF podem ser derivados dele. Usar sem instalar nada: nem toda pessoa que revisa arquitetura tem Go ou Node na máquina, então o editor web gera o diagrama direto no navegador.
O fork mantém a CLI do upstream e adiciona essas camadas por cima. Não é um projeto novo, é uma extensão com escopo definido.
O que o fork acrescenta ao upstream
--drawio ou -o output.drawio, com o pipeline escrito em Go em internal/ctl/drawio.go e drawio_assets.go..drawio: quando o binário drawio está disponível, o .drawio continua sendo a fonte de verdade em ambiente local e fora de serverless.pkg/diagram: wrapper público para embutir a geração em ferramentas de IaC, agentes de IA ou editores gráficos.cmd/api-dev: servidor local para testar o handler da API sem a Vercel CLI.Dois caminhos para o mesmo motor
A CLI e o editor web chamam o mesmo núcleo em Go. O que muda é onde ele roda e qual saída você recebe.
- awsdac · flags -o, --drawio, -t, -c
- drawio (opcional) · PNG/PDF a partir do .drawio
- Editor Monaco · dac.moretes.com
- Vercel Function · handler em Go
- pkg/diagram · layout de grupos e ícones
- Definition files · ícones AWS oficiais
- PNG / PDF
- .drawio · fonte editável
Instalar e gerar o primeiro diagrama
- 1
Escolha o caminho de instalação
O README recomenda
npm install -g awsdac(Node.js 14+), que baixa o binário certo para seu sistema e CPU. No macOS também hábrew install awsdac. Se você precisa das extensões deste fork, como--drawio, prefirago installou o build a partir do código, que apontam para o repositório do fork. - 2
Ou compile do código
Com Go 1.21+, clone o repositório e rode
make build; sai um./awsdac(ouawsdac.exeno Windows). Node.js 18+ só é necessário para o frontend web. - 3
Confira a versão
Rode
awsdac --versionantes de qualquer coisa. Em CI, fixe a versão: diagrama gerado por binário diferente em cada run vira diff falso no pull request. - 4
Gere a partir de um exemplo
awsdac examples/alb-ec2.yamlgeraoutput.png. Use-opara nomear a saída e-fpara sobrescrever sem confirmação, o que é obrigatório em pipeline não interativo. - 5
Sem instalar nada
Abra dac.moretes.com, escolha um template, edite o YAML e baixe em PNG ou draw.io.
# build from source (Go 1.21+)
git clone https://github.com/fernando-moretes/tool-diagram-as-code.git
cd tool-diagram-as-code
make build
./awsdac --version
# PNG (default output: output.png)
./awsdac examples/alb-ec2.yaml
# named output, overwrite without prompting (CI-safe)
./awsdac my-architecture.yaml -o my-diagram.png -f
# editable draw.io file (fork extension)
./awsdac examples/alb-ec2.yaml --drawio -o output.drawio
# PDF instead of PNG
./awsdac my-architecture.yaml --pdf -o my-diagram.pdf
# [beta] diagram straight from a CloudFormation template
./awsdac template.yaml -c -o from-cfn.png
# [beta] emit dac YAML from CloudFormation, then edit it by hand
./awsdac template.yaml -d -o generated.yamlComo funciona por dentro
O YAML descreve recursos e grupos; o motor em Go calcula posição e tamanho dos grupos sozinho. Você não declara coordenadas, declara hierarquia (conta, região, VPC, subnet, recurso) e as ligações entre eles. Isso é o que permite revisar um diagrama como código: o diff mostra "entrou um RDS na subnet privada", não "a caixa andou 40 pixels".
Os ícones e estilos vêm de definition files, que seguem as diretrizes oficiais de ícones da AWS. A flag --allow-untrusted-definitions deixa explícito que, por padrão, só definições do repositório oficial são carregadas; --override-def-file troca a fonte para testes. O mesmo mecanismo permite diagramas fora da AWS: basta escrever um arquivo de definição novo.
Três flags mudam o uso no dia a dia. -t: processa a entrada como text/template do Go, útil para gerar o mesmo desenho por ambiente. -c (beta): desenha direto de um template CloudFormation. -d (beta): converte CloudFormation em YAML no formato dac, que você ajusta à mão depois.
No editor web, o handler roda como Vercel Function em Go e chama o mesmo núcleo. O cmd/api-dev sobe esse handler localmente, então dá para depurar a API sem conta na Vercel.
O que observar antes de colocar em CI
-c e -d estão marcados como beta no upstream: trate a saída como rascunho, não como diagrama oficial gerado automaticamente. E, sem -f, a CLI pede confirmação para sobrescrever o arquivo, o que trava um job não interativo em vez de falhar com erro claro.
Perguntas frequentes
Qual a diferença para o awslabs/diagram-as-code?
A CLI base é a mesma. O fork acrescenta export .drawio nativo, o pacote público pkg/diagram, o cmd/api-dev e o editor web. Se você só precisa de PNG, o upstream atende.
Preciso do draw.io instalado?
Não para gerar .drawio nem PNG. O binário drawio só entra quando você quer derivar PNG ou PDF a partir do .drawio, mantendo ele como fonte de verdade.
Funciona para diagramas que não são AWS?
Sim, escrevendo arquivos de definição próprios. Para carregá-los de uma URL fora do repositório oficial, você precisa de --allow-untrusted-definitions, e vale revisar esse arquivo como revisaria qualquer dependência.
Referências
Quando usar
Use este fork quando o diagrama precisa acompanhar o código, passar por revisão no pull request e ainda ser editável por quem não escreve YAML: o .drawio cobre esse último ponto. Use o editor web para revisão pontual ou para quem não vai instalar Go. Fique no upstream se PNG basta e você prefere seguir só a versão da awslabs. E não espere que -c gere o diagrama oficial de uma stack CloudFormation grande: enquanto for beta, ele é ponto de partida para o YAML que você mantém.
Deep dives de arquitetura, AWS, IA e mercado: direto no seu email. Grátis.
Sem spam · cancele quando quiser