Skip to main content

ADR-019: PSX-to-SaaS BestEx Integration

Status​

Proposed

Context​

The PowerSeller ecosystem has two products that perform pricing analysis:

  • PowerSeller X — evaluates loans against anonymous PSX buyers' rate sheets (Python/FastAPI, 8-phase stacking engine)
  • PSSaaS — evaluates loans against the lender's own investor relationships and delivery commitments (.NET 8, 24-step BestEx engine)

Today these operate independently. A principal (e.g., Watermark TPO) must run separate analyses in separate systems to answer the fundamental question: "What's the best path for this loan — agency delivery, PSX sale, or bulk sale?"

Integrating the two would enable a unified best-path comparison within PSX, giving principals a complete picture without switching between systems.

Decision​

Allow PowerSeller X to call the PSSaaS BestEx API as a service-to-service integration. PSX acts as an API client of PSSaaS, sending loan data and receiving BestEx analysis results.

Authentication​

  • Use OAuth2 client credentials grant (machine-to-machine) for service-to-service authentication
  • PSX registers as an API client in the PSSaaS identity provider
  • The client credential includes a tenant claim that identifies which principal's BestEx configuration to use
  • No user context needed — PSX acts on behalf of the principal's organization

Tenant Resolution​

  • Each principal on PSX maps to a tenant in PSSaaS
  • PSX includes the principal's PSSaaS tenant identifier in the API request (via JWT claim or header)
  • PSSaaS resolves the tenant's database and BestEx profiles from this identifier
  • A principal must have an active PSSaaS subscription to use this integration

Data Contract​

PSX uses a normalized loan schema (~33 MISMO-aligned fields). PSSaaS uses the legacy loan table (157 columns). Rather than forcing either side to adopt the other's schema:

  • PSSaaS exposes a dedicated integration endpoint that accepts a simplified loan payload (the ~20 fields BestEx actually needs)
  • PSX maps its NormalizedLoan to this simplified format before calling
  • The integration endpoint writes loans to a temporary analysis table, runs BestEx, and returns results — without persisting loans in the tenant's loan table

API Design​

POST /api/bestex/integration/analyze

Request:

{
  "profileName": "default",
  "loans": [
    {
      "loanId": "EX-12345",
      "loanAmount": 350000.00,
      "noteRate": 6.750,
      "instrumentName": "FNMA 30yr Fixed",
      "state": "CA",
      "lockExpirationDate": "2026-04-15",
      "closeDate": "2026-03-20",
      "creditScore": 740,
      "ltv": 75.000,
      "cltv": 75.000,
      "purposeCode": "Purchase",
      "occupancyCode": "PrimaryResidence",
      "propertyType": "SFR",
      "amortType": "Fixed",
      "numOfUnits": 1,
      "productCode": "CONV30"
    }
  ]
}

Response:

{
  "runDate": "2026-03-17T14:30:00Z",
  "loansProcessed": 1,
  "scenariosGenerated": 12,
  "errorCount": 0,
  "results": [
    {
      "loanId": "EX-12345",
      "rank": 1,
      "investorId": "FNMA",
      "investorInstrumentName": "FNMA 30 FXD",
      "totalPrice": 101.250000,
      "profitPrice": 1.250000,
      "profitAmount": 4375.00,
      "pricingWindowInDays": 30,
      "lockWindowInDays": 30,
      "servicingType": "sell"
    }
  ],
  "errors": []
}

Consequences​

Positive​

  • Unified best-path analysis — principals compare agency delivery, PSX sale, and bulk sale in one view
  • No data duplication — loans aren't permanently stored in PSSaaS; analysis runs against temporary data
  • Leverages existing engine — the full 24-step BestEx pipeline runs without modification
  • Revenue opportunity — the integration becomes a premium feature of PowerSeller X, creating cross-sell between products
  • API-first validation — proves the BestEx API works for external consumers, not just the PSSaaS frontend

Negative​

  • Cross-system dependency — PSX availability now partially depends on PSSaaS availability
  • Latency — network round-trip between PSX and PSSaaS adds latency to the principal's analysis flow
  • Principal onboarding — each principal who wants this feature needs BestEx profiles configured in PSSaaS (investor mappings, pricing data, delivery windows)
  • Schema mapping maintenance — changes to either loan schema require updating the mapping

Neutral​

  • The integration is optional — principals who don't have PSSaaS subscriptions continue using PSX-only analysis
  • The simplified loan payload is a subset of both schemas — it can be extended as needed without breaking changes