Update (Jul 2026): v1.1.0 is out — aspect-correct icons, the official Oracle v24.2 palette and container styles, orthogonal edge routing by default, and a shipped overlap checker. Existing scripts keep running unchanged. See "What's new in v1.1.0" below, or jump straight to the release notes.
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.9+
-
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.1.0/oci-drawio-architect-v1.1.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:
What's new in v1.1.0
I've kept using this plugin since I posted this, and v1.1.0 is a big step up in rendering fidelity and workflow safety. Here's what changed.
Aspect-correct icons. v1.0.0 forced every icon into a fixed 75x95 slot, which stretched non-square icons by 15-20% on one axis. v1.1.0 reads each SVG's native aspect ratio and derives the cell size from it — fixed 95px height, width computed from the icon's own proportions (or the other way around if you only pass w or h to add_icon()). Icons render true to their actual shape now.
Styles aligned to Oracle's official v24.2 toolkit, plus 5 new container types. The color palette and every container style are now extracted directly from Oracle's official OCI Architecture Diagram Toolkit (v24.2): dotted-Sienna compartments with Bark labels, a #9E9892 2pt services-panel border, centered region labels, plain dashed connectors. Five new group types fill out the container vocabulary: tenancy, availability_domain, fault_domain, oracle_services_network, and onprem (the old hub type still works — it's now a deprecated alias of onprem).
Orthogonal edge routing by default. Port-less add_edge() calls now hand routing to draw.io's own orthogonal router instead of pinning a fixed exit/entry side. You get cleaner, auto-routed connectors without touching your script.
Before (v1.0.0, pinned ports on every edge):
d.add_edge(lb, vm, "443", parent=vcn,
exit_x=1.0, exit_y=0.5, entry_x=0.0, entry_y=0.5)
After (v1.1.0, default — let draw.io route it):
d.add_edge(lb, vm, "443", parent=vcn)
Scripts that still pass exit_x/exit_y/entry_x/entry_y or waypoints keep their exact v1.0.0 pinned behavior — nothing breaks.
A shipped overlap checker, now a workflow gate. scripts/check_overlaps.py is a standalone CLI (exit 0 clean, 1 overlaps found, 2 usage/parse error), backed by DrawioBuilder.check_overlaps(). The /drawio-architect command now runs it as a mandatory gate before handing you the .drawio file, so overlapping containers get caught before you open draw.io, not after.
Metadata and tooltips. add_icon() and add_group() take optional metadata= and tooltip= arguments now, stored as draw.io <object> attributes. Hover a shape in draw.io to see the tooltip, or open Edit Data to see the metadata — useful for attaching OCIDs, workload tags, or anything else you want to keep with a shape.
detect_settings hardening. The Terraform-directory and tenancy-detection logic got a pass: the tenancy-OCID regex is now bounded (no more cross-variable false matches), Terraform-directory discovery is deterministic, OCI CLI JSON handling is more robust, and there's an optional plugin-local logos/ directory for embedding your own logo in a diagram.
A real demo. examples/generate_demo_diagram.py builds a full sample architecture — tenancy → on-prem + region → availability/fault domains, compartment → VCN → subnets, a services panel, an Oracle Services Network panel — exercising every container type, the main icon-sizing and edge modes, metadata/tooltips, and the overlap gate in one script. It doubles as a post-install smoke test.
Python 3.9 is now the floor (was 3.8).
Compatibility
Existing v1.0.0 scripts run unchanged — positional arguments, keyword ports plus waypoints, and the hub group type are all preserved. Regenerated diagrams will pick up the refreshed v24.2 styling and aspect-correct icons automatically.
Full release notes: https://github.com/sergio-farfan/OCI-draw.io-Architect/releases/tag/v1.1.0
Top comments (0)