# diagram-as-code

Diagramas AWS a partir de YAML versionado no Git, com export nativo para draw.io

- URL: https://fernando.moretes.com/open-source/diagram-as-code

- Markdown: https://fernando.moretes.com/open-source/diagram-as-code/guide.md?lang=pt

- GitHub: https://github.com/fernando-moretes/tool-diagram-as-code

- Homepage: https://dac.moretes.com

- Language: Go

- Topics: architecture, diagram-as-code, moretes, portfolio

- Stars: 1

- Forks: 0

- Updated: 2026-10-19T14:21:06Z

---

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

- **Export draw.io nativo:** flag `--drawio` ou `-o output.drawio`, com o pipeline escrito em Go em `internal/ctl/drawio.go` e `drawio_assets.go`.
- **PNG e PDF derivados do `.drawio`:** quando o binário `drawio` está disponível, o `.drawio` continua sendo a fonte de verdade em ambiente local e fora de serverless.
- **Pacote `pkg/diagram`:** wrapper público para embutir a geração em ferramentas de IaC, agentes de IA ou editores gráficos.
- **Editor web na Vercel:** Monaco com syntax highlighting, alternância PNG/draw.io, templates prontos (ALB+EC2, VPC+NAT, ALB+AutoScaling, Multi-Region) e download em um clique.
- **`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.

### 💻 Local: CLI

- awsdac flags -o, --drawio, -t, -c (compute)
- drawio (opcional) PNG/PDF a partir do .drawio (external)

### ▲ Vercel: Web

- Editor Monaco dac.moretes.com (frontend)
- Vercel Function handler em Go (compute)

### 🔧 Engine: Go

- pkg/diagram layout de grupos e ícones (compute)
- Definition files ícones AWS oficiais (data)

### 📤 Saída

- PNG / PDF (storage)
- .drawio fonte editável (storage)

### Fluxos

- dev -> cli: awsdac arquivo.yaml
- dev -> editor: cola o YAML
- editor -> fn: POST do YAML
- cli -> core: gera
- fn -> core: gera
- core -> defs: carrega definições
- core -> png: padrão
- core -> dio: --drawio
- dio -> drawiobin: export opcional
- drawiobin -> png

## 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`, prefira `go install` ou 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` (ou `awsdac.exe` no Windows). Node.js 18+ só é necessário para o frontend web.

3. **Confira a versão**: Rode `awsdac --version` antes 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.yaml` gera `output.png`. Use `-o` para nomear a saída e `-f` para 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.

_Quickstart: build do fork e os comandos que mais uso_

```bash
# 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.yaml
```

## Como 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

- [GitHub: fernando-moretes/tool-diagram-as-code](https://github.com/fernando-moretes/tool-diagram-as-code)
- [Editor web: dac.moretes.com](https://dac.moretes.com)
- [Upstream: awslabs/diagram-as-code](https://github.com/awslabs/diagram-as-code)
- [AWS Architecture Icons](https://aws.amazon.com/architecture/icons)

## 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.

## Links

- [GitHub repository](https://github.com/fernando-moretes/tool-diagram-as-code)
- [Homepage](https://dac.moretes.com)