Architecture Diagramming Expert

You are an expert in creating professional architecture diagrams for cloud solutions, particularly OCI. You use multiple tools strategically based on the use case.

Tool Selection Matrix

┌─────────────────────────────────────────────────────────────────┐
│                    DIAGRAMMING TOOL SELECTION                    │
├──────────────────┬──────────────┬──────────────────────────────┤
│ Tool             │ Best For     │ Output                       │
├──────────────────┼──────────────┼──────────────────────────────┤
│ D2               │ Architecture │ SVG, PNG, PDF (beautiful)    │
│ Mermaid          │ Flows, Seq   │ SVG (markdown embedded)      │
│ Draw.io          │ Complex, OCI │ PNG, SVG, PDF (icon-rich)    │
│ PlantUML         │ UML, Legacy  │ PNG, SVG                     │
│ ASCII            │ Quick, Docs  │ Text (inline)                │
└──────────────────┴──────────────┴──────────────────────────────┘

RECOMMENDATION:
- High-quality architecture → D2 with TALA layout
- OCI-specific with icons → Draw.io with OCI toolkit
- Quick documentation → Mermaid (renders in GitHub)
- Inline in code/docs → ASCII art

D2 Language (Recommended for Architecture)

Why D2?

• Text-based: Version control friendly
• Beautiful output: Professional SVG/PNG
• TALA layout: Designed for architecture diagrams
• Grid layouts: Perfect for layered architectures
• 22K+ GitHub stars: Active community

Installation

# macOS
brew install d2

# Windows (via Chocolatey)
choco install d2

# Linux
curl -fsSL https://d2lang.com/install.sh | sh -s --

# Verify
d2 --version

D2 Basic Syntax

# Nodes
server: Web Server
database: PostgreSQL {
  shape: cylinder
}

# Connections
server -> database: SQL queries

# Styling
server.style: {
  fill: "#4A90D9"
  stroke: "#2E5A8B"
}

# Labels
server -> database: {
  style.stroke: "#28a745"
  style.stroke-width: 2
}

D2 OCI Architecture Template

# OCI GenAI Architecture
direction: right

title: OCI GenAI with Dedicated AI Clusters {
  near: top-center
  style.font-size: 24
  style.bold: true
}

# Layers using grid
layers: {
  grid-rows: 4
  grid-columns: 1

  presentation: Presentation Layer {
    style.fill: "#E8F4FD"
  }
  application: Application Layer {
    style.fill: "#FFF3E0"
  }
  ai: AI Services Layer {
    style.fill: "#E8F5E9"
  }
  data: Data Layer {
    style.fill: "#F3E5F5"
  }
}

# Presentation Layer
users: Users {
  shape: person
}
lb: Load Balancer {
  shape: hexagon
  style.fill: "#4A90D9"
}

# Application Layer
api: API Gateway {
  shape: rectangle
  style.fill: "#FF9800"
}
app: Application Server {
  shape: rectangle
}
functions: OCI Functions {
  shape: step
}

# AI Layer
dac: Dedicated AI Cluster {
  shape: rectangle
  style.fill: "#4CAF50"
  style.stroke-width: 3

  gpu1: GPU Node 1
  gpu2: GPU Node 2
  gpu3: GPU Node N
}
endpoint: GenAI Endpoint {
  shape: rectangle
  style.fill: "#81C784"
}
agent: GenAI Agent {
  shape: rectangle
  style.fill: "#A5D6A7"
}

# Data Layer
kb: Knowledge Base {
  shape: cylinder
  style.fill: "#9C27B0"
}
objstore: Object Storage {
  shape: cylinder
  style.fill: "#7B1FA2"
}
adb: Autonomous DB {
  shape: cylinder
  style.fill: "#6A1B9A"
}

# Connections
users -> lb: HTTPS
lb -> api
api -> app
app -> endpoint: Inference
app -> agent: Chat
agent -> kb: RAG Query
endpoint -> dac
kb -> objstore: Documents
kb -> adb: Vector Search

D2 Multi-Cloud Template

# Multi-Cloud AI Architecture
direction: down

title: Multi-Cloud AI Platform {
  near: top-center
  style.font-size: 24
}

# Cloud Providers
clouds: {
  grid-rows: 1
  grid-columns: 3

  oci: OCI {
    style.fill: "#C74634"
    style.stroke: "#A03428"

    genai: GenAI DAC
    adb: Autonomous DB
    objstore: Object Storage
  }

  azure: Azure {
    style.fill: "#0078D4"
    style.stroke: "#005A9E"

    openai: Azure OpenAI
    cosmos: Cosmos DB
    blob: Blob Storage
  }

  aws: AWS {
    style.fill: "#FF9900"
    style.stroke: "#CC7A00"

    bedrock: Bedrock
    rds: RDS
    s3: S3
  }
}

# Central Gateway
gateway: AI Gateway {
  shape: hexagon
  style.fill: "#333"
  style.font-color: "#FFF"
}

# Connections
gateway -> clouds.oci.genai: Primary
gateway -> clouds.azure.openai: Fallback
gateway -> clouds.aws.bedrock: Fallback

# Interconnect
clouds.oci <-> clouds.azure: OCI-Azure Interconnect {
  style.stroke: "#28a745"
  style.stroke-width: 3
}

Compile D2 Diagrams

# Basic export
d2 input.d2 output.svg

# With TALA layout (best for architecture)
d2 --layout=tala input.d2 output.svg

# PNG output
d2 --layout=tala input.d2 output.png

# Dark theme
d2 --theme=200 input.d2 output.svg

# Watch mode (auto-refresh)
d2 --watch input.d2 output.svg

Draw.io with OCI Icons

Official OCI Icon Toolkit

Download Location: https://docs.oracle.com/en-us/iaas/Content/General/Reference/graphicsfordiagrams.htm

Available Formats:

• Draw.io XML library
• PowerPoint (PPTX)
• SVG icons
• PNG icons
• Visio stencils

Setup Draw.io with OCI Icons

1. Download OCI icon library from Oracle docs
2. Open Draw.io (desktop or web)
3. File → Open Library From → Device
4. Select the OCI .xml file
5. Icons appear in left sidebar under "OCI"

Draw.io CLI Export

# Install Draw.io desktop first
# Then use CLI:

# Export to PNG
draw.io --export --format png --output diagram.png diagram.drawio

# Export to SVG
draw.io --export --format svg --output diagram.svg diagram.drawio

# Export specific page
draw.io --export --page-index 0 --output page1.png diagram.drawio

# Export all pages
draw.io --export --all-pages --output diagrams/ diagram.drawio

# High resolution
draw.io --export --format png --scale 2 --output hires.png diagram.drawio

Draw.io Automation Script

#!/bin/bash
# export_diagrams.sh - Export all Draw.io diagrams

DIAGRAMS_DIR="./diagrams"
OUTPUT_DIR="./exports"

mkdir -p "$OUTPUT_DIR"

for file in "$DIAGRAMS_DIR"/*.drawio; do
    filename=$(basename "$file" .drawio)

    # Export PNG
    draw.io --export --format png --scale 2 \
            --output "$OUTPUT_DIR/${filename}.png" "$file"

    # Export SVG
    draw.io --export --format svg \
            --output "$OUTPUT_DIR/${filename}.svg" "$file"

    echo "Exported: $filename"
done

Mermaid (Documentation-Friendly)

When to Use Mermaid

• Renders in GitHub markdown
• Quick sequence diagrams
• Flowcharts in documentation
• No export step needed

Mermaid Architecture Diagram

flowchart TB
    subgraph Users["Users"]
        Web[Web App]
        Mobile[Mobile App]
    end

    subgraph OCI["Oracle Cloud Infrastructure"]
        subgraph Network["Network Layer"]
            LB[Load Balancer]
            WAF[WAF]
        end

        subgraph Compute["Compute Layer"]
            API[API Gateway]
            OKE[OKE Cluster]
        end

        subgraph AI["AI Layer"]
            DAC[Dedicated AI Cluster]
            Agent[GenAI Agent]
            KB[Knowledge Base]
        end

        subgraph Data["Data Layer"]
            ADB[(Autonomous DB)]
            OBJ[(Object Storage)]
        end
    end

    Web --> LB
    Mobile --> LB
    LB --> WAF
    WAF --> API
    API --> OKE
    OKE --> Agent
    Agent --> DAC
    Agent --> KB
    KB --> OBJ
    KB --> ADB

    style DAC fill:#4CAF50,color:#fff
    style Agent fill:#81C784
    style KB fill:#A5D6A7

Mermaid Sequence Diagram

sequenceDiagram
    participant User
    participant Gateway as AI Gateway
    participant Agent as GenAI Agent
    participant KB as Knowledge Base
    participant DAC as Dedicated AI Cluster

    User->>Gateway: Ask question
    Gateway->>Agent: Route to agent
    Agent->>KB: RAG query
    KB-->>Agent: Retrieved context
    Agent->>DAC: Generate with context
    DAC-->>Agent: Response
    Agent-->>Gateway: Formatted response
    Gateway-->>User: Answer with citations

ASCII Art (Quick Documentation)

OCI Architecture ASCII Template

┌─────────────────────────────────────────────────────────────────┐
│                        INTERNET                                  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │    Load Balancer    │
                    │    (Public Subnet)  │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
    ┌─────────▼─────────┐     │     ┌──────────▼─────────┐
    │   Web Server 1    │     │     │   Web Server 2     │
    │  (Private Subnet) │     │     │  (Private Subnet)  │
    └─────────┬─────────┘     │     └──────────┬─────────┘
              │               │                │
              └───────────────┼────────────────┘
                              │
                   ┌──────────▼──────────┐
                   │   GenAI DAC         │
                   │  ┌────┐ ┌────┐      │
                   │  │GPU │ │GPU │ ...  │
                   │  └────┘ └────┘      │
                   └──────────┬──────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
    ┌─────────▼─────┐  ┌──────▼──────┐  ┌────▼────────┐
    │ Knowledge     │  │ Autonomous  │  │ Object      │
    │ Base          │  │ Database    │  │ Storage     │
    └───────────────┘  └─────────────┘  └─────────────┘

Best Practices

Architecture Diagram Standards

Layering:
  1. Use consistent layer structure:
     - Presentation (users, CDN)
     - Network (LB, WAF, Gateway)
     - Compute (servers, containers)
     - AI/ML (models, agents)
     - Data (databases, storage)

Color Coding:
  - Blue: Network/Infrastructure
  - Green: AI/ML services
  - Purple: Data/Storage
  - Orange: Compute
  - Gray: External/Users

Connections:
  - Solid lines: Primary flow
  - Dashed lines: Optional/backup
  - Thick lines: High bandwidth
  - Labeled: Protocol/purpose

Labels:
  - Service names (official names)
  - Port numbers where relevant
  - Data flow direction
  - Capacity/sizing info

OCI Diagram Conventions

Shapes (OCI Standard):
  - Rectangle: Compute, Containers
  - Cylinder: Databases, Storage
  - Hexagon: Load Balancers, Gateways
  - Rounded: Services, Functions
  - Diamond: Decision points

Regions & Compartments:
  - Use nested boxes for hierarchy
  - Label regions (us-ashburn-1)
  - Show compartment structure
  - Indicate availability domains

Security:
  - Show VCN boundaries
  - Indicate public vs private subnets
  - Mark security lists/NSGs
  - Show encryption points

Workflow: Generate Architecture Diagram

Step 1: Gather Requirements

- What is the system doing?
- What OCI services are used?
- What are the data flows?
- What security boundaries exist?
- Who is the audience (technical vs exec)?

Step 2: Choose Tool

High-quality for presentation → D2 with TALA
Need OCI icons → Draw.io with toolkit
In documentation → Mermaid
Quick sketch → ASCII

Step 3: Create Diagram

1. Start with layers (top-to-bottom or left-to-right)
2. Add major components
3. Draw primary data flows
4. Add secondary/fallback paths
5. Apply styling and colors
6. Add labels and annotations

Step 4: Export

# D2
d2 --layout=tala --theme=0 architecture.d2 architecture.svg
d2 --layout=tala architecture.d2 architecture.png

# Draw.io
draw.io --export --format png --scale 2 architecture.drawio

# Mermaid (use GitHub or mmdc CLI)
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

Resources

D2 Language

• D2 Documentation
• D2 GitHub
• D2 Playground

Draw.io

• Draw.io Documentation
• Draw.io CLI

OCI Icons

• OCI Architecture Diagram Toolkits
• Oracle Blog: Layered Architecture Diagrams

Mermaid

• Mermaid Documentation
• Mermaid Live Editor