Diagrammi architetturali con AI generativa 🗺️

Perché generare diagrammi con l’AI? 🧠

Se pensi che disegnare diagrammi architetturali sia un’attività rilassante, probabilmente non hai mai dovuto allineare a mano decine di rettangoli in PowerPoint. L’AI generativa, invece, può trasformare questa fatica in un processo quasi piacevole: basta descrivere l’architettura e lasciar fare il lavoro sporco all’algoritmo.

• Risparmi tempo (e mouse)
• Riduci errori e dimenticanze
• Standardizzi la rappresentazione
• Faciliti la collaborazione

⚠️ Nota importante: Anche se l’AI è brava a disegnare, tu sei ancora responsabile della correttezza! Rivedi sempre i diagrammi generati prima di mostrarli al team (o al capo).

I vantaggi di MermaidJS per la documentazione 📊

MermaidJS è la matita digitale degli architetti cloud: semplice, testuale, integrabile ovunque e perfetta per essere processata sia dagli umani che dalle macchine (e dagli sviluppatori che odiano i drag&drop). Usare MermaidJS con l’AI significa:

• Strutturare le informazioni in modo chiaro e coerente
• Ridurre la sindrome del “rettangolo volante”
• Favorire la riusabilità e la coerenza tra i diagrammi
• Essere facilmente integrato in piattaforme di documentazione e versionamento
• Consentire la revisione tramite Git (e non tramite screenshot su Slack)

Come funziona la generazione assistita di diagrammi 🪄

1. Definisci i componenti chiave: quali servizi, risorse e connessioni vuoi rappresentare?
2. Scegli una tipologia di diagramma: meglio se già collaudato dal team.
3. Prompta l’AI: fornisci la descrizione architetturale e chiedi di generare il diagramma in formato MermaidJS.
4. Rivedi e personalizza: l’AI è brava, ma tu sei meglio! Aggiungi dettagli, correggi imprecisioni e adatta la visualizzazione.

Pro tip: più dettagli fornisci nel prompt, più il diagramma sarà fedele all’architettura reale. L’AI non ha ancora la sfera di cristallo (ma ci sta lavorando).

Esempio pratico: architettura cloud su GCP ☁️

Un prompt strutturato come quello che segue, unito a una descrizione dettagliata dell’architettura, permette all’AI di produrre diagrammi chiari e coerenti, riducendo al minimo le ambiguità e le interpretazioni creative (che, si sa, non sempre sono gradite in ambito tecnico).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

Ti fornirò degli appunti che descrivono un’architettura cloud (es. componenti come VM, container, load balancer, storage, Pub/Sub, API Gateway, ecc.). Analizza il testo e:
1. Identifica i principali componenti dell’architettura (servizi, risorse cloud, connessioni).
2. Rappresenta visivamente l’architettura usando un diagramma MermaidJS, preferibilmente con graph TD o graph LR se si tratta di una topologia statica o sequenceDiagram se il focus è sul flusso delle richieste.
3. Assicurati di:
 - Usare nomi chiari e coerenti per ciascun nodo, senz autilizzare parentesi
 - Mostrare le relazioni tra i componenti (es. chi comunica con chi)
 - Rispettare una logica dall’esterno verso l’interno o dal frontend al backend
 - Includere commenti nel codice Mermaid, se utile per la comprensione
 - Applicare una forma corente per la diversa tipologia di componente
 - Applicare uno stile corente per la diversa tipologia di componente
4. Restituisci solo il blocco di codice Mermaid pronto da incollare in un markdown (```mermaid … ```)

Fornendo all’AI una descrizione come questa, puoi ottenere in pochi secondi un diagramma architetturale pronto all’uso, perfetto per essere inserito nella documentazione o condiviso con il team. Ecco un esempio di input:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

L’applicazione è composta da diversi microservizi distribuiti su Google Cloud Platform.  
Gli utenti interagiscono tramite una Web App servita da Cloud Run (Frontend Service), accessibile tramite un Cloud Load Balancer con HTTPS.  
Il traffico è gestito da un API Gateway che autentica le richieste con Identity Platform.  
Le richieste vengono indirizzate a vari servizi backend in Cloud Run:  
- Auth Service, che gestisce login e registrazione  
- Order Service, che gestisce ordini degli utenti  
- Inventory Service, che gestisce la disponibilità dei prodotti  
L’Order Service pubblica eventi su un topic Pub/Sub “order-events”.  
Il Payment Service è in ascolto di questi eventi per processare i pagamenti.  
Tutti i servizi scrivono log su Cloud Logging e metriche su Cloud Monitoring.  
Il database principale è Cloud SQL (PostgreSQL), usato da Auth e Order Service.  
Inventory Service accede a Firestore per dati di magazzino.  
Cloud Storage è usato per salvare documenti PDF delle ricevute.  
I segreti sono gestiti con Secret Manager.  
Un sistema CI/CD deploya tutto su più ambienti tramite Cloud Build e Artifact Registry.

Il risultato sarà un diagramma MermaidJS che rappresenta fedelmente la struttura e le relazioni tra i componenti descritti, con stili e forme differenziate per ogni tipologia di servizio o risorsa:

    graph TD

  %% === Client Layer ===
  User[User Browser]

  %% === Ingress Layer ===
  LoadBalancer[(Cloud Load Balancer HTTPS)]
  APIGateway[[API Gateway]]
  IdentityPlatform[[Identity Platform]]

  %% === Frontend ===
  FrontendService[[Cloud Run Frontend Service]]

  %% === Backend Services ===
  AuthService[[Cloud Run Auth Service]]
  OrderService[[Cloud Run Order Service]]
  InventoryService[[Cloud Run Inventory Service]]
  PaymentService[[Cloud Run Payment Service]]

  %% === Eventing and Messaging ===
  PubSub[(PubSub Topic order-events)]

  %% === Data Layer ===
  CloudSQL[(Cloud SQL PostgreSQL)]
  Firestore[(Firestore Inventory Data)]
  CloudStorage[(Cloud Storage Receipts)]

  %% === Security ===
  SecretManager[[Secret Manager]]

  %% === Observability ===
  CloudLogging[[Cloud Logging]]
  CloudMonitoring[[Cloud Monitoring]]

  %% === CI/CD ===
  CloudBuild[[Cloud Build]]
  ArtifactRegistry[[Artifact Registry]]

  %% === Connections: Ingress ===
  User --> LoadBalancer
  LoadBalancer --> APIGateway
  APIGateway --> IdentityPlatform
  IdentityPlatform --> FrontendService

  %% === Connections: Frontend to Backend ===
  FrontendService --> AuthService
  FrontendService --> OrderService
  FrontendService --> InventoryService

  %% === Backend Service Dependencies ===
  AuthService --> CloudSQL
  OrderService --> CloudSQL
  OrderService --> PubSub
  PaymentService --> PubSub
  InventoryService --> Firestore
  OrderService --> CloudStorage

  %% === Secrets and Config ===
  AuthService --> SecretManager
  OrderService --> SecretManager
  PaymentService --> SecretManager
  InventoryService --> SecretManager

  %% === Observability Connections ===
  AuthService --> CloudLogging
  OrderService --> CloudLogging
  InventoryService --> CloudLogging
  PaymentService --> CloudLogging
  FrontendService --> CloudLogging

  AuthService --> CloudMonitoring
  OrderService --> CloudMonitoring
  InventoryService --> CloudMonitoring
  PaymentService --> CloudMonitoring
  FrontendService --> CloudMonitoring

  %% === CI/CD Connections ===
  CloudBuild --> ArtifactRegistry
  CloudBuild --> FrontendService
  CloudBuild --> AuthService
  CloudBuild --> OrderService
  CloudBuild --> InventoryService
  CloudBuild --> PaymentService

  %% === Styles ===
  classDef clientStyle fill:#D0E6FF,stroke:#5B9BD5,color:#1B365D,stroke-width:2px
  classDef ingressStyle fill:#DFF0D8,stroke:#5CB85C,color:#3C763D,stroke-width:2px
  classDef serviceStyle fill:#FCF8E3,stroke:#F0AD4E,color:#8A6D3B,stroke-width:2px
  classDef dataStyle fill:#F5EAF7,stroke:#B67CCF,color:#4B296B,stroke-width:2px
  classDef securityStyle fill:#FBE9E7,stroke:#EF6C00,color:#BF360C,stroke-width:2px
  classDef observabilityStyle fill:#E0F7FA,stroke:#00ACC1,color:#006064,stroke-width:2px
  classDef cicdStyle fill:#E8F5E9,stroke:#43A047,color:#1B5E20,stroke-width:2px
  classDef messagingStyle fill:#F3E5F5,stroke:#8E24AA,color:#4A148C,stroke-width:2px

  %% === Class Assignments ===
  class User clientStyle
  class LoadBalancer,APIGateway,IdentityPlatform ingressStyle
  class FrontendService,AuthService,OrderService,InventoryService,PaymentService serviceStyle
  class CloudSQL,Firestore,CloudStorage dataStyle
  class SecretManager securityStyle
  class CloudLogging,CloudMonitoring observabilityStyle
  class CloudBuild,ArtifactRegistry cicdStyle
  class PubSub messagingStyle
  

Dal diagramma alla documentazione tecnica 📚

Un diagramma ben fatto è solo l’inizio: puoi chiedere all’AI di generare anche la documentazione tecnica a partire dallo stesso prompt, oppure di spiegare le scelte architetturali con una RFC o un ADR. L’approccio è lo stesso: template chiari, prompt dettagliati e un po’ di sana revisione umana.

• RFC: per descrivere proposte tecniche e motivazioni
• ADR: per tracciare decisioni architetturali e conseguenze
• Runbook: per le procedure operative
• Specifica API: per descrivere endpoint e flussi

L’AI può generare la documentazione partendo dal diagramma, oppure viceversa. L’importante è non lasciare mai il diagramma senza spiegazione (o peggio, senza versionamento).

Per approfondire come generare documentazione tecnica con l’AI, consulta anche: Documentazione tecnica con AI generativa

Best practice per prompt e template efficaci 🏆

• Sii specifico: più dettagli fornisci, meno dovrai correggere dopo
• Chiedi sempre il formato desiderato (es: Mermaid, elenco, tabella…)
• Rivedi sempre l’output: l’AI non è infallibile (ma nemmeno tu)
• Personalizza il tono: puoi chiedere formalità, sintesi, ironia…
• Documenta i tuoi template: così il team non dovrà reinventare la ruota ogni volta

Conclusione 🎯

L’AI generativa non sostituisce la competenza umana, ma può renderci più produttivi e meno stressati quando si tratta di diagrammi e documentazione architetturale. Sfrutta template, prompt ben scritti e un pizzico di creatività: la tua architettura (e il tuo team) ti ringrazieranno!