@jterrats/open-orchestra 1.0.1 → 1.0.3

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.