Architectural Diagrams with Generative AI 🗺️

Docs

Why generate diagrams with AI? 🧠

If you think drawing architectural diagrams is a relaxing activity, you’ve probably never had to manually align dozens of rectangles in PowerPoint. Generative AI, on the other hand, can transform this chore into an almost pleasant process: just describe the architecture and let the algorithm do the heavy lifting.

You save time (and mouse clicks)
Reduce errors and oversights
Standardize representation
Facilitate collaboration

⚠️ Important note: Even though AI is good at drawing, you’re still responsible for accuracy! Always review generated diagrams before showing them to the team (or the boss).

The advantages of MermaidJS for documentation 📊

MermaidJS is the digital pencil of cloud architects: simple, text-based, integrable anywhere and perfect for being processed by both humans and machines (and developers who hate drag-and-drop). Using MermaidJS with AI means:

Structure information in a clear and coherent way
Reduce the “flying rectangle” syndrome
Encourage reusability and consistency across diagrams
Be easily integrated into documentation and versioning platforms
Allow reviews via Git (not via Slack screenshots)

How AI-assisted diagram generation works 🪄

Define the key components: which services, resources and connections do you want to represent?
Choose a diagram type: preferably one already tested by the team.
Prompt the AI: provide the architectural description and ask it to generate the diagram in MermaidJS format.
Review and customize: the AI is good, but you’re better! Add details, correct inaccuracies and adapt the visualization.

Pro tip: the more details you provide in the prompt, the more the diagram will match the actual architecture. The AI doesn’t have a crystal ball yet (but it’s working on it).

Practical example: GCP cloud architecture ☁️

A structured prompt like the one below, combined with a detailed description of the architecture, allows the AI to produce clear and coherent diagrams, reducing ambiguities and creative interpretations (which, as we know, are not always welcome in technical matters).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


I will provide you with notes describing a cloud architecture (e.g., components like VMs, containers, load balancer, storage, Pub/Sub, API Gateway, etc.). Analyze the text and:
1. Identify the main components of the architecture (services, cloud resources, connections).
2. Visually represent the architecture using a MermaidJS diagram, preferably with graph TD or graph LR if it's a static topology or sequenceDiagram if the focus is on request flow.
3. Make sure to:
 - Use clear and consistent names for each node, without using parentheses
 - Show relationships between components (e.g., who communicates with whom)
 - Follow a logic from outside to inside or from frontend to backend
 - Include comments in the Mermaid code, if useful for understanding
 - Apply consistent shapes for different component types
 - Apply consistent styles for different component types
4. Return only the MermaidJS code block ready to paste into markdown (```mermaid … ```)

By providing the AI with a description like this, you can get in seconds an architectural diagram ready to use, perfect for insertion in documentation or sharing with the team. Here’s an example of input:

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


The application consists of several microservices distributed on Google Cloud Platform.
Users interact via a Web App served by Cloud Run (Frontend Service), accessible via a Cloud Load Balancer with HTTPS.
Traffic is managed by an API Gateway that authenticates requests with Identity Platform.
Requests are routed to various backend services in Cloud Run:
- Auth Service, which manages login and registration
- Order Service, which manages user orders
- Inventory Service, which manages product availability
The Order Service publishes events to a Pub/Sub topic "order-events".
The Payment Service listens for these events to process payments.
All services write logs to Cloud Logging and metrics to Cloud Monitoring.
The main database is Cloud SQL (PostgreSQL), used by Auth and Order Service.
Inventory Service accesses Firestore for warehouse data.
Cloud Storage is used to save PDF receipt documents.
Secrets are managed with Secret Manager.
A CI/CD system deploys everything to multiple environments via Cloud Build and Artifact Registry.

The result will be a MermaidJS diagram that faithfully represents the structure and relationships between the described components, with differentiated styles and shapes for each type of service or resource:

    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

From diagram to technical documentation 📚

A well-made diagram is just the beginning: you can also ask the AI to generate technical documentation starting from the same prompt, or explain the architectural choices with an RFC or an ADR. The approach is the same: clear templates, detailed prompts and some healthy human review.

RFC: to describe technical proposals and motivations
ADR: to track architectural decisions and consequences
Runbook: for operational procedures
API Specification: to describe endpoints and flows

The AI can generate documentation from the diagram, or vice versa. The important thing is to never leave the diagram without explanation (or worse, without versioning).

To learn more about generating technical documentation with AI, also see: Technical Documentation with Generative AI

Best practices for effective prompts and templates 🏆

Be specific: the more details you provide, the less you’ll have to correct later
Always ask for the desired format (e.g.: Mermaid, list, table…)
Always review the output: the AI is not infallible (neither are you)
Personalize the tone: you can ask for formality, brevity, irony…
Document your templates: so the team doesn’t have to reinvent the wheel every time

Conclusion 🎯

Generative AI doesn’t replace human expertise, but it can make us more productive and less stressed when it comes to diagrams and architectural documentation. Take advantage of templates, well-written prompts and a touch of creativity: your architecture (and your team) will thank you!

Last updated on 26 June 2026

Technical Documents with AI Security Audit with AI