generating-gcp-diagrams

GCP DrawIO Diagram Generator

Generates professional DrawIO XML diagrams for Google Cloud Platform architectures.

Capabilities

1. Extract - Analyze existing DrawIO XML files to identify GCP shapes, connections, and structure
2. Identify - Recognize GCP service icons from architecture diagram images
3. Generate - Create valid DrawIO XML from images or text descriptions
4. Convert - Transform GCP architecture diagrams into editable DrawIO format

Quick Reference

GCP Shape Pattern

shape=mxgraph.gcp2.{service_name}

Note: GCP uses snake_case for shape names (e.g., cloud_run, cloud_sql, cloud_storage).

Icon Pattern: Unlike AWS, GCP uses a single icon pattern for all services — there is no service vs instance icon distinction. The same shape=mxgraph.gcp2.{name} is used whether labeling the service itself ("Cloud Run") or a specific instance ("Cloud Run (API Handler)"). Differentiate by label text only.

Common GCP Services

| Service | Shape Code |

|---------|-----------|

| Cloud Run | mxgraph.gcp2.cloud_run |

| BigQuery | mxgraph.gcp2.bigquery |

| Cloud Storage | mxgraph.gcp2.cloud_storage |

| Vertex AI | mxgraph.gcp2.cloud_machine_learning |

| Cloud Scheduler | mxgraph.gcp2.cloud_scheduler |

| Apigee | mxgraph.gcp2.apigee_api_platform |

| Pub/Sub | mxgraph.gcp2.cloud_pubsub |

| Cloud SQL | mxgraph.gcp2.cloud_sql |

| GKE | mxgraph.gcp2.compute_engine |

| Cloud Functions | mxgraph.gcp2.cloud_functions |

GCP Container Types

| Container | Use Case |

|-----------|----------|

| gcp_project | Main project boundary (two-cell pattern) |

| gcp_vpc_sc | VPC Service Controls perimeter (green border) |

| gcp_region | Regional grouping |

| gcp_zone | Zone grouping |

| logical_group_dashed | Logical grouping with dashed border |

| logical_group_solid | Solid border grouping |

| subnet | Subnet boundary |

| firewall_rules | Firewall rules grouping |

| instance_group | Instance group container |

---

Task 1: Analyze a DrawIO File

Use this workflow to extract and document all components from an existing DrawIO file.

Steps

1. Read the file - Load the .drawio XML file
2. Parse structure - Extract all <mxCell> elements
3. Identify shapes - Find cells with vertex="1"
4. Identify connections - Find cells with edge="1"
5. Extract styles - Parse style strings for each element
6. Map hierarchy - Build container/child relationships using parent attribute
7. Generate report - Output findings in structured format

Input

• Path to .drawio file

Output

Generate a Markdown report with:

# DrawIO Analysis Report

## Summary
- Total shapes: X
- Total connections: Y
- Containers: Z

## Shape Inventory

| ID | Label | Type | Position | Parent |
|----|-------|------|----------|--------|
| abc | Cloud Run | mxgraph.gcp2.cloud_run | (100,200) | vpc1 |

## Connection Matrix

| From | To | Label | Type |
|------|-----|-------|------|
| Cloud Run | BigQuery | API | solid |

## Container Hierarchy

- VPC-SC (vpc1)
  - Cloud Run (run1)
  - Cloud Run (run2)
  - BigQuery (bq1)

## Style Analysis

### Unique Shapes Found
- mxgraph.gcp2.cloud_run (4 instances)
- mxgraph.gcp2.bigquery (2 instances)

---

Task 2: Convert Image to DrawIO

Use this workflow to recreate a GCP architecture diagram from an image.

Steps

1. Analyze image - Identify all visual elements:

• GCP service icons (shape, color, label)
• Containers/boundaries (color, border style)
• Connections (solid, dashed, arrows)
• Labels and text

1. Map to library - For each identified element:

• Look up in assets/gcp-icons.json by visual signature or label
• Match containers to assets/containers.json
• Note any unrecognized elements

1. Estimate layout - Determine positions:

• Identify container boundaries first
• Place icons within containers
• Estimate x,y coordinates and dimensions
• Standard icon size: 50x50 pixels

1. Generate XML - Build the DrawIO structure:

• Start with base template from assets/templates/drawio-base.xml
• Add containers first (they become parents)
• Add service icons with correct parent references
• Add connections between shapes

1. Create confidence report - Document accuracy:

• List all identified components
• Note any uncertain matches
• Flag potential issues

Input

• GCP architecture diagram image (PNG/JPG)

Output

1. Valid .drawio XML file
2. Confidence report (Markdown)

Confidence Report Format

# Conversion Confidence Report

## Overall Confidence: 85%

## Identified Components

### High Confidence (>90%)
- Cloud Run x4 - Clear icon match
- BigQuery x2 - Clear icon match
- VPC-SC container - Green border, correct label

### Medium Confidence (70-90%)
- Vertex AI Search - Icon similar, label confirms

### Low Confidence (<70%)
- Unknown icon at position (300, 400) - Mapped to generic service

## Connection Accuracy
- 12/14 connections clearly visible
- 2 connections inferred from layout

## Notes
- "Same Instance" dashed container identified
- Bidirectional arrows on 3 connections

---

Task 3: Create DrawIO from Description

Use this workflow to generate a new GCP diagram from text specifications.

Steps

1. Parse requirements - Extract from description:

• Required GCP services
• Container/grouping needs
• Connection requirements
• Layout preferences

1. Select components - From libraries:

• Look up services in assets/gcp-icons.json
• Choose containers from assets/containers.json
• Select connection styles

1. Plan layout - Design the arrangement:

• Determine canvas size
• Position containers first
• Arrange services logically (left-to-right data flow, top-to-bottom hierarchy)
• Standard spacing: 100px between 50x50 icons

1. Generate XML - Build the diagram:

• Use assets/templates/drawio-base.xml as starting point
• Add elements in order: containers, services, connections
• Assign unique IDs to all elements

1. Validate - Check the output:

• All requested components present
• Connections reference valid IDs
• Layout is logical and readable

Input

• Text description of desired GCP architecture

Output

• Valid .drawio XML file

Example Input

Create a GCP architecture with:
- VPC-SC container
- Cloud Scheduler triggering Cloud Run
- Cloud Run connecting to BigQuery and Cloud Storage
- Vertex AI Search connected to BigQuery

Example Output Structure

<mxfile ...>
  <diagram name="GCP Architecture">
    <mxGraphModel ...>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- VPC-SC Container -->
        <mxCell id="vpc" value="VPC-SC" style="..." vertex="1" parent="1">
          <mxGeometry x="50" y="50" width="700" height="400" />
        </mxCell>
        <!-- Cloud Scheduler -->
        <mxCell id="sched" value="Cloud Scheduler" style="...mxgraph.gcp2.cloud_scheduler" vertex="1" parent="vpc">
          <mxGeometry x="50" y="100" width="50" height="50" />
        </mxCell>
        <!-- More shapes... -->
        <!-- Connections -->
        <mxCell id="conn1" edge="1" source="sched" target="run" style="..." />
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

---

Shape Library Reference

Looking Up a GCP Service

1. Open assets/gcp-icons.json
2. Search by service_name or recognition_keywords
3. Use the drawio_shape.full_style for complete styling
4. Or construct style using shape=mxgraph.gcp2.{shape_name}

Service Coverage:

• 46 GCP services across 11 categories
• 40 exact matches, 6 fallback icons
• Categories: compute, database, storage, networking, ai_ml, integration, operations, api_management, data_analytics, devops, security

Note: 6 services use fallback icons (Workflows, Eventarc, Artifact Registry, Cloud Deploy, Secret Manager, Identity Platform) as they're newer services not yet in DrawIO's mxgraph.gcp2 stencil. See [references/ICON-COMPATIBILITY.md](references/ICON-COMPATIBILITY.md) for complete validation details.

GCP Service Categories

| Category | Services |

|----------|----------|

| compute | Cloud Run, Compute Engine, GKE, Cloud Functions, App Engine |

| database | BigQuery, Cloud SQL, Firestore, Spanner, Bigtable, Memorystore |

| storage | Cloud Storage, Filestore, Persistent Disk |

| networking | VPC, Load Balancing, CDN, DNS, Armor, Cloud NAT |

| ai_ml | Vertex AI, AI Platform, Vision, NLP, Speech-to-Text |

| integration | Pub/Sub, Cloud Tasks, Workflows, Eventarc, Scheduler |

| operations | Logging, Monitoring, Trace, Error Reporting |

| api_management | Apigee, API Gateway |

| data_analytics | Dataflow, Dataproc, Cloud Composer |

| devops | Cloud Build, Artifact Registry, Container Registry, Cloud Deploy |

| security | Cloud KMS, Secret Manager, Identity Platform |

---

Visual Best Practices (Summary)

For detailed visual design guidelines, see [references/DIAGRAM-BEST-PRACTICES.md](references/DIAGRAM-BEST-PRACTICES.md).

GCP Project Zone (Two-Cell Pattern)

The GCP Project container uses two cells, not one:

1. Container cell: Plain rectangle with fillColor=#F6F6F6;strokeColor=none; and HTML value <b>Google </b>Cloud Platform
2. Logo child cell: shape=mxgraph.gcp2.google_cloud_platform at 23x20px with relative=1 geometry

See assets/templates/node-template.xml for the exact template.

Font Colors

• Service icon labels: fontColor=#424242 (dark gray)
• GCP Project zone text: fontColor=#717171
• VPC-SC container title: fontColor=#2E7D32 (dark green)
• Dashed group labels: fontColor=#424242

Icon Spacing

• Icon size: 50x50 pixels
• Standard spacing: 100px between icons
• Container padding: 20-30px

Connection Labels

Always add these properties to labeled connections:

labelBackgroundColor=#FFFFFF;fontSize=10;fontColor=#333333;

Connection Best Practices

• Standard width: strokeWidth=1 for most connections
• Thick width: strokeWidth=2 only for primary data paths (use sparingly - max 1-3 per diagram)
• Orthogonal routing: edgeStyle=orthogonalEdgeStyle for professional appearance
• When 3+ connections cross same corridor: consolidate into single connection

---

XML Structure Quick Reference

For complete XML examples and detailed structure, see [references/xml-examples.md](references/xml-examples.md).

The key building blocks:

• Shape: <mxCell id="..." value="Label" style="..." vertex="1" parent="1"> with <mxGeometry>
• Connection: <mxCell id="..." edge="1" source="..." target="..." style="...">
• Container: Shape with container=1 in style; children set parent to container ID
• Root cells: Every diagram needs <mxCell id="0"/> and <mxCell id="1" parent="0"/>

For XML parsing and extraction techniques, see [references/xml-parser-guide.md](references/xml-parser-guide.md).

---

Troubleshooting

Icon Not Displaying

• Verify shape name matches exactly: mxgraph.gcp2.cloud_run (underscore, not hyphen)
• Check [references/ICON-COMPATIBILITY.md](references/ICON-COMPATIBILITY.md) for correct shape names
• Ensure vertex="1" is present
• Check that <mxGeometry> has valid width/height (50x50)
• For Workflows/Eventarc, note these don't have exact icon matches in DrawIO's library

Connection Not Rendering

• Verify source and target IDs exist
• Ensure edge="1" is set
• Check that source/target shapes are vertices

Shapes Not Inside Container

• Set child's parent attribute to container's ID
• Ensure container has container=1 in style
• Position child coordinates relative to container (not absolute)

Label Not Showing

• Check value attribute is set
• Verify fontSize is reasonable (11-14)
• Ensure fontColor=#424242 is set

File Won't Open in DrawIO

• Validate XML structure (proper closing tags)
• Ensure id="0" and id="1" root cells exist
• Check for special characters in labels (use 
 for newlines)

---

Desktop Integration

After generating a .drawio file, you can validate and preview it:

1. Validate: python scripts/validate-drawio.py output.drawio --verbose
2. Analyze: python scripts/analyze-existing.py output.drawio --markdown
3. Validate Icons: python scripts/validate-gcp-icons.py
4. Export PNG: ./scripts/export-diagram.sh output.drawio png
5. Open in DrawIO: ./scripts/open-diagram.sh output.drawio

Requires DrawIO Desktop. Install on macOS: brew install drawio

---

Files in This Skill

| File | Purpose |

|------|---------|

| SKILL.md | This file - main instructions |

| Assets | |

| assets/gcp-icons.json | GCP service icon database (46 services) |

| assets/containers.json | GCP container and connection styles |

| assets/templates/drawio-base.xml | Base XML template |

| assets/templates/node-template.xml | Shape insertion template |

| assets/templates/connection-template.xml | Connection template |

| References | |

| references/ICON-COMPATIBILITY.md | Icon validation reference |

| references/DIAGRAM-BEST-PRACTICES.md | Visual design and layout guidelines |

| references/xml-parser-guide.md | Detailed XML parsing reference |

| references/xml-examples.md | Copy-paste XML examples |

| references/coordinate-system.md | Positioning and layout guide |

| references/style-guide.md | Style string reference |

| Scripts | |

| scripts/validate-drawio.py | Validate .drawio XML structure |

| scripts/validate-gcp-icons.py | Validate GCP icon compatibility |

| scripts/fix-gcp-icons.py | Auto-fix icon shape names |

| scripts/fix-drawio-icons.py | Bulk fix icon references in .drawio files |

| scripts/extract-shape-names.py | Extract available shapes from DrawIO stencil |

| scripts/analyze-existing.py | Extract shapes/connections from .drawio files |

| scripts/export-diagram.sh | Export to PNG/PDF via DrawIO Desktop CLI |

| scripts/open-diagram.sh | Open .drawio file in DrawIO Desktop |