raulrgmx/oci-deal-accelerator
1
0
Fork 0
forked from diegoecab/oci-deal-accelerator
Code Pull Requests Activity
Files
c46219468fe476847a55d976a329942c63ded37a
oci-deal-accelerator/kb/diagram/oci-toolkit-styles.yaml
root b30a4f0d32 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>
2026-04-25 21:15:21 -03:00

301 lines
19 KiB
YAML
Raw Blame History

# OCI Official Diagram Styles — Extracted from OCI Style Guide for Draw.io Toolkit v24.2
# Source: OCI Library.xml + OCI Architecture Diagram Toolkit v24.2.drawio
# This supersedes earlier palette files based on inference from reference architectures.
# ============================================================
# CONTAINER STYLES (from Physical Groupings in the toolkit)
# These are the EXACT styles Oracle uses for diagram containers.
# ============================================================
containers:
tenancy:
# Toolkit item [200]: Physical - Grouping - Tenancy
style: "whiteSpace=wrap;html=1;strokeWidth=1;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#312D2A;strokeColor=#9E9892;fontSize=12;spacingLeft=5;"
notes:
- "DASHED gray border, NO fill"
- "Text color is charcoal #312D2A"
- "Border is warm gray #9E9892"
region:
# Toolkit item [202]: Physical - Grouping - OCI Region
style: "whiteSpace=wrap;html=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=#F5F4F2;rounded=1;arcSize=5;strokeColor=#9E9892;fontColor=#312D2A;fontSize=12;fontStyle=1;spacingLeft=8;spacingTop=5;"
notes:
- "SOLID border, rounded corners"
- "FILLED with warm gray #F5F4F2"
- "This is the only container with a solid background fill"
availability_domain:
# From template styles
style: "whiteSpace=wrap;html=1;strokeWidth=1;align=center;fontFamily=Oracle Sans;verticalAlign=top;fillColor=#DFDCD8;fontColor=#312D2A;strokeColor=#9E9892;rounded=1;arcSize=1;fontStyle=1;"
notes:
- "Slightly darker gray fill #DFDCD8"
- "Bold text (fontStyle=1)"
vcn:
# Toolkit item [197]: Physical - Grouping - VCN
style: "whiteSpace=wrap;html=1;strokeWidth=2;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#AE562C;strokeColor=#AE562C;perimeterSpacing=0;fontSize=12;spacingLeft=5;"
notes:
- "DASHED BURNT ORANGE border — this is the signature OCI VCN visual"
- "strokeWidth=2 (thicker than subnet)"
- "Text AND border are both #AE562C (burnt orange)"
- "NO fill — transparent background"
subnet:
# Toolkit item [198]: Physical - Grouping - Subnet
style: "whiteSpace=wrap;html=1;strokeWidth=1;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#AE562C;perimeterSpacing=0;strokeColor=#AE562C;fontSize=12;spacingLeft=5;"
notes:
- "DASHED BURNT ORANGE border — same color as VCN but THINNER (strokeWidth=1)"
- "Inside templates, subnet interior uses fillColor=#FCFBFA (near-white)"
- "Text is #AE562C (burnt orange)"
compartment:
# Toolkit item [199]: Physical - Grouping - Compartment
style: "whiteSpace=wrap;html=1;strokeWidth=1;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#312D2A;strokeColor=#9E9892;fontSize=12;spacingLeft=5;"
notes:
- "Same as tenancy style — dashed gray"
fault_domain:
# Toolkit item [204]
style: "whiteSpace=wrap;html=1;strokeWidth=1;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#312D2A;strokeColor=#9E9892;fontSize=12;spacingLeft=5;"
tier:
# Toolkit item [201]
style: "whiteSpace=wrap;html=1;strokeWidth=1;dashed=1;align=left;fontFamily=Oracle Sans;verticalAlign=top;fillColor=none;fontColor=#312D2A;strokeColor=#9E9892;fontSize=12;spacingLeft=5;"
# ============================================================
# SERVICE ICON COLORS
# ============================================================
service_colors:
oci_teal: "#2D5967"
oracle_copper: "#AA643B"
oracle_purple: "#804998"
burnt_orange: "#AE562C" # Used ONLY for VCN/Subnet borders and text — NOT for service icons
oracle_red: "#C74634" # Accent only
# ============================================================
# BACKGROUND AND TEXT COLORS
# ============================================================
backgrounds:
region_fill: "#F5F4F2" # Warm gray — region containers
ad_fill: "#DFDCD8" # Slightly darker — AD containers
subnet_fill: "#FCFBFA" # Near-white — subnet interiors in templates
dormant: "#DFDCD8" # Dormant/inactive elements
text:
primary: "#312D2A" # Charcoal — ALL text (never pure black)
secondary: "#70665E" # Medium gray — step circles, muted text
on_dark: "#FFFFFF" # White — text on colored service blocks
borders:
container: "#9E9892" # Warm gray — tenancy, region, compartment borders
vcn_subnet: "#AE562C" # Burnt orange — VCN and subnet borders ONLY
connector: "#312D2A" # Charcoal — ALL connection arrows (matches text color)
# ============================================================
# CONNECTOR STYLES (from toolkit items [206-214])
# ALL connectors use charcoal #312D2A — same as text color.
# Differentiation is via dash pattern, not color.
# ============================================================
connectors:
standard:
# Toolkit item [206]: Physical - Connector
style: "endArrow=open;endFill=0;strokeColor=#312D2A;strokeWidth=1;edgeStyle=orthogonalEdgeStyle;endSize=6;rounded=0"
notes:
- "Open arrow tip (not filled)"
- "Orthogonal routing (right-angle turns)"
- "endSize=6 for small consistent arrowheads"
- "Color is charcoal #312D2A — NOT gray"
fastconnect:
# Toolkit items [209-210]: Physical - Special Connectors - FastConnect
style: "endArrow=open;endFill=0;startArrow=open;startFill=0;strokeColor=#312D2A;strokeWidth=1;edgeStyle=orthogonalEdgeStyle;endSize=6;rounded=0"
notes:
- "Bidirectional open arrows"
- "Same charcoal color as standard"
- "In toolkit, has lightning/zigzag icon overlay — not reproducible in simple edges"
site_to_site_vpn:
# Toolkit items [211-212]
style: "endArrow=open;endFill=0;strokeColor=#312D2A;strokeWidth=1;dashed=1;edgeStyle=orthogonalEdgeStyle;endSize=6;rounded=0"
notes: "Dashed line with lock icon overlay"
remote_peering:
# Toolkit items [213-214]
style: "endArrow=open;endFill=0;strokeColor=#312D2A;strokeWidth=1;dashed=1;edgeStyle=orthogonalEdgeStyle;endSize=6;rounded=0"
notes: "Dashed line for inter-region connectivity"
# ============================================================
# TYPOGRAPHY
# ============================================================
typography:
font_family: "Oracle Sans"
fallback_fonts: "Segoe UI, Helvetica Neue, Arial, sans-serif"
container_labels: "fontSize=12, fontColor=#312D2A"
service_labels: "fontSize=8-9, fontColor=#FFFFFF (on colored background)"
title_text: "fontSize=10, fontColor=#70665E, fontStyle=2 (italic)"
# ============================================================
# KEY VISUAL RULES (from toolkit analysis)
# ============================================================
design_rules:
# Container rules (confirmed from OCI Toolkit v24.2 + 7 Oracle Architecture Center reference diagrams)
- "VCN and Subnet borders are ALWAYS dashed burnt orange (#AE562C) — this is the signature Oracle visual"
- "VCN border is strokeWidth=2, Subnet border is strokeWidth=1"
- "Region containers are the ONLY ones with solid background fill (#F5F4F2)"
- "Tenancy and Compartment containers are dashed gray, NO fill"
- "VCN and Subnet labels are BOLD, ORANGE (#AE562C), left-aligned inside the container (top-left)"
- "Subnet labels sometimes include CIDR notation below in smaller text (10pt gray)"
# Visual hygiene rules — observed from OCI Toolkit v24.2 reference
# diagrams + diagram best practices. Added 2026-04-25 after Diego
# flagged labels overlapping connectors and containers stacked
# without breathing room.
# Connector labels — verified from OCI Toolkit v24.2 slide 11 "Connector Labels":
# "Use connector labels to distinguish different types of logical connections and relationships."
# "Use 8pt font size and Bark color for label text."
# "Place connector labels on the horizontal portions of a line whenever possible."
# "Center connector labels on the connector line."
- "Connector labels are a PROPERTY of the connector edge, not a standalone text shape — set them on the connection's `label` field, not in a separate labels[] entry"
- "Connector label typography: fontSize=8 (raw points), fontColor=#312D2A (Bark), Oracle Sans"
- "Center the label on the connector — drawio's edge labels carve a small whitespace cutout in the line so text remains legible without a white background box"
- "Place labels on the HORIZONTAL portion of the line whenever possible (avoid placing on a vertical segment)"
- "Do NOT use a separate text shape and labelBackgroundColor=#FFFFFF — that's a workaround that breaks if the line moves"
- "Container minimum padding: 18px between an inner container's bottom edge and its parent's bottom edge (so nested borders don't visually merge)"
- "Container minimum padding: 12px between an inner container's top edge and the parent container's label baseline"
- "Vertical gap between sibling subnets inside a VCN: ≥20px (Oracle ref average)"
- "Service icons inside a subnet: ≥18px from the subnet top edge so the subnet label doesn't visually collide with the icon"
- "Two service icons in the same row: ≥30px horizontal gap (Oracle ref average)"
- "When two ADs span the same subnet horizontally, leave ≥25px gap between AD right and AD left so the subnet's vertical band reads as continuous"
# VCN/Subnet corner markers — clarification 2026-04-25
# Per OCI Toolkit v24.2 slide 18 ("Grouping"):
# "VCN, routing table, and security list icons are used at half size as
# labels to differentiate the VCN and subnet."
# OPTIONAL ("if they add clarity") but the documented standard. Many
# Architecture Center references omit them on simple diagrams; reference
# diagrams with multiple VCNs/subnets typically use them.
- "OPTIONAL: VCN containers may carry a half-size vcn_icon at the top-right corner"
- "OPTIONAL: Subnet containers may carry a half-size route_table_and_security_list icon at the top-right corner"
- "Authoring rule (absolute_layout): add as a service with type=route_table_and_security_list at (container.x + container.w - 24, container.y - 4) with w=h=22 for VCN, 18 for subnet"
- "DEFAULT: ONE marker per VCN, NOT per subnet. Six markers in a 2-region diagram is visual noise that competes with the data flow — the validator's EXCESSIVE_CORNER_MARKERS warns at ≥6"
- "Skip these markers on simple diagrams — they reduce clutter only when there is a single VCN/subnet"
# Connection edge ports — added 2026-04-25 after Diego flagged
# "colita / semicírculo al inicio de las flechas" caused by
# mismatched waypoints with explicit ports.
- "Use exit_x/exit_y/entry_x/entry_y on connections to disambiguate parallel edges from the same source (e.g. Local DG and Remote DG both leaving exa_primary)"
- "Distinct exit_y values: 0.4 vs 0.8 routes the two arrows on different horizontal bands"
- "When using explicit ports, DO NOT also pass waypoints — drawio auto-routes orthogonally between ports. Mismatched waypoints behind the exit port make drawio draw a curve-loop 'tail' at the source"
- "The renderer drops waypoints automatically when ports are explicit, with a stderr warning, but the spec author should not author both"
- "Auto-port detection in the renderer is also disabled when waypoints are present: if the spec author chose explicit waypoints, they own the route — adding auto-ports on top would re-introduce the curve-tail bug for every connection in the spec"
# Multi-cloud diagrams — added 2026-04-25 (Diego: "si usa AWS-branded
# cuando sea necesario claro, no solo ec2 tambien los demas componentes")
- "Multi-cloud diagrams: use the official provider stencil (AWS, GCP, Azure) for components that belong to that cloud — NOT an OCI stencil. Spec field: cloud_icon (e.g. cloud_icon: ec2, cloud_icon: rds, cloud_icon: s3). The renderer maps to mxgraph.aws4.* / mxgraph.gcp2.* via _aws_icon_style / _gcp_icon_style"
- "Available AWS keys: ec2, eks, ecs, lambda, rds, aurora, dynamodb, s3, elb, alb, cloudfront, vpc, direct_connect, route53, sqs, sns, kinesis, api_gateway, cognito, iam, cloudwatch, sagemaker, bedrock (see AWS_ICONS in tools/oci_diagram_gen.py — extend by adding entries to that table)"
- "Available GCP keys: gce, gke, cloud_sql, bigquery, cloud_storage, cloud_run, cloud_functions, pub_sub, cloud_dns, cloud_load_balancing, cloud_cdn, cloud_iam, cloud_armor, spanner, firestore, memorystore, ai_platform, vertex_ai, dataflow, dataproc, composer (GCP_ICONS table)"
- "Available Azure keys: vm, virtual_machine, vmss, aks, app_service, function, container_instance, sql_database, cosmos_db, blob_storage, data_lake, vnet, load_balancer, application_gateway, expressroute, vpn_gateway, azure_dns, front_door, key_vault, active_directory, sentinel, monitor, log_analytics, event_grid, service_bus, api_management, openai, ml_studio (AZURE_ICONS table — added 2026-04-25)"
# Multi-cloud CONTAINER styles (added 2026-04-25 — Diego: "vpc de aws
# por ejemplo no tiene una forma en particular?"):
- "Multi-cloud containers: spec a container with `cloud: aws|gcp|azure` plus the standard `type` field, and the renderer applies the cloud-native style (color, dash, font). Falls through to OCI style if no cloud match"
- "AWS container types: region, vpc, subnet, subnet_public, subnet_private, az — colors per AWS Architecture Icon Guidelines (#232F3E text, #8C4FFF VPC, #7AA116 public subnet, #00A4A6 private subnet)"
- "GCP container types: project, region, vpc, subnet — Google blue #4285F4, lighter #669DF6 for subnets"
- "Azure container types: subscription, region, vnet, subnet — Azure #0078D4 throughout, Segoe UI font"
- "When unsure, default to OCI stencil (type=...) rather than guessing a wrong AWS key — the visual is OCI-compatible and clearly distinguishable from native AWS shapes"
- "Visual-weight parity: AWS/GCP filled-square stencils render ~72% of the spec bbox so they match the visual weight of OCI line-art stencils at identical w/h. The renderer applies this scaling automatically when cloud_icon is set"
# CIDR conventions — added 2026-04-25 (Diego: "le agregaste cidr a la
# network y eso no lo pedi")
- "Do NOT add CIDR notation to subnet/VCN labels unless the user explicitly requested it. The label is just 'VCN', 'DB Subnet', etc. CIDRs are an implementation detail that clutters high-level architecture diagrams"
- "Same rule for IP addresses, port numbers, instance counts, SLA numbers — add only what the user asked for, nothing else"
# Service icon rules (confirmed from 7 Oracle Architecture Center reference diagrams)
- "Service icons are LINE ART / OUTLINE style in teal (#2D5967) — NOT filled colored rectangles"
- "Service icons do NOT have colored background boxes when rendered as OCI library stencils"
- "Service label is BELOW the icon, centered, in dark charcoal (#312D2A)"
- "Service label font size is 10-11pt (NOT 14pt) — confirmed from Oracle ref arch diagrams"
- "Total service block height (icon + label) should be ~90px for OCI services, not 45px"
# External cloud rules (confirmed from multicloud Oracle reference diagrams)
- "Azure containers use SOLID blue border (#0078D4) with light blue fill (#EBF5FF)"
- "Azure container labels are bold, dark blue (#0050A2)"
- "GCP containers use solid green border (#34A853) with light green fill (#E8F5E9)"
- "AWS/generic containers use dashed muted gray border (no specific Oracle style defined)"
# Oracle Services Network panel (confirmed from hub-spoke, OKE, lakehouse Oracle diagrams)
- "Oracle Services Network is a right-side dashed gray panel containing managed OCI services"
- "Services in Oracle Services Network are NOT in any VCN/Subnet — they float in the panel"
- "Use compartment-style container with oracle_services_network label for this panel"
- "OSN panel has NO fill (transparent) — dashed gray border only"
# Flow differentiation — Oracle uses line patterns, NOT numbered circles
- "Oracle differentiates flow types by DASH PATTERN, not numbered circle badges"
- "Ingest: dotted fine; Transform: dash-dot; Curate: fine dotted; Analyze: dashed"
- "Flow labels are text strings on the arrow path ('Process and store', 'Deploy model')"
- "A legend box at the bottom explains the line patterns if multiple flow types exist"
# Connector and typography rules
- "Service blocks use solid fills with NO stroke (strokeColor=none)"
- "Text is NEVER pure black — always charcoal #312D2A"
- "Font is Oracle Sans (falls back to Segoe UI)"
- "Icons are composite multi-layer Visio stencils in the OCI Library.xml"
- "ALL connectors use charcoal #312D2A — same as text, NOT colored"
- "Connectors use open arrow tips (endArrow=open, endFill=0) — never filled blocks"
- "Connectors use orthogonal routing (edgeStyle=orthogonalEdgeStyle) — never diagonal"
- "Arrow size is small and consistent (endSize=6)"
- "Dashed lines differentiate replication/migration from standard flows"
- "FastConnect is bidirectional (startArrow=open + endArrow=open)"
- "Oracle DB-related services use copper #AA643B"
- "Integration/messaging services use purple #804998"
- "All other OCI services use teal #2D5967"
reference_diagrams_analyzed:
# 7 Oracle Architecture Center diagrams analyzed visually (2026-03-17)
# Used to confirm and extend the style guide from OCI Toolkit v24.2
- url: "https://docs.oracle.com/en/solutions/exadb-dr-on-db-azure/img/exadb-dr-db-azure.png"
topology: "multi-region multi-cloud (ExaDB DR on Database@Azure)"
- url: "https://docs.oracle.com/en/solutions/hub-spoke-network-drg/img/hub-and-spoke-drg.png"
topology: "hub-spoke networking with DRG"
- url: "https://docs.oracle.com/en/solutions/data-platform-lakehouse/img/lakehouse-architecture.png"
topology: "data lakehouse (multi-tier, analytics)"
- url: "https://docs.oracle.com/en/solutions/deploy-oke-with-bastion-and-github/img/oke-bastion-deployment-diagram.png"
topology: "OKE with Bastion and GitHub Actions"
- url: "https://docs.oracle.com/en/solutions/cis-oci-benchmark/img/oci-core-landingzone.png"
topology: "CIS Landing Zone (complex, multi-compartment)"
- url: "https://docs.oracle.com/en/solutions/deploy-autonomous-database-db-at-azure/img/autonomous-database-db-azure-diagram.png"
topology: "ADB-S on Database@Azure (multi-cloud)"
- url: "https://docs.oracle.com/en/solutions/data-application-integration-workloads/img/integration-architecuture-pattern-1.png"
topology: "data integration pattern"
# ============================================================
# FULL ICON CATALOG (224 icons in OCI Library.xml)
# ============================================================
# See separate file for the full icon list.
# Key icons for Deal Accelerator:
# 37: Database - Autonomous DB
# 18: Networking - Load Balancer
# 32: Networking - Internet Gateway
# 33: Networking - NAT Gateway
# 31: Networking - Service Gateway
# 30: Networking - Dynamic Routing Gateway DRG
# 102: Identity and Security - WAF
# 105: Identity and Security - Vault
# 106: Identity and Security - Bastion
# 45: Database - Data Safe
# 46: Database - NoSQL
# 74: Developer Services - Container Engine for Kubernetes
# 2: Compute - Functions
# 3: Compute - Virtual Machine VM
# 65: Analytics and AI - Streaming
# 127: Observability and Management - Queuing
# 79: Developer Services - API Gateway
# 120: Observability and Management - Monitoring
# 123: Observability and Management - Logging Analytics
View Git Blame Copy Permalink