tech-diagram-generator

name: tech-diagram-generator description: Generate professional technical diagrams (Mermaid, ASCII, flowcharts, architecture diagrams) for AI/ML articles. Supports neural network architectures, data pipelines, algorithm flows, and system architectures.

Technical Diagram Generator

This skill helps you create professional, publication-quality technical diagrams for AI/ML technical articles using Mermaid, ASCII art, and structured formats.

When to Use This Skill

• Creating neural network architecture diagrams
• Visualizing data pipelines and ETL flows
• Documenting algorithm flows and decision trees
• Designing system architecture diagrams
• Explaining transformer attention mechanisms
• Showing training/inference workflows
• Creating comparison tables and matrices

Supported Diagram Types

1. Mermaid Diagrams

graph TB
    Input[Input Data] --> Preprocess[Preprocessing]
    Preprocess --> Model[Neural Network]
    Model --> Output[Predictions]

2. ASCII Art Diagrams

+------------------+     +------------------+
|   Input Layer    | --> |   Hidden Layer   |
|   (784 neurons)  |     |   (256 neurons)  |
+------------------+     +------------------+
                                |
                                v
                         +------------------+
                         |   Output Layer   |
                         |   (10 neurons)   |
                         +------------------+

3. Architecture Blocks

┌─────────────────────────────────────────┐
│            Transformer Block            │
├─────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    │
│  │Multi-Head   │    │  Feed       │    │
│  │Attention    │───>│  Forward    │    │
│  └─────────────┘    └─────────────┘    │
│        │                   │            │
│        └───────┬───────────┘            │
│                ▼                        │
│        ┌─────────────┐                 │
│        │Layer Norm   │                 │
│        └─────────────┘                 │
└─────────────────────────────────────────┘

Instructions

For Neural Network Architectures

When asked to visualize a neural network:

## Network Architecture: [Name]

### Overview
[Brief description of the architecture]

### Architecture Diagram

```mermaid
graph TB
    subgraph Input
        X[Input Features<br/>shape: (batch, seq, dim)]
    end

    subgraph Encoder
        E1[Embedding Layer]
        E2[Positional Encoding]
        E3[Multi-Head Attention]
        E4[Layer Norm + FFN]
    end

    subgraph Output
        O1[Linear Projection]
        O2[Softmax]
        Y[Predictions]
    end

    X --> E1 --> E2 --> E3 --> E4 --> O1 --> O2 --> Y

Layer Details

Key Components

1. Embedding Layer: Maps tokens to dense vectors
2. Positional Encoding: Adds position information
3. Multi-Head Attention: Computes attention weights
4. Feed-Forward Network: Non-linear transformation

### For Data Pipelines

When asked to visualize a data pipeline:

```markdown
## Data Pipeline: [Name]

### Pipeline Flow

┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Raw Data │───>│ Validation │───>│ Transform │ │ (S3/GCS) │ │ & Clean │ │ & Feature │ └──────────────┘ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Serving │<───│ Training │<───│ Data │ │ Layer │ │ Pipeline │ │ Splitting │ └──────────────┘ └──────────────┘ └──────────────┘

### Processing Steps

| Stage | Operation | Tools | Output |
|-------|-----------|-------|--------|
| Ingestion | Read from source | Spark, Beam | Raw DataFrame |
| Validation | Schema check | Great Expectations | Cleaned DataFrame |
| Transform | Feature engineering | Pandas, PySpark | Feature Matrix |
| Split | Train/Val/Test | Scikit-learn | Split Data |

For Algorithm Flows

When asked to visualize an algorithm:

## Algorithm: [Name]

### Flowchart

```mermaid
flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
    C --> E[Process]
    D --> E
    E --> F{Converged?}
    F -->|No| B
    F -->|Yes| G[End]

Pseudocode

algorithm AlgorithmName(input):
    # Step 1: Initialization
    initialize parameters

    # Step 2: Main Loop
    while not converged:
        # Step 2.1: Compute
        result = compute(input)

        # Step 2.2: Update
        parameters = update(result)

        # Step 2.3: Check
        if convergence_criteria():
            break

    return output

Complexity Analysis

### For Attention Mechanisms

When asked to explain attention:

```markdown
## Attention Mechanism

### Scaled Dot-Product Attention

       Query (Q)
          │
          ▼

┌─────────────────────────────┐ │ │ │ Q × K^T │ │ │ │ │ ▼ │ │ / √d_k (Scale) │ ←── Key (K) │ │ │ │ ▼ │ │ Softmax │ │ │ │ │ ▼ │ │ × V (Weighted Sum) │ ←── Value (V) │ │ │ │ ▼ │ │ Output │ │ │ └─────────────────────────────┘

### Multi-Head Attention

```mermaid
graph LR
    Q[Query] --> H1[Head 1]
    Q --> H2[Head 2]
    Q --> H3[Head 3]
    Q --> Hn[Head N]

    K[Key] --> H1
    K --> H2
    K --> H3
    K --> Hn

    V[Value] --> H1
    V --> H2
    V --> H3
    V --> Hn

    H1 --> C[Concat]
    H2 --> C
    H3 --> C
    Hn --> C

    C --> L[Linear]
    L --> O[Output]

Mathematical Formulation

$$\text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V$$

Where:

• $Q \in \mathbb{R}^{n \times d_k}$ (Query matrix)
• $K \in \mathbb{R}^{n \times d_k}$ (Key matrix)
• $V \in \mathbb{R}^{n \times d_v}$ (Value matrix)
• $d_k$ = dimension of keys

### For Training Workflows

When asked to show training process:

```markdown
## Training Workflow

### Training Loop

```mermaid
sequenceDiagram
    participant D as DataLoader
    participant M as Model
    participant L as Loss Function
    participant O as Optimizer

    loop For each epoch
        D->>M: Forward pass (batch)
        M->>L: Compute loss
        L->>O: Backward pass
        O->>M: Update weights
    end

    Note over M: Model converged!

Training Pipeline

┌────────────────────────────────────────────────────────┐
│                    Training Loop                        │
├────────────────────────────────────────────────────────┤
│                                                        │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐            │
│   │  Batch  │──>│ Forward │──>│  Loss   │            │
│   │  Data   │   │  Pass   │   │  Calc   │            │
│   └─────────┘   └─────────┘   └─────────┘            │
│                                     │                  │
│                                     ▼                  │
│   ┌─────────┐   ┌─────────┐   ┌─────────┐            │
│   │ Update  │<──│Gradient │<──│Backward │            │
│   │ Weights │   │  Calc   │   │  Pass   │            │
│   └─────────┘   └─────────┘   └─────────┘            │
│                                                        │
└────────────────────────────────────────────────────────┘

Hyperparameters

### For System Architectures

When asked to show system design:

```markdown
## System Architecture: [Name]

### High-Level Architecture

```mermaid
graph TB
    subgraph Client
        UI[Web UI]
        API[API Client]
    end

    subgraph Load Balancer
        LB[Nginx/ALB]
    end

    subgraph Application
        API1[API Server 1]
        API2[API Server 2]
    end

    subgraph Services
        Auth[Auth Service]
        ML[ML Service]
        Cache[Redis Cache]
    end

    subgraph Data
        DB[(PostgreSQL)]
        S3[(S3 Storage)]
    end

    UI --> LB
    API --> LB
    LB --> API1
    LB --> API2
    API1 --> Auth
    API2 --> ML
    ML --> Cache
    Auth --> DB
    ML --> S3

Component Details

## Best Practices

### Diagram Design Principles

1. **Clarity First**: Diagrams should be immediately understandable
2. **Consistent Styling**: Use consistent colors, shapes, and fonts
3. **Logical Flow**: Information should flow naturally (top-to-bottom or left-to-right)
4. **Appropriate Detail**: Show enough detail without overwhelming
5. **Clear Labels**: Every component should be labeled

### Color Coding

┌─────────────────────────────────────────┐ │ Color Coding Guide │ ├─────────────────────────────────────────┤ │ 🔵 Blue - Input/Output layers │ │ 🟢 Green - Processing/Transform │ │ 🟡 Yellow - Decision points │ │ 🔴 Red - Error/Warning states │ │ 🟣 Purple - Model components │ │ ⚪ Gray - Infrastructure │ └─────────────────────────────────────────┘

### Shape Conventions

┌─────────────┐ Rectangle: Process/Data │ Process │ └─────────────┘

  ◇          Diamond: Decision
/   \

/
◇───────◇

(Circle) Circle: Start/End

[/Parallel] Parallelogram: I/O

## Quick Reference

### Mermaid Syntax Cheat Sheet

graph TB # Top-bottom flowchart graph LR # Left-right flowchart flowchart TD # Flowchart with decisions sequenceDiagram # Sequence diagram classDiagram # UML class diagram stateDiagram # State machine pie # Pie chart gantt # Gantt chart

### Common Patterns

**Neural Network Layer**:
```mermaid
graph LR
    Input[Input<br/>B×L×D] --> Linear[Linear<br/>D→H]
    Linear --> Activation[ReLU/GELU]
    Activation --> Output[Output<br/>B×L×H]

Attention Block:

graph TB
    X[Input] --> QKV[Q, K, K Projection]
    QKV --> Attn[Scaled Dot-Product]
    Attn --> Proj[Output Projection]
    Proj --> Add[Residual Add]
    Add --> Out[Output]

Data Flow:

graph LR
    A[Source] -->|Read| B[Transform]
    B -->|Process| C[Validate]
    C -->|Write| D[Sink]

Examples

Example 1: Transformer Architecture

## Transformer Architecture

### Complete Architecture

```mermaid
graph TB
    subgraph Input
        Tok[Tokenization]
        Pos[Positional Encoding]
    end

    subgraph Encoder
        E_MHA[Multi-Head Attention]
        E_FF[Feed Forward]
        E_N1[Layer Norm]
        E_N2[Layer Norm]
    end

    subgraph Decoder
        D_MHA1[Masked Attention]
        D_MHA2[Cross Attention]
        D_FF[Feed Forward]
        D_N1[Layer Norm]
        D_N2[Layer Norm]
        D_N3[Layer Norm]
    end

    subgraph Output
        Linear[Linear]
        Softmax[Softmax]
    end

    Tok --> Pos --> E_MHA --> E_N1 --> E_FF --> E_N2
    E_N2 --> D_MHA2
    Pos --> D_MHA1 --> D_N1 --> D_MHA2 --> D_N2 --> D_FF --> D_N3 --> Linear --> Softmax

### Example 2: Diffusion Model

```markdown
## Diffusion Model Architecture

### Forward & Reverse Process

    Forward Process (Add Noise)
    ───────────────────────────>

x₀ ──► x₁ ──► x₂ ──► ... ──► xₜ ──► ... ──► x_T 🖼️ 🌫️ 🌫️ 🌫️ 📺

    <───────────────────────────
    Reverse Process (Denoise)

    x₀ ←── x₁ ←── x₂ ←── ... ←── xₜ ←── ... ←── x_T
    🖼️     🌫️     🌫️              🌫️           📺
          │      │               │
          ▼      ▼               ▼
        ε̂₁    ε̂₂    ...       ε̂ₜ
        (Predicted Noise)

### U-Net Denoiser

```mermaid
graph TB
    subgraph Encoder
        E1[Conv 64]
        E2[Conv 128]
        E3[Conv 256]
        E4[Conv 512]
    end

    subgraph Bottleneck
        B[Attention Blocks]
    end

    subgraph Decoder
        D4[UpConv 256]
        D3[UpConv 128]
        D2[UpConv 64]
        D1[Output Conv]
    end

    x_t --> E1 --> E2 --> E3 --> E4 --> B
    B --> D4 --> D3 --> D2 --> D1 --> ε̂

    E1 -.-> D2
    E2 -.-> D3
    E3 -.-> D4

## Tips for AI/ML Diagrams

1. **Show Tensor Shapes**: Always include dimensions (B, L, D)
2. **Mark Trainable Parameters**: Use different colors for learnable vs fixed
3. **Highlight Data Flow**: Use arrows to show information flow
4. **Include Mathematical Notation**: Add equations where helpful
5. **Show Batch Dimension**: Always include B for batch
6. **Use Subgraphs**: Group related components together