# Registration Flow Quick Summary

## Architecture Overview

The registration flow consists of **2 main pages + 1 form component** orchestrating 3 logical steps:

```
Welcome Page → Onboarding Page Container → OnboardingForm (3-step client component)
```

## The Three Pages/Components

### 1. Welcome Page (`/registration/welcome`)

- **File:** `app/registration/welcome/page.tsx` (407 lines)
- **Route:** `GET /registration/welcome?session_id=cs_xxx&reload_count=0`
- **Purpose:** Post-checkout confirmation with auto-polling for dealer creation
- **Key Features:**
  - Verifies Stripe payment completed
  - Polls database for dealer account (webhook delay handling)
  - Shows "What Happens Next?" checklist
  - 30-second timeout with manual refresh option

### 2. Onboarding Container (`/registration/onboarding`)

- **File:** `app/registration/onboarding/page.tsx` (139 lines)
- **Route:** `GET /registration/onboarding?session_id=cs_xxx`
- **Purpose:** Server-side validation wrapper + data initialization
- **Key Features:**
  - Verifies session and loads dealer data
  - Determines initial step (subdomain if new, profile if resumed)
  - Passes all data to client component
  - Auto-loads previous responses

### 3. Onboarding Form (`OnboardingForm.tsx`) - **All 3 Steps Here**

- **File:** `app/registration/onboarding/OnboardingForm.tsx` (493 lines)
- **Type:** Client Component (`'use client'`)
- **Manages:** All 3 steps with internal state

## The Three Steps (All in OnboardingForm)

| Step             | Field                            | Purpose                   | API Call                         | Status Change                      |
| ---------------- | -------------------------------- | ------------------------- | -------------------------------- | ---------------------------------- |
| **1: Subdomain** | Subdomain input                  | Choose unique dealer URL  | `GET /api/check-subdomain`       | None yet                           |
| **2: Profile**   | Phone, address, city, state, zip | Capture business info     | `POST /api/register/complete`    | Changes to `registration_complete` |
| **3: Review**    | Read-only summary                | Confirm before publishing | `POST /api/dealers/{id}/publish` | Changes to `active`                |

## Key API Endpoints

| Endpoint                    | Method | Purpose                        | Key Check                                                              |
| --------------------------- | ------ | ------------------------------ | ---------------------------------------------------------------------- |
| `/api/check-subdomain`      | GET    | Real-time availability check   | Format + reserved + tuple uniqueness (subdomain, domainPrefix, domain) |
| `/api/register/complete`    | POST   | Save profile, ready to publish | Dealer ownership + subdomain valid                                     |
| `/api/dealers/{id}/publish` | POST   | Set status to active           | NextAuth + Stripe validation                                           |

## State Flow in Database

```
After Checkout (Webhook)
├─ status: registration_pending
├─ subdomain: null
└─ contact fields: null

After Step 2 (Profile Saved)
├─ status: registration_complete (CHANGED)
├─ subdomain: "bobsoil" (SET)
├─ phone, address, city, state, zip: populated
└─ migrationStatus: registration_complete

After Step 3 (Published)
├─ status: active (CHANGED)
├─ migrationStatus: completed (CHANGED)
└─ All fields as above
```

## Files Summary

### Components (1,097 lines total)

- `welcome/page.tsx` - 407 lines - Success + polling
- `onboarding/page.tsx` - 139 lines - Container + data fetch
- `onboarding/OnboardingForm.tsx` - 493 lines - All 3 steps
- `components/AutoReload.tsx` - 36 lines - Polling component
- `components/RefreshButton.tsx` - 22 lines - Manual refresh

### API Routes (493 lines total)

- `api/check-subdomain/route.ts` - 104 lines - Validation
- `api/register/complete/route.ts` - 204 lines - Profile save
- `api/dealers/[id]/publish/route.ts` - 185 lines - Publish

### Utilities (319 lines total)

- `lib/subdomain-validation.ts` - 127 lines - Format + uniqueness
- `lib/registration-helpers.ts` - 192 lines - Validation + transaction

### Styles (19 lines total)

- `styles/registration-theme.css` - CSS variables for theme

## What Needs Consolidation

1. **OnboardingForm is 493 lines** - Could split into 3 step components
2. **State management** - Uses useState only, could use Context for clarity
3. **Validation logic** - Duplicated in frontend + API + lib (by design)
4. **API naming inconsistency** - Mix of kebab-case and RESTful patterns

## Critical Security Checks

- All endpoints verify Stripe session payment status
- Dealer ownership verified via Stripe customer ID
- Publish endpoint requires NextAuth + userId match
- Subdomain validation prevents race conditions with transactions
- Rate limiting: 10 req/min subdomain, 5 req/min publish

## URL Flow

```
Checkout success
  ↓ Redirect
/registration/welcome?session_id=cs_xxx
  ↓ Continue button
/registration/onboarding?session_id=cs_xxx
  ↓ Render OnboardingForm in Step 1
  ↓ User fills subdomain
  ↓ Continue
  → OnboardingForm in Step 2
  ↓ User fills profile + POST /api/register/complete
  ↓ Continue
  → OnboardingForm in Step 3
  ↓ User clicks Publish + POST /api/dealers/{id}/publish
  ↓ Redirect
/dashboard?published=true
```

---

**Full Details:** See `REGISTRATION_FLOW_MAP.md` for complete documentation