OCI-draw.io-Architect
CLAUDE.md9 starsChanged 57 days agoMITView on GitHub
oci-drawio-architect is a Claude Code plugin (v1.5.0) that generates production-quality .drawio architecture diagrams for Oracle Cloud Infrastructure (OCI) from Terraform configs, a live tenancy, or free-form descriptions. Input is normalized into a small diagram model; a deterministic layout recipe (oci_layout.py) and a stdlib-only builder (drawio_builder.py) turn it into a validated, Oracle-styled diagram. Since 1.4.0 the location boxes (On-Premises, Internet, 3rd Party Cloud) are page-level siblings of the region, the Internet-facing gateways form a column on the border facing the Internet…
- Installs packages
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 71
All commands run from the repo root against the source tree.
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project
oci-drawio-architect is a Claude Code plugin (v1.5.0) that generates production-quality .drawio architecture diagrams for Oracle Cloud Infrastructure (OCI) from Terraform configs, a live tenancy, or free-form descriptions. Input is normalized into a small diagram model; a deterministic layout recipe (oci_layout.py) and a stdlib-only builder (drawio_builder.py) turn it into a validated, Oracle-styled diagram. Since 1.4.0 the location boxes (On-Premises, Internet, 3rd Party Cloud) are page-level siblings of the region, the Internet-facing gateways form a column on the border facing the Internet box, the Oracle Services Network is a band below the VCN stack, and compartments and grouping boxes are opt-in containers. The plugin is distributed as a reproducible archive (oci-drawio-architect-v1.5.0.tar.gz) built by pack.sh.
Author: Sergio Farfan
Repository Contents
The plugin source is tracked directly in this repo, under oci-drawio-architect/. Edit it there — there is no archive to extract.
OCI-draw.io-Architect/
├── README.md # Installation & usage guide
├── CLAUDE.md # This file
├── LICENSE # MIT (plugin code)
├── OCI_Architecture.drawio # Reference sample the layout recipe reproduces
├── screenshots/, Screens/ # README images; regenerate with oci-drawio-architect/examples/make_screenshots.py
├── dev.to/ # Article assets (do not regenerate)
└── oci-drawio-architect/ # Plugin source (edit here)pack.sh builds oci-drawio-architect-v<VERSION>.tar.gz from this source tree; the tarball is published as a GitHub release asset, not committed (*.tar.gz is gitignored). install.sh installs directly from the source directory. .gitignore also covers .claude/*.local.md, *.drawio.png, *.drawio.svg, /oci-drawio-architect/logos/, __pycache__/ and .venv/.
Plugin source layout:
oci-drawio-architect/
├── .claude-plugin/plugin.json # Plugin metadata (version source of truth)
├── commands/drawio-architect.md # /drawio-architect command
├── skills/oci-drawio-architect/
│ ├── SKILL.md # Full skill workflow
│ └── references/
│ ├── oracle-styles.md # Container / edge / colour reference
│ ├── icon-catalog.md # Generated by build_icon_catalog.py
│ ├── gotchas.md # Common pitfalls
│ └── templates/ # physical_example_*.svg composites (docs only)
├── scripts/
│ ├── drawio_builder.py # Core builder (v1.5.0)
│ ├── oci_layout.py # Model -> diagram recipe (CLI + build_diagram/write_diagram)
│ ├── check_overlaps.py # Validator CLI (mandatory workflow gate)
│ ├── render_drawio.py # draw.io desktop export (PNG/SVG/PDF)
│ ├── detect_settings.py # Settings probe (Terraform, ~/.oci/config, OCI CLI)
│ ├── parse_terraform.py # HCL dir / plan JSON / state JSON -> model
│ ├── query_tenancy.py # Experimental: live tenancy -> model (OCI CLI)
│ ├── oci_topology.py # Topology classification, legacy-model migration, DRG-style choice
│ ├── oci_view.py # View resolution, caption rendering, filtering (purposes, detail levels, layers)
│ ├── build_icon_catalog.py # Regenerate / --check the icon catalog
│ └── smoke_test.sh # Demo -> gate -> PNG
├── examples/
│ ├── generate_demo_diagram.py # Six-page demo / post-install smoke test
│ └── generate_reference_layout.py # Rebuilds the reference sample from a MODEL dict
├── tests/ # unittest suite (builder, layout, topology, settings, icons) + fixtures/detect/*, fixtures/terraform/hub_spoke/
│ # v1.5.0 adds test_oci_view.py, test_view_layers.py / test_builder_layers.py, test_layout_label_modes.py,
│ # test_detail_levels.py, test_filter_model.py / test_layout_filtering.py, test_layout_purposes.py / test_detect_purpose.py,
│ # test_global_services.py / test_layout_global_bucket.py, test_parse_terraform_views.py, test_query_tenancy_views.py,
│ # test_examples_views.py and fixtures/terraform/tagged_app/
├── icons/ # 159 OCI SVG icons, 12 categories, + NOTICE (Oracle terms)
├── LICENSE # MIT (code only; icons are Oracle's, see icons/NOTICE)
├── install.sh # Install / --uninstall
├── pack.sh # Reproducible packaging
├── CHANGELOG.md
└── README.mdCommands
All commands run from the repo root against the source tree; nothing needs to be installed first.
# Tests
python3 -m unittest discover -s oci-drawio-architect/tests # builder, settings detection, icons
# End-to-end smoke test (demo diagram -> check_overlaps -> PNG if draw.io desktop exists)
oci-drawio-architect/scripts/smoke_test.sh # SMOKE_SKIP_PNG=1 / SMOKE_OUT_DIR=...
# Validate a diagram (exit 0 clean, 1 errors or --strict warnings, 2 unusable input)
python3 oci-drawio-architect/scripts/check_overlaps.py [--strict] [--quiet] file.drawio [...]
# Render (exit 0 ok, 1 export failed, 3 no draw.io binary; DRAWIO_BIN overrides the lookup)
python3 oci-drawio-architect/scripts/render_drawio.py file.drawio [-f png|svg|pdf|jpg] [-o OUT] [-s SCALE]
# Terraform -> model JSON (exit 0 ok, 1 nothing recognisable, 2 bad input); MODEL schema_version 1
python3 oci-drawio-architect/scripts/parse_terraform.py [tf_dir] [--plan-json F | --state-json F] [--vcn NAME] [--out FILE] [--no-inferred-edges] [--filter EXPR] [--tag K=V] [--compartment NAME] [--subnet NAME] [--resource-type TYPE] [--mode all|participating] [--discovery K,K] [--relationships FILE]
# Layout CLI: model JSON -> .drawio (+ validate, optional render)
python3 oci-drawio-architect/scripts/oci_layout.py model.json -o out.drawio [--profile default|official|v1.0] [--legend] [--logo f] [--strict] [--render png] [--drg-style auto|icon|box] [--locations outside|nested] [--gateway-edge auto|internet|top|bottom] [--subnet-label twoline|inline] [--attachment-style solid|dotted] [--show-compartments] [--purpose network|dataflow|security|inventory|dependency|ha] [--detail executive|application|network|engineering] [--label-mode minimal|network|detailed] [--label-fields F,F] [--label-tag-keys K,K] [--layers off|auto|L,L] [--hidden-layers L,L] [--filter EXPR] [--mode all|participating] [--discovery K,K] [--annotate-discovery] [--global-services osn|bucket] [--no-edges]
# Settings probe (exit 0 ok, 1 nothing detected, 2 bad dir); prints YAML frontmatter to stdout
python3 oci-drawio-architect/scripts/detect_settings.py [--no-cli] [terraform_dir]
# Icon catalog (exit 0 ok, 1 problems, 2 usage); run --check after touching icons/
python3 oci-drawio-architect/scripts/build_icon_catalog.py [--check] [--out FILE]
# Examples
python3 oci-drawio-architect/examples/generate_demo_diagram.py [out.drawio] [--render]
python3 oci-drawio-architect/examples/generate_reference_layout.py [out.drawio] [--render]
# Package (version read from plugin.json; excludes logos/ and tarballs; prints entries + SHA256)
oci-drawio-architect/pack.sh [/path/to/output]
# Install / uninstall
oci-drawio-architect/install.sh # then /plugin marketplace add ~/.claude/plugins/marketplaces/local
# /plugin install oci-drawio-architect@local ; restart Claude Code
~/.claude/plugins/marketplaces/local/plugins/oci-drawio-architect/install.sh --uninstallArchitecture
drawio_builder.py — Core XML Builder
Stdlib-only (Pillow optional, only for PNG/JPEG logos in add_image()). Generated scripts import it in place — sys.path.insert(0, "<plugin>/scripts") — it is not copied into the user's project.
Key design decisions:
- Icon resolution order:
$OCI_SVG_DIR→<builder dir>/../icons(plugin layout) →<builder dir>/icons→$CLAUDE_PLUGIN_ROOT/icons→~/.claude/plugins/marketplaces/*/plugins/oci-drawio-architect/icons→~/.claude/plugins/cache/*/oci-drawio-architect/*/iconsand.../cache/*/oci-drawio-architect/icons→~/.claude/plugins/oci-drawio-architect/icons.set_icon_dir(path)overrides at runtime. Every SVG is registered by file stem at import (159) plus 206 short aliases inICON_ALIASES(354 keys inICON_MAP; 11 aliases coincide with stems). Unknown keys raise with close-match suggestions. - URL-encoding: SVG data URIs use
urllib.parse.quote(), NOT base64. A raw;base64,marker breaks draw.io's semicolon-delimited style parsing. - Glyph cropping:
_load_svg()strips the stencil export's caption-placeholder rectangle, computes the real glyph bounds, crops the viewBox to them and fits the glyph into a uniformGLYPH_W x GLYPH_H = 70x70area at the top of theICON_W x ICON_H = 75x95slot, so every icon renders at the same visual size and is centred. - Style profiles:
STYLE_PROFILES=default(reference look with official 12px labels,dashPattern=6 3),official(strict OCI toolkit v24.2: 1px edges, open dashed arrows, AD/FD arcSize 8/7) andv1.0(byte-for-byte 1.0.0 sample;sampleis an alias). Region / on-prem / compartment labels top-left; services panel charcoal#312D2A1px dashed; all text usesFONT_STACK = "Oracle Sans,Arial,Helvetica,sans-serif".GROUP_TYPES: region, tenancy, availability_domain, fault_domain, compartment, vcn, subnet, services, oracle_services_network, onprem (hub= deprecated alias), other, metro_or_realm, third_party_cloud, internet, drg, user_group, tier, oke_cluster (the last three from deck slides 18 and 32, v1.4.0). Thecompartmentlabel is bold Sienna since 1.4.0 (slide 18). Every container style now carries anociGroup=<type>;token right beforecontainer=1;, sovalidate_file()(and hand-written files) can recognise a cell'sgroup_typewithout a style heuristic.GROUP_TYPESis unchanged in 1.5.0 - a view layer is draw.io's own layer mechanism (add_layer, a page-level sibling of the containers, not agroup_type), and the global-services bucket reuses the existingtenancygroup type rather than adding a new one. - Container hierarchy:
add_group()returns a cell ID used asparentfor children. Sizes are provisional — callfit_to_children()bottom-up after adding children, thenfit_page().add_box()adds a small labelled rounded rectangle (DRG attachment marker) that is a routing obstacle and a valid edge endpoint;add_icon(label_fill=)gives the caption an opaque background for icons whose glyph straddles a dashed border (gateways on the VCN edge); the DRG glyph itself carries anociRole=drg;style token so the validator can recognise it without relying on its caption. - Lattice routing:
add_edge()defaults toroute="auto": the parent is the common ancestor of source and target, and atvalidate()/write()time the router picks docking sides and waypoints on a lattice of container margins and gutters so connectors avoid unrelated icons, captions and container titles; an edge is not charged for the padding inside its own endpoints' slots, a docking point another connector already uses costs_PORT_SHARE_COST(calibrated above a three-bend detour), and labels are placed to avoid collisions.route="direct"= draw.io's port-less orthogonal router (1.1.0 default);route="pinned"= fixedexit_x/exit_y/entry_x/entry_y+waypoints(1.0.0 behaviour), selected automatically when pins or waypoints are passed.add_edge(kind="data"|"control"|"association"|"attachment")appliesEDGE_KIND_STYLES(dashed / arrowhead / width / dash pattern per kind; explicitarrow=still wins);add_legend()gained rows for all four kinds plus region/VCN/subnet/OSN.append_pages(other)appends another builder's pages as read-only (deep-copied,otherstays usable). - Validation:
validate()returnsERROR:/OVERLAP:(unknown parent/source/target ids — which otherwise make draw.io silently drop the diagram — any-two-container overlaps, containment, icon/caption/text collisions) andWARNING:(captions overMAX_LABEL_LINES=3,add_box()labels of any line count taller than their box, estimated edge crossings, empty pages, content exceeding the page). Two more rules:ERROR: DRG '<label>' is inside VCN '<vcn>'when a DRG icon's box is parented inside avcncontainer, and a foreign-containmentERROR: '<label>' ... lies inside '<VCN or subnet>' ... but is not one of its childrenfor any leaf overlapping a network container it does not belong to;STRADDLE_TOL(4px) andFOREIGN_TOL(ICON_W/4= 18.75px) keep border-straddling gateways from tripping either check.check_overlaps()returns only the blocking ones;strict=Truepromotes warnings.validate_file()(used by the CLI) inflates compressed pages and understands<object>/<UserObject>wrappers.write()writescompressed="false"XML and acceptsstrorPath. - Deterministic ids and metadata:
key=on any add_* call fixes the cell id (stable diffs, update-in-place);metadata=/tooltip=wrap the cell in<object>,link=in<UserObject>. New fixed ids in 1.5.0:layer-<name>for each enabled view layer,globalfor the global-services bucket container,global-compartmentsfor its compartment-list text cell.
API summary:
| Method | Purpose |
DrawioBuilder(page_name, width, height, style_profile, font_family) | New document; first page |
add_page(name, w, h) / use_page(idx_or_name) / add_layer(name) | Multi-page / layered output |
add_group(label, x, y, w, h, parent, group_type, metadata, tooltip, key, link) | Container rectangle; returns id |
add_icon(label, icon_key, x, y, parent, w, h, metadata, tooltip, key, label_fill) | OCI icon + caption in a 75x95 slot; label_fill for a caption crossing a dashed border |
add_box(label, x, y, w, h, parent, key, style_extra, metadata, tooltip) | Small labelled rounded rectangle (DRG attachment marker); routing obstacle, valid edge endpoint |
place_icons(parent, items, cols, x0, y0, col_w) | Grid of icons; returns ids and the bounding box |
add_badge(icon_key, cx, cy, parent, host, size, key, metadata, tooltip) | Caption-less 22 px icon centred on (cx, cy): route table / security list on a subnet corner, NSG on a resource icon |
add_image(path, x, y, w, h) | Logo (SVG directly; PNG/JPEG via Pillow) |
add_text / add_title / add_legend / add_table | Text, standard title block, legend, rule table |
add_edge(source, target, label, parent=None, dashed, color, route, ..., kind) | Connector; auto-routed by default; kind applies EDGE_KIND_STYLES |
append_pages(other) | Append another builder's pages as read-only (deep-copied) |
fit_to_children(cid) / resize(cid, ...) / fit_page() | Size containers and the page from content |
validate(strict) / check_overlaps(strict) | Problem lists; call before write() |
layout_info | Recipe metadata dict (topology, warnings, drg_style); empty unless oci_layout.build_diagram() filled it |
write(path) / render(path, fmt) | Output .drawio; export via draw.io desktop |
add_icons_to_map(dict) / set_icon_dir(path) | Extend ICON_MAP; override the icon directory |
Layout constants: ICON_W=75, ICON_H=95, GLYPH_W=GLYPH_H=70, LABEL_H=45, LABEL_GAP=2 → 142px per icon footprint; PAD=20, GAP=20, ROW1_Y=50, COL_W=130, ROW_H=160; DRG_GAP=45, ATT_W x ATT_H=100x44, ATT_GAP/ATT_PITCH=15/56, DRG_CLUSTER_GAP=40, OSN_GAP=45, GW_STRADDLE/GW_SIDE_DX=40/38, SIDE_GW_Y0/LEFT_GW_Y0/SIDE_GW_PITCH=50/50/160, VCN_BOTTOM_PAD_GW/VCN_SIDE_PAD/SIDE_INSET=60/60/40, VCN_COLUMN_GAP_GW=110. v1.4.0 adds LOC_W=180, LOC_GAP_MIN/LOC_GAP_RIGHT/LOC_STACK_GAP=70/10/10, LOC_MIN_H=160, INTERNET_SPLIT=0.45, OSN_BAND_GAP=45, VCN_TOP_PAD_GW/TOP_GW_X0=60/50, CMP_PAD/CMP_TITLE_H/CMP_GAP=30/40/40, TEN_PAD/TEN_TITLE_H=25/40, GRP_PAD/GRP_TITLE_H=15/30, DRG_RT_GAP/DRG_RT_MAX=6/2, LEGEND_BADGE_SIZE=16. v1.5.0 adds LABEL_H_DETAILED=88 and LABEL_LINE_BUDGET (the detailed caption box and its per-mode line count) and, for the global-services bucket, GLOBAL_BAND_GAP=45, GLOBAL_LABEL ("Global services"), GLOBAL_MAX_COMPARTMENTS=12 and GLOBAL_TEXT_H=40.
oci_layout.py — Layout Recipe
build_diagram(model) / write_diagram(model, path) lay out a schema-2, JSON-serialisable model (subject, region, region_label, compartment, drg_style, hub on-premises-only, drgs[] with typed attachments[], vcns[] with subnets[]/services[]/gateways[], regional services[], edges[], notes) as: title block, region (label top-left), VCN column(s) with subnet rows in traffic order (lb → app → compute → mgmt, 2 icon columns), OCI Services panel right of row 1 for VCN-resident items only, data-tier subnets stretched to the row width, border gateways facing what they connect to (IGW then NAT on the border facing the Internet box - the VCN's right border on the default outside canvas, the bottom border when nested - SGW facing the OSN, LPG facing its peer VCN), an on-premises panel and a DRG column both vertically centred on the VCN stack (DRG icon or drg_style="box" group, one attachment box per attachment, a strip of up to two route-table badges under the glyph), an Oracle Services Network panel for regional services fed by the Service Gateway (a right-hand column when nested, a full-width band below the VCN stack when outside), optional compartment / tenancy containers around the VCNs (show_compartments) and optional groups[] boxes inside a VCN or a subnet, then a page-level pass that translates the region and emits the On-Premises / Internet / 3rd Party sibling boxes, auto-routed edges, optional legend with a row per badge kind. Edge kind: data (solid Bark, open arrow), control (dashed Bark, open arrow), association (dotted, no arrowhead), attachment (thin solid, no arrowhead), analytics (solid Sienna), datalake (dashed purple). Schema-1 models (DRG in hub.items or a drg gateway) are migrated automatically with a WARNING: legacy model: ... line. Subnet route_table / security_lists, item nsgs and drgs[].route_table become badges (_add_subnet_badges, _add_nsg_badge, _drg_route_table_badges; ids <subnet>-rt, <subnet>-sl, <icon>-nsg, <drg key>-rt, <drg key>-rt2). examples/generate_reference_layout.py is the canonical model that reproduces OCI_Architecture.drawio.
detect_settings.py — OCI Environment Probe
Probe order: (1) Terraform dir discovery — shallowest dir with a provider "oci" block, else tfvars; .terraform, .git, node_modules, .venv, __pycache__ pruned; ties reported in terraform_dirs. (2) Terraform files with comments stripped: non-aliased provider "oci" block only (terraform {}/backend {} and other providers ignored); var./local. resolved via terraform.tfvars, *.auto.tfvars[.json], then brace-matched variable defaults; tenancy_ocid must match ^ocid1.tenancy.; oci_core_vcn / oci_identity_compartment resources and vcns = {...} maps fill vcns / compartments. (3) ~/.oci/config (or $OCI_CLI_CONFIG_FILE) with [DEFAULT] inheritance → fallback region, auth_tenancy_ocid, oci_auth: security_token. (4) OCI CLI (oci iam tenancy get, oci iam region-subscription list; 8 s timeout each; --auth security_token when applicable; --no-cli skips). (5) Logo scan: logos/, assets/logos/, assets/images/, docs/logos/ (relative paths) then plugin-local logos/ (absolute); *dark*/*black* → logo_light, *white*/*light* → logo_dark. Region labels come from a 55-entry table (uk-london-1 is London; no eu-london-1) with a derived fallback. Output is YAML frontmatter (escaped) for .claude/oci-drawio-architect.local.md; delete that file to re-trigger detection.
/drawio-architect Command — 7-Step Workflow
- Settings — load
.claude/oci-drawio-architect.local.mdor rundetect_settings.pyand confirm with the user - Input — Terraform path, VCN name, or description
- Model — build the normalized schema-2 model (
drgs[]with typed attachments, regionalservices[],gateways[].peer), viaparse_terraform.pyfor HCL / plan / state,query_tenancy.pyfor a live tenancy, or by hand for descriptions - Generate — write
generate_<name>_drawio.pyimporting from${CLAUDE_PLUGIN_ROOT}/scripts(no copy) - Run — execute the script
- Validate + render —
check_overlaps.pymust exit 0 (mandatory gate);render_drawio.pyPNG when draw.io desktop is available - Report — path, size, contents, settings used, viewing instructions
OCI Color Palette (COLORS)
| Token | Hex | Use |
region_fill | #F5F4F2 | Region / on-prem / third-party / internet fill (Neutral 1) |
region_stroke | #9E9892 | Region / tenancy / AD / FD / metro borders (Neutral 3) |
neutral_2 | #DFDCD8 | Availability Domain fill |
neutral_4 | #70736E | Secondary text, connector labels |
air | #FCFBFA | Fault Domain / Oracle Services Network fill |
vcn_stroke / vcn_label | #AE562C | VCN / subnet / compartment borders and labels (Sienna) |
text_primary | #312D2A | Text, services-panel border, connectors (Bark) |
rose | #A36472 | Oracle Services Network border / label |
ivy | #759C6C | OCI logical component border |
ocean | #2C5967 | Icon ink colour |
oracle_red | #C74634 | On-premises logical component border |
edge_color | #312D2A | Default connector colour (Bark) |
edge_accent | #AE562C | Highlighted edges (project extension) |
edge_purple | #7B61FF | Special connection type (project extension) |
Dependencies
- Python 3.9+ (standard library only for the builder, layout, validator and settings probe)
- Pillow (optional) — only
add_image()with PNG/JPEG logos;python3 -m pip install --user Pillow - draw.io desktop (optional) — viewing, and
render_drawio.py/smoke_test.shPNG export (DRAWIO_BINoverrides the lookup) - OCI CLI (optional) — tenancy name and region subscriptions in
detect_settings.py; live topology inquery_tenancy.py
Licensing note
Plugin code is MIT. The SVGs under icons/ are Oracle's OCI Architecture Diagram Toolkit icons under Oracle's terms (icons/NOTICE); pack.sh refuses to build an archive without LICENSE and icons/NOTICE.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

