Assist_Design/docs/features/unified-get-started-flow.md

Unified "Get Started" Flow

Overview

The unified get-started flow provides a single entry point for customer account creation and eligibility checking. It replaces separate /signup and /migrate pages with a streamlined flow at /auth/get-started.

User Flows

1. Direct Account Creation (/auth/get-started)

/auth/get-started
     │
     ├─→ Step 1: Enter email
     │
     ├─→ Step 2: Verify email (6-digit OTP)
     │
     └─→ Step 3: System checks accounts & routes:
          │
          ├─→ Portal exists        → "Go to login"
          ├─→ WHMCS exists (unmapped) → "Link account" (enter WHMCS password)
          ├─→ SF exists (unmapped)    → "Complete account" (pre-filled form)
          └─→ Nothing exists          → "Create account" (full form)

2. Eligibility Check First (/services/internet/check-availability)

For customers who want to check internet availability before creating an account:

/services/internet (public)
     │
     └─→ Click "Check Availability"
          │
          └─→ /services/internet/check-availability (dedicated page)
               │
               ├─→ Step 1: Enter name, email, address
               │
               ├─→ Step 2: Verify email (6-digit OTP)
               │
               └─→ Step 3: SF Account + Case created immediately
                    │
                    ├─→ "Create Account Now" → Redirect to /auth/get-started
                    │                          (email pre-verified, goes to complete-account)
                    │
                    └─→ "Maybe Later" → Return to /services/internet
                                        (SF Account created for agent to review)

Account Status Routing

Portal	WHMCS	Salesforce	Mapping	→ Result
✓	✓	✓	✓	Go to login
✓	✓	-	✓	Go to login
-	✓	✓	-	Link WHMCS account (migrate)
-	✓	-	-	Link WHMCS account (migrate)
-	-	✓	-	Complete account (pre-filled)
-	-	-	-	Create new account (full form)

Frontend Structure

apps/portal/src/features/get-started/
├── api/get-started.api.ts           # API client functions
├── stores/get-started.store.ts      # Zustand state management
├── components/
│   ├── GetStartedForm/
│   │   ├── GetStartedForm.tsx       # Main form container
│   │   └── steps/
│   │       ├── EmailStep.tsx        # Email input
│   │       ├── VerificationStep.tsx # OTP verification
│   │       ├── AccountStatusStep.tsx# Route based on status
│   │       ├── CompleteAccountStep.tsx # Full signup form
│   │       └── SuccessStep.tsx      # Success confirmation
│   └── OtpInput/OtpInput.tsx        # 6-digit code input
├── views/GetStartedView.tsx         # Page view
└── index.ts                         # Public exports

Eligibility Check Page

Location: apps/portal/src/features/services/views/PublicEligibilityCheck.tsx Route: /services/internet/check-availability

A dedicated page for guests to check internet availability. This approach provides:

• Better mobile experience with proper form spacing
• Clear user journey with bookmarkable URLs
• Natural browser navigation (back button works)
• Focused multi-step experience

Flow:

1. Collects name, email, and address (with Japan ZIP code lookup)
2. Verifies email with 6-digit OTP
3. Creates SF Account + Eligibility Case immediately on verification
4. Shows success with options: "Create Account Now" or "Maybe Later"

Backend Endpoints

Endpoint	Rate Limit	Purpose
POST /auth/get-started/send-code	5/5min	Send OTP to email
POST /auth/get-started/verify-code	10/5min	Verify OTP, return account status
POST /auth/get-started/quick-check	5/15min	Guest eligibility (creates SF Account + Case)
POST /auth/get-started/complete-account	5/15min	Complete SF-only account
POST /auth/get-started/maybe-later	3/10min	Create SF + Case (legacy)

Domain Schemas

Location: packages/domain/get-started/

Key schemas:

• sendVerificationCodeRequestSchema - email only
• verifyCodeRequestSchema - email + 6-digit code
• quickEligibilityRequestSchema - sessionToken, name, address
• completeAccountRequestSchema - sessionToken + password + profile fields
• accountStatusSchema - portal_exists | whmcs_unmapped | sf_unmapped | new_customer

OTP Security

• Storage: Redis with key format otp:{email}
• TTL: 10 minutes
• Max Attempts: 3 per code
• Rate Limits: 5 codes per 5 minutes

Handoff from Eligibility Check

When a user clicks "Create Account Now" from the eligibility check page:

1. Email stored in sessionStorage: get-started-email
2. Verification flag stored: get-started-verified=true
3. Redirect to: /auth/get-started?email={email}&verified=true
4. GetStartedView detects handoff and:
   • Sets account status to sf_unmapped (SF Account was created during eligibility)
   • Skips to complete-account step
   • User only needs to add password + profile details

When a user clicks "Maybe Later":

• Returns to /services/internet plans page
• SF Account already created during eligibility check (agent can review)
• User can return anytime and use the same email to continue

Testing Checklist

Manual Testing

1. New customer flow: Enter new email → Verify OTP → Full signup form
2. SF-only flow: Enter email with SF account → Verify → Pre-filled form, just add password
3. WHMCS migration: Enter email with WHMCS → Verify → Enter WHMCS password
4. Eligibility check: Click "Check Availability" on plans page → Dedicated page → Enter details → OTP → "Create Account" or "Maybe Later"
5. Return flow: Customer returns, enters same email → Auto-links to SF account
6. Mobile experience: Test eligibility check page on mobile viewport

Security Testing

• Verify OTP expires after 10 minutes
• Verify max 3 attempts per code
• Verify rate limits on all endpoints
• Verify email enumeration is prevented (same response until OTP verified)

Routes

Route	Action
/auth/get-started	Unified account creation page
/auth/signup	Redirects to /auth/get-started
/auth/migrate	Redirects to /auth/get-started
/services/internet/check-availability	Guest eligibility check (public)

Environment Variables

# OTP Configuration
OTP_TTL_SECONDS=600        # 10 minutes
OTP_MAX_ATTEMPTS=3
GET_STARTED_SESSION_TTL=3600  # 1 hour