How Origo Integrates — End-to-End Architecture

Ref: suitability-engine-arch-1 · Capability: SUITABILITY-ENGINE · Status: draft Repo: suitability-engine

Ties together SPEC-152 (extraction), the licence-gating mechanism, the multi-tenant template fix, and the two UX specs into one integration picture. Each linked doc is the source of truth for its own area; this page is the map, not a restatement.

1. Topology

┌─────────────────────────────────────────────────────────────────────┐
│ Origo's own infrastructure (self-hosted, SPEC-152 Option D)         │
│                                                                       │
│  ┌───────────────────┐        ┌──────────────────────────────────┐ │
│  │ Origo adviser UI   │        │ suitability-engine container      │ │
│  │ (their own build,  │───────▶│ - licenced at startup (offline,   │ │
│  │  SPEC-005 design)  │  HTTP  │   Ed25519, docs/features/002)     │ │
│  └───────────────────┘        │ - per-tenant template store        │ │
│  ┌───────────────────┐        │   (TEMPLATE_STORE_DIR volume,      │ │
│  │ Origo client UI    │        │   docs/features/003)               │ │
│  │ (their own build,  │───────▶│ - POST .../suitability/export      │ │
│  │  SPEC-004 design)  │  HTTP  │   ?format=json|docx                │ │
│  └───────────────────┘        └────────────────┬───────────────────┘ │
└─────────────────────────────────────────────────┼─────────────────────┘
                                                     │ HTTPS, API-key-with-
                                                     │ scopes (Origo-facing
                                                     │ external contract)
                                                     ▼
                                     ┌───────────────────────────────┐
                                     │ client-onboarding              │
                                     │ internal read-API (WTP-        │
                                     │ operated) — the ONLY thing     │
                                     │ that ever crosses back to WTP  │
                                     │ infra. No client data at rest  │
                                     │ in the suitability-engine      │
                                     │ container itself.              │
                                     └───────────────────────────────┘

The load-bearing design fact: even in self-hosted mode, the extracted engine has no data store of its own — it calls back to client-onboarding’s internal read-API for the client data it needs, every time (docs/external/origo-suitability-and-adviser-api-design.md §2.3 / §4 in client-onboarding). Self-hosting relocates where the engine process runs, not where the system of record lives. This is why Origo’s own client data never has to be declared to Origo’s own clients as passing through WTP — but it also means the container has a hard runtime dependency on that read-API being reachable.

2. Sequence — generating and reviewing a report

1. Startup: the container verifies its licence (offline, Ed25519 — docs/features/002) and refuses to boot if invalid/expired. No WTP network call at any point.
2. Data fetch: on a request, the engine calls client-onboarding’s internal read-API (GET /api/internal/v1/suitability-data/{token}) over the network, authenticated by a shared-secret bearer token distinct from every other auth layer in this picture.
3. Derivation: the four-stage pipeline (Data Assembler → Recommendation Rules → Template Engine → Readiness/Lineage) runs, producing SuitabilityData + a DerivationAuditRecord.
4. Adviser review (Origo-built, SPEC-005): an adviser reviews the field-level derivation audit before the report goes to the client. Not built or hosted by WTP.
5. Client view (Origo-built from SPEC-004’s reference implementation, or their own equivalent): the client reviews the report section-by-section; each section view is recorded, gating an acceptance action. The audit trail for this step is Origo’s own responsibility, server-side — see SPEC-004 §2.2.
6. Document export: format=docx renders against Origo’s own registered template (suitability-engine#6, fixed 2026-08-16) if a branded document (not just the web view) is needed.

3. Auth layers — five distinct credentials, do not conflate

Layer	Credential	Who holds it	Scope
Container licence	Ed25519-signed licence file	Origo (issued by WTP)	Gates whether the process runs at all
Origo → engine (per-request)	SUITABILITY_ENGINE_SERVER_TOKEN shared secret, or future API-key-with-scopes	Origo’s own back end	Gates calls to the export endpoint
Engine → client-onboarding	SUITABILITY_ENGINE_INTERNAL_TOKEN shared secret	WTP-operated, baked into deploy config	The one call that crosses back to WTP infra
Origo adviser session	Origo’s own	Origo	Entirely outside this engine’s scope
Origo client session	Origo’s own	Origo	Entirely outside this engine’s scope

4. Known gaps in this picture (do not treat as solved)

These are cross-referenced from their owning docs, collected here because they compound — a partner evaluating “can I actually launch on this” needs the full list in one place, not scattered:

• No template upload API — a template is placed on disk + config today, not self-serve. (003 §“Deliberately not solved here”)
• No PDF export — format=pdf is 501, only docx works. (003)
• No remote licence revocation — expiry-only, by design. (002)
• suitabilityReasons narrative content has no home in the data contract — the client view’s “Why This is Suitable” section is a simplification of client-onboarding’s real page. (004 §2.4)
• No genuine per-field confidence scoring — only a categorical, template-level sourceClass, not joined to a specific client’s derived audit. (005 §3)
• Bidirectional CRM/Adviser API (SPEC-153) is separate and far less mature than the Suitability Engine — see client-onboarding’s docs/features/153-origo-adviser-crm-api.md. This document is Suitability-Engine-only.

5. What WTP ships vs. what Origo builds — summary

	WTP ships	Origo builds
Suitability Engine container	✅ (this repo)	—
Licence issuance	✅ (scripts/sign-licence.mjs, WTP-run)	—
Client-facing report UI	Spec + reference implementation	Production build
Adviser review UI	Spec + wireframe only	Everything
Their own auth/session/audit infra	—	✅ entirely