Deep Dive : Gerar diagramas AWS com um agente de IA e Draw.io MCP

Para entender melhor uma infraestrutura, um bom diagrama é sempre apreciado. Mas criá-los manualmente leva tempo: encontrar os ícones certos, posicionar os elementos, traçar as conexões… O que me entusiasma hoje é poder automatizar tudo isso com IA.

Neste artigo mostro que é possível usar um agente de IA com o MCP Draw.io para gerar automaticamente diagramas de arquitetura AWS. Eu uso o Claude Code no meu contexto, mas essa abordagem funciona com qualquer agente compatível com MCP.

O ponto de partida: atualizar um esquema antigo

Eu já tinha um artigo sobre a infraestrutura deste blog datado de 2018 com um diagrama feito manualmente no Draw.io. A infraestrutura não mudou muito desde então — eu basicamente adicionei OAC (Origin Access Control) e uma CloudFront Function — mas os ícones da AWS evoluíram e eu quis atualizar o diagrama com as versões mais recentes.

Ao procurar soluções para automatizar isso, encontrei o Draw.io MCP Server com sua extensão para Chrome. Testei… e achei tão legal que decidi escrever um artigo para compartilhar a descoberta!

O MCP Draw.io: controlar o Draw.io com IA

O Draw.io MCP Server criado pelo Ladislav (lgazo) é um servidor MCP (Model Context Protocol) que permite controlar o Draw.io programaticamente. Na prática, isso significa que um agente de IA pode criar, modificar e organizar elementos em um diagrama do Draw.io.

As ferramentas disponíveis

Configuração necessária

Para que o agente de IA consiga comunicar-se com o Draw.io, é preciso configurar dois elementos como indicado na documentação do projeto:

1. Um servidor MCP local — configurado no arquivo de settings do seu agente (ex: .mcp.json para Claude Code)
2. A extensão Chrome Draw.io MCP — que faz a ponte entre o servidor MCP e a aplicação Draw.io no navegador

Com esses dois elementos em funcionamento, o agente pode manipular diretamente o canvas do Draw.io: criar shapes, posicioná-las, traçar conexões — tudo de forma programática.

Ao testar o MCP Draw.io, constatei que é preciso guiar o agente para obter um resultado limpo: não inventar recursos, usar os ícones AWS corretos, respeitar um posicionamento coerente, aplicar cores por categoria, evitar HTML nos textos… Por isso criei um skill Claude Code que codifica essas regras.

Criação do skill /aws-diagram

Um skill Claude Code é um ficheiro Markdown que define um workflow e regras. Quando invocamos /aws-diagram, o Claude Code carrega essas instruções e as aplica automaticamente.

O workflow

O skill segue um processo em 4 etapas:

1. Ler o código da infraestrutura (Terraform, CloudFormation)
2. Extrair os recursos AWS e suas relações
3. Construir o diagrama com os ícones oficiais da AWS
4. Adicionar as conexões com labels descritivos

## Workflow

1. **Read infrastructure code** (Terraform, CloudFormation, etc.)
2. **Extract AWS resources** and their relationships
3. **Build diagram** with official AWS icons
4. **Add connections** with descriptive labels

As regras críticas

Tive de codificar várias regras importantes no skill:

1. Nunca inventar recursos

Esse era o principal risco. Os LLMs tendem a “completar” o que lhes parece lógico. “Tem CloudFront, então deve haver Lambda@Edge para…” — Não! O diagrama deve representar exatamente o que existe no código, nada mais.

### NEVER invent resources

**Only diagram what actually exists in the infrastructure code.**

| Situation                  | Wrong                                         | Correct                                      |
| -------------------------- | --------------------------------------------- | -------------------------------------------- |
| No Lambda in Terraform     | Add Lambda@Edge because "it would make sense" | Don't add Lambda                             |
| CloudFront Function exists | Use Lambda icon                               | Use CloudFront icon with "CF Function" label |
| No WAF configured          | Add WAF for "security"                        | Don't add WAF                                |

2. Os usuários são externos

Os “Users” não são recursos AWS. Eles devem aparecer fora do grupo AWS Cloud.

### Users OUTSIDE the AWS Cloud

**Users are NOT AWS resources.** They represent external actors.

WRONG:
┌─────────────────────────────────┐
│ AWS Cloud │
│ [Users] → [Route53] → [CF] │ ❌ Users inside cloud
└─────────────────────────────────┘

CORRECT:
[Users] → ┌─────────────────────────┐
│ AWS Cloud │
│ [Route53] → [CF] → [S3] │ ✅ Users outside
└─────────────────────────┘

3. Sem HTML nos textos

O Draw.io não renderiza HTML. Se você escrever text: "S3<br>Private", verá literalmente <br> no diagrama.

### NEVER use HTML in text parameters

Draw.io does NOT render HTML tags in text fields. They display as raw text.

**FORBIDDEN (will show ugly raw HTML):**

text: "S3 Bucket<br>Private" ❌ Shows "<br>" literally
text: "Route 53&nbsp;DNS" ❌ Shows "&nbsp;" literally
text: "<font color='red'>ACM</font>" ❌ Shows raw HTML tags

**CORRECT (clean text):**

text: "S3 Bucket" ✅ Single line, clean
text: "Route 53" ✅ Service name only
text: "ACM" ✅ Simple label

4. Planejar o layout para evitar colisões

As arestas que se cruzam tornam o diagrama ilegível. O skill recomenda colocar o fluxo principal numa linha horizontal, e os serviços auxiliares acima ou abaixo.

### Rule 1: Main Flow on a Horizontal Line

Place the primary data flow (request path) on a single horizontal row:

[Entry] → [Service A] → [Service B] → [Service C]
y=300 y=300 y=300 y=300

### Rule 2: Auxiliary Services Above or Below

Services that connect TO a main service (not part of the flow) go above or below:

        [Auth]     [Edge Logic]     ← Auxiliary row (y=150)
           \           /
            \         /
             ↓       ↓

[Entry] → [Gateway] → [Compute] → [Storage] ← Main flow (y=300)

5. Anotações à direita, não abaixo

Os ícones da AWS têm seu rótulo automaticamente colocado abaixo. Se você adicionar anotações também abaixo, elas irão sobrepor a linha seguinte. Coloque-as à direita do ícone.

### Annotation Placement Rules

**CRITICAL: Place annotations to the RIGHT of icons, not below.**

**WRONG - Annotations below icons:**

[CloudFront] [S3]
|
"Cache Policies" ← Overlaps with next row!
"Security Headers"
|
[CloudFront Preview] ← Collision!

**CORRECT - Annotations to the RIGHT:**

[CloudFront] ── "Cache Policies: HTML 0s | Assets 1y"
| "Security: CSP | HSTS"
↓
[CloudFront Preview] ← No collision

O sistema de cores

Defini uma paleta coerente com as convenções AWS:

Para os fluxos de dados, uso cores por ambiente:

• Production : verde #4CAF50
• Preview : laranja #FF9800
• Configuration : cinza #AAAAAA (dashed)

### Colors by Category

| Category       | Color               | Services                                   |
| -------------- | ------------------- | ------------------------------------------ |
| **Networking** | `#8C4FFF` (violet)  | Route53, CloudFront, VPC, ELB, API Gateway |
| **Compute**    | `#ED7100` (orange)  | Lambda, EC2, ECS, Fargate                  |
| **Storage**    | `#7AA116` (green)   | S3, EFS, EBS                               |
| **Database**   | `#C925D1` (magenta) | RDS, DynamoDB, ElastiCache                 |
| **Security**   | `#DD344C` (red)     | ACM, IAM, WAF, Cognito                     |
| **General**    | `#232F3D` (gray)    | Users, Generic                             |

### AWS Icon Style Template

sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=<COLOR>;strokeColor=#ffffff;
dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;
fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;
resIcon=mxgraph.aws4.<SERVICE>;

### Edge Colors by Environment

| Environment   | Color     | Usage                  |
| ------------- | --------- | ---------------------- |
| Production    | `#4CAF50` | Main production flow   |
| Preview       | `#FF9800` | Staging environments   |
| Configuration | `#AAAAAA` | Dashed, non-data links |

Aplicação concreta: a infraestrutura jls42.org

Para testar o skill, utilizei-o na infraestrutura deste blog.

O código Terraform analisado

terraform/
├── cloudfront-astro.tf    # Distribution CloudFront prod
├── s3-astro.tf            # Bucket S3 privé avec OAC
├── acm-astro.tf           # Certificat SSL
├── route53.tf             # DNS
└── variables.tf           # Variables

A arquitetura extraída

O diagrama gerado

Aqui está o resultado final:

A partir de um prompt simples em linguagem natural:

«Analyse en profondeur l’infrastructure de ce projet puis réalise un super schéma de l’architecture AWS comme un pro. Juste l’infra de prod, pas preview ni legacy.»

🇵🇹 «Analisa em profundidade a infraestrutura deste projeto e depois faz um excelente diagrama da arquitetura AWS como um profissional. Só a infra de produção, nada de preview nem legacy.»

O Claude Code primeiro analisou os ficheiros Terraform para identificar a infraestrutura, depois carregou o skill /aws-diagram cujas instruções permitiram:

1. Criar os componentes principais (Users, Route53, CloudFront, S3, ACM)
2. Adicionar as anotações detalhadas (políticas de cache, headers de segurança, configuração do bucket…)
3. Traçar as conexões com labels (HTTPS, Alias DNS, OAC, TLS Cert…)
4. Adicionar serviços externos (Plausible Analytics, Gandi para emails)
5. Gerar uma legenda por categoria

Tudo respeitando um layout limpo com:

• A nuvem AWS dimensionada automaticamente (900×420px)
• Os Users à esquerda da nuvem
• Os serviços externos à direita
• Uma legenda abaixo do diagrama

O workflow completo: do Terraform ao vídeo

Levei a experiência mais além criando um vídeo de demonstração.

Gravação

Gravei a geração do diagrama em tempo real: 4 minutos e 10 segundos do Claude Code lendo o Terraform, criando os elementos um a um e construindo o diagrama diante dos meus olhos.

Pós-produção com FFmpeg

4 minutos é longo para uma demo. Usei o FFmpeg para criar uma versão acelerada com velocidades variáveis:

Resultado: um vídeo de 42 segundos em vez de 4 minutos, mantendo os momentos-chave em velocidade normal.

Narração com HeyGen

Para adicionar uma voz-off, escrevi um guião de narração, dividi o vídeo em segmentos de 30 segundos (limite do HeyGen) e gerei a voz em francês. As vozes básicas não me convenceram, então usei a função de design vocal deles que permite criar uma voz on-the-fly ajustando um prompt até encontrar o tom perfeito.

O resultado final é o vídeo que você pode ver no topo deste artigo.

Segundo exemplo: Arquitetura EKS Alta Disponibilidade

Para ilustrar o quão bem o MCP Draw.io funciona, aqui está um segundo exemplo mais complexo: uma arquitetura EKS (Elastic Kubernetes Service) altamente disponível. O MCP faz todo o trabalho de criação no Draw.io — eu só precisei fornecer um prompt detalhado.

Dessa vez, forneci um prompt detalhado descrevendo a arquitetura desejada:

Architecture EKS Hautement Disponible

Génère un diagramme d'architecture AWS EKS avec les composants suivants :

## Services AWS à inclure

### Externes (gauche du cloud)

- Users (icône utilisateurs générique)

### Networking

- Route 53 (DNS)
- Application Load Balancer (ALB) - dans les subnets publics
- NAT Gateway (3x, un par AZ)
- VPC avec 3 AZ

### Compute (subnets privés)

- EKS Control Plane (géré par AWS - représenter séparément)
- 3 Node Groups (un par AZ) avec pods à l'intérieur

### Storage

- EFS (stockage partagé cross-AZ)

### Security

- ACM (Certificate Manager)
- IAM (pour Pod Identity / IRSA)

### Observability

- CloudWatch (logs et métriques)

## Connexions à tracer

| Source            | Target      | Label               | Style       |
| ----------------- | ----------- | ------------------- | ----------- |
| Users             | Route 53    | HTTPS               | Solid green |
| Route 53          | ALB         | DNS Alias           | Solid green |
| ALB               | Node Groups | Traffic             | Solid green |
| ACM               | ALB         | TLS                 | Dashed gray |
| Node Groups       | EFS         | NFS Mount           | Solid green |
| EKS Control Plane | Node Groups | kubectl API         | Solid green |
| EKS Control Plane | IAM         | IRSA / Pod Identity | Dashed gray |
| Node Groups       | CloudWatch  | Logs / Metrics      | Dashed gray |

O resultado gerado

Este diagrama ilustra uma arquitetura Kubernetes pronta para produção com:

• 3 Availability Zones para alta disponibilidade
• NAT Gateways redundantes (um por AZ) para saída à Internet
• Node Groups distribuídos com pods em cada AZ
• EFS cross-AZ para armazenamento compartilhado persistente
• Control Plane gerido pela AWS separado visualmente
• IRSA (IAM Roles for Service Accounts) para a segurança dos pods

O MCP Draw.io interpretou corretamente a estrutura criando os grupos VPC e AZ, posicionando as NAT Gateways nos subnets públicos e os Node Groups nos subnets privados. O resultado oferece uma excelente base de trabalho para refinar depois conforme preferências visuais, ou corrigir eventuais erros — muito mais rápido do que começar do zero.

O que este projeto revela

Esta experiência destaca vários aspetos do meu modo de trabalhar:

• Automatizar a documentação: o código é a fonte de verdade, o diagrama deveria decorrer automaticamente dele
• Usar as ferramentas certas: o MCP Draw.io era exatamente o que eu precisava, não reinventei a roda
• Codificar as regras: os skills permitem capturar a expertise e evitar erros comuns — aplicável a qualquer tipo de diagrama Draw.io, não só AWS
• Testar em algo concreto: usei a minha própria infraestrutura como campo de experimentação
• Ir mais longe: da geração automática ao vídeo narrado, cada etapa foi uma oportunidade de aprender

O skill agora está integrado ao meu workflow. Da próxima vez que eu modificar a infraestrutura, poderei regenar o diagrama com um simples prompt.

Recursos

• Draw.io MCP Server por Ladislav (lgazo)
• MCP - Model Context Protocol por Anthropic
• Claude Code — a ferramenta CLI que uso no dia a dia

Se você usa um agente de codificação compatível com MCP e tem infraestruturas para documentar, encorajo a experimentar essa abordagem. É gratificante ver um diagrama limpo sendo construído automaticamente diante dos seus olhos.

Obrigado por ler — espero que este artigo tenha inspirado você a experimentar!

Este documento foi traduzido da versão fr para a língua pt usando o modelo gpt-5-mini. Para mais informações sobre o processo de tradução, consulte https://gitlab.com/jls42/ai-powered-markdown-translator