Assist_Design/docs/development/portal/integration-overview.md

# Portal Integration Overview — Salesforce + WHMCS

This document explains how the portal integrates Salesforce (catalog, orders, provisioning control) and WHMCS (billing, invoices, subscriptions, payments). It covers the main flows end‑to‑end, what checks occur, and where the logic lives in code.

## System Overview

- Components
  - Frontend: Next.js portal (`apps/portal`)
  - Backend (BFF): NestJS (`apps/bff`), orchestrates Salesforce + WHMCS
  - Billing: WHMCS (invoices, payment methods, subscriptions)
  - CRM/Control Plane: Salesforce (catalog via Product2, Orders, provisioning trigger)
  - Infra: PostgreSQL (mappings), Redis (cache), BullMQ (queues)

- Sources of truth
  - Salesforce: Product catalog, Pricebook pricing, Orders, provisioning status and tracking
  - WHMCS: Customer profile, payment methods, subscriptions, invoices
  - BFF: Orchestration + ID mappings only; no customer data authority

- Key environment flags (validation schema)
  - `SF_EVENTS_ENABLED`, `SF_PROVISION_EVENT_CHANNEL`, `SF_*` for Salesforce; `WHMCS_*` for WHMCS; `PORTAL_PRICEBOOK_ID/PORTAL_PRICEBOOK_NAME` for catalog/pricing. See env sample for full list (env/portal-backend.env.sample:1).

## Identity & Mapping

- Purpose: link a portal user to a WHMCS client and Salesforce Account.
- Persistence: `idMapping` table via `MappingsService` (apps/bff/src/mappings/mappings.service.ts:1).
- Lookups
  - By user → WHMCS client ID (apps/bff/src/mappings/mappings.service.ts:148)
  - By Salesforce Account → WHMCS client ID (apps/bff/src/mappings/mappings.service.ts:63)
- Usage: Most flows start by resolving mapping to enforce access and route calls correctly (e.g., invoices, orders).

## Catalog (Shown in Portal)

- Source of truth: Salesforce Product2 + PricebookEntry.
- Field mapping is configurable via env (apps/bff/src/common/config/field-map.ts:1). Important fields include:
  - `Product2.StockKeepingUnit` (SKU), portal visibility flags, `Item_Class__c`, billing cycle, and WHMCS product id/name.
- Base query helper uses a “Portal” pricebook (ID or name) and builds SOQL with visible/accessible filters (apps/bff/src/catalog/services/base-catalog.service.ts:1).
- SIM catalog example: returns plans, activation fees, add‑ons; optionally personalizes based on existing WHMCS services (apps/bff/src/catalog/services/sim-catalog.service.ts:1).
- Principle: Frontend selects explicit SKUs; backend validates SKUs exist in the portal pricebook and creates Salesforce OrderItems accordingly. See docs/PRODUCT-CATALOG-ARCHITECTURE.md:1.

## Invoices & Payments

- Endpoints: `GET /invoices`, `GET /invoices/:id`, `GET /invoices/:id/subscriptions`, `POST /invoices/:id/sso-link`, `POST /invoices/:id/payment-link` (apps/bff/src/invoices/invoices.controller.ts:1).
- Service flow: resolve mapping → fetch from WHMCS via `WhmcsService` → transform/cache → return (apps/bff/src/invoices/invoices.service.ts:24).
  - List/paginate via WHMCS GetInvoices; details enriched with line items and `serviceId` links (apps/bff/src/integrations/whmcs/services/whmcs-invoice.service.ts:1).
  - Subscriptions listed via WHMCS GetClientsProducts; transformed and cached (apps/bff/src/integrations/whmcs/services/whmcs-subscription.service.ts:1).
  - Payment methods/gateways via WHMCS; cached in Redis; also used for gating order creation/provisioning (apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:1).
- SSO links: invoice view/download/pay and payment-page with preselected method/gateway (apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:168).

## Orders — Creation (Portal ➝ Salesforce)

- Entry point: `OrderOrchestrator.createOrder()` (apps/bff/src/orders/services/order-orchestrator.service.ts:36).
- Steps
  1. Validate request, user mapping, and business rules via `OrderValidator.validateCompleteOrder()` (apps/bff/src/orders/services/order-validator.service.ts:296):
     - Format: `orderType`, non‑empty `skus[]` (apps/bff/src/orders/services/order-validator.service.ts:24)
     - Mapping present: user ↔ WHMCS client ↔ SF Account (apps/bff/src/orders/services/order-validator.service.ts:79)
     - Payment method exists in WHMCS (gating) (apps/bff/src/orders/services/order-validator.service.ts:96)
     - SKU existence in portal pricebook (apps/bff/src/orders/services/order-validator.service.ts:197)
     - Business rules by type (SIM, VPN, Internet) e.g. SIM requires activation fee (apps/bff/src/orders/services/order-validator.service.ts:225)
     - Internet duplication guard: one active Internet service per account (apps/bff/src/orders/services/order-validator.service.ts:166)
  2. Build Order header fields including activation fields and address snapshot (apps/bff/src/orders/services/order-builder.service.ts:22)
     - Address snapshot always sets BillTo\* fields; sets `Address_Changed__c` if user supplied a different address at checkout (apps/bff/src/orders/services/order-builder.service.ts:88)
  3. Create Salesforce Order and then OrderItems by SKU using the pricebook entry and unit price (apps/bff/src/orders/services/order-item-builder.service.ts:20)
- Result: Returns `sfOrderId` with status Created for operator review/approval in Salesforce.

## Orders — Provisioning (Salesforce ➝ WHMCS)

- Trigger: Salesforce publishes a Platform Event (record‑triggered flow) on approval. The BFF subscriber listens when `SF_EVENTS_ENABLED=true` and enqueues provisioning (apps/bff/src/vendors/salesforce/events/pubsub.subscriber.ts:58).
- Queue: BullMQ `provisioning` queue with idempotent job IDs (apps/bff/src/orders/queue/provisioning.queue.ts:1).
- Processor guardrails (apps/bff/src/orders/queue/provisioning.processor.ts:26):
  - Only process when Order `Activation_Status__c` is `Activating` (apps/bff/src/orders/queue/provisioning.processor.ts:35)
  - Skip if last error is `PAYMENT_METHOD_MISSING` to avoid thrash (apps/bff/src/orders/queue/provisioning.processor.ts:52)
  - Commit Salesforce Pub/Sub replay IDs for exactly‑once handling (apps/bff/src/orders/queue/provisioning.processor.ts:73)
- Orchestration steps (apps/bff/src/orders/services/order-fulfillment-orchestrator.service.ts:57):
  - Validate request: not already provisioned (checks `WHMCS_Order_ID__c`), ensure client has payment method; resolve mapping (apps/bff/src/orders/services/order-fulfillment-validator.service.ts:23)
  - Set SF activation status to `Activating` (apps/bff/src/orders/services/order-fulfillment-orchestrator.service.ts:98)
  - Load SF Order details + OrderItems, map each to WHMCS items using the Product2 mapping (`WH_Product_ID__c`) and billing cycle (apps/bff/src/orders/services/order-whmcs-mapper.service.ts:1)
  - Create WHMCS order (AddOrder) with Stripe as payment method; optional promo code and tracking notes (apps/bff/src/integrations/whmcs/services/whmcs-order.service.ts:20)
  - Accept/provision order (AcceptOrder), capture service IDs and invoice ID returned (apps/bff/src/integrations/whmcs/services/whmcs-order.service.ts:60)
  - Update SF: `Status=Completed`, `Activation_Status__c=Activated`, and write back `WHMCS_Order_ID__c` (apps/bff/src/orders/services/order-fulfillment-orchestrator.service.ts:117)
- Error handling: On failure, set `Status=Pending Review`, `Activation_Status__c=Failed`, and write concise error code/message for operator triage (apps/bff/src/orders/services/order-fulfillment-orchestrator.service.ts:146).

## Subscriptions (Shown in Portal)

- Data comes from WHMCS products/services via `GetClientsProducts` and is transformed into a standard Subscription list (apps/bff/src/integrations/whmcs/services/whmcs-subscription.service.ts:1).
- Cached per user; supports status filtering; invoice items link to `serviceId` to show related subscriptions (apps/bff/src/integrations/whmcs/transformers/whmcs-data.transformer.ts:35).

## Payments & SSO

- Payment methods summary drives UI gating and provisioning validation (apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:44).
- SSO flows
  - General WHMCS SSO (dashboard/settings) via `CreateSsoToken`
  - Invoice view/download/pay SSO (apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:168)
  - Payment link with pre‑selected saved method or gateway (apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:168)

## Caching & Performance

- Redis cache is used for: invoices (lists and by ID), subscriptions, payment methods, payment gateways, user mappings (apps/bff/src/common/cache/cache.service.ts:1).
- Cache invalidation helpers exist per domain (e.g., `invalidatePaymentMethodsCache`, `invalidateInvoiceCache`).
- HTTP pagination/limits enforced in controller input validation for invoices (apps/bff/src/invoices/invoices.controller.ts:1).

## Field Map (Configurable)

- All SF field API names are env‑driven and wrapped by `getSalesforceFieldMap()` (apps/bff/src/common/config/field-map.ts:1).
- Key paths used in flows
  - Order activation: type/scheduledAt/status
  - WHMCS IDs: `Order.WHMCS_Order_ID__c`, `OrderItem.WHMCS_Service_ID__c`
  - Address snapshot: BillingStreet/City/State/Postal/Country + `Address_Changed__c`

## Environment & Health

- Env validation schema lists required/optional vars and sensible defaults (apps/bff/src/common/config/env.validation.ts:1). Sample file provides production-ready defaults (env/portal-backend.env.sample:1).
- Health endpoints expose DB/queue/feature flags and Salesforce events status (apps/bff/src/health/health.controller.ts:1).

## End‑to‑End Flow Summary

1. User links account at signup; mapping stored. Adds payment method in WHMCS via SSO.
2. Portal shows catalog from Salesforce Product2 + Pricebook. User selects options; frontend builds explicit SKUs.
3. `POST /orders` triggers validation (mapping, payment method exists, SKUs exist, business rules) → creates SF Order + OrderItems with address snapshot.
4. Operator approves in Salesforce; Platform Event published.
5. BFF subscriber enqueues provisioning; worker validates, maps items to WHMCS, creates/accepts WHMCS order, and updates Salesforce with status/IDs.
6. Portal pages show subscriptions and invoices from WHMCS with SSO links for payment.

## Key Checks & Guards

- Payment method required before order creation and before provisioning.
- SKU validity in pricebook; missing UnitPrice is a hard error.
- Business rules per order type (SIM requires activation fee, etc.).
- Internet duplication guard to prevent multiple active Internet services.
- Idempotency: If `WHMCS_Order_ID__c` is set, fulfillment short‑circuits as already provisioned.
- Queue processor only acts in `Activating` state; skips when awaiting user‑actionable errors.

## Where to Look in Code

- Order creation orchestration: apps/bff/src/orders/services/order-orchestrator.service.ts:36
- Validation (format/mapping/PM/SKUs/rules): apps/bff/src/orders/services/order-validator.service.ts:24
- Order header + address snapshot: apps/bff/src/orders/services/order-builder.service.ts:22
- OrderItems from SKUs: apps/bff/src/orders/services/order-item-builder.service.ts:20
- Fulfillment orchestration: apps/bff/src/orders/services/order-fulfillment-orchestrator.service.ts:57
- Salesforce events subscriber: apps/bff/src/vendors/salesforce/events/pubsub.subscriber.ts:58
- Provisioning queue processor: apps/bff/src/orders/queue/provisioning.processor.ts:26
- Invoices service: apps/bff/src/invoices/invoices.service.ts:24
- Subscriptions service: apps/bff/src/integrations/whmcs/services/whmcs-subscription.service.ts:1
- Payment/SSO service: apps/bff/src/integrations/whmcs/services/whmcs-payment.service.ts:1

---

For deeper details, see:

- docs/PORTAL-ORDERING-PROVISIONING.md
- docs/ORDER-FULFILLMENT-COMPLETE-GUIDE.md
- docs/PRODUCT-CATALOG-ARCHITECTURE.md
- docs/ADDRESS_SYSTEM.md