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
• Silver Internet: Customer configures access mode (IPoE-BYOR vs PPPoE), standard pricing
• Gold Internet: Customer selects tier only, premium pricing, shows operator review message
• Platinum Internet: Customer selects tier only, premium pricing + additional fees message:

  *IMPORTANT* For PLATINUM subscribers
  * Additional fees are incurred for the PLATINUM service. Please refer to the
    information from our tech team for details.
  * Will appear on the invoice as "Platinum Base Plan". Device subscriptions
    will be added later.
  

• SIM: Personalized catalog shows regular or family discount products based on existing services
• VPN: Customer selects region at order time

4. Checkout (create Order)

• All Internet plans: POST /orders → create Salesforce Order (Pending Review)
• All plans: OrderItem created with customer's selected product and its default WHMCS_Product_Id__c
• Silver: Customer selections saved (access mode, installment, etc.)
• Gold/Platinum: Customer tier selection saved, operator can modify WHMCS Product ID during review
• Portal shows "Awaiting review" for all orders

5. Review & Provision (operator)

• Silver Orders: Operator reviews customer configuration, approves as-is or makes adjustments
• Gold/Platinum Orders: Operator reviews customer location/requirements and may:
  • Change WHMCS Product ID on OrderItem if different product needed based on infrastructure
  • Set Access_Mode__c (IPoE-BYOR, IPoE-HGW, PPPoE) based on technical assessment
  • Add additional fees or services as needed
  • Update order with final configuration
• Default behavior: If no changes needed, order provisions with customer's selected product
• Operator 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 (uses WHMCS Product ID set by operator)
  • 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

Simplified Internet Plan Process

Overview

All Internet plans (Silver, Gold, Platinum) are separate products with manual operator review. No complex configuration flows needed.

Process Flow

1. Customer Selection

   POST /orders {
     orderType: "Internet",
     selections: {
       planTier: "Platinum",           // Customer choice
       installmentType: "24-month",    // Customer choice
       weekendInstall: true,           // Customer choice
       accessMode: null                // Silver: customer sets, Gold/Platinum: operator sets
     }
   }
   

2. Order Creation (BFF)

   • Creates Salesforce Order with Status = "Pending Review"
   • All customer selections saved to Order fields
   • OrderItem created with customer's selected product and its default WHMCS_Product_Id__c
   • Operator can change WHMCS_Product_Id__c during review if needed

3. Operator Review

   • Silver: Operator reviews customer configuration, approves or adjusts
   • Gold/Platinum: Operator reviews and may:
     • Change WHMCS Product ID if different product needed
     • Set Access_Mode__c based on technical assessment
     • Add additional services/fees as needed
   • Default: If no changes needed, uses customer's selected product

4. Provision

   • Operator clicks "Provision in WHMCS"
   • BFF uses WHMCS Product ID set by operator
   • Standard provisioning flow

Status Progression

Draft → Pending Review → Approved → Provisioned

Product Structure

-- All visible to customers with default WHMCS Product IDs
"Internet Silver Plan" → SKU: "INTERNET-SILVER" → WHMCS_Product_Id__c: 184
"Internet Gold Plan" → SKU: "INTERNET-GOLD" → WHMCS_Product_Id__c: 188 (default, operator can change)
"Internet Platinum Plan" → SKU: "INTERNET-PLATINUM" → WHMCS_Product_Id__c: 183 (default, operator can change)

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

Salesforce prerequisites for Catalog:

• Enable Products and Price Books (Setup → Product Settings)
• Product2 required fields for portal queries: SKU__c, Portal_Visible__c, Portal_Category__c
• Ensure integration user has Read on Product2 and field-level read access to those fields
• Create a Portal price book and ensure PricebookEntry exists for each visible product
• 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.