# diagram-as-code

Diagramas AWS a partir de YAML versionado no Git, com export draw.io e editor web

- 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-03T02:44:32Z

---

Este repositório é o meu fork do awslabs/diagram-as-code: um CLI em Go que desenha diagramas de infraestrutura AWS a partir de YAML. Eu acrescentei export nativo para draw.io, um pacote Go público para embutir em outras ferramentas e um editor web hospedado em dac.moretes.com.

## Por que mantenho este fork

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](https://aws.amazon.com/architecture/icons), 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 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`.
- **`.drawio` como fonte de verdade:** PNG e PDF podem ser gerados a partir do `.drawio` quando o binário `drawio` está disponível, no CLI local e em ambientes não serverless.
- **Pacote público `pkg/diagram`:** para embutir a geração em outras ferramentas Go, de IaC a agentes de IA.
- **Editor web em dac.moretes.com:** editor YAML com Monaco, alternância entre PNG e draw.io, quatro templates prontos (ALB+EC2, VPC+NAT, ALB+AutoScaling, Multi-Region) e download com um clique.
- **`cmd/api-dev`:** servidor local para testar o handler da API sem o Vercel CLI.

## Como um YAML vira diagrama

Duas portas de entrada, o CLI e o editor web, chegam ao mesmo motor em Go. A saída é PNG, PDF ou `.drawio`.

### 💻 Local: CLI

- awsdac cmd/awsdac (compute)
- CloudFormation -c / -d (beta) (external)

### ▲ Vercel: Web

- Editor web Monaco + TypeScript (frontend)
- Go Function Vercel Functions (compute)

### 🔧 Motor Go

- pkg/diagram parse + layout (compute)
- Definition files ícones AWS (data)
- internal/ctl/drawio.go export draw.io (compute)

### 📤 Saída

- PNG / PDF (storage)
- .drawio (storage)

### Fluxos

- dev -> cli: awsdac arquivo.yaml
- dev -> web: cola o YAML
- cfn -> cli: template CFN
- web -> fn: POST do YAML
- cli -> pkg: chama
- fn -> pkg: chama
- pkg -> defs: carrega ícones
- pkg -> png: renderiza
- pkg -> drawio: --drawio
- drawio -> dio: grava
- dio -> png: binário drawio, opcional

## Instalar e gerar o primeiro diagrama

1. **Sem instalar nada: use o editor web**: Abra dac.moretes.com, escolha um dos quatro templates e edite o YAML. Alterne entre PNG e draw.io e baixe o resultado. É o caminho mais rápido para avaliar se o formato serve para o seu time.

2. **Instale o CLI**: O README recomenda `npm install -g awsdac` (Node.js 14+), que baixa o binário certo para o seu SO e CPU. No macOS também há `brew install awsdac`. Com Go 1.21+, `go install` funciona. Confira com `awsdac --version`.

3. **Ou compile a partir do fonte**: `git clone` do repositório e `make build`, que gera `./awsdac` (ou `awsdac.exe` no Windows). Pré-requisitos: Go 1.21+, e Node.js 18+ só se for mexer no frontend web. É o caminho que garante que você está rodando exatamente o código do fork.

4. **Gere a partir de um exemplo**: `awsdac examples/alb-ec2.yaml` gera `output.png`. Use `-o` para escolher o nome, `-f` para sobrescrever sem confirmação e `--drawio` para sair em `.drawio`.

5. **Leve para o pipeline**: Como o binário não depende de navegador nem GUI, ele roda num job de CI comum. Gere o diagrama a cada merge e publique o artefato junto com a documentação.

_Quickstart com os comandos do README_

```bash
# install (Node.js 14+)
npm install -g awsdac
awsdac --version

# or build the fork from source (Go 1.21+)
git clone https://github.com/fernando-moretes/tool-diagram-as-code.git
cd tool-diagram-as-code
make build

# PNG (default output.png)
awsdac examples/alb-ec2.yaml

# custom name, overwrite without asking
awsdac my-architecture.yaml -o my-diagram.png -f

# draw.io file (fork extension)
awsdac examples/alb-ec2.yaml --drawio -o output.drawio

# PDF
awsdac my-architecture.yaml --pdf -o my-diagram.pdf

# [beta] diagram straight from a CloudFormation template
awsdac template.yaml -c -o from-cfn.png
```

## Como funciona por dentro

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.

> **Confira de onde vem o binário:** O README ainda aponta `go install` e os releases para `github.com/fernandofatech/diagram-as-code`, nome anterior à migração do repositório para a org `fernando-moretes`. O GitHub redireciona o clone, mas `npm install -g awsdac` e `brew install awsdac` podem entregar o binário do upstream, sem a flag `--drawio`. Se o export draw.io é o motivo de você estar aqui, rode `awsdac --help` e confirme que a flag aparece; se não aparecer, compile com `make build`.

## Onde ele se encaixa no fluxo de arquitetura

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.

## Perguntas frequentes

### Qual a diferença para o awslabs/diagram-as-code?

O motor de layout e o formato YAML são os do upstream. O fork acrescenta export `.drawio` nativo, o pacote público `pkg/diagram`, o servidor `cmd/api-dev` e o editor web hospedado na Vercel.

### Serve para diagramas que não são AWS?

Sim, via definition files adicionais, como o upstream já permite. Para carregá-los de uma URL fora do repositório oficial, é preciso `--allow-untrusted-definitions`.

### Consigo gerar o diagrama direto do meu CloudFormation?

Sim, com `-c`, mas a função está em beta. Para templates grandes, prefira `-d` para converter em YAML dac e ajustar a hierarquia à mão antes de desenhar.

### PDF funciona no editor web?

O editor web oferece PNG e draw.io. A geração de PNG/PDF a partir do `.drawio` depende do binário `drawio`, por isso fica restrita ao CLI local e a ambientes não serverless.

## 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 a infraestrutura no mesmo repositório, quando você quer gerar no CI sem navegador headless, ou quando o time termina os diagramas no draw.io e precisa de um `.drawio` editável como ponto de partida. Use o upstream da awslabs se PNG basta e você prefere a linha mantida pela própria AWS. Para diagramas conceituais sem ícones AWS, um editor visual ou Mermaid custa menos para manter.

## Links

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