Deep Dive : Generare diagrammi AWS con un agente IA e Draw.io MCP

Per avere una visione chiara di un’infrastruttura, un buon diagramma è sempre apprezzabile. Ma crearli a mano richiede tempo: trovare le icone giuste, posizionare gli elementi, tracciare le connessioni… Ciò che mi appassiona oggi è poter automatizzare tutto questo con l’IA.

In questo articolo vi mostro che è possibile usare un agente IA con il MCP Draw.io per generare automaticamente diagrammi di architettura AWS. Io uso Claude Code nel mio contesto, ma questo approccio funziona con qualsiasi agente compatibile MCP.

Il punto di partenza: aggiornare un vecchio schema

Avevo già un articolo sull’infrastruttura di questo blog risalente al 2018 con uno schema realizzato manualmente in Draw.io. L’infrastruttura non è cambiata molto da allora — ho essenzialmente aggiunto OAC (Origin Access Control) e una CloudFront Function — ma le icone AWS sono evolute e volevo aggiornare lo schema con le versioni più recenti.

Cercando soluzioni per automatizzare questo processo, mi sono imbattuto nel Draw.io MCP Server con la sua estensione Chrome. Ho provato… e l’ho trovato così interessante che ho deciso di scriverne un articolo per condividerlo!

Il MCP Draw.io: controllare Draw.io con l’IA

Il Draw.io MCP Server creato da Ladislav (lgazo) è un server MCP (Model Context Protocol) che permette di controllare Draw.io programmativamente. In pratica, ciò significa che un agente IA può creare, modificare e organizzare elementi in un diagramma Draw.io.

Gli strumenti disponibili

Requisiti di configurazione

Per permettere all’agente IA di comunicare con Draw.io, è necessario configurare due elementi come indicato nella documentazione del progetto:

1. Un server MCP locale — configurato nel file di settings del vostro agente (es: .mcp.json per Claude Code)
2. L’estensione Chrome Draw.io MCP — che fa da ponte tra il server MCP e l’applicazione Draw.io nel browser

Una volta che questi due elementi sono in funzione, l’agente può manipolare direttamente la tela Draw.io: creare forme, posizionarle, tracciare connessioni, tutto in modo programmatico.

Nel testare il MCP Draw.io, ho constatato che è necessario guidare l’agente per ottenere un risultato pulito: non inventare risorse, usare le icone AWS corrette, rispettare un posizionamento coerente, applicare i colori per categoria, evitare l’HTML nei testi… Per questo ho creato un skill Claude Code che codifica queste regole.

Creazione dello skill /aws-diagram

Uno skill Claude Code è un file Markdown che definisce un workflow e delle regole. Quando si invoca /aws-diagram, Claude Code carica queste istruzioni e le applica automaticamente.

Il workflow

Lo skill segue un processo in 4 fasi:

1. Leggere il codice dell’infrastruttura (Terraform, CloudFormation)
2. Estrarre le risorse AWS e le loro relazioni
3. Costruire il diagramma con le icone ufficiali AWS
4. Aggiungere le connessioni con etichette descrittive

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

Le regole critiche

Ho dovuto codificare diverse regole importanti nello skill:

1. Non inventare mai risorse

Questo era il principale tranello. I LLM tendono a “completare” ciò che considerano logico. “C’è CloudFront, quindi dovrebbe esserci Lambda@Edge per…” — No! Il diagramma deve rappresentare esattamente ciò che esiste nel codice, nient’altro.

### 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. Gli utenti sono esterni

Gli “Users” non sono risorse AWS. Devono apparire al di fuori del gruppo 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. Niente HTML nei testi

Draw.io non rende l’HTML. Se scrivi text: "S3<br>Private", vedrai letteralmente <br> nel diagramma.

### 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. Pianificare il layout per evitare collisioni

Gli edge che si incrociano rendono il diagramma illeggibile. Lo skill raccomanda di posizionare il flusso principale su una linea orizzontale, e i servizi ausiliari sopra o sotto.

### 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. Annotazioni a destra, non sotto

Le icone AWS hanno la loro etichetta automaticamente posizionata sotto. Se aggiungete annotazioni anche sotto, si sovrapporranno alla riga successiva. Mettetale a destra dell’icona.

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

Il sistema di colori

Ho definito una palette coerente con le convenzioni AWS:

Per i flussi di dati, utilizzo colori per ambiente:

• Production : verde #4CAF50
• Preview : arancione #FF9800
• Configuration : grigio #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 |

Applicazione concreta: l’infrastruttura jls42.org

Per testare lo skill, l’ho usato sull’infrastruttura di questo blog.

Il codice Terraform analizzato

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

L’architettura estratta

Il diagramma generato

Ecco il risultato finale:

A partire da un semplice prompt in linguaggio naturale:

«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.»

🇮🇹 «Analizza in profondità l’infrastruttura di questo progetto poi realizza un super schema dell’architettura AWS come un professionista. Solo l’infra di prod, non preview né legacy.»

Claude Code ha prima analizzato i file Terraform per identificare l’infrastruttura, poi ha caricato lo skill /aws-diagram le cui istruzioni hanno permesso di:

1. Creare i componenti principali (Utenti, Route53, CloudFront, S3, ACM)
2. Aggiungere le annotazioni dettagliate (cache policies, security headers, configurazione del bucket…)
3. Tracciare le connessioni con etichette (HTTPS, DNS Alias, OAC, TLS Cert…)
4. Aggiungere i servizi esterni (Plausible Analytics, Gandi per le email)
5. Generare una legenda per categoria

Il tutto rispettando un layout pulito con:

• Il cloud AWS dimensionato automaticamente (900×420px)
• Gli Utenti a sinistra del cloud
• I servizi esterni a destra
• Una legenda sotto il diagramma

Il workflow completo: da Terraform al video

Ho portato l’esperienza oltre creando un video dimostrativo.

Registrazione

Ho registrato la generazione del diagramma in tempo reale: 4 minuti e 10 secondi di Claude Code che legge il Terraform, crea gli elementi uno per uno, e costruisce il diagramma davanti ai miei occhi.

Post-produzione con FFmpeg

4 minuti sono lunghi per una demo. Ho usato FFmpeg per creare una versione accelerata con velocità variabili:

Risultato: un video di 42 secondi invece di 4 minuti, mantenendo i momenti chiave a velocità normale.

Narrazione con HeyGen

Per aggiungere una voce narrante, ho scritto uno script di narrazione, suddiviso il video in segmenti da 30 secondi (limite HeyGen) e generato la voce in francese. Le voci di base non mi convincevano, quindi ho usato la loro funzione di design vocale che permette di creare una voce al volo regolando un prompt fino a trovare il tono perfetto.

Il risultato finale è il video che potete vedere in cima a questo articolo.

Secondo esempio: Architettura EKS Alta Disponibilità

Per illustrare quanto bene funziona il MCP Draw.io, ecco un secondo esempio più complesso: un’architettura EKS (Elastic Kubernetes Service) altamente disponibile. Il MCP si occupa di tutto il lavoro di creazione in Draw.io — io ho soltanto fornito un prompt dettagliato.

Questa volta ho fornito un prompt dettagliato descrivendo l’architettura desiderata:

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 |

Il risultato generato

Questo diagramma illustra un’architettura Kubernetes pronta per la produzione con:

• 3 Availability Zone per l’alta disponibilità
• NAT Gateways ridondanti (uno per AZ) per l’uscita internet
• Node Groups distribuiti con pod in ogni AZ
• EFS cross-AZ per lo storage condiviso persistente
• Control Plane gestito da AWS separato visivamente
• IRSA (IAM Roles for Service Accounts) per la sicurezza dei pod

Il MCP Draw.io ha interpretato correttamente la struttura creando i gruppi VPC e AZ, posizionando le NAT Gateways nelle subnet pubbliche e i Node Groups nelle subnet private. Il risultato fornisce una ottima base di lavoro da rifinire poi secondo le proprie preferenze visive, o correggere eventuali errori — molto più veloce che partire da zero.

Ciò che rivela questo progetto

Questa esperienza illustra diversi aspetti del mio modo di lavorare:

• Automatizzare la documentazione: il codice è la fonte di verità, il diagramma dovrebbe derivarne automaticamente
• Usare gli strumenti giusti: il MCP Draw.io era esattamente ciò che mi serviva, non ho reinventato la ruota
• Codificare le regole: gli skill permettono di catturare l’expertise ed evitare errori comuni — applicabile a qualsiasi tipo di diagramma Draw.io, non solo AWS
• Testare sul concreto: ho usato la mia infrastruttura come campo di sperimentazione
• Spingere l’esplorazione: dalla generazione automatica al video narrato, ogni passo è stata un’occasione per imparare

Lo skill è ora integrato nel mio workflow. La prossima volta che modificherò l’infrastruttura, potrò rigenerare il diagramma con un semplice prompt.

Risorse

• Draw.io MCP Server di Ladislav (lgazo)
• MCP - Model Context Protocol di Anthropic
• Claude Code — lo strumento CLI che utilizzo quotidianamente

Se usate un agente di coding compatibile MCP e avete infrastrutture da documentare, vi incoraggio a provare questo approccio. È soddisfacente vedere un diagramma pulito costruirsi automaticamente davanti ai vostri occhi.

Grazie per aver letto, spero che questo articolo vi abbia dato voglia di sperimentare!

Questo documento è stato tradotto dalla versione fr alla lingua it utilizzando il modello gpt-5-mini. Per ulteriori informazioni sul processo di traduzione, consultare https://gitlab.com/jls42/ai-powered-markdown-translator