Architecture Diagramming Expert

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