WTP Suitability Engine — Vision
Platform hub: docs.wealthtechpros.com — the Firm-of-the-Future architecture this product slots into.
Source repo: github.com/WealthTechPros/suitability-engine
This repo is the standalone SUITABILITY-ENGINE capability, extracted from
client-onboarding
per SPEC-152
(client-onboarding/docs/features/152-origo-suitability-engine-extraction.md).
Read SPEC-152 in full before changing anything architectural — it is the
ratified design record for this repo’s existence, scope boundary, auth
model, and deployment topology; this Vision restates the parts of it that
belong at this repo’s own Layer 0, it does not replace it.
Provenance.
SUITABILITY-ENGINEwas a capability ofclient-onboarding(domainCORE-ENGINE) until SPEC-152 and client-onboarding#2669 moved its implementation here.client-onboardingremains the data owner and the capability’s other consumer (client-portal) is unaffected — only where the engine code and its governance artefacts live has changed.
Why this repo exists
Section titled “Why this repo exists”client-onboarding proved the suitability-report pipeline (Data Assembler →
Recommendation Rules → Template Engine → Readiness/Lineage) as an embedded,
pure-TypeScript module with no React/Next.js coupling. Origo, an external
adviser-tech vendor, wants to consume that same engine as a standalone
service rather than build their own suitability-report generator. Rather
than let an external partner depend on code living inside a Next.js app
repo, SPEC-152 ratified extracting it to its own repo, its own release
lifecycle, and (per SPEC-152’s 2026-08-16 amendment) a self-hosted-first
deployment model.
What good looks like (outcomes, not outputs)
Section titled “What good looks like (outcomes, not outputs)”- The four-stage pipeline produces a suitability report (JSON and/or rendered DOCX/PDF) that is genuinely per-client and per-tenant derived — not a hardcoded stand-in for one tenant’s fixed data.
- Every derived field carries a
DerivationAuditRecord(rule ID, inputs read, value set) and every report generation event is durably auditable — regulatory traceability travels with the output, not just the code. - The engine deploys identically whether WTP hosts it (SaaS) or Origo hosts it (self-hosted, licence-gated) — one release artifact, no drift between what WTP runs and what a partner runs.
client-onboardingand any external partner consume the same versioned contract — no partner-specific fork of the pipeline.
MVP — for the Origo pilot
Section titled “MVP — for the Origo pilot”The minimum surface needed for Origo to self-host this engine against a
real (non-Benchmark) tenant’s data via client-onboarding’s internal
read-API, with the traceability hard-blocker closed and a durable audit
trail. Per SPEC-152’s 2026-08-16 amendment, Option D (self-hosted,
Origo-operated container) is the pilot path, not WTP-hosted SaaS.
Non-goals
Section titled “Non-goals”- Owning suitability advice logic or regulatory judgement — this engine renders and derives from data using WTP-authored, WTP-versioned rules; it does not decide what advice is suitable.
- Any rendered end-client UI. Presentation is
client-portal’s job (internal) or Origo’s own build (external). - Owning client data. This repo never queries the warehouse directly — it
calls
client-onboarding’s internal read-API. - Letting a self-hosted deployer modify rule-engine logic. Template customisation is fair game for a self-hosted operator; regulatory traceability requires the rules themselves stay WTP-controlled and WTP-versioned even off WTP’s own infra.
- The
suitability-cohort/readiness triage layer used internally by WTP/Benchmark operations — explicitly out of scope per SPEC-152’s scope boundary.
Architecture — the four-stage pipeline
Section titled “Architecture — the four-stage pipeline”| Stage | Path | Status |
|---|---|---|
| Data Assembler | src/data-client/ | Typed HTTP client shell against client-onboarding’s internal read-API — not yet a working integration (blocked on client-onboarding#2670) |
| Recommendation Rules | src/suitability-rules/ | Moved as-is (SPEC-113) |
| Template Engine | src/suitability-template/ | Moved as-is (SPEC-108/109/110/121) |
| Readiness / Lineage | src/suitability-readiness/ | Moved as-is (SPEC-122/127/133) |
See SPEC-001 for the full as-built baseline and known gaps, and SPEC-152-Q5 for the self-hosted licence-gating mechanism.
Status
Section titled “Status”Scaffold, actively building. Blocks client-onboarding#2516 (the client-onboarding-side refactor to consume this service once it’s real). Depends on client-onboarding#2670 (internal read-API) before the Data Assembler stage does anything but throw.