Assist_Design/docs/PORTAL-NONTECH-PRESENTATION.md

# Customer Portal — Simple Overview (Non‑Technical)

Use these slide-ready bullets to explain, in plain language, how our portal works with Salesforce and WHMCS.

## 1) What The Portal Does

- Purpose: One place for customers to browse plans, place orders, and view/pay bills.
- Connects two company systems: Salesforce (service control) and WHMCS (billing).
- Goal: Smooth experience for customers, clear control and visibility for our team.

## 2) The Two Systems We Connect

- Salesforce: Our “control center” for products and orders. Staff review and approve here.
- WHMCS: Our “billing system” for invoices, payment methods, and subscriptions.
- The Portal: The “bridge” customers use. It talks to both safely in the background.

## 3) How It Fits Together (Big Picture)

- Customer uses the Portal → chooses products → places an order.
- Portal creates the order in Salesforce for review/approval.
- After approval, the Portal provisions the order in WHMCS.
- WHMCS then holds the subscription and generates the invoices customers can pay.

## 4) Catalog (What Customers Can Buy)

- We show the catalog from Salesforce so prices and products are consistent.
- Products are organized (e.g., Internet, SIM, VPN) with clear names and monthly/one‑time fees.
- The Portal only shows what’s approved for online sale.

## 5) Customer Journey (At a Glance)

1. Sign up and link your account.
2. Add a payment method (credit card or gateway) — one‑time step.
3. Browse the catalog and select a plan.
4. Place an order (Portal sends it to Salesforce).
5. Staff reviews/approves in Salesforce, and the Portal activates it in WHMCS.
6. Customer sees subscriptions and invoices in the Portal and pays securely.

## 5a) Sign Up & Account Linking (Plain English)

- What we ask for: email, password, name, and your Customer Number (Salesforce number) — this lets us find your existing account.
- What happens: we create a billing profile in WHMCS and securely link three IDs together behind the scenes:
  - Portal user ↔ WHMCS client ↔ Salesforce account.
- Why this matters: from then on, the Portal always shows the right invoices, payment methods, and subscriptions for that customer.

## 5b) Address — Where It Lives and How We Use It

- Required at signup: we capture a full billing address and store it in WHMCS (our billing source of truth).
- Always available: the Portal pulls your current address from WHMCS so checkout is smooth.
- Snapshotted on every order: we copy the current address into the Salesforce order so staff can review what was used at the time.
- Internet orders: we ask you to explicitly confirm the installation address (technician visit). If you change it, we mark the order “address changed” for staff visibility.
- Updates later: when customers update address in the Portal, we sync it to WHMCS so billing and future orders are correct.

## 5c) Payment Methods — Why We Require One First

- Fewer failures: we only allow ordering after a payment method is on file.
- How customers add it: the Portal opens WHMCS’s secure payment page (single sign‑on); cards are stored by WHMCS, not by the Portal.
- Provisioning also checks: even after approval, we re‑check payment to avoid failed activations.

## 6) Ordering Flow (Simple)

- Before ordering, the Portal checks: “Do you have a saved payment method?”
- The Portal sends your chosen items to Salesforce as an order for review.
- After approval, the Portal creates the service in WHMCS and finishes activation.

## 6a) Business Rules We Enforce (Simple)

- Internet: must include a service plan; installation options are clearly shown; we prevent duplicate active Internet services for the same account.
- SIM: must include a SIM plan and a one‑time activation fee; optional add‑ons (e.g., voicemail) can be added; for number transfer (MNP), we collect the reservation details.
- VPN: must include the VPN activation fee; regions/options are chosen up front.
- Product validity: only products that are approved and priced are allowed to be ordered.

## 7) Billing & Payments (Simple)

- Invoices: Created by WHMCS and shown in the Portal.
- Payment: The Portal opens a secure payment page (SSO) directly in WHMCS.
- Subscriptions: Ongoing services (e.g., monthly plans) displayed in the Portal.

## 8) Built‑In Safeguards (What We Check Automatically)

- Payment method required: prevents failed activations and billing issues.
- Product validity: only approved, priced items can be ordered.
- Duplicate protection: e.g., avoids ordering a second Internet line by mistake.
- Status tracking: Salesforce and WHMCS stay in sync (Created → Activating → Activated).

## 8a) Behind the Scenes (Safe & Repeatable)

- Approvals: staff review orders in Salesforce; on approval, the Portal activates the order in WHMCS.
- Single sign‑on (SSO): the Portal uses expiring links to WHMCS for invoices and payments; we don’t handle card numbers directly.
- Clear errors: if something blocks activation (e.g., missing payment method), we pause and show a short, human‑readable note to staff and a clear status to the customer.

## 9) If Something Goes Wrong

- The order is paused with a clear status (e.g., “Awaiting payment method”).
- Staff sees a short error code and message in Salesforce to resolve quickly.
- Customers keep seeing clear status updates in the Portal.

## 10) Why This Is Better

- For customers: Clear catalog, simple checkout, easy invoice payments.
- For staff: Single review step in Salesforce, automated activation, fewer manual tasks.
- For the business: Consistent pricing, faster time‑to‑activate, fewer errors.

---

# Suggested Slide Deck (Titles + Bullets + Notes)

1. Title — “Customer Portal: How It Works”
   - Bullets: One place to buy, manage, and pay.
   - Notes: We connect Salesforce (control) and WHMCS (billing).

2. The Systems
   - Bullets: Salesforce = control; WHMCS = billing; Portal = bridge.
   - Notes: Keep the mental model: control center vs. billing system.

3. Big Picture Flow
   - Bullets: Choose → Order in Salesforce → Approve → Activate in WHMCS → Pay.
   - Notes: Emphasize approvals happen in Salesforce; invoices in WHMCS.

4. The Catalog
   - Bullets: Products come from Salesforce; only approved offers appear.
   - Notes: Ensures one source of truth for products and prices.

5. Customer Journey
   - Bullets: Sign up → Add payment → Choose plan → Order → Approve → Activate → Pay.
   - Notes: This is what a typical customer sees end‑to‑end.

6. Ordering Checks
   - Bullets: Payment method required; valid items only; no duplicates.
   - Notes: Prevents surprises and support tickets later.

7. Billing & Payments
   - Bullets: Invoices from WHMCS; pay via secure SSO; subscriptions visible.
   - Notes: We never store card numbers in the Portal.

8. Status & Errors
   - Bullets: Clear statuses; short error messages for staff.
   - Notes: Faster turnaround and fewer escalations.

9. Benefits
   - Bullets: Better customer experience; less manual work; consistent pricing.
   - Notes: Close with impact on activation time and error reduction.

10. Q&A

- Bullets: —
- Notes: Keep backup slides with examples/screenshots.

---

Tip: Pair these slides with a simple swimlane diagram (Customer, Portal, Salesforce, WHMCS) showing the hand‑offs at order and activation.

References for deeper reading (optional for presenters)

- Address flow details: docs/ADDRESS_SYSTEM.md
- Technical overview: docs/PORTAL-INTEGRATION-OVERVIEW.md

Diagram (PNG/SVG for slides)

- Swimlane visual: docs/assets/portal-swimlane.svg

---

## 11) Migration (Moving Existing WHMCS Users Into the Portal)

Goal: Let existing customers with WHMCS billing accounts start using the new Portal without losing history.

How it works (plain English):

- Check your email: if you already have a WHMCS billing account, choose “Link account”.
- One-time check: enter your current WHMCS password once. We only verify it directly with WHMCS to prove ownership — we don’t copy it.
- Auto‑linking: we read your Customer Number from WHMCS and find the matching Salesforce account. Then we create your Portal account and link all three IDs.
- Set a new Portal password: we ask you to create a new password for the Portal (your WHMCS password stays in WHMCS).
- After that: log in with your new Portal password; continue to manage payment methods and invoices via secure SSO into WHMCS.

Why setting a NEW Portal password is better than reusing the old one:

- Separation of risk: WHMCS and the Portal are different systems. Separate passwords reduce the blast radius if one is compromised.
- Stronger policy & protections: the Portal enforces modern hashing, lockouts, and audit logs tailored to our app. We don’t control WHMCS’s password rules.
- Least privilege: the Portal never stores or proxies your WHMCS password. We only validate it once during linking, then discard it.
- Future flexibility: lets us improve Portal security (e.g., MFA, rotation rules) without affecting WHMCS.
- Clear SSO flow: customers use the Portal to reach WHMCS billing pages securely without sharing credentials.

Simple talking points for the migration slide:

- “Link your existing billing account by confirming your current password once.”
- “Create a new Portal password — safer, independent, and future‑proof.”
- “Nothing is lost — subscriptions and invoices automatically appear once linked.”