The problem
Manually drawing OCI diagrams in draw.io is tedious...
If you have ever had to document an OCI architecture, the process is familiar. You open draw.io, locate the correct Oracle icon set, drag shapes onto the canvas, manually wire up VCNs and subnets, nudge elements into alignment — then spend another 30 minutes reconciling colors against Oracle's official template, only to discover that the Terraform configuration changed the previous week and the diagram is already out of date.
For cloud architects working with OCI, this is a recurring overhead on every project:
Diagrams drift from reality
Terraform is the source of truth, but draw.io has no awareness of it. Every infrastructure change requires a manual diagram update — one that typically does not occur until someone requests it during a review.
The OCI icon set is not native to draw.io
It must be located, imported, and mapped to the correct services across 15 categories and 220+ icons — a non-trivial exercise before any actual diagramming begins.
Layout is time-consuming
Correctly representing the Region → VCN → Subnet → Service hierarchy, with proper spacing, non-overlapping containers, and Oracle's color scheme, requires significant effort even for experienced practitioners.
Hub-and-spoke topologies are especially difficult
Arranging 10–15 spoke VCNs connected through a DRG in a clean, readable layout is an hour-long exercise in manual positioning.
Diagrams are created once and abandoned
Because updates are costly, teams stop maintaining them. By the time a new team member onboards or an audit is conducted, the diagram reflects an architecture from two sprints prior.
The root cause is that architecture diagrams are treated as design artifacts — something produced manually — rather than something derived directly from the infrastructure definition.
What I built
https://github.com/sergio-farfan/OCI-draw.io-Architect
A Claude Code plugin — type /drawio-architect in any project...
How it works
The plugin accepts three input types: a Terraform directory path — parsed to extract VCNs, subnets, gateways, and DRG attachments — a VCN name resolved against existing .tfvars files, or a plain-text description of the target architecture.
From any of these inputs, it computes a pixel-precise grid layout, calculating container bounding boxes to eliminate element overlap, and generates a Python script leveraging a custom DrawioBuilder class backed by 220 bundled OCI SVG icons. Executing the script produces a .drawio file fully styled with Oracle's official color palette.
The entire workflow is invoked within Claude Code via a single /drawio-architect command.
Step by Step Installation
Prerequisites
- Claude Code (CLI) installed and working
- Python 3.8+
-
draw.io desktop for viewing generated
.drawiofiles
The plugin bundles 220 OCI SVG icons and auto-installs Pillow (Python imaging library) if missing.
Installation
Step 1 - Download, Extract and Install
One command:
curl -fsSL https://github.com/sergio-farfan/OCI-draw.io-Architect/releases/download/v1.0.0/oci-drawio-architect-v1.0.0.tar.gz | tar -xz && ./oci-drawio-architect/install.sh
This will:
- Download, extract and execute the Installer script
- Check prerequisites (Python 3, Pillow)
- Install Pillow automatically if missing
- Create a local marketplace at
~/.claude/plugins/marketplaces/local/ - Copy the plugin files into the marketplace
- Verify all components (5 checks)
Step 2 - Register in Claude Code
Open Claude Code and run these two commands:
/plugin marketplace add ~/.claude/plugins/marketplaces/local
/plugin install oci-drawio-architect@local
Exit Claude Code and reopen it for the plugin to load.
Step 3 - Verify
Run inside Claude Code:
/drawio-architect
The command should prompt you for what to diagram.
Example Snippet:
Top comments (0)