Assist_Design/docs/PORTAL-FLOW.md

Portal Ordering & Provisioning – Flow

This document explains the end-to-end customer and operator flow, systems involved, and the request/response choreography. For data model and field-level details, see PORTAL-DATA-MODEL.md.

Architecture at a Glance

• Salesforce: Product2 + PricebookEntry (catalog & eligibility), Order/OrderItem (review/trigger), reporting
• WHMCS: customer profile (authoritative), payment methods, invoices, subscriptions, provisioning
• Portal BFF: orchestration and ID mappings; centralized logging (dino)

Customer Flow

1. Signup

• Inputs: email, confirm email, password, confirm password, first/last name, optional company/phone, Customer Number (SF Number)
• Actions: create portal user, create WHMCS client with Customer Number custom field, create mapping (userId ↔ whmcsClientId ↔ sfAccountId)
• Email: Welcome (customer, CC support)

2. Add payment method (required)

• UI: CTA opens WHMCS payment methods via SSO
• API: BFF checks hasPaymentMethod via WHMCS GetPayMethods; gate checkout until true

3. Browse catalog and configure

• BFF serves Product2 catalog (portal-visible only), with personalization for Internet based on Account eligibility fields
• Product detail collects configurable options

4. Checkout (create Order)

• BFF: POST /orders → create Salesforce Order (Pending Review) + OrderItems (snapshots: Quantity, UnitPrice, Billing_Cycle, optional ConfigOptions)
• Portal shows “Awaiting review”

5. Review & Provision (operator)

• Operator approves in Salesforce and clicks “Provision in WHMCS” (Quick Action)
• Salesforce calls BFF POST /orders/{sfOrderId}/provision (signed & idempotent)
• BFF:
  • Re-check hasPaymentMethod in WHMCS; if missing, set SF status Failed (Payment Required)
  • eSIM: activate if applicable
  • WHMCS: AddOrder → AcceptOrder
  • Update Salesforce Order with WHMCS IDs and status (Provisioned or Failed)
  • Emails: Activation/Provisioned

5a) Immediate vs Scheduled activation (eSIM example)

• Ops selects Activation Type on the Order:
  • Immediate: BFF runs activation and WHMCS order right after approval.
  • Scheduled: set Activation_Scheduled_At__c; BFF runs at that time.
• BFF enqueues delayed jobs:
  • Preflight (e.g., T-3 days): verify WHMCS payment method; notify if missing.
  • Execute (at scheduled date): set Activation status → Activating; run eSIM activation; on success run WHMCS AddOrder → AcceptOrder; write back IDs and set Activation → Activated; on error set Activation → Failed and log error fields.
• Manual override “Activate Now” can trigger the same execute path immediately.

Scheduling options

• Option A: Salesforce Flow (no portal job)
  • Record-Triggered Flow on Order with a Scheduled Path at Activation_Scheduled_At__c when Status = Approved, Activation_Type__c = Scheduled, Activation_Status__c = Not Started.
  • Action: Flow HTTP Callout (Named Credential) → POST /orders/{sfOrderId}/provision with headers Idempotency-Key, X-Timestamp, X-Nonce.
  • Alternative: Scheduled-Triggered Flow (every 15m) querying due Orders (NOW() ≥ Activation_Scheduled_At__c) and invoking the same callout.
• Option B: Portal BFF delayed jobs (BullMQ)
  • Use when you want retry/backoff control and consolidated observability in BFF.

Status interaction (business vs technical)

• Order Status: Pending Review → Approved → (Completed/Cancelled).
• Activation Status: Not Started → Activating → Activated/Failed.
• UI: Show Activation fields only when Order Status is Approved/Completed.

6. Completion

• Subscriptions and invoices show in portal from WHMCS via BFF endpoints
• Order status in portal reflects Salesforce status

API Surface (BFF)

• Auth: POST /auth/signup (requires sfNumber = Customer Number)
• Billing: GET /billing/payment-methods/summary, POST /auth/sso-link
• Catalog: GET /catalog, GET /catalog/personalized
• Orders: POST /orders, GET /orders/:sfOrderId, POST /orders/:sfOrderId/provision
• eSIM actions: POST /subscriptions/:id/reissue-esim, POST /subscriptions/:id/topup

Security & Reliability

• Salesforce → BFF: Named Credentials + HMAC headers; IP allowlisting; 5m TTL; Idempotency-Key
• WHMCS: timeouts, retries, circuit breakers; redact sensitive data in logs
• Idempotency: checkout keyed by cart hash; provisioning keyed by Idempotency-Key; include sfOrderId in WHMCS notes
• Observability: correlation IDs, metrics, alerts on failures/latency

Business Rules

• Home Internet: billing address equals service address.

  • Capture once after signup and save to WHMCS; at checkout only verify.
  • Snapshot the same address onto the Salesforce Order (Bill To). No separate service address UI.

• Single Internet per account: disallow a second Home Internet order.

  • Backend: POST /orders checks WHMCS client services (active/pending/suspended) for Internet; if present, return 409 and a manage link.
  • Frontend: hide/disable Internet products when such a service exists; show “Manage/Upgrade” CTA.
  • Salesforce (optional): validation/Flow to prevent Internet lines when the account already has an Internet service.

• One service per Order (1:1 with Opportunity)

• Cart is split so each selected service becomes its own Salesforce Order containing exactly one OrderItem.

• Each Order links to exactly one Opportunity (1 opportunity represents 1 service).

• Activation fields (Activation_Type__c, Activation_Scheduled_At__c, Activation_Status__c) apply to that single service.

• Result: for two eSIMs (even same date), we create two Orders, two Opportunities, two WHMCS Orders/Invoices/Services.