Generate Architecture Diagrams with AI in 15 Minutes

Use Claude and Mermaid.js to create system design diagrams from natural language. No more wrestling with diagramming tools.
·
7 min read
·
Mark
·
Software Development

Problem: Diagramming Tools Waste Your Time

You need to document a microservice architecture for your team, but you're spending hours fighting with Lucidchart's alignment tools instead of actually designing systems.

You'll learn:

  • How to generate Mermaid diagrams from plain English
  • Practical patterns for system architecture, sequences, and data flows
  • When to use AI vs manual diagramming

Time: 15 min | Level: Beginner

Why This Works

Mermaid.js uses text-based syntax to render diagrams. AI models like Claude can generate valid Mermaid code because they've been trained on thousands of diagram examples.

Common use cases:

  • System architecture (microservices, databases, APIs)
  • Sequence diagrams (authentication flows, API calls)
  • Data flows (ETL pipelines, event streaming)
  • Entity relationships (database schemas)

What you need:

  • Claude.ai account (free tier works)
  • GitHub, GitLab, or Notion (all support Mermaid)
  • Or any Mermaid live editor

Solution

Step 1: Describe Your System

Open Claude.ai and describe what you want to diagram in plain English. Be specific about relationships.

Example prompt:

Create a Mermaid architecture diagram for an e-commerce system with:
- React frontend talking to an API gateway
- API gateway routes to 3 microservices: orders, payments, inventory
- All services connect to PostgreSQL and Redis
- Payments service calls Stripe API
- Show the data flow when a user places an order

Expected: Claude generates a graph or flowchart Mermaid diagram.

If it fails:

  • Too generic: Add more detail about service names and connections
  • Wrong diagram type: Specify "use a flowchart" or "use a sequence diagram"

Step 2: Copy the Mermaid Code

Claude returns something like this:

graph TB
    subgraph "Frontend"
        A[React App]
    end
    
    subgraph "Backend"
        B[API Gateway]
        C[Orders Service]
        D[Payments Service]
        E[Inventory Service]
    end
    
    subgraph "Data Layer"
        F[(PostgreSQL)]
        G[(Redis Cache)]
    end
    
    subgraph "External"
        H[Stripe API]
    end
    
    A -->|HTTPS| B
    B -->|Routes| C
    B -->|Routes| D
    B -->|Routes| E
    
    C --> F
    C --> G
    D --> F
    D --> G
    D -->|Process Payment| H
    E --> F
    E --> G
    
    style A fill:#e3f2fd
    style B fill:#fff3e0
    style C fill:#f3e5f5
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#fce4ec

Copy everything between the triple backticks (including the word mermaid).

Step 3: Render It

Option A: GitHub/GitLab README

Paste into your README.md:

## System Architecture

```mermaid
[paste Mermaid code here]
```

GitHub and GitLab render it automatically. No extensions needed.

Option B: Live Editor

Go to mermaid.live:

  1. Paste the code in the left panel
  2. Diagram renders on the right
  3. Export as SVG or PNG

Option C: Notion

In Notion:

  1. Type /code
  2. Select "Mermaid" as language
  3. Paste code
  4. Toggle "Preview" to see the diagram

Step 4: Refine with AI

Ask Claude to modify the diagram:

Refinement prompts:

Add a message queue between the API gateway and services

Make the payments service flow more detailed - show validation, 
charging, and confirmation steps

Convert this to a sequence diagram showing what happens when 
a user clicks "Buy Now"

Use different colors for frontend (blue), backend (orange), 
and data (green)

Claude regenerates the diagram with your changes.

Practical Examples

Example 1: Sequence Diagram (Authentication Flow)

Prompt:

Create a Mermaid sequence diagram for OAuth2 login:
User clicks login, frontend redirects to Auth0, user approves, 
Auth0 redirects back with code, frontend exchanges code for token, 
stores token, makes API call with token

Generated:

sequenceDiagram
    actor User
    participant Frontend
    participant Auth0
    participant API
    
    User->>Frontend: Click "Login"
    Frontend->>Auth0: Redirect to /authorize
    Auth0->>User: Show consent screen
    User->>Auth0: Approve
    Auth0->>Frontend: Redirect with code
    Frontend->>Auth0: POST /token (code)
    Auth0-->>Frontend: Access token + refresh token
    Frontend->>Frontend: Store token in localStorage
    Frontend->>API: GET /profile (Bearer token)
    API-->>Frontend: User data

Use when: Documenting API interactions, debugging flows, onboarding engineers.

Example 2: Data Flow Diagram

Prompt:

Show an ETL pipeline: S3 raw data → Lambda processor → 
validates and transforms → writes to Redshift and ElasticSearch

Generated:

graph LR
    A[S3 Raw Data] -->|Trigger| B[Lambda Processor]
    B -->|Validate| C{Valid?}
    C -->|Yes| D[Transform Data]
    C -->|No| E[DLQ]
    D -->|Batch Insert| F[(Redshift)]
    D -->|Index| G[(ElasticSearch)]
    
    style E fill:#ffebee
    style F fill:#e8f5e9
    style G fill:#e8f5e9

Use when: Explaining data pipelines, documenting ETL jobs.

Example 3: Microservices Architecture

Prompt:

Diagram a microservices setup with API gateway, 4 services 
(user, order, payment, notification), shared Postgres, 
individual Redis instances, and Kafka for events

Generated:

graph TB
    subgraph "Clients"
        A[Web App]
        B[Mobile App]
    end
    
    C[API Gateway]
    
    subgraph "Services"
        D[User Service]
        E[Order Service]
        F[Payment Service]
        G[Notification Service]
    end
    
    H[(Shared Postgres)]
    I[Kafka Event Bus]
    
    subgraph "Cache"
        J[(Redis - User)]
        K[(Redis - Order)]
        L[(Redis - Payment)]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    C --> G
    
    D --> H
    E --> H
    F --> H
    
    D --> J
    E --> K
    F --> L
    
    E -->|OrderCreated| I
    F -->|PaymentProcessed| I
    I -->|Events| G

Use when: Architecture reviews, system design interviews, documentation.

Mermaid Syntax Cheatsheet

Graph Types

graph TB  %% Top to Bottom
graph LR  %% Left to Right
graph TD  %% Top Down (alias for TB)

Node Shapes

graph LR
    A[Rectangle]
    B(Rounded)
    C([Stadium])
    D[(Database)]
    E{{Hexagon}}
    F{Diamond}

Arrow Types

graph LR
    A -->|Solid| B
    A -.->|Dotted| C
    A ==>|Thick| D
    A --x|Cross| E
    A --o|Circle| F

Styling

graph TB
    A[Node]
    style A fill:#e3f2fd,stroke:#1976d2,stroke-width:2px

Color palette:

  • #e3f2fd = Blue (frontend)
  • #fff3e0 = Orange (gateway/middleware)
  • #f3e5f5 = Purple (services)
  • #e8f5e9 = Green (databases)
  • #ffebee = Red (errors/warnings)

Advanced: Claude in Claude

You can embed Claude's API into artifacts to create an interactive diagram generator.

Create a React artifact:

import { useState } from 'react';

export default function DiagramGenerator() {
  const [prompt, setPrompt] = useState('');
  const [mermaidCode, setMermaidCode] = useState('');
  const [loading, setLoading] = useState(false);

  const generateDiagram = async () => {
    setLoading(true);
    const response = await fetch('https://api.anthropic.com/v1/messages', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        model: 'claude-sonnet-4-20250514',
        max_tokens: 1000,
        messages: [{
          role: 'user',
          content: `Generate a Mermaid.js diagram for: ${prompt}. 
                    Return only the Mermaid code, no explanation.`
        }]
      })
    });
    
    const data = await response.json();
    const code = data.content[0].text
      .replace(/```mermaid\n?/g, '')
      .replace(/```\n?/g, '');
    setMermaidCode(code);
    setLoading(false);
  };

  return (
    <div className="p-6 max-w-4xl mx-auto">
      <h1 className="text-2xl font-bold mb-4">AI Diagram Generator</h1>
      
      <textarea
        value={prompt}
        onChange={(e) => setPrompt(e.target.value)}
        placeholder="Describe your system architecture..."
        className="w-full p-3 border rounded mb-4 h-32"
      />
      
      <button
        onClick={generateDiagram}
        disabled={loading}
        className="bg-blue-600 text-white px-6 py-2 rounded hover:bg-blue-700"
      >
        {loading ? 'Generating...' : 'Generate Diagram'}
      </button>
      
      {mermaidCode && (
        <div className="mt-6">
          <h2 className="text-xl font-semibold mb-2">Generated Code:</h2>
          <pre className="bg-gray-100 p-4 rounded overflow-x-auto">
            {mermaidCode}
          </pre>
          
          <h2 className="text-xl font-semibold mt-6 mb-2">Rendered:</h2>
          <div className="border p-4 rounded">
            <div dangerouslySetInnerHTML={{
              __html: `<pre class="mermaid">${mermaidCode}</pre>`
            }} />
          </div>
        </div>
      )}
      
      <script type="module">
        {`import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
          mermaid.initialize({ startOnLoad: true });`}
      </script>
    </div>
  );
}

This creates: An interactive tool where users type descriptions and get live diagrams.

Verification

Test your diagram in multiple places:

# GitHub preview (if using VS Code)
code README.md  # Preview pane shows rendered Mermaid

# Or use mermaid-cli
npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg

You should see: A clean, readable diagram with correct connections.

What You Learned

  • AI can generate Mermaid syntax from natural language descriptions
  • Mermaid works natively in GitHub, GitLab, Notion, and many wikis
  • Sequence diagrams are best for flows; graphs are best for architecture
  • Iterative refinement with AI is faster than manual diagramming

Limitations:

  • AI sometimes creates invalid Mermaid syntax (test in live editor)
  • Complex diagrams (20+ nodes) may need manual layout tweaks
  • Mermaid doesn't support every diagram type (no UML class diagrams)

When NOT to use this:

  • Highly precise technical drawings (use Figma/Visio)
  • Diagrams requiring pixel-perfect alignment
  • When you need non-standard shapes or icons

Common Patterns Library

Save these prompts for quick diagram generation:

REST API Flow

Create a sequence diagram: Client sends POST /users, 
API validates, checks database for duplicate, 
creates user, returns 201 with user ID

Event-Driven Architecture

Diagram event flow: Order service publishes OrderCreated to Kafka,
payment service consumes it, processes payment, 
publishes PaymentCompleted, notification service sends email

Database Schema

Create an ER diagram with User (id, email, name), 
Post (id, user_id, title, content), 
Comment (id, post_id, user_id, text). 
Show foreign key relationships.

CI/CD Pipeline

Flowchart of CI/CD: Push to GitHub, 
triggers Actions, runs tests, builds Docker image, 
pushes to ECR, deploys to EKS, runs smoke tests

Tested with Claude Sonnet 4, Mermaid v10.6+, GitHub/GitLab/Notion (Feb 2026)