Diagram generation: ref-arch-driven procedure + spec validator + KB enrichment
The diagram path now follows a documented standard procedure (lookup the closest Oracle Architecture Center reference → confirm components → author absolute_layout → spec validator → render → visually verify) and ships persistent guardrails so layout regressions can't recur. Persistent procedure changes (apply to all users, all sessions): - tools/diagram_spec_validator.py — geometry checks (CONTAINER_TOO_THIN, CONTAINER_PADDING_VIOLATION, LABEL_OVERFLOW_PARENT) run BEFORE either renderer (drawio + PPTX). Catches the subnet-collapse / label-overflow bugs that the post-render drawio validator missed. - tools/oci_diagram_gen.py + tools/oci_pptx_diagram_gen.py — call the spec validator before emitting any output. Adds mysql / mysql_heatwave type aliases. - tools/archcenter_pattern_lookup.py — scores against cached page descriptions (not just the 1-line summary), supports --queries for multi-fragment composition, and applies synonym expansion via kb/architecture-center/synonyms.yaml so "LB HA cross AD" matches "load balancer high availability availability domain". - kb/architecture-center/synonyms.yaml — canonical synonym table (load balancer, autonomous database, data guard, …) used by the lookup scorer. KB enrichment: - tools/archcenter_description_fetcher.py + 121 cached _description.md under kb/diagram/assets/archcenter-refs/<slug>/. Removes the runtime dependency on docs.oracle.com when authoring specs and feeds the pattern-lookup scorer. - 110+ cached .drawio / .svg / .png references for offline reuse, plus the OCI Toolkit v24.2 import (kb/diagram/assets/oci-toolkit-drawio). Documentation: - docs/skill/output-formats.md — new "Standard diagram-generation procedure (MANDATORY)" + geometry rules + the new validator entry. - SKILL.md option 2 — references the mandatory procedure. - README.md — describes the spec validator, archcenter_pattern_lookup and description fetcher, and updates the KB-health table. Tooling that backs the procedure (cumulative across recent sessions): tools/archcenter_case_runner.py, archcenter_batch_driver.py, archcenter_zip_downloader.py, drawio_visual_validator.py, drawio_fidelity_eval.py, harvest_drawio_icon.py, import_oci_library.py, oci_pptx_diagram_gen.py, oci_pptx_render.py, refresh_pptx_icon_index.py. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
root
49
kb/diagram/reference-layouts/archcenter-batch-benchmark.yaml
Normal file
49
kb/diagram/reference-layouts/archcenter-batch-benchmark.yaml
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
last_verified: 2026-04-25
|
||||
scope: Oracle Architecture Center batch visual benchmarking
|
||||
tool: tools/oci_archcenter_batch.py
|
||||
make_target: archcenter-benchmark-20
|
||||
---
|
||||
|
||||
purpose:
|
||||
- Validate acquisition, provenance, editable reconstruction, and comparison plumbing across at least 20 official Architecture Center reference architectures.
|
||||
- Prefer ZIP-backed native reconstruction and use page-image fallback only when an official ZIP is unavailable or unusable.
|
||||
|
||||
acceptance_states:
|
||||
visual_pass:
|
||||
definition: Official diagram asset was downloaded and the coordinate-faithful render matches the official image threshold.
|
||||
caveat: This state alone does not guarantee editable/native PPTX quality.
|
||||
native_editable_pass:
|
||||
definition: The generated draw.io and PowerPoint contain reconstructed editable OCI elements and pass structural and visual comparison against the official reference.
|
||||
required_evidence:
|
||||
- generated .drawio
|
||||
- generated .pptx
|
||||
- reference assets
|
||||
- render/diff evidence
|
||||
- structural validation
|
||||
- icon alias/mapping coverage
|
||||
|
||||
operating_procedure:
|
||||
- Run `make archcenter-benchmark-20`.
|
||||
- Inspect `examples/eval-2026-04-25-archcenter-native-20-v8/batch-summary.md`.
|
||||
- For pages with multiple ZIP assets, prefer filenames containing `architecture`, `physical`, `logical`, `topology`, or `arch`; penalize `functional`, `overview`, `process`, and `context`.
|
||||
- Treat draw.io fidelity as the primary editable benchmark: export the rebuilt `.drawio` with the real `draw.io.exe` binary and diff that PNG against the official Oracle PNG.
|
||||
- Treat native PPTX fidelity as a required gate: rasterize the editable slide with `tools/oci_pptx_render.py`, not `soffice` or LibreOffice.
|
||||
- Curate the benchmark pool before counting a case toward the 20 processed target. Skip diagrams that are annotation-dominant or that require multiple draw.io icon families still missing from `kb/diagram/oci-icons.json`.
|
||||
- Treat low icon-cluster coverage as FAIL even when pixel similarity passes, to avoid false positives on business-context or unlabeled functional diagrams.
|
||||
- Persist any learned icon aliases, layout conventions, renderer fixes, or benchmark-selection heuristics in `kb/diagram/reference-layouts/` and the corresponding generator code.
|
||||
|
||||
latest_run:
|
||||
output_root: examples/eval-2026-04-25-archcenter-native-20-v8
|
||||
requested: 20
|
||||
considered: 28
|
||||
processed: 20
|
||||
skipped: 8
|
||||
native_pass: 20
|
||||
fail: 0
|
||||
notes:
|
||||
- Primary visual truth is now the rebuilt draw.io exported through `draw.io.exe` under Windows/WSL; SVG-only comparison is fallback-only.
|
||||
- The benchmark now uses pure-Python native PPTX rasterization (`tools/oci_pptx_render.py`), so slide fidelity no longer depends on LibreOffice availability.
|
||||
- Preserving official `raw_icon_cells` plus background/context `raw_underlay_cells` closed the last native draw.io benchmark gap in the validated pool.
|
||||
- The latest verified run is 20 PASS / 0 FAIL over 20 processed cases while still considering 28 official references.
|
||||
- Remaining work is confined to the skipped pool, not the validated benchmark set: annotation-heavy diagrams and missing draw.io icon families such as DNS/VPN/maximum-security-zone variants.
|
||||
219
kb/diagram/reference-layouts/archcenter-batch-runner.yaml
Normal file
219
kb/diagram/reference-layouts/archcenter-batch-runner.yaml
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
last_verified: 2026-04-25
|
||||
runner: tools/archcenter_case_runner.py
|
||||
batch_driver: tools/oci_archcenter_batch.py
|
||||
evaluator: tools/oci_archcenter_eval.py
|
||||
---
|
||||
|
||||
purpose: |
|
||||
Reusable harness that converts an Oracle Architecture Center
|
||||
reference (.drawio + optional .png) into:
|
||||
1. a verbatim .drawio output (the source of visual truth),
|
||||
2. an auto-extracted absolute_layout YAML rebuilt through
|
||||
oci_diagram_gen.py (regression evidence),
|
||||
3. a native .pptx deck with OCI-styled shapes via the deck
|
||||
generator's native_pptx mode,
|
||||
4. a pure-Python raster render of that native PPTX slide via
|
||||
tools/oci_pptx_render.py,
|
||||
5. a draw.io fidelity render exported from the rebuilt `.drawio`
|
||||
via the real draw.io binary when available,
|
||||
6. a geometry eval rendered from the same YAML and diffed against
|
||||
the canonical PNG.
|
||||
|
||||
key_lessons:
|
||||
- >-
|
||||
Oracle drawio exports wrap many cells in <UserObject id="…"> rather
|
||||
than mxCell. The id lives on the wrapper, the geometry/style on the
|
||||
inner mxCell. Iterating only mxCell breaks the parent chain. The
|
||||
runner's _load_drawio handles both shapes and demotes UserObject
|
||||
parents back into the lookup.
|
||||
- >-
|
||||
Official OCI service icons are often multi-cell stencils with nested
|
||||
overlays or satellite cells. Cluster contained cells together and
|
||||
preserve their exact source XML as `raw_icon_cells`; otherwise the
|
||||
rebuilt draw.io drifts even when the semantic service type is right.
|
||||
- >-
|
||||
Pre-2024 references use plain rectangles (no shape=mxgraph.oracle.*
|
||||
stencil) for region/AD/VCN/subnet tiers. Classification therefore
|
||||
rides on fillColor (#f5f4f2 = region, #e4e1dd = AD,
|
||||
fillColor=none + orange stroke = VCN/subnet) rather than stencil
|
||||
family.
|
||||
- >-
|
||||
Caption text for an icon often sits in a *separate* anchor block
|
||||
(UserObject) BELOW the icon's anchor — not as a child. The label
|
||||
scanner walks every cell with absolute coordinates and looks
|
||||
in four cardinal directions, plus an "overlap" zone for caption
|
||||
boxes that visually overlap their icon.
|
||||
- >-
|
||||
For icons that have NO caption (policies, route-table/security-list,
|
||||
DRG-with-only-badge), the anchor's (width, height) tuple is a stable
|
||||
fingerprint across exports. The runner ships an ANCHOR_FINGERPRINTS
|
||||
table; extend it whenever a new size is observed.
|
||||
- >-
|
||||
Many official Oracle `.drawio` files store the `<diagram>` payload as
|
||||
base64 + raw-deflate XML. Both extraction and validation must support
|
||||
compressed payloads; otherwise the benchmark silently degrades into
|
||||
empty specs and false PASS/FAIL signals.
|
||||
- >-
|
||||
Per-subnet route-table/security-list icons sit *outside* the VCN.
|
||||
Do not bind them to the subnet container in absolute_layout — keep
|
||||
them on the region canvas.
|
||||
- >-
|
||||
The extractor now canonicalizes service captions instead of blindly
|
||||
reusing every nearby text block. This matters for DRG and Exadata
|
||||
anchors, where nearby route statements or container headers would
|
||||
otherwise become duplicated captions in the rebuilt draw.io.
|
||||
- >-
|
||||
draw.io icon alias coverage and PPTX icon alias coverage are separate
|
||||
concerns. PPTX can resolve more families than `kb/diagram/oci-icons.json`.
|
||||
Benchmark-pool curation must therefore skip some official references
|
||||
that still need draw.io icon harvesting, even if PPTX already renders
|
||||
them natively.
|
||||
- >-
|
||||
Some references keep important page furniture outside the semantic
|
||||
model: on-prem boxes, small context glyphs, accent bars, and similar
|
||||
stencils that are not services or containers. Preserve them as
|
||||
`raw_underlay_cells` and inject them immediately after the root scaffold
|
||||
in the rebuilt draw.io so they stay behind editable objects but still
|
||||
count in the real draw.io export fidelity benchmark.
|
||||
|
||||
threshold_guidance: |
|
||||
- 0.82 is appropriate for hand-tuned single-case reconstructions
|
||||
where every label, connector, and caption is curated.
|
||||
- 0.78 is the right threshold for the auto-extracted batch path; the
|
||||
eval renderer is intentionally minimalist (PIL boxes), so a
|
||||
geometry-faithful reproduction lands in the 0.80–0.86 band.
|
||||
- If a case dips below 0.78, first check whether the canvas size
|
||||
matches the official PNG; canvas mismatch dominates the RMS metric.
|
||||
|
||||
fidelity_guidance: |
|
||||
Primary method (persistent, canonical):
|
||||
- Export the rebuilt `.drawio` through `draw.io.exe` (or a Linux
|
||||
draw.io binary if available) and diff that PNG against the official
|
||||
Architecture Center PNG.
|
||||
- This is the only path that validates the editable artifact we
|
||||
generated. It catches missing stencils, bad page geometry, and
|
||||
caption regressions that an SVG-only comparison cannot see.
|
||||
|
||||
Fallback method:
|
||||
- If the draw.io binary is unavailable or errors, render the official
|
||||
SVG companion through cairosvg and compare it to the official PNG.
|
||||
- This verifies provenance and Oracle asset identity, but it is not a
|
||||
substitute for rebuilt draw.io fidelity.
|
||||
|
||||
Recommended threshold: 0.90.
|
||||
- Rebuilt draw.io exports that are truly aligned with the reference land
|
||||
at ~0.90–0.93 on the perceptual metric.
|
||||
- Official SVG companion renders land at ~0.95–1.00.
|
||||
- Below 0.90 usually means either icon-family coverage is incomplete or
|
||||
the rebuilt draw.io still carries label/layout deviations worth fixing.
|
||||
|
||||
drawio_visual_validator: |
|
||||
Added 2026-04-25 to catch bugs the raster eval misses:
|
||||
- fontSize ≥ 50pt (PPTX 1/100-pt vs drawio pt unit confusion)
|
||||
- duplicate cell ids
|
||||
- off-canvas geometry
|
||||
- dangling edge endpoints
|
||||
- compressed official draw.io payloads that would otherwise report
|
||||
`cell_count=0`
|
||||
|
||||
Run before the raster eval. Surfaces issues raster comparisons
|
||||
cannot — e.g. a 700pt label that visually breaks PowerPoint but
|
||||
doesn't move enough pixels to trip the RMS metric.
|
||||
|
||||
drawio_render_via_drawio_exe: |
|
||||
CANONICAL fidelity test for the rebuilt drawio (added 2026-04-25
|
||||
rev. 3). Why this is the canonical method, not just a fallback:
|
||||
|
||||
- The earlier path rendered the OFFICIAL .svg companion through
|
||||
cairosvg and compared it against the OFFICIAL .png. That validates
|
||||
Oracle's identity (svg and png come from the same drawio source)
|
||||
but is BLIND to bugs introduced by our reconstruction. It would
|
||||
have happily reported PASS on a rebuilt drawio with a 700pt title
|
||||
or empty service boxes.
|
||||
- The canonical method now exports the *rebuilt* drawio through
|
||||
draw.io itself (drawio.exe under WSL on the developer's Windows
|
||||
host) and pixel-diffs that PNG against the canonical PNG. This
|
||||
is the only path that catches rebuild regressions.
|
||||
|
||||
Implementation:
|
||||
- tools/drawio_to_png.py — WSL-aware wrapper. Maps /mnt/c/... →
|
||||
C:\... so drawio.exe (a Windows binary) can read/write the file.
|
||||
Stages WSL-only paths into project tmp/drawio-render-stage/.
|
||||
Falls back to a Linux drawio binary if found via PATH.
|
||||
- tools/drawio_fidelity_eval.py — accepts either --drawio (preferred,
|
||||
via the helper above) or --svg (cairosvg fallback). Uses a
|
||||
perceptual diff: 256px downsample + 1.0px Gaussian blur, so
|
||||
rasterizer anti-aliasing differences don't dominate the score.
|
||||
- tools/archcenter_case_runner.py — Step 7 detects drawio.exe via
|
||||
DRAWIO_WINDOWS_CANDIDATES (env DRAWIO_EXE override + standard
|
||||
install paths) and prefers that path. Records `method` in the
|
||||
fidelity payload so reports state which path was taken.
|
||||
- kb/diagram/oci-icons.json — drawio's stencil library; harvest the
|
||||
relevant icons from official Architecture Center .drawio files
|
||||
when adding new ones (policies, route_table_and_security_list,
|
||||
oracle_exadata_database_service were added 2026-04-25).
|
||||
|
||||
Operating procedure:
|
||||
- Always prefer the drawio.exe path on Windows/WSL hosts. If a case
|
||||
drops below threshold, the diff PNG (under renders/) shows what
|
||||
moved; common causes are missing icon stencils in
|
||||
`kb/diagram/oci-icons.json`, wrong canvas dimensions, or
|
||||
incorrect fontSize unit.
|
||||
- If drawio.exe fails for a case, `archcenter_case_runner.py` now
|
||||
records the CLI error and falls back cleanly to SVG fidelity rather
|
||||
than aborting the entire case.
|
||||
- When extending the harness for a new env, set DRAWIO_EXE to the
|
||||
full path of the binary or add the path to
|
||||
DRAWIO_WINDOWS_CANDIDATES in archcenter_case_runner.py.
|
||||
|
||||
This is the persistent test method — do not regress to SVG-only
|
||||
comparisons across sessions.
|
||||
|
||||
pptx_render_without_libreoffice: |
|
||||
Native PPTX fidelity no longer depends on `soffice`.
|
||||
|
||||
- `tools/oci_pptx_render.py` renders the editable slide directly from
|
||||
OpenXML using lxml + Pillow + cairosvg.
|
||||
- The renderer supports `sp`, `grpSp`, `pic`, and `cxnSp`, which is
|
||||
enough for the OCI-native diagram slides emitted by this repo.
|
||||
- Unsupported `WMF/EMF` media are skipped and recorded under
|
||||
`skipped_media` instead of aborting the benchmark. This keeps the
|
||||
run deterministic while surfacing the exact missing assets.
|
||||
|
||||
icon_aliases_added_2026_04_25:
|
||||
- exadata, exacs, oracle_exadata_database_service → oracle_exadata_database_service
|
||||
- drg, dynamic_routing_gateway → drg
|
||||
- policies, iam_policies → policies
|
||||
- security_list(s), route_table(_and_security_list) →
|
||||
route_table_and_security_list / security_lists
|
||||
- fastconnect, vpn, site_to_site_vpn, nat_gateway, natgw → matching shapes
|
||||
- bastion, vault, cloud_guard, maximum_security_zone, full_stack_disaster_recovery
|
||||
- data_catalog, data_integration, oci_data_integration, goldengate
|
||||
- block_storage, file_storage, network_firewall (→ firewall),
|
||||
web_application_firewall (→ waf)
|
||||
|
||||
how_to_run: |
|
||||
Single case:
|
||||
python tools/archcenter_case_runner.py \
|
||||
--case-id <id> --drawio <path> --png <path> \
|
||||
--title "<title>" --source-url "<url>" \
|
||||
--threshold 0.82 --fidelity-threshold 0.90
|
||||
Batch (20 cases):
|
||||
python tools/oci_archcenter_batch.py \
|
||||
--limit 20 \
|
||||
--threshold 0.82 \
|
||||
--fidelity-threshold 0.90 \
|
||||
--output-root examples/eval-2026-04-25-archcenter-native-20-v8
|
||||
|
||||
latest_verified_run:
|
||||
output_root: examples/eval-2026-04-25-archcenter-native-20-v8
|
||||
considered: 28
|
||||
processed: 20
|
||||
skipped: 8
|
||||
pass: 20
|
||||
fail: 0
|
||||
notes:
|
||||
- Case 12 now passes because the rebuilt draw.io preserves both `raw_icon_cells` and non-semantic `raw_underlay_cells` before export through `draw.io.exe`.
|
||||
- The validated 20-case pool has no open FAILs as of 2026-04-25.
|
||||
- Remaining gaps are limited to the skipped pool and should be solved by expanding draw.io icon coverage or by explicitly keeping those cases out of the native benchmark set.
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
last_verified: 2026-04-25
|
||||
source: https://docs.oracle.com/en/solutions/dataguard-exadata-dedicated-infrastructure/index.html
|
||||
arch_zip: exadata-dedicated-region-dataguard.zip
|
||||
diagram_asset: examples/dataguard-exa-dedicated-in-region/reference/exadata-dedicated-in-region-dataguard.png
|
||||
publication_date: "2025-07"
|
||||
pattern: in-region-data-guard-on-exadb-d-dedicated
|
||||
classification: single-region HA + automatic failover
|
||||
---
|
||||
|
||||
lessons:
|
||||
- Oracle's drawio exports wrap many cells in <UserObject id="…"> instead
|
||||
of mxCell. Iterating only mxCell loses the addressable id, breaking
|
||||
every parent-chain calculation. Always iterate UserObject elements
|
||||
too and treat them as the addressable cell.
|
||||
- Reference diagrams that pre-date 2024 use plain rectangles for the
|
||||
region/AD/VCN/subnet tiers (no shape=mxgraph.oracle.* stencil).
|
||||
Classify them by fillColor: #f5f4f2 region, #e4e1dd AD,
|
||||
fillColor=none orange-stroked containers for VCN/subnet.
|
||||
- Per-subnet route-table/security-list icons are placed *outside* the
|
||||
VCN, on the right edge, vertically aligned with each subnet.
|
||||
Policies sits at the top-right of the region, also outside the VCN.
|
||||
Do not bind these to subnet containers in the layout — they must
|
||||
live on the region canvas.
|
||||
- The DRG icon for a region with FastConnect / DRG attaches sits on
|
||||
the LEFT outside the VCN at roughly mid-height, with a "DRG" label
|
||||
badge underneath the stencil. The runner's stencil-fingerprint
|
||||
table (55x66 → drg) covers this case when no caption is present.
|
||||
- Two ExaDB-D stencils flank a horizontal "← Oracle Data Guard →"
|
||||
label. The Data Guard label is rendered as a text block, not as
|
||||
the OCI data_guard stencil — keep that intent in absolute_layout.
|
||||
|
||||
layout_rules:
|
||||
absolute_layout:
|
||||
use_when:
|
||||
- Two Availability Domain columns span horizontal subnet bands.
|
||||
- Per-subnet small icons (route table + security list) sit
|
||||
outside the VCN, aligned with their subnet.
|
||||
- DRG sits to the left of the VCN with no other gateways.
|
||||
canonical_geometry:
|
||||
canvas: {width: 627, height: 389}
|
||||
region: {x: 0, y: 0, w: 627, h: 389}
|
||||
vcn: {x: 28, y: 51, w: 589, h: 328}
|
||||
ad1: {x: 145, y: 17, w: 185, h: 346}
|
||||
ad2: {x: 364, y: 17, w: 185, h: 346}
|
||||
client_subnet: {x: 60, y: 102, w: 549, h: 75}
|
||||
backup_subnet: {x: 60, y: 219, w: 549, h: 127}
|
||||
drg: {x: 7, y: 188, w: 55, h: 66}
|
||||
policies: {x: 566, y: 35, w: 42, h: 40}
|
||||
route_table_client: {x: 558, y: 80, w: 42, h: 42}
|
||||
route_table_backup: {x: 558, y: 197, w: 42, h: 42}
|
||||
exa_ad1: {x: 205, y: 152, w: 64, h: 84}
|
||||
exa_ad2: {x: 425, y: 152, w: 64, h: 84}
|
||||
|
||||
service_aliases:
|
||||
exadata: oracle_exadata_database_service
|
||||
exacs: oracle_exadata_database_service
|
||||
oracle_exadata_database_service: oracle_exadata_database_service
|
||||
drg: drg
|
||||
dynamic_routing_gateway: drg
|
||||
policies: policies
|
||||
security_list: security_lists
|
||||
security_lists: security_lists
|
||||
route_table: route_table_and_security_list
|
||||
route_table_and_security_list: route_table_and_security_list
|
||||
|
||||
benchmark_case:
|
||||
workspace: examples/dataguard-exa-dedicated-in-region
|
||||
drawio_spec: examples/dataguard-exa-dedicated-in-region/specs/dataguard-exa-dedicated-in-region-diagram-spec.yaml
|
||||
deck_spec: examples/dataguard-exa-dedicated-in-region/specs/dataguard-exa-dedicated-in-region-deck-spec.yaml
|
||||
output_drawio: examples/dataguard-exa-dedicated-in-region/out/dataguard-exa-dedicated-in-region.drawio
|
||||
output_pptx: examples/dataguard-exa-dedicated-in-region/out/dataguard-exa-dedicated-in-region-native.pptx
|
||||
evaluation: examples/dataguard-exa-dedicated-in-region/evidence/dataguard-exa-dedicated-in-region-eval.md
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
last_verified: 2026-04-25
|
||||
source: https://docs.oracle.com/en/solutions/implement-lbaas-error-page/index.html
|
||||
diagram_asset: https://docs.oracle.com/en/solutions/implement-lbaas-error-page/img/lbaas-maintenance-page.png
|
||||
pattern: cloud-native-lbaas-error-page
|
||||
classification: single-region cloud-native operations workflow
|
||||
---
|
||||
|
||||
lessons:
|
||||
- Oracle Architecture Center operational workflow diagrams can place regional managed services outside the VCN while still inside the OCI region boundary. Do not force Object Storage, Monitoring, Notifications, or DNS into a subnet unless the source diagram does.
|
||||
- Numbered flow badges are part of the official visual grammar for process-oriented reference architectures. Render them only when the spec provides `flow_order`.
|
||||
- The LBaaS custom error page reference uses a fixed-coordinate composition rather than a standard tiered top-to-bottom layout: users and Object Storage are left of the VCN, Monitoring and Notifications are below the VCN, and DNS sits at the lower-right edge of the VCN.
|
||||
- Native PowerPoint reconstruction needs icon aliases for `internet_gateway`, `functions`, `monitoring`, `notifications`, and `dns`; otherwise the renderer falls back to generic service cards.
|
||||
|
||||
layout_rules:
|
||||
absolute_layout:
|
||||
use_when:
|
||||
- Reconstructing an official Architecture Center diagram from a PNG/SVG reference.
|
||||
- The source diagram uses non-grid subnets, regional services outside VCN, or numbered workflow connectors.
|
||||
required_fields:
|
||||
- canvas
|
||||
- containers
|
||||
- services
|
||||
- connections
|
||||
validation:
|
||||
- Generate draw.io and native PPTX from the same coordinate model.
|
||||
- Render the coordinate model to PNG using `tools/oci_archcenter_eval.py`.
|
||||
- Compare against the official PNG and inspect deviations before accepting.
|
||||
|
||||
service_aliases:
|
||||
internet_gateway: internet_gateway
|
||||
igw: internet_gateway
|
||||
functions: oci_functions
|
||||
function: oci_functions
|
||||
monitoring: monitoring
|
||||
notifications: notifications
|
||||
notification: notifications
|
||||
dns: dns
|
||||
|
||||
benchmark_case:
|
||||
workspace: examples/eval-2026-04-25-lbaas-error-page
|
||||
drawio_spec: examples/eval-2026-04-25-lbaas-error-page/specs/lbaas-error-page-diagram-spec.yaml
|
||||
deck_spec: examples/eval-2026-04-25-lbaas-error-page/specs/lbaas-error-page-deck-spec.yaml
|
||||
45
kb/diagram/reference-layouts/oci-toolkit-import.yaml
Normal file
45
kb/diagram/reference-layouts/oci-toolkit-import.yaml
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
last_verified: 2026-04-25
|
||||
source_zip: https://docs.oracle.com/iaas/Content/Resources/Assets/OCI-Style-Guide-for-Drawio.zip
|
||||
toolkit_version: v24.2
|
||||
toolkit_path: kb/diagram/assets/oci-toolkit-drawio/
|
||||
indexer: tools/import_oci_library.py
|
||||
refresh: tools/refresh_oci_drawio_toolkit.py
|
||||
---
|
||||
|
||||
audit_2026_04_25:
|
||||
finding: |
|
||||
The hand-curated kb/diagram/oci-icons.json had 67 entries, mostly
|
||||
harvested ad-hoc from a few Architecture Center exports. The official
|
||||
OCI Library.xml (Oracle Style Guide for Drawio v24.2) ships 223 shapes
|
||||
spread across 20 categories. Without a bulk importer, whole product
|
||||
families silently rendered as fallback rectangles in user diagrams.
|
||||
|
||||
category_breakdown:
|
||||
Logical: 34
|
||||
Identity_and_Security: 27
|
||||
Physical: 26
|
||||
Database: 25
|
||||
Applications: 20
|
||||
Networking: 18
|
||||
Developer_Services: 15
|
||||
Analytics_and_AI: 14
|
||||
Observability_and_Management: 13
|
||||
Storage: 10
|
||||
Compute: 7
|
||||
Governance_and_Administration: 5
|
||||
Migration: 2
|
||||
Container: 1
|
||||
Marketplace: 1
|
||||
Cloud: 1
|
||||
other: 9
|
||||
|
||||
fix:
|
||||
- "tools/import_oci_library.py decodes every entry (zlib + base64 + URL-encoded XML), normalises geometry so the wrapper sits at (0, 0, w, h), and writes oci-icons.json."
|
||||
- "tools/refresh_oci_drawio_toolkit.py fetches the Style Guide zip and stages it under kb/diagram/assets/oci-toolkit-drawio/."
|
||||
- "After import: 67 → 302 entries (223 canonical + 79 short aliases like 'adb' → 'database_autonomous_database')."
|
||||
|
||||
operating_procedure:
|
||||
- "When Oracle ships a new toolkit version, run `python tools/refresh_oci_drawio_toolkit.py` then `python tools/import_oci_library.py` (the importer overwrites; pass --keep-existing to preserve hand-curated entries)."
|
||||
- "When a service type appears as a fallback colored rectangle in generated diagrams, first check oci-icons.json for the canonical key, then add a new alias to import_oci_library.py::SHORT_ALIASES if the user's spec uses a friendly short name."
|
||||
- "Container-corner markers (per OCI Toolkit slide 18 'Grouping'): VCN gets vcn_icon, Subnet gets route_table_and_security_list, both at half-size in the top-right. OPTIONAL but standard — see oci-toolkit-styles.yaml § design_rules."
|
||||
Reference in New Issue
Block a user