oci-deal-accelerator/docs/skill/output-formats.md

Output Formats and Conventions

Referenced from SKILL.md § Output Generation.

Output directory convention

All generated files MUST be saved inside a dedicated output folder per customer/initiative:

examples/output-<customer>-<initiative>/

Examples:

• examples/output-meli-im06/ — MELI MySQL engagement
• examples/output-meli-im30/ — MELI ElasticSearch engagement
• examples/output-acme-migration/ — ACME cloud migration

This folder contains ALL outputs for that engagement: .pptx, .drawio, .yaml specs, .pdf, scorecards. The folder is gitignored via examples/output-*/ — never commit customer data.

YAML spec files (architecture, workload-profile, diagram-spec) are saved IN the output folder, not loose in examples/. This keeps everything grouped and portable.

Format options

Default output is a slide deck (.pptx). The architect can specify:

Format	Output
deck (default)	10-12 slide presentation, with native OCI PowerPoint diagram when applicable
deck + drawio	+ editable architecture diagram
deck + doc	+ technical document (15-25 pages)
deck + xlsx	+ cost spreadsheet with formulas
deck + pdf	+ customer-facing PDF (branded, no internal refs)
pdf	Customer PDF only
full	Everything (pptx + drawio + docx + xlsx + pdf)
doc only	Technical document without slides
deliver	Handover + go-live checklist + success criteria

Slide deck structure

Slide count adapts to engagement tier (6-8 small, 10-12 standard, 12-16 complex):

1. Title — customer, project, date (dark background)
2. Value Story — business driver, hypothesis, desired outcomes
3. Service Tiering — workload-to-tier mapping (Platinum/Gold/Silver/Bronze) with SLA, RTO/RPO
4. Architecture Principles — selected ECAL principles (Design/Deployment/Service) that govern the architecture
5. Architecture Diagram — fills 85% of slide; prefer native OCI PowerPoint shapes inside the deck when the architecture is structured enough
6. Architecture Decisions — 4-6 key decisions with rationale
7. HA/DR — topology + RTO/RPO per tier
8. Security & Compliance — controls grid, compliance badges
9. Environment Catalogue — Prod/Pre-Prod/Dev-Test/DR per workload with sizing and isolation
10. Cost Estimate — PAYG vs BYOL table with assumptions (all environments)
11. Cost Comparison (optional) — vs current state or competitor
12. Migration Approach — phased timeline, tools, downtime strategy
13. Operational RACI — responsibility matrix (customer vs Oracle/partner)
14. Risk Register — severity-coded risk table
15. Well-Architected Scorecard — 5-pillar traffic-light indicators
16. Next Steps — concrete SMART actions with dates

Use tools/oci_deck_gen.py for generation. Decks should prefer native OCI PowerPoint diagrams over pasted images when the architecture can be rendered from structured input. Colors: teal #2D5967, copper #AA643B, purple #804998. Font: Segoe UI. Design standards: config/output-formats.yaml.

Architecture diagram

Use tools/oci_diagram_gen.py with OCI official styles from kb/diagram/oci-toolkit-styles.yaml when the user wants an editable technical diagram (.drawio). For customer-facing or presentation-ready output, prefer the native PowerPoint path via tools/oci_deck_gen.py and the PPTX icon library/index under kb/diagram/.

Standard diagram-generation procedure (MANDATORY)

Follow these steps for every diagram, in order. Skipping a step is the single most common source of layout regressions.

1. Reference architecture lookup. Run python tools/archcenter_pattern_lookup.py "<topology keywords>" against kb/architecture-center/catalog.yaml (123 entries). Pick the highest-scoring entry whose topology matches what the user asked for. The lookup surfaces cached .drawio / .svg under kb/diagram/assets/archcenter-refs/<slug>/ — open it to copy proven container nesting, padding, and AD/subnet placement instead of inventing geometry.
2. Pre-generation review (per SKILL.md § What You Do NOT Do). Confirm the component list with the user. Never add services the user did not mention except via the explicit auto-include whitelist.
3. Author the spec. Use absolute_layout for ref-arch reproductions or any topology where geometry matters. Honor the geometry rules below (the spec validator enforces them).
4. Spec validation runs automatically. Both tools/oci_diagram_gen.py (drawio) and tools/oci_pptx_diagram_gen.py (PPTX, called via oci_deck_gen.py) call tools/diagram_spec_validator.py before emitting any output. A fail status raises and aborts generation — fix the geometry, re-run.
5. Render. Generate the .drawio and/or .pptx. The drawio path additionally runs drawio_visual_validator.py post-render to catch anything the spec validator missed (font sizes, off-canvas, duplicate ids).
6. Visually verify. Rasterize the PPTX with python tools/oci_pptx_render.py --pptx X.pptx --output X.png --width 1600 and inspect the PNG before reporting success.

Geometry rules for absolute_layout

These rules are enforced by tools/diagram_spec_validator.py and exist because each one corresponds to a regression that previously shipped to the user:

• Container padding ≥ 12px. Every nested container must keep ≥12px between its bottom edge and its parent's bottom edge. Otherwise the borders visually merge (CONTAINER_PADDING_VIOLATION).
• Subnet height ≥ label band + 12px. A container labeled at 11pt needs h ≥ ~30px to avoid the label collapsing onto the bottom edge. Public-subnet bands holding an icon need to clear icon height + label band + breathing room (CONTAINER_TOO_THIN).
• Labels stay inside their parent, ≥ 6px from the bottom edge. Free-floating labels under a service icon must not cross or sit within 6px of the enclosing subnet's bottom edge (LABEL_OVERFLOW_PARENT).
• AD columns nest INSIDE the VCN, never beside it. Otherwise AD borders align with VCN borders and visually merge.
• Subnets may span AD columns (regional public subnet, cross-AD DB subnet) — that is the canonical Oracle pattern for HA topologies; do not split a regional subnet per AD.

Diagram modes

The diagram generator accepts two spec shapes — but only ONE is acceptable for any output an SA shows a customer:

1. absolute_layout (REQUIRED for any new diagram). Explicit (x, y, w, h) for every container, service, label, and connection. Resolves real OCI stencils from kb/diagram/oci-icons.json, runs through tools/diagram_spec_validator.py (geometry rules), and produces output visually consistent with Oracle Architecture Center references. This is the only mode the standard procedure supports. Pair it with the ref-arch lookup (tools/archcenter_pattern_lookup.py) so geometry derives from a canonical Oracle reference, not invented from scratch.
2. Workload-driven (DEPRECATED). tenancy → region(s) → vcn(s) → subnet(s) → service(s). The generator auto-lays out blocks but does NOT resolve OCI icon stencils — services render as colored rectangles with text labels, connector text gets baked into edge values (which the connector-label rule forbids), and the spec validator does NOT run. Output looks like a wireframe placeholder, not an architecture diagram. Kept only for back-compat with very old specs; do not author new specs in this shape.

absolute_layout:
  canvas: {width: 720, height: 420}
  containers:
    - {id: region, type: region, label: "OCI Region", x: 0, y: 0, w: 720, h: 420}
    - {id: vcn, type: vcn, label: "VCN 10.10.0.0/16", x: 28, y: 52, w: 670, h: 348}
  services:
    - {id: drg,  label: "", type: drg,  x: 8, y: 200, w: 55, h: 66}
    - {id: adb,  label: "", type: adb_d, x: 230, y: 240, w: 60, h: 80}
  labels:
    - {id: lbl_drg, text: "DRG", x: 8, y: 268, w: 55, h: 14, fontSize: 700}
  connections:
    - {id: c1, from: drg, to: adb, type: standard, points: [[63, 233], [260, 240]]}

fontSize is shared with the PPTX absolute_layout schema — it's hundredths of a point (720 → 7.2pt). The drawio renderer auto-converts.

The Architecture Center reconstruction pipeline lives at tools/archcenter_case_runner.py (single case) and tools/archcenter_batch_driver.py (batch). Reference: kb/diagram/reference-layouts/archcenter-batch-runner.yaml.

Pre-delivery validation (automatic)

Both generators run sanity checks before the file ships, so a broken artifact never reaches the user:

• tools/diagram_spec_validator.py — runs automatically before either renderer (drawio or PPTX). Validates the parsed absolute_layout for CONTAINER_TOO_THIN, CONTAINER_PADDING_VIOLATION, and LABEL_OVERFLOW_PARENT. A fail aborts generation. Set OCI_DIAGRAM_VALIDATOR_SOFT=1 to demote errors to warnings.
• tools/drawio_visual_validator.py — runs automatically inside OCIDiagramGenerator.save(). Hard-fails on fontSize ≥ 50pt (catches the PPTX-cents-of-pt → drawio-pt unit confusion that produced 700pt labels), duplicate cell ids, off-canvas geometry, and dangling edge endpoints. Reports OK/warnings/errors to stderr. Pass --strict on the CLI to make errors fail the build.
• OCIDeckGenerator.save() post-check — verifies [Content_Types].xml declares a <Default> for every embedded media extension (PowerPoint refuses to open a deck and prompts to "repair" it when this is missing — the SVG-backed icons in OCI_Icons.pptx are the canonical case), and that no slide rels point to absent media or duplicate cNvPr ids.
• tools/drawio_fidelity_eval.py — pixel-diff the rebuilt drawio against a canonical Architecture Center PNG. Runs automatically when the spec carries source.diagram_asset (or via --reference-png on the CLI). Default rendering path is the SVG companion via cairosvg (works in any environment); the rebuilt-drawio path through the actual draw.io binary is opt-in via the DRAWIO_EXE env var (the binary is not bundled with the skill — install on demand).

CLI usage:

# Standard run (validators on by default)
python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio

# Fail the build if validator finds errors
python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio --strict

# Fidelity comparison vs canonical PNG
python tools/oci_diagram_gen.py --spec my-spec.yaml --output out.drawio \
   --reference-png kb/diagram/reference-layouts/.../canonical.png

# Strict draw.io binary path (opt-in)
DRAWIO_EXE=/usr/bin/drawio python tools/oci_diagram_gen.py --spec ... --reference-png ...

Skip validators only when intentionally generating a fixture or test: --no-validate.

Service categorization

Category	Color	Use
Infrastructure	Teal #2D5967	Compute, OKE, LB, Gateways, WAF, Bastion, Storage, Monitoring
Database	Copper #AA643B	ADB-S/D, DBCS, ExaCS, MySQL, PostgreSQL, NoSQL, GoldenGate
Integration	Purple #804998	DRG, Streaming, Queue, OIC, FastConnect, Service Connector Hub
Dormant	Light gray #DFDCD8	Standby/inactive resources (DR tier)
Legacy	Medium gray #70665E	Non-OCI systems (MQ Series, legacy middleware)