agentleFS
sergio-farfansergio-farfan/OCI-draw.io-Architect/CLAUDE.md

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
  1. Distinctive:

    All commands run from the repo root against the source tree.

    line 71

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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.md

Commands

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 --uninstall

Architecture

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/*/icons and .../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 in ICON_ALIASES (354 keys in ICON_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 uniform GLYPH_W x GLYPH_H = 70x70 area at the top of the ICON_W x ICON_H = 75x95 slot, 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) and v1.0 (byte-for-byte 1.0.0 sample; sample is an alias). Region / on-prem / compartment labels top-left; services panel charcoal #312D2A 1px dashed; all text uses FONT_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). The compartment label is bold Sienna since 1.4.0 (slide 18). Every container style now carries an ociGroup=<type>; token right before container=1;, so validate_file() (and hand-written files) can recognise a cell's group_type without a style heuristic. GROUP_TYPES is 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 a group_type), and the global-services bucket reuses the existing tenancy group type rather than adding a new one.
  • Container hierarchy: add_group() returns a cell ID used as parent for children. Sizes are provisional — call fit_to_children() bottom-up after adding children, then fit_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 an ociRole=drg; style token so the validator can recognise it without relying on its caption.
  • Lattice routing: add_edge() defaults to route="auto": the parent is the common ancestor of source and target, and at validate()/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" = fixed exit_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") applies EDGE_KIND_STYLES (dashed / arrowhead / width / dash pattern per kind; explicit arrow= 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, other stays usable).
  • Validation: validate() returns ERROR:/OVERLAP: (unknown parent/source/target ids — which otherwise make draw.io silently drop the diagram — any-two-container overlaps, containment, icon/caption/text collisions) and WARNING: (captions over MAX_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 a vcn container, and a foreign-containment ERROR: '<label>' ... lies inside '<VCN or subnet>' ... but is not one of its children for any leaf overlapping a network container it does not belong to; STRADDLE_TOL (4px) and FOREIGN_TOL (ICON_W/4 = 18.75px) keep border-straddling gateways from tripping either check. check_overlaps() returns only the blocking ones; strict=True promotes warnings. validate_file() (used by the CLI) inflates compressed pages and understands <object>/<UserObject> wrappers. write() writes compressed="false" XML and accepts str or Path.
  • 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, global for the global-services bucket container, global-compartments for its compartment-list text cell.

API summary:

MethodPurpose
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_tableText, 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_infoRecipe 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

  1. Settings — load .claude/oci-drawio-architect.local.md or run detect_settings.py and confirm with the user
  2. Input — Terraform path, VCN name, or description
  3. Model — build the normalized schema-2 model (drgs[] with typed attachments, regional services[], gateways[].peer), via parse_terraform.py for HCL / plan / state, query_tenancy.py for a live tenancy, or by hand for descriptions
  4. Generate — write generate_<name>_drawio.py importing from ${CLAUDE_PLUGIN_ROOT}/scripts (no copy)
  5. Run — execute the script
  6. Validate + render — check_overlaps.py must exit 0 (mandatory gate); render_drawio.py PNG when draw.io desktop is available
  7. Report — path, size, contents, settings used, viewing instructions

OCI Color Palette (COLORS)

TokenHexUse
region_fill#F5F4F2Region / on-prem / third-party / internet fill (Neutral 1)
region_stroke#9E9892Region / tenancy / AD / FD / metro borders (Neutral 3)
neutral_2#DFDCD8Availability Domain fill
neutral_4#70736ESecondary text, connector labels
air#FCFBFAFault Domain / Oracle Services Network fill
vcn_stroke / vcn_label#AE562CVCN / subnet / compartment borders and labels (Sienna)
text_primary#312D2AText, services-panel border, connectors (Bark)
rose#A36472Oracle Services Network border / label
ivy#759C6COCI logical component border
ocean#2C5967Icon ink colour
oracle_red#C74634On-premises logical component border
edge_color#312D2ADefault connector colour (Bark)
edge_accent#AE562CHighlighted edges (project extension)
edge_purple#7B61FFSpecial 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.sh PNG export (DRAWIO_BIN overrides the lookup)
  • OCI CLI (optional) — tenancy name and region subscriptions in detect_settings.py; live topology in query_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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.