# diagram-as-code

Gere diagramas AWS a partir de YAML — CLI em Go com frontend web e exportação 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/fernandofatech/diagram-as-code

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

- Language: Go

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

- Stars: 1

- Forks: 0

- Updated: 2026-05-16T02:43:37Z

---

diagram-as-code é uma CLI em Go que converte arquivos YAML em diagramas de arquitetura AWS, com extensões que adicionei ao fork original: exportação nativa para draw.io, um frontend web com editor Monaco hospedado em Vercel e um pacote público para embedding em ferramentas externas.

## O que é e por que existe

Este repositório é um fork de [awslabs/diagram-as-code](https://github.com/awslabs/diagram-as-code), mantido por mim como parte do portfólio de arquitetura em [fernando.moretes.com](https://fernando.moretes.com). O projeto original resolve um problema real: diagramas de arquitetura costumam viver em ferramentas visuais desconectadas do código — Lucidchart, draw.io manual, PowerPoint — e envelhecem rapidamente. Ao descrever a infraestrutura em YAML versionável, o diagrama passa a ser tratado como qualquer outro artefato de engenharia: revisado em PR, testado em CI e rastreado no Git.

O upstream já entregava a CLI e conformidade com as diretrizes visuais da AWS. O que adicionei neste fork:

- **Exportação draw.io nativa** via flag `--drawio`, implementada inteiramente em Go (`internal/ctl/drawio.go`), sem dependência de binário externo para o caso serverless.
- **Frontend web** hospedado em [dac.moretes.com](https://dac.moretes.com), com editor Monaco, preview ao vivo, templates embutidos e download em PNG ou draw.io — zero instalação local.
- **Backend serverless** via Vercel Functions, que executa o mesmo binário Go da CLI por trás da API.
- **Pacote público `pkg/diagram`** para quem quiser embeddar a geração de diagramas em outras ferramentas Go, pipelines de IaC ou agentes de IA.

O resultado é uma ferramenta que funciona tanto no terminal quanto no browser, mantendo o YAML como fonte da verdade.

## Destaques do fork

- CLI em Go puro — sem dependência de browser headless, Graphviz ou bibliotecas de imagem externas.
- Exportação nativa para draw.io (`--drawio`) implementada em Go, mantendo o `.drawio` como fonte da verdade para edição posterior.
- Frontend web em [dac.moretes.com](https://dac.moretes.com) com editor Monaco, templates prontos e download direto — sem instalar nada.
- Compatível com CI/CD: roda em container, aceita flags de automação (`-f`, `--verbose`) e integra com pipelines de IaC.
- Pacote `pkg/diagram` público para embedding em ferramentas externas, agentes de IA ou GUIs de desenho.
- Suporte a templates CloudFormation (`--cfn-template`) e geração reversa de YAML a partir de stacks existentes (`--dac-file`).

## Como as peças se conectam

O mesmo núcleo Go serve tanto a CLI local quanto o backend serverless do frontend web.

### 👤 Author / User

- Engineer (terminal) (user)
- Visitor (browser) (user)

### 📄 Input

- YAML diagram file (data)
- CloudFormation template (data)

### 💻 CLI (Go binary — awsdac)

- awsdac cmd/awsdac (compute)
- Diagram engine internal/ctl (compute)
- draw.io exporter drawio.go (compute)
- pkg/diagram (public API) (compute)

### ☁️ Vercel (Web)

- Web editor dac.moretes.com (frontend)
- Vercel Function cmd/api-dev (compute)

### 📦 Output

- PNG diagram (storage)
- .drawio file (storage)

### Fluxos

- user_cli -> yaml: escreve
- user_cli -> cfn: fornece
- yaml -> cli: entrada
- cfn -> cli: --cfn-template
- cli -> core: processa
- core -> drawio_pkg: --drawio
- core -> png: gera
- drawio_pkg -> drawio: exporta
- pkg -> core: embeds
- user_web -> frontend: edita YAML
- frontend -> api: POST /generate
- api -> core: invoca
- api -> frontend: retorna PNG/.drawio
- frontend -> user_web: download

## Instalação e uso

1. **Instalar via npm (recomendado — todas as plataformas)** — Requer Node.js 14+. Baixa o binário correto para seu OS e CPU automaticamente.
```bash
npm install -g awsdac
awsdac --version
```

2. **Instalar via Go (requer Go 1.21+)** — ```bash
go install github.com/fernandofatech/diagram-as-code/cmd/awsdac@latest
```

3. **Compilar a partir do código-fonte** — ```bash
git clone https://github.com/fernandofatech/diagram-as-code.git
cd diagram-as-code
make build   # produz ./awsdac (ou awsdac.exe no Windows)
```
Pré-requisitos: Go 1.21+ · Node.js 18+ (apenas para o frontend web)

4. **Gerar um diagrama PNG** — ```bash
awsdac examples/alb-ec2.yaml
# saída padrão: output.png

awsdac my-architecture.yaml -o my-diagram.png
```

5. **Exportar para draw.io** — ```bash
awsdac examples/alb-ec2.yaml --drawio -o output.drawio
```
O arquivo `.drawio` pode ser aberto no draw.io desktop ou web para edição posterior.

6. **Gerar diagrama a partir de um template CloudFormation** — ```bash
awsdac my-stack.yaml --cfn-template -o infra-diagram.png
```
Esta funcionalidade está em beta. Use `--dac-file` para gerar o YAML intermediário e inspecionar antes de renderizar.

7. **Usar o frontend web (sem instalação)** — Acesse [dac.moretes.com](https://dac.moretes.com), escolha um template embutido (ALB+EC2, VPC+NAT, ALB+AutoScaling, Multi-Region) ou cole seu próprio YAML, selecione o formato de saída (PNG ou draw.io) e clique em download.

_Exemplo mínimo de YAML — ALB na frente de duas instâncias EC2_

```yaml
# examples/alb-ec2.yaml (simplified)
Diagram:
  Title: ALB + EC2
  Resources:
    ALB:
      Type: AWS::ElasticLoadBalancingV2::LoadBalancer
      Direction: right
      Children:
        - EC2a
        - EC2b
    EC2a:
      Type: AWS::EC2::Instance
    EC2b:
      Type: AWS::EC2::Instance
```

## Como funciona internamente

O binário `awsdac` lê o arquivo YAML de entrada e o desserializa em uma estrutura de grafo interno. Cada nó corresponde a um recurso AWS tipado (EC2, ALB, VPC, etc.) definido em arquivos de definição que mapeiam tipos CloudFormation para ícones e metadados visuais conformes com as [diretrizes de ícones da AWS](https://aws.amazon.com/architecture/icons). O engine calcula automaticamente posições e tamanhos de grupos, sem exigir coordenadas manuais no YAML.

Para saída PNG, o engine renderiza diretamente em Go usando a biblioteca de imagens padrão — sem Chromium, sem Graphviz, sem dependências de sistema operacional. Isso é o que torna o binário adequado para containers Alpine e pipelines CI sem GUI.

Para saída draw.io, o pipeline em `internal/ctl/drawio.go` serializa o mesmo grafo interno para o formato XML do draw.io, incluindo assets embutidos (`drawio_assets.go`). O arquivo `.drawio` resultante é editável no draw.io desktop ou web, o que é útil quando o diagrama gerado precisa de ajustes manuais antes de ser publicado.

O servidor de desenvolvimento local (`cmd/api-dev`) replica o handler da Vercel Function localmente, permitindo testar o backend sem o Vercel CLI. O frontend TypeScript/React em Vercel consome essa mesma API, enviando o YAML via POST e recebendo o binário do diagrama de volta para download direto no browser.

A separação entre `internal/ctl` (lógica de renderização) e `pkg/diagram` (API pública) é intencional: permite que ferramentas externas importem o pacote Go sem depender dos detalhes internos do CLI.

> **Nota do mantenedor:** Mantenho este fork principalmente para demonstrar integração de ferramentas de IaC com geração automatizada de documentação visual. O frontend web em [dac.moretes.com](https://dac.moretes.com) é o ponto de entrada mais rápido para quem quer experimentar sem instalar nada. Para uso em pipelines CI, a instalação via npm (`npm install -g awsdac`) é a rota mais portável entre Linux, macOS e Windows. O suporte a CloudFormation (`--cfn-template`) ainda está em beta — funciona para stacks simples, mas diagramas complexos podem precisar de ajustes manuais no YAML gerado.

## Perguntas frequentes

### Este fork é compatível com o upstream awslabs/diagram-as-code?

Sim. Todo YAML válido para o upstream funciona aqui. As extensões (--drawio, pkg/diagram, frontend web) são aditivas e não quebram a interface existente.

### Posso usar isso para diagramas que não são AWS?

Sim, com ressalvas. O engine suporta arquivos de definição customizados via --override-def-file, o que permite criar recursos não-AWS. A flag --allow-untrusted-definitions é necessária para definições fora do repositório oficial.

### O frontend web envia meu YAML para algum servidor?

Sim — o YAML é enviado via POST para a Vercel Function que executa o binário Go. Não há persistência: o diagrama é gerado e retornado imediatamente, sem armazenamento. Para dados sensíveis, use a CLI local.

### Como testar o backend da API localmente sem o Vercel CLI?

Use o servidor de desenvolvimento incluído: `go run ./cmd/api-dev`. Ele replica o handler da Vercel Function em localhost.

## Para quem é útil

Este projeto é útil para engenheiros e arquitetos que já versionam infraestrutura como código e querem manter diagramas de arquitetura no mesmo fluxo — revisados em PR, gerados em CI, rastreados no Git. A CLI é suficiente para a maioria dos casos de automação. O frontend web em [dac.moretes.com](httpsac.moretes.com) é o caminho mais rápido para experimentar ou para compartilhar diagramas com stakeholders que não têm ambiente de desenvolvimento. A exportação draw.io é o diferencial quando o diagrama precisa ser editado manualmente depois de gerado — por exemplo, para apresentações ou documentação técnica que exige ajustes visuais finos. Não é uma ferramenta para quem precisa de diagramas altamente customizados com layouts complexos; para isso, o draw.io ou Lucidchart manual ainda são mais flexíveis. O valor está na automação, no versionamento e na integração com pipelines de IaC.

## Referências

- [fernandofatech/diagram-as-code — GitHub](https://github.com/fernandofatech/diagram-as-code)
- [dac.moretes.com — Web frontend (live)](https://dac.moretes.com)
- [awslabs/diagram-as-code — Upstream repository](https://github.com/awslabs/diagram-as-code)
- [AWS Architecture Icons — Guidelines](https://aws.amazon.com/architecture/icons)
- [Introduction Guide — doc/introduction.md](https://github.com/fernandofatech/diagram-as-code/blob/main/doc/introduction.md)

## Links

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