Deep Dive : Generowanie diagramów AWS za pomocą agenta AI i Draw.io MCP

Aby mieć jasny obraz infrastruktury, dobry schemat zawsze się przydaje. Ręczne tworzenie ich zabiera jednak czas: trzeba znaleźć odpowiednie ikony, ustawić elementy, narysować połączenia… To, co mnie ekscytuje dziś, to możliwość zautomatyzowania tego wszystkiego przy pomocy AI.

W tym artykule pokazuję, że można użyć agenta AI z MCP Draw.io, by automatycznie generować diagramy architektury AWS. Używam Claude Code w swoim kontekście, ale podejście działa z każdym agentem kompatybilnym z MCP.

Punkt wyjścia: aktualizacja starego schematu

Miałem już artykuł o infrastrukturze tego bloga z 2018 roku ze schematem ręcznie zrobionym w Draw.io. Infrastruktura nie zmieniła się znacząco — dodałem głównie OAC (Origin Access Control) i funkcję CloudFront — ale ikony AWS ewoluowały i chciałem zaktualizować schemat do najnowszych wersji.

Szukając sposobów na automatyzację, natrafiłem na Serwer Draw.io MCP z rozszerzeniem do Chrome. Przetestowałem to… i uznałem, że to takie fajne, że postanowiłem napisać o tym artykuł, żeby podzielić się informacją!

MCP Draw.io: kontrolowanie Draw.io za pomocą AI

Serwer Draw.io MCP stworzony przez Ladislava (lgazo) to serwer MCP (Model Context Protocol), który pozwala programowo kontrolować Draw.io. W praktyce oznacza to, że agent AI może tworzyć, modyfikować i organizować elementy na diagramie Draw.io.

Dostępne narzędzia

Wymagane ustawienia

Aby agent AI mógł komunikować się z Draw.io, trzeba skonfigurować dwa elementy, jak opisano w dokumentacji projektu:

1. Lokalny serwer MCP — skonfigurowany w pliku ustawień agenta (np. .mcp.json dla Claude Code)
2. Rozszerzenie Chrome Draw.io MCP — które robi most między serwerem MCP a aplikacją Draw.io w przeglądarce

Gdy te dwa elementy są na miejscu, agent może bezpośrednio manipulować canvase’em Draw.io: tworzyć kształty, pozycjonować je, rysować połączenia — wszystko programowo.

Testując MCP Draw.io zauważyłem, że trzeba poprowadzić agenta, żeby uzyskać estetyczny wynik: nie wymyślać zasobów, używać właściwych ikon AWS, trzymać spójne pozycjonowanie, stosować kolory według kategorii, unikać HTML w tekstach… Dlatego stworzyłem skilla Claude Code, który koduje te zasady.

Tworzenie skilla /aws-diagram

Skill Claude Code to plik Markdown definiujący workflow i reguły. Gdy wywołujemy /aws-diagram, Claude Code ładuje te instrukcje i stosuje je automatycznie.

Workflow

Skill podąża procesem w 4 krokach:

1. Odczytanie kodu infrastruktury (Terraform, CloudFormation)
2. Wyodrębnienie zasobów AWS i ich relacji
3. Zbudowanie diagramu z wykorzystaniem oficjalnych ikon AWS
4. Dodanie połączeń z opisowymi etykietami

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

Krytyczne reguły

Musiałem zakodować kilka ważnych reguł w skillu:

1. Nigdy nie wymyślać zasobów

To była główna pułapka. LLM mają tendencję do „uzupełniania” tego, co wydaje im się logiczne. „Jest CloudFront, więc powinien być Lambda@Edge dla…” — Nie! Diagram musi dokładnie odzwierciedlać to, co jest w kodzie, nic więcej.

### 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. Użytkownicy są zewnętrzni

„Users” to nie zasoby AWS. Powinni pojawić się poza grupą 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. Żaden HTML w tekstach

Draw.io nie renderuje HTML. Jeśli wpiszesz text: "S3<br>Private", zobaczysz dosłownie <br> na diagramie.

### 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. Zaplanować layout, by unikać kolizji

Przecinające się krawędzie czynią diagram nieczytelnym. Skill zaleca umieścić główny przepływ na linii poziomej, a usługi pomocnicze nad lub pod nim.

### 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. Adnotacje po prawej, nie pod ikoną

Ikony AWS mają etykietę automatycznie umieszczoną pod ikoną. Jeśli dodasz adnotacje również pod spodem, będą nachodzić na następną linię. Umieszczaj je po prawej stronie ikony.

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

System kolorów

Zdefiniowałem spójną paletę zgodną z konwencjami AWS:

Dla przepływów danych używam kolorów środowisk:

• Production : zielony #4CAF50
• Preview : pomarańczowy #FF9800
• Configuration : szary #AAAAAA (przerywana)

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

Zastosowanie praktyczne: infrastruktura jls42.org

Aby przetestować skilla, użyłem go na infrastrukturze tego bloga.

Analizowany kod Terraform

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

Wyodrębniona architektura

Wygenerowany diagram

Oto wynik końcowy:

Na podstawie prostego polecenia w języku naturalnym:

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

🇵🇱 «Przeanalizuj szczegółowo infrastrukturę tego projektu, a następnie stwórz profesjonalny schemat architektury AWS. Tylko infra produkcyjna, bez preview i legacy.»

Claude Code najpierw przeanalizował pliki Terraform, aby zidentyfikować infrastrukturę, a potem załadował skilla /aws-diagram, którego instrukcje pozwoliły na:

1. Utworzenie głównych komponentów (Users, Route53, CloudFront, S3, ACM)
2. Dodanie szczegółowych adnotacji (polityki cache, nagłówki bezpieczeństwa, konfiguracja bucketów…)
3. Narysowanie połączeń z etykietami (HTTPS, alias DNS, OAC, certyfikat TLS…)
4. Dodanie usług zewnętrznych (Plausible Analytics, Gandi dla e-maili)
5. Wygenerowanie legendy według kategorii

Wszystko przy zachowaniu czytelnego layoutu:

• Chmura AWS automatycznie dostosowana (900×420px)
• Użytkownicy po lewej stronie chmury
• Usługi zewnętrzne po prawej
• Legenda pod diagramem

Pełny workflow: od Terraform do wideo

Posunąłem eksperyment dalej, tworząc wideo demonstracyjne.

Nagrywanie

Nagrałem generowanie diagramu w czasie rzeczywistym: 4 minuty 10 sekund Claude Code czytającego Terraform, tworzącego elementy jeden po drugim i budującego diagram na moich oczach.

Postprodukcja z FFmpeg

4 minuty to długo jak na demo. Użyłem FFmpeg, by stworzyć wersję przyspieszoną z różnymi prędkościami:

Wynik: wideo trwające 42 sekundy zamiast 4 minut, zachowujące kluczowe momenty w normalnej prędkości.

Narracja z HeyGen

Aby dodać lektora, napisałem scenariusz narracji, podzieliłem wideo na segmenty po 30 sekund (limit HeyGen) i wygenerowałem głos po francusku. Domyślne głosy mi nie odpowiadały, więc skorzystałem z funkcji design vocal, która pozwala stworzyć głos „na żywo” poprzez dopracowywanie promptu, aż znajdzie się idealny ton.

Końcowy efekt to wideo, które można obejrzeć na początku tego artykułu.

Drugi przykład: wysoka dostępność EKS

Aby pokazać, jak dobrze działa MCP Draw.io, oto drugi, bardziej złożony przykład: architektura EKS (Elastic Kubernetes Service) o wysokiej dostępności. MCP wykonał całą pracę tworzenia w Draw.io — jedyne, co musiałem zrobić, to dostarczyć szczegółowy prompt.

Tym razem dostarczyłem szczegółowy prompt opisujący pożądaną architekturę:

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 |

Wygenerowany rezultat

Ten diagram ilustruje środowisko Kubernetes gotowe do produkcji z:

• 3 strefy dostępności dla wysokiej dostępności
• Redundantne NAT Gatewaye (po jednym na AZ) dla wyjścia do internetu
• Node Groups rozmieszczone z podami w każdej AZ
• EFS cross-AZ dla współdzielonego, trwałego storage’u
• Control Plane zarządzany przez AWS oddzielony wizualnie
• IRSA (IAM Roles for Service Accounts) dla zabezpieczenia podów

MCP Draw.io poprawnie zinterpretował strukturę, tworząc grupy VPC i AZ, umieszczając NAT Gatewaye w subnetach publicznych i Node Groups w subnetach prywatnych. Wynik daje doskonałą bazę do dalszej pracy i dopracowań według własnych preferencji lub korekt ewentualnych błędów — znacznie szybciej niż zaczynając od zera.

Co odsłania ten projekt

To doświadczenie uwypukla kilka elementów mojego sposobu pracy:

• Automatyzacja dokumentacji: kod jest źródłem prawdy, diagram powinien z niego wynikać automatycznie
• Używanie właściwych narzędzi: MCP Draw.io okazał się dokładnie tym, czego potrzebowałem — nie wymyślałem koła na nowo
• Kodowanie reguł: skill pozwala uchwycić wiedzę ekspercką i unikać typowych błędów — stosowalne do każdego typu diagramu w Draw.io, nie tylko AWS
• Testy na konkretnych przykładach: użyłem własnej infrastruktury jako pola do eksperymentów
• Poszerzanie eksperymentu: od automatycznego generowania po wideo z narracją — każda faza była okazją do nauki

Skill jest teraz zintegrowany z moim workflow. Następnym razem, gdy zmienię infrastrukturę, będę mógł wygenerować diagram ponownie jednym prostym promptem.

Zasoby

• Serwer Draw.io MCP — Ladislav (lgazo)
• MCP - Model Context Protocol — Anthropic
• Claude Code — narzędzie CLI, którego używam na co dzień

Jeśli używasz agenta kodującego kompatybilnego z MCP i masz infrastrukturę do udokumentowania, zachęcam do wypróbowania tego podejścia. To satysfakcjonujące widzieć, jak czytelny diagram buduje się automatycznie na twoich oczach.

Dziękuję za lekturę — mam nadzieję, że artykuł zachęcił Cię do eksperymentów!

Ten dokument został przetłumaczony z wersji fr na język pl przy użyciu modelu gpt-5-mini. Aby uzyskać więcej informacji na temat procesu tłumaczenia, zobacz https://gitlab.com/jls42/ai-powered-markdown-translator