@jterrats/open-orchestra 1.0.2 → 1.0.4

package/docs/diagrams/payment-gateway/architecture.md

@@ -0,0 +1,57 @@
+# Payment Gateway Architecture
+
+Task: ARCH-PAYMENT-GATEWAY-DIAGRAM
+
+## Source Mode
+
+`source-free`
+
+No visual source reference was provided. This diagram is validated against its
+own architecture contract and the current diagram quality rules.
+
+## Architecture Contract
+
+- Audience: architect, security, developer, QA, and release reviewers.
+- Required systems:
+  - Web interface for merchants, admins, and customers.
+  - APIs / middleware layer for payment orchestration.
+  - Payment gateway core service.
+  - Transaction database.
+  - Security layer.
+- Added supporting elements:
+  - Identity provider for authentication.
+  - WAF / API gateway for edge protection.
+  - Token vault / KMS for card tokenization and key management.
+  - Fraud/risk engine for transaction scoring.
+  - Audit log / monitoring for compliance and operations.
+  - External payment processor / card network.
+- Required relationships:
+  - Users access the web interface through edge security.
+  - Web interface calls APIs through the API gateway.
+  - Middleware orchestrates payment requests and routes them to the payment
+    gateway core.
+  - Gateway core stores transaction state in the database.
+  - Gateway core tokenizes sensitive payment data through token vault / KMS.
+  - Gateway core requests fraud/risk scoring before authorization.
+  - Gateway core sends authorization/capture/refund messages to the external
+    processor.
+  - Middleware and gateway core emit audit and operational events.
+- Visual requirements:
+  - Security controls are visually distinct and readable.
+  - API/middleware and core payment responsibilities are separated.
+  - Connectors are orthogonal, visibly attached, and do not cover text.
+  - Parent containers leave visible padding around child nodes.
+  - Empty whitespace is intentional and supports scan order.
+
+## Validation Notes
+
+- All requested systems are present.
+- The security layer is shown as a distinct trust/control band.
+- Connector labels sit in whitespace or on readable label backgrounds.
+- The first render was reviewed and adjusted for label lanes and connector
+  endpoint clarity before acceptance.
+- Preview `output/diagram-experiments/payment-gateway/preview-v6.png` is the
+  current visual candidate for review after applying prompt v14. The pass moved
+  competing labels into separate lanes, split and repositioned the long
+  application note, terminated `user traffic` at the Security Edge boundary, and
+  resized Security Controls so Audit / Monitoring remains fully contained.

package/docs/diagrams/payment-gateway/architecture.mmd

@@ -0,0 +1,39 @@
+flowchart LR
+  users["Users\nMerchants / Admins / Customers"]
+
+  subgraph edge["Security Edge"]
+    waf["WAF / API Gateway\nTLS, throttling, threat rules"]
+    idp["Identity Provider\nOIDC / MFA / service auth"]
+  end
+
+  subgraph app["Application Layer"]
+    web["Web Interface\ncheckout, admin, merchant portal"]
+    middleware["APIs / Middleware\norchestration, idempotency, routing"]
+    core["Payment Gateway Core\nauthorize, capture, refund"]
+  end
+
+  subgraph security["Security Controls"]
+    vault["Token Vault / KMS\ntokenization, keys, secrets"]
+    fraud["Fraud / Risk Engine\nscoring, rules, velocity checks"]
+    audit["Audit Log / Monitoring\nPCI evidence, traces, alerts"]
+  end
+
+  subgraph data["Data Layer"]
+    db["Transaction Database\norders, payments, ledger state"]
+  end
+
+  processor["External Processor / Card Network\nauthorization, settlement"]
+
+  users -->|"browser / API traffic"| waf
+  waf -->|"validated traffic"| web
+  waf -->|"API requests"| middleware
+  idp -->|"tokens / claims"| waf
+  web -->|"checkout + admin calls"| middleware
+  middleware -->|"payment commands"| core
+  core <-->|"transaction state"| db
+  core <-->|"tokenize / detokenize"| vault
+  core -->|"risk scoring"| fraud
+  fraud -->|"score + decision"| core
+  core <-->|"auth / capture / refund"| processor
+  middleware -->|"events + metrics"| audit
+  core -->|"payment events"| audit

package/docs/diagrams/payment-gateway/architecture.svg

@@ -0,0 +1,171 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1440" height="900" viewBox="0 0 1440 900" role="img" aria-labelledby="title desc">
+  <title id="title">Payment gateway architecture</title>
+  <desc id="desc">Architecture diagram showing users, security edge, web interface, APIs and middleware, payment gateway core, database, token vault, fraud engine, audit monitoring, and external processor.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M0 0 L10 5 L0 10 z" fill="#475569"/>
+    </marker>
+    <marker id="arrow-start" viewBox="0 0 10 10" refX="1" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M10 0 L0 5 L10 10 z" fill="#475569"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}
+      .title{font-size:28px;font-weight:700;fill:#172033}
+      .subtitle{font-size:13px;fill:#4b596c}
+      .boundary{fill:#f7fafc;stroke:#94a3b8;stroke-width:1.5}
+      .edgeBoundary{fill:#f3f8ff;stroke:#89a9d8;stroke-width:1.5}
+      .appBoundary{fill:#f8fbf7;stroke:#93bd9b;stroke-width:1.5}
+      .securityBoundary{fill:#fff7ed;stroke:#e7b274;stroke-width:1.5}
+      .dataBoundary{fill:#f8f5ff;stroke:#b7a5e8;stroke-width:1.5}
+      .externalBoundary{fill:#fff8f8;stroke:#dda2a2;stroke-width:1.5}
+      .label{font-size:13px;font-weight:700;fill:#526174;text-transform:uppercase}
+      .card{fill:#fff;stroke:#64748b;stroke-width:1.5}
+      .cardTitle{font-size:17px;font-weight:700;fill:#1f2a3d}
+      .cardSub{font-size:12px;fill:#445267}
+      .badge{font-size:11px;font-weight:700;fill:#fff}
+      .edge{fill:none;stroke:#475569;stroke-width:2;marker-end:url(#arrow)}
+      .edgeBoth{fill:none;stroke:#475569;stroke-width:2;marker-start:url(#arrow-start);marker-end:url(#arrow)}
+      .labelBg{fill:#fff;stroke:#d8dee8;stroke-width:1}
+      .edgeLabel{font-size:12px;fill:#263445}
+      .note{font-size:12px;fill:#506074}
+    </style>
+  </defs>
+  <rect width="1440" height="900" fill="#ffffff"/>
+  <g class="font">
+    <text class="title" x="56" y="58">Payment Gateway Architecture</text>
+    <text class="subtitle" x="56" y="82">Source-free architecture candidate generated for visual validation.</text>
+
+    <rect class="card" x="56" y="362" width="166" height="100" rx="12"/>
+    <circle cx="88" cy="396" r="17" fill="#334155"/>
+    <text class="badge" x="88" y="400" text-anchor="middle">U</text>
+    <text class="cardTitle" x="118" y="392">Users</text>
+    <text class="cardSub" x="78" y="424">Merchants / admins</text>
+    <text class="cardSub" x="78" y="444">customers</text>
+
+    <rect class="edgeBoundary" x="274" y="170" width="254" height="484" rx="18"/>
+    <text class="label" x="304" y="204">Security Edge</text>
+    <rect class="card" x="314" y="256" width="174" height="104" rx="12"/>
+    <circle cx="346" cy="290" r="17" fill="#2563eb"/>
+    <text class="badge" x="346" y="294" text-anchor="middle">GW</text>
+    <text class="cardTitle" x="374" y="286">WAF / API</text>
+    <text class="cardTitle" x="374" y="306">Gateway</text>
+    <text class="cardSub" x="336" y="334">TLS, throttling</text>
+    <text class="cardSub" x="336" y="352">threat rules</text>
+
+    <rect class="card" x="314" y="456" width="174" height="104" rx="12"/>
+    <circle cx="346" cy="490" r="17" fill="#4f46e5"/>
+    <text class="badge" x="346" y="494" text-anchor="middle">ID</text>
+    <text class="cardTitle" x="374" y="486">Identity</text>
+    <text class="cardTitle" x="374" y="506">Provider</text>
+    <text class="cardSub" x="336" y="534">OIDC / MFA</text>
+    <text class="cardSub" x="336" y="552">service auth</text>
+
+    <rect class="appBoundary" x="584" y="118" width="404" height="620" rx="18"/>
+    <text class="label" x="616" y="152">Application Layer</text>
+    <rect class="card" x="632" y="214" width="206" height="112" rx="12"/>
+    <circle cx="664" cy="248" r="17" fill="#059669"/>
+    <text class="badge" x="664" y="252" text-anchor="middle">WEB</text>
+    <text class="cardTitle" x="696" y="244">Web Interface</text>
+    <text class="cardSub" x="658" y="278">checkout, admin</text>
+    <text class="cardSub" x="658" y="298">merchant portal</text>
+
+    <rect class="card" x="632" y="394" width="206" height="118" rx="12"/>
+    <circle cx="664" cy="428" r="17" fill="#0f766e"/>
+    <text class="badge" x="664" y="432" text-anchor="middle">API</text>
+    <text class="cardTitle" x="696" y="424">APIs / Middleware</text>
+    <text class="cardSub" x="658" y="460">orchestration</text>
+    <text class="cardSub" x="658" y="480">idempotency + routing</text>
+
+    <rect class="card" x="632" y="586" width="206" height="112" rx="12"/>
+    <circle cx="664" cy="620" r="17" fill="#0ea5e9"/>
+    <text class="badge" x="664" y="624" text-anchor="middle">PAY</text>
+    <text class="cardTitle" x="696" y="616">Gateway Core</text>
+    <text class="cardSub" x="658" y="650">authorize, capture</text>
+    <text class="cardSub" x="658" y="670">refund</text>
+
+    <rect class="securityBoundary" x="1038" y="118" width="326" height="482" rx="18"/>
+    <text class="label" x="1070" y="152">Security Controls</text>
+    <rect class="card" x="1086" y="210" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="242" r="17" fill="#d97706"/>
+    <text class="badge" x="1118" y="246" text-anchor="middle">KMS</text>
+    <text class="cardTitle" x="1150" y="238">Token Vault / KMS</text>
+    <text class="cardSub" x="1110" y="272">tokenization, keys</text>
+    <text class="cardSub" x="1110" y="290">secrets</text>
+
+    <rect class="card" x="1086" y="348" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="380" r="17" fill="#dc2626"/>
+    <text class="badge" x="1118" y="384" text-anchor="middle">FR</text>
+    <text class="cardTitle" x="1150" y="376">Fraud / Risk</text>
+    <text class="cardTitle" x="1150" y="396">Engine</text>
+    <text class="cardSub" x="1110" y="424">scoring + rules</text>
+
+    <rect class="card" x="1086" y="486" width="228" height="92" rx="12"/>
+    <circle cx="1118" cy="518" r="17" fill="#7c3aed"/>
+    <text class="badge" x="1118" y="522" text-anchor="middle">AUD</text>
+    <text class="cardTitle" x="1150" y="514">Audit / Monitoring</text>
+    <text class="cardSub" x="1110" y="548">PCI evidence</text>
+    <text class="cardSub" x="1110" y="566">traces + alerts</text>
+
+    <rect class="dataBoundary" x="1038" y="620" width="326" height="160" rx="18"/>
+    <text class="label" x="1070" y="654">Data Layer</text>
+    <rect class="card" x="1086" y="680" width="228" height="78" rx="12"/>
+    <circle cx="1118" cy="712" r="17" fill="#6d28d9"/>
+    <text class="badge" x="1118" y="716" text-anchor="middle">DB</text>
+    <text class="cardTitle" x="1150" y="708">Transaction DB</text>
+    <text class="cardSub" x="1110" y="738">orders, payments, ledger</text>
+
+    <rect class="externalBoundary" x="1020" y="812" width="360" height="60" rx="18"/>
+    <text class="label" x="1048" y="848">External Processor / Card Network</text>
+
+    <path class="edge" d="M222 412 H274"/>
+    <rect class="labelBg" x="224" y="388" width="86" height="20" rx="4"/>
+    <text class="edgeLabel" x="232" y="402">user traffic</text>
+
+    <path class="edge" d="M488 308 H632"/>
+    <rect class="labelBg" x="518" y="284" width="106" height="20" rx="4"/>
+    <text class="edgeLabel" x="526" y="298">validated UI</text>
+
+    <path class="edge" d="M488 326 H560 Q584 326 584 453 H632"/>
+    <rect class="labelBg" x="510" y="350" width="86" height="20" rx="4"/>
+    <text class="edgeLabel" x="518" y="364">API calls</text>
+
+    <path class="edge" d="M401 456 V360"/>
+    <rect class="labelBg" x="414" y="400" width="90" height="20" rx="4"/>
+    <text class="edgeLabel" x="422" y="414">auth claims</text>
+
+    <path class="edge" d="M735 326 V394"/>
+    <rect class="labelBg" x="752" y="350" width="116" height="20" rx="4"/>
+    <text class="edgeLabel" x="760" y="364">checkout calls</text>
+
+    <path class="edge" d="M735 512 V586"/>
+    <rect class="labelBg" x="752" y="540" width="136" height="20" rx="4"/>
+    <text class="edgeLabel" x="760" y="554">payment command</text>
+
+    <path class="edgeBoth" d="M838 686 H960 Q1000 686 1000 718 H1086"/>
+    <rect class="labelBg" x="906" y="706" width="126" height="20" rx="4"/>
+    <text class="edgeLabel" x="914" y="720">transaction state</text>
+
+    <path class="edgeBoth" d="M838 620 H930 Q958 620 958 256 H1086"/>
+    <rect class="labelBg" x="850" y="586" width="130" height="20" rx="4"/>
+    <text class="edgeLabel" x="858" y="600">token operations</text>
+
+    <path class="edge" d="M838 648 H966 Q1000 648 1000 394 H1086"/>
+    <rect class="labelBg" x="908" y="366" width="88" height="20" rx="4"/>
+    <text class="edgeLabel" x="916" y="380">risk score</text>
+
+    <path class="edge" d="M838 666 H944 Q982 666 982 532 H1086"/>
+    <rect class="labelBg" x="986" y="556" width="110" height="20" rx="4"/>
+    <text class="edgeLabel" x="994" y="570">payment events</text>
+
+    <path class="edge" d="M838 453 H1010 Q1038 453 1038 532 H1086"/>
+    <rect class="labelBg" x="852" y="460" width="104" height="20" rx="4"/>
+    <text class="edgeLabel" x="860" y="474">API metrics</text>
+
+    <path class="edgeBoth" d="M735 698 V838 H1020"/>
+    <rect class="labelBg" x="782" y="816" width="168" height="20" rx="4"/>
+    <text class="edgeLabel" x="790" y="830">auth / capture / refund</text>
+
+    <text class="note" x="752" y="754">Application responsibilities are separated</text>
+    <text class="note" x="752" y="772">from security controls and persistent state.</text>
+  </g>
+</svg>

package/docs/diagrams/prompt-bank.md

@@ -0,0 +1,48 @@
+# Diagram Prompt Bank
+
+Use this index to decide which diagram-generation prompt assets should feed the
+master prompt and which should remain only as experiment history.
+
+## Keep In Prompt Bank
+
+- `diagram-master-prompt.md`: canonical source-free prompt for diagram
+  generation, target selection, layout reflow, connector routing, validation,
+  evidence, and final artifact hygiene.
+- `mermaid-target-strategy.md`: target-selection guidance for when Mermaid is
+  acceptable and when draw.io/Lucid-style editable geometry is needed.
+- `v14-stress-test/README.md` and `v14-stress-test/stress-test.svg`: source-free
+  validation fixture for checking whether the prompt rules catch bounded text,
+  label lanes, containment, and connector route problems.
+
+## Keep As Visual Examples, Not Prompt Rules
+
+- `enterprise-set/*.svg`: source-free diagram candidates useful for visual QA
+  practice. Do not copy their business labels into the master prompt.
+- `payment-gateway/*`: architecture example useful for visual regression checks.
+  Do not promote payment-domain wording into the master prompt.
+- `salesforce-integration/*`: architecture example useful for target-format
+  comparison. Do not promote platform-specific wording into the master prompt.
+
+## Keep As Experiment Archive Only
+
+- `state-uml-recreated.prompt.md` through `state-uml-recreated.prompt.v11.md`:
+  historical deltas from a specific recreation exercise. Extract only generic
+  rules already represented in v12/v14.
+- `state-uml-recreated.prompt.v12.md` and `state-uml-recreated.prompt.v14.md`:
+  reusable deltas that have been consolidated into `diagram-master-prompt.md`.
+  Keep them only as provenance until the master prompt is accepted.
+- `experiments/**/experiment.md` and `source-fidelity-review.md`: these contain
+  downloaded-source observations and PDF/page-specific analysis. Keep them for
+  traceability, but exclude their source text from the prompt bank.
+- `experiments/**/*.mmd` and `experiments/**/*.svg`: rendered experiment outputs.
+  Useful for manual comparison, not for master-prompt wording.
+
+## Promotion Criteria
+
+- Promote only rules that are domain-agnostic and apply to any diagram type.
+- Exclude source text, platform names, business labels, PDF wording, and
+  one-off coordinates from reusable prompt guidance.
+- A prompt-bank candidate must include a validation rule, not only a drawing
+  instruction.
+- If two regenerated versions preserve the same visual error, the rule is not
+  strong enough. Add a geometry-change requirement before keeping it.

package/docs/diagrams/salesforce-integration/architecture.md

@@ -0,0 +1,56 @@
+# Salesforce Integration Architecture
+
+Task: ARCH-SALESFORCE-INTEGRATION-DIAGRAM
+
+## Source Mode
+
+`source-free`
+
+No visual source reference was provided. The diagram is validated against this
+contract rather than against a source screenshot.
+
+## Architecture Contract
+
+- Audience: architect and delivery team reviewing integration boundaries.
+- Systems:
+  - Experience Cloud as the user-facing portal.
+  - Salesforce Core as CRM and business process system of record.
+  - MuleSoft as API orchestration and integration broker.
+  - Data 360 as customer data unification and profile/segment layer.
+  - S3 bucket as file repository/object storage.
+  - Payment Gateway as external payment processor.
+- Required relationships:
+  - Users access Experience Cloud.
+  - Experience Cloud invokes Salesforce services for portal workflows.
+  - Salesforce publishes and consumes APIs through MuleSoft.
+  - MuleSoft coordinates payment calls with the payment gateway.
+  - MuleSoft coordinates file upload/download metadata and object operations
+    with S3.
+  - Salesforce and Data 360 exchange customer/profile data.
+  - MuleSoft can feed integration events into Data 360 when needed.
+- Visual requirements:
+  - Clear trust/system boundaries.
+  - Orthogonal connectors with arrowheads on target edges.
+  - No text overflow.
+  - Composite containers grow around their child nodes with visible padding.
+  - External services are visually distinct from Salesforce platform services.
+
+## Architect Result
+
+The Architect decision recorded through Orchestra:
+
+> Use a layered integration architecture with Salesforce core, Experience Cloud
+> frontend, MuleSoft integration layer, Data 360 data layer, S3 file repository,
+> and payment gateway external service.
+
+## Validation Notes
+
+- All requested systems are present.
+- Salesforce platform services are grouped together.
+- External services are grouped separately.
+- MuleSoft sits between Salesforce and external dependencies.
+- Connectors are orthogonal and terminate at visible target edges.
+- Parent containers have padding around child nodes and labels.
+- The rendered SVG was reflowed after label placement so connector labels sit in
+  clear lanes and parent containers still contain their children after sizing
+  changes.

package/docs/diagrams/salesforce-integration/architecture.mmd

@@ -0,0 +1,26 @@
+flowchart LR
+  user[External Users]
+
+  subgraph sf["Salesforce Platform Boundary"]
+    exp["Experience Cloud\nPortal / Self-Service"]
+    core["Salesforce Core\nCRM + Business Processes"]
+    d360["Data 360\nUnified Profiles + Segments"]
+  end
+
+  subgraph integration["Integration Layer"]
+    mulesoft["MuleSoft\nAPI Orchestration"]
+  end
+
+  subgraph external["External Services"]
+    s3["Amazon S3 Bucket\nFile Repository"]
+    pay["Payment Gateway\nPayments + Status"]
+  end
+
+  user -->|"portal access"| exp
+  exp -->|"authenticated workflows"| core
+  core <-->|"customer/profile sync"| d360
+  core <-->|"system APIs + events"| mulesoft
+  mulesoft <-->|"file metadata + object ops"| s3
+  mulesoft <-->|"payment auth/capture/status"| pay
+  mulesoft -->|"integration events"| d360
+

package/docs/diagrams/salesforce-integration/architecture.svg

@@ -0,0 +1,123 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="760" viewBox="0 0 1280 760" role="img" aria-labelledby="title desc">
+  <title id="title">Salesforce integration architecture</title>
+  <desc id="desc">Architecture diagram showing Experience Cloud, Salesforce Core, Data 360, MuleSoft, S3 file repository, and payment gateway relationships.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M0 0 L10 5 L0 10 z" fill="#526174"/>
+    </marker>
+    <marker id="arrow-start" viewBox="0 0 10 10" refX="1" refY="5" markerWidth="8" markerHeight="8" orient="auto">
+      <path d="M10 0 L0 5 L10 10 z" fill="#526174"/>
+    </marker>
+    <style>
+      .font{font-family:Arial,Helvetica,sans-serif}
+      .title{font-size:26px;font-weight:700;fill:#172033}
+      .subtitle{font-size:13px;fill:#4b596c}
+      .boundary{fill:#f3f7ff;stroke:#9fb4d8;stroke-width:1.5}
+      .boundaryExternal{fill:#f7faf8;stroke:#9bc3aa;stroke-width:1.5}
+      .boundaryIntegration{fill:#fff7ed;stroke:#e7b274;stroke-width:1.5}
+      .label{font-size:13px;font-weight:700;fill:#526174;text-transform:uppercase}
+      .card{fill:#fff;stroke:#6f7e92;stroke-width:1.5}
+      .cardTitle{font-size:17px;font-weight:700;fill:#1f2a3d}
+      .cardSub{font-size:12px;fill:#445267}
+      .badge{font-size:11px;font-weight:700;fill:#fff}
+      .edge{fill:none;stroke:#526174;stroke-width:2;marker-end:url(#arrow)}
+      .edgeBoth{fill:none;stroke:#526174;stroke-width:2;marker-start:url(#arrow-start);marker-end:url(#arrow)}
+      .edgeSoft{fill:none;stroke:#6b7b8f;stroke-width:1.8;stroke-dasharray:7 5;marker-end:url(#arrow)}
+      .labelBg{fill:#fff;stroke:#d8dee8;stroke-width:1}
+      .edgeLabel{font-size:12px;fill:#2f3a4c}
+      .note{font-size:12px;fill:#506074}
+    </style>
+  </defs>
+  <rect width="1280" height="760" fill="#ffffff"/>
+  <g class="font">
+    <text class="title" x="56" y="58">Salesforce Integration Architecture</text>
+    <text class="subtitle" x="56" y="82">Source-free architecture candidate generated from the Orchestra Architect handoff.</text>
+
+    <rect class="card" x="56" y="332" width="150" height="86" rx="12"/>
+    <circle cx="86" cy="362" r="16" fill="#334155"/>
+    <text class="badge" x="86" y="366" text-anchor="middle">U</text>
+    <text class="cardTitle" x="116" y="358">Users</text>
+    <text class="cardSub" x="76" y="386">Customers / partners</text>
+    <text class="cardSub" x="76" y="404">self-service access</text>
+
+    <rect class="boundary" x="250" y="132" width="468" height="560" rx="18"/>
+    <text class="label" x="278" y="166">Salesforce Platform Boundary</text>
+
+    <rect class="card" x="292" y="214" width="210" height="112" rx="12"/>
+    <circle cx="324" cy="246" r="17" fill="#0f65d8"/>
+    <text class="badge" x="324" y="250" text-anchor="middle">EC</text>
+    <text class="cardTitle" x="356" y="242">Experience Cloud</text>
+    <text class="cardSub" x="320" y="276">Portal workflows</text>
+    <text class="cardSub" x="320" y="296">authentication surface</text>
+
+    <rect class="card" x="292" y="424" width="210" height="120" rx="12"/>
+    <circle cx="324" cy="456" r="17" fill="#1798c1"/>
+    <text class="badge" x="324" y="460" text-anchor="middle">SF</text>
+    <text class="cardTitle" x="356" y="452">Salesforce Core</text>
+    <text class="cardSub" x="320" y="488">CRM records</text>
+    <text class="cardSub" x="320" y="508">business processes</text>
+
+    <rect class="card" x="532" y="424" width="150" height="120" rx="12"/>
+    <circle cx="564" cy="456" r="17" fill="#6952ff"/>
+    <text class="badge" x="564" y="460" text-anchor="middle">D3</text>
+    <text class="cardTitle" x="596" y="452">Data 360</text>
+    <text class="cardSub" x="556" y="488">Unified profiles</text>
+    <text class="cardSub" x="556" y="508">segments + signals</text>
+
+    <rect class="boundaryIntegration" x="784" y="318" width="212" height="242" rx="18"/>
+    <text class="label" x="812" y="352">Integration Layer</text>
+    <rect class="card" x="824" y="426" width="132" height="92" rx="12"/>
+    <circle cx="856" cy="456" r="17" fill="#00a1df"/>
+    <text class="badge" x="856" y="460" text-anchor="middle">M</text>
+    <text class="cardTitle" x="884" y="452">MuleSoft</text>
+    <text class="cardSub" x="846" y="482">API orchestration</text>
+    <text class="cardSub" x="846" y="500">events + routing</text>
+
+    <rect class="boundaryExternal" x="1028" y="174" width="220" height="392" rx="18"/>
+    <text class="label" x="1060" y="208">External Services</text>
+
+    <rect class="card" x="1060" y="252" width="156" height="92" rx="12"/>
+    <circle cx="1104" cy="284" r="17" fill="#e87912"/>
+    <text class="badge" x="1104" y="288" text-anchor="middle">S3</text>
+    <text class="cardTitle" x="1132" y="280">S3 Bucket</text>
+    <text class="cardSub" x="1098" y="314">file repository</text>
+    <text class="cardSub" x="1098" y="332">object storage</text>
+
+    <rect class="card" x="1060" y="418" width="156" height="102" rx="12"/>
+    <circle cx="1104" cy="450" r="17" fill="#0f766e"/>
+    <text class="badge" x="1104" y="454" text-anchor="middle">PG</text>
+    <text class="cardTitle" x="1132" y="444">Payment</text>
+    <text class="cardTitle" x="1132" y="464">Gateway</text>
+    <text class="cardSub" x="1098" y="494">payment auth</text>
+    <text class="cardSub" x="1098" y="512">status callbacks</text>
+
+    <path class="edge" d="M206 375 H292"/>
+    <text class="edgeLabel" x="222" y="362">portal access</text>
+
+    <path class="edge" d="M385 326 V424"/>
+    <text class="edgeLabel" x="404" y="378">workflow services</text>
+
+    <path class="edgeBoth" d="M502 484 H532"/>
+    <rect class="labelBg" x="510" y="550" width="130" height="20" rx="4"/>
+    <text class="edgeLabel" x="518" y="564">customer/profile sync</text>
+
+    <path class="edgeBoth" d="M682 484 H824"/>
+    <rect class="labelBg" x="702" y="456" width="108" height="20" rx="4"/>
+    <text class="edgeLabel" x="710" y="470">integration events</text>
+
+    <path class="edgeBoth" d="M397 544 V586 H756 Q784 586 784 494 H824"/>
+    <rect class="labelBg" x="560" y="592" width="126" height="20" rx="4"/>
+    <text class="edgeLabel" x="568" y="606">system APIs + events</text>
+
+    <path class="edgeBoth" d="M956 456 H1014 Q1028 456 1028 298 H1060"/>
+    <rect class="labelBg" x="928" y="390" width="96" height="20" rx="4"/>
+    <text class="edgeLabel" x="936" y="404">file/object ops</text>
+
+    <path class="edgeBoth" d="M956 486 H1060"/>
+    <rect class="labelBg" x="970" y="500" width="82" height="20" rx="4"/>
+    <text class="edgeLabel" x="978" y="514">payment API</text>
+
+    <text class="note" x="258" y="668">Composite platform container is sized around child services with visible padding.</text>
+    <text class="note" x="806" y="578">MuleSoft centralizes API policy and routing.</text>
+  </g>
+</svg>

package/docs/diagrams/source-fidelity-review.md

@@ -0,0 +1,116 @@
+# Source Fidelity Review
+
+Task: DIAGRAM-SOURCE-FIDELITY-REVIEW
+Date: 2026-05-16
+
+## Clarification
+
+The first diagram experiment batch produced type examples and findings. Those
+outputs were reviewed for nonblank rendering, text fit, and broad structure.
+They were not accepted as pixel-perfect recreations.
+
+For future work, any task labeled as `recreation` must be evaluated pixel-perfect
+against the source reference. Similar structure is not sufficient.
+
+## Required Recreation Workflow
+
+1. Classify the task:
+   - `semantic`: explain the concept.
+   - `inspired-by-reference`: reuse visual ideas without fidelity acceptance.
+   - `recreation`: reproduce the source.
+2. For `recreation`, extract the source region first. Ignore browser chrome,
+   page headers, footers, and download-site UI unless they are explicitly part
+   of the requested diagram.
+3. Build a source inventory:
+   - page/canvas size and aspect ratio.
+   - every container and nested container.
+   - all text, including line breaks, rotation, alignment, size, and approximate color.
+   - every connector, endpoint, arrowhead, bend point, line style, and label.
+   - icons, badges, legend entries, borders, fills, shadows, and z-order.
+4. Render the output.
+5. Compare source versus output by element or visual region.
+6. Correct and re-render until gaps are closed or explicitly documented.
+7. If the target cannot support required fidelity, reclassify the deliverable as
+   approximation and escalate to draw.io/Lucid for the authoritative artifact.
+
+## Required Source-Free Workflow
+
+Diagrams without a source reference are not exempt from visual precision. They
+must be pixel-perfect against their own declared contract before handoff.
+
+1. Define the contract before drawing: canvas size, diagram type, groups, nodes,
+   labels, relationships, reading flow, expected connector endpoints, and layout
+   constraints.
+2. Render the diagram.
+3. Inspect the render, not only the source file:
+   - text fits inside every container.
+   - containers are not too small or visually unbalanced.
+   - connector endpoints visibly touch the intended source and target edges.
+   - arrowheads are visible and not hidden behind shapes.
+   - lines do not cross labels, important symbols, or containers unless explicitly
+     justified.
+   - labels have clearance from borders, connectors, and arrowheads.
+   - whitespace is intentional and does not make the layout feel broken.
+4. Correct and re-render before delivery.
+5. Record residual issues if a diagram is accepted as an approximation.
+
+## Findings From Current Experiments
+
+### Swimlane
+
+Current output is structurally similar but not pixel-perfect:
+
+- header icons are approximated with text symbols.
+- lane header colors and body colors are close but not measured from source.
+- node positions and connector bends are simplified.
+- source legend and typography are not fully recreated.
+
+Target recommendation for recreation: draw.io or SVG with measured coordinates.
+Mermaid recommendation: semantic swimlane only.
+
+### Technology Roadmap
+
+Current output is a representative roadmap, not a source-accurate recreation:
+
+- card sizes, shadows, and exact month grid positions differ.
+- icon badges are simplified.
+- source legend shape and title band are approximated.
+- typography and card spacing were manually adjusted for readability, not exact fidelity.
+
+Target recommendation for recreation: draw.io/SVG with extracted source metrics.
+Mermaid recommendation: `gantt` semantic schedule.
+
+### Timeline Infographic
+
+The downloaded PDF contains web page chrome. Current output intentionally uses
+only the visible infographic idea and is not a recreation:
+
+- source region extraction was not performed.
+- exact colors, icons, and preview card details were not recreated.
+- layout was normalized into a clean six-step diagram.
+
+Target recommendation for recreation: first extract the actual infographic image
+region, then recreate in draw.io/SVG. Mermaid recommendation: `timeline` semantic
+milestones.
+
+### Layered Implementation Architecture
+
+Current output is an abstraction, not a pixel-perfect recreation:
+
+- many source micro-icons and vendor badges were collapsed.
+- layer rail labels and system cards were simplified.
+- connector count and routing are reduced.
+- dense source labels were omitted to preserve readability.
+
+Target recommendation for recreation: draw.io/Lucid with density budget and
+source inventory. Mermaid recommendation: semantic layer/component map only.
+
+## Rule Candidates
+
+- `recreation` requires pixel-perfect review.
+- `inspired-by-reference` must not be described as recreation.
+- PDF/web captures require source-region extraction before diagram authoring.
+- Mermaid outputs must be labeled semantic unless exact layout is not acceptance criteria.
+- Every recreation needs a source-vs-output gap table before handoff.
+- Source-free diagrams need a contract-vs-output gap table before handoff when
+  any visual issue remains.