Perfect! Now I have a comprehensive view. Let me create a detailed report of the worker user flow. Let me generate the final comprehensive documentation:

## RATERIGHT WORKER USER FLOW - COMPREHENSIVE DOCUMENTATION

Based on my thorough exploration of the RateRight codebase, here is a complete documentation of every screen, component, API call, and data collection point for workers:

---

### **1. AUTHENTICATION & INITIAL SIGNUP**

#### **Route: `/auth/signup` → Select User Type**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/auth/signup/page.tsx`
- **Type:** Client component
- **What Happens:**
  - User lands on sign-up page
  - Selects "Worker" vs "Contractor"
  - Enters email and password
  - Agrees to Terms of Service and Privacy Policy
- **Data Collected:**
  - Email
  - Password (min 6 chars)
  - User type: "worker"
  - Terms agreement checkbox
- **API Calls:**
  - `supabase.auth.signUp()` with user type metadata
  - Redirect to: `/auth/verify-email` (email verification page)

#### **Auth Flow:**
- Supabase Auth creates user in `auth.users`
- Trigger: `handle_new_user` creates row in `profiles` table with:
  - `id` (from auth.users)
  - `type` = "worker"
  - `onboarding_completed` = false

---

### **2. WORKER PROFILE CREATION (PRIMARY FLOW)**

#### **Route: `/worker/signup` (New Multi-Step Flow)**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/worker/signup/page.tsx`
- **Authentication Guard:** Yes - redirects if not logged in via `(authenticated)` layout
- **Component Structure:**
  - Master page manages state and step navigation
  - 9 steps total: auth → method → voice → trade → experience → location → availability → certs → review
  - Progress bar tracks 8 user-facing steps (voice is transparent)

#### **Step 1: Auth (if not authenticated)**
- **Component:** `AuthStep.tsx`
- **Data Collected:**
  - Email
  - Password
- **API Calls:**
  - `supabase.auth.signUp()` or `supabase.auth.signInWithPassword()`
- **State Variables (from `useWorkerAuth` hook):**
  - `isAuthenticated`, `email`, `password`, `authError`, `authLoading`

#### **Step 2: Method Selection**
- **Component:** `MethodStep.tsx`
- **Choices:**
  - "Type your answers" → proceed to Trade step
  - "Tell us with your voice" → proceed to Voice step
- **No data collected yet** - just navigation choice

#### **Step 3A: Voice Recording (Optional/Alternative Path)**
- **Component:** `VoiceStep.tsx`
- **File:** `/home/ccuser/the-50-dollar-app/src/components/VoiceRecorder.tsx`
- **What Happens:**
  - User records audio describing themselves
  - Example prompt: "I'm a chippie with 8 years experience in Parramatta, looking for full-time work"
- **Data Collected:**
  - Audio blob (WebM format)
- **API Calls:**
  1. **POST `/api/ai/transcribe-voice`** (FormData with CSRF token)
     - Input: `audio` file
     - Output: `{ text: "transcribed speech" }`
     - Rate limited: 10 requests/15 minutes
     - Auth required: Yes

  2. **POST `/api/ai/parse-profile-voice`** (JSON with CSRF token)
     - Input: `{ transcript: "..." }`
     - Output: `{ trades: [], trade: null, experience_years: number, location: string, availability: string, additional_details: string }`
     - Uses GPT-4o-mini to parse
     - Validates against TRADES list and AVAILABILITY options
     - Rate limited: 10 requests/15 minutes
     - Auth required: Yes

  - **State from `useVoiceProcessing` hook:**
    - `voiceState`: { processing, status, error, transcript }
    - Pre-fills: trades, experience, suburb, availability
  - **If all fields extracted:** Skip to Review step
  - **If partial:** Go to first missing field step
  - **If error:** Show error, return to Method step

#### **Step 3B: Trade Selection**
- **Component:** `TradeStep.tsx`
- **Display:** Grid of 16 trades (Labourer, Steel Fixer, Formworker, Carpenter, Electrician, Plumber, Concreter, Bricklayer, Painter, Roofer, Scaffolder, Tiler, Plasterer, Welder, Crane Operator, Excavator Operator)
- **Data Collected:**
  - `selectedTrades: string[]` (can select multiple)
- **Stored in State:**
  - Via `useWorkerProfile.toggleTrade(trade)`
- **Validation:** At least 1 trade must be selected

#### **Step 4: Experience**
- **Component:** `ExperienceStep.tsx`
- **Options:**
  - "Less than 1 year" → value: 0
  - "1-3 years" → value: 2
  - "3-5 years" → value: 4
  - "5-10 years" → value: 7
  - "10+ years" → value: 12
- **Data Collected:**
  - `experience: number` (years)

#### **Step 5: Location**
- **Component:** `LocationStep.tsx`
- **What It Does:**
  - User enters suburb/area (e.g., "Parramatta", "Blacktown")
  - **LATER:** Geocoded to lat/lng via `POST /api/geocode`
- **Data Collected:**
  - `suburb: string`
  - Location geocoded to PostgreSQL point format during save
- **Validation:** Required, must not be empty

#### **Step 6: Availability**
- **Component:** `AvailabilityStep.tsx`
- **Options:**
  - "Full-time" (Mon-Fri, regular hours)
  - "Casual" (As needed, flexible)
  - "Weekends" (Saturday & Sunday)
  - "Flexible" (Any time, any days)
- **Data Collected:**
  - `availability: "full-time" | "casual" | "weekends" | "flexible"`

#### **Step 7: Certifications**
- **Component:** `CertificationsStep.tsx`
- **Options (can select multiple):**
  - White Card
  - Forklift Licence
  - EWP (Elevated Work Platform)
  - Working at Heights
  - First Aid
  - Traffic Control
  - Rigging
  - Dogging
  - Confined Spaces
- **Data Collected:**
  - `certifications: string[]` (array of selected certs)

#### **Step 8: Review & Confirmation**
- **Component:** `ReviewStep.tsx`
- **Displays:**
  - Summary of all entered data (trades, experience, location, availability, certs)
  - AI-generated bio (generated on-the-fly from data)
  - Edit buttons for each field
- **Data shown but not editable here:**
  - Bio is generated via `generateBio(workerData)` utility function
- **Save Action:**
  - Calls `saveWorkerProfile()` from `useWorkerProfile` hook

#### **Profile Save Logic (`saveWorkerProfile` in `useWorkerProfile.ts`):**
1. **Validate:** availability and experience must be set
2. **Geocode suburb:** `POST /api/geocode` → converts suburb to lat/lng
3. **Update `profiles` table:**
   ```
   {
     name: email.split("@")[0],
     suburb: string,
     location: point (PostgreSQL format),
     onboarding_completed: true
   }
   ```
4. **Insert into `worker_profiles` table:**
   ```
   {
     profile_id: user.id,
     trades: string[],
     experience_years: number,
     availability: "full-time" | "casual" | "weekends" | "flexible",
     certifications: string[],
     bio: string (generated),
     ai_extracted: {
       source: "typed_answers",
       created_at: ISO string
     }
   }
   ```
5. **Redirect to `/dashboard`**

---

### **3. ALTERNATIVE: PROFILE BUILD FLOW**

#### **Route: `/worker/profile/build` (Alternative/Edit Interface)**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/worker/profile/build/page.tsx`
- **Purpose:** Edit existing profile or create from scratch with AI generation
- **Key Difference from Signup:** Includes AI profile generation with skills and certifications
- **Steps:** trade → experience → location → availability → [generating] → review
- **Enhanced Endpoint Usage:**
  - **POST `/api/ai/generate-profile`** (JSON with CSRF token)
    - Input: `{ trade, trades, experience, location, availability, voiceTranscript }`
    - Output: `{ bio, skills: string[], certifications: string[] }`
    - Generates AI-enriched profile with extracted skills and suggested certs
  - **POST `/api/ai/voice-complete`** (consolidated endpoint)
    - Input: Audio file (FormData with CSRF)
    - Output: Combined transcription + parsing + generation
    - Used for faster voice processing (combines 3 operations)
    - Rate limited: 5 requests/15 minutes

---

### **4. WORKER DASHBOARD**

#### **Route: `/dashboard`**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/dashboard/page.tsx`
- **Type:** Server component
- **Guard:** Must be logged in
- **For Workers (when `profile.type === "worker"`):**
  - Shows "Let's get you on a job" message
  - **Pending Ratings Card** (if unrated hired matches exist)
    - Shows list of jobs to rate
    - Link: `/rate/{matchId}`
  - **"Find Work" CTA Card**
    - Link: `/worker/jobs`
  - **"Your Profile" Card**
    - If onboarding not complete: "Build Profile" → `/worker/profile/build`
    - If complete: "View Profile" → `/worker/profile`
- **Data Fetched (Server):**
  - User profile: type, name, onboarding_completed
  - Pending ratings: hired matches that haven't been rated

---

### **5. JOB BROWSING & APPLICATION**

#### **Route: `/worker/jobs`**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/worker/jobs/page.tsx`
- **Type:** Client component
- **Features:**
  - **Trade Filters** (horizontal scrollable):
    - "All" + each trade from TRADES list
    - Filter jobs by selected trade
  - **Swipeable Job Cards:**
    - Swipe right to apply (>100px triggers apply)
    - Tap to view full details
    - Shows: trade badge, title, location, pay range, start date, workers needed
    - Shows "Applied" badge if already applied
  - **Pagination:** 10 items per page with prev/next controls

#### **Data Collected/Fetched:**
- **On Load (useEffect):**
  1. Get current user
  2. Fetch all active jobs with pagination:
     - Query: `jobs` table where `status = 'active'`
     - Select: id, title, trade, suburb, rate_min, rate_max, rate_type, start_date, workers_needed, status, created_at, location
     - Order: newest first
     - Limit: 10 per page
  3. Fetch already-applied jobs:
     - Query: `matches` table where `worker_id = user.id`
     - Gets set of job IDs worker already applied to

#### **Job Application Flow:**
- **When Worker Swipes or Clicks "Apply with One Tap":**
  1. Check: user must be authenticated and not already applied
  2. **Insert into `matches` table:**
     ```
     {
       job_id: string,
       worker_id: user.id,
       status: "applied",
       contractor_action: "pending",
       worker_action: "accepted",
     }
     ```
  3. Haptic feedback (if supported)
  4. Show success toast
  5. Update UI: show "Applied" badge
- **No cost to worker** - always free for workers (shown in messaging)

#### **Job Detail Sheet (Bottom Modal):**
- Shows expanded job info when tapped:
  - Trade badge
  - Title, location, pay, start date, duration
  - Full description
  - Required certifications (as badges)
  - "Apply with One Tap" button or "Already Applied" button

---

### **6. WORKER PROFILE VIEW**

#### **Route: `/worker/profile`**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/worker/profile/page.tsx`
- **Type:** Server component
- **Guard:** Requires `onboarding_completed = true`
- **If Not Complete:** Redirects to `/worker/profile/build`

#### **Profile Display:**
- **Avatar Upload Section:**
  - Component: `AvatarUpload.tsx`
  - Upload to Supabase Storage (bucket: `avatars`)
- **Basic Info:**
  - Name (from profiles table)
  - Trades (as badges)
  - Suburb with icon
  - Experience level
  - Average rating (if available)
  - Availability badge
- **Bio Section:**
  - From `worker_profiles.bio`
- **Skills Section:**
  - From `worker_profiles.ai_extracted.skills[]`
  - Displayed as colored badges
- **Certifications Section:**
  - From `worker_profiles.certifications[]`
  - Displayed as list items with shield icon
- **Ratings Section:**
  - Fetches last 3 ratings via join to profiles table
  - Shows average rating and count
  - "View All Reviews" button if >3 ratings
- **Edit Profile Button:**
  - Link: `/worker/profile/build`

#### **Data Fetched (Server):**
1. `profiles`: id, name, avatar_url, suburb, onboarding_completed
2. `worker_profiles`: trades, experience_years, certifications, bio, ai_extracted, availability
3. `ratings` (with join to profiles): score, comment, from_profile (name, avatar_url)

---

### **7. GETTING HIRED - MATCH PROCESS**

#### **Worker Actions on Matches:**
1. **Worker Applies via `/worker/jobs`**
   - Creates match with `status = "applied"`, `worker_action = "accepted"`, `contractor_action = "pending"`

2. **Contractor Reviews & Hires**
   - (Different flow - not worker-initiated)
   - Contractor accepts match → match status changes to "hired"
   - Payment: $50 flat fee charged to contractor

3. **Worker Receives Notification** (via Supabase Realtime)
   - Match hired notification sent
   - Worker can see on dashboard

#### **Data Points Revealed:**
- When match is created (application):
  - Contractor can see: worker trades, experience, availability, certifications, profile info
  - When accessed via `/contractor/matches` page
- **Contact Details:**
  - Worker email is NOT revealed until match is `hired`
  - Only then can contractor initiate messaging via `/api/messages/start`

---

### **8. JOB COMPLETION & PAYMENT**

#### **Hired Match Status:**
- Match must be `status = "hired"` before worker can message or be rated
- When contractor hires:
  - Stripe charge of $50 AUD initiated immediately
  - Payment record created in `payments` table
  - Match.hired_at timestamp set
  - Match.fee_charged = true

#### **Messaging After Hire:**
- **Route: `/messages` and sub-routes**
- Worker and contractor can message each other
- **POST `/api/messages/start`:**
  - Starts conversation between worker and contractor
  - Uses RPC: `get_or_create_conversation(user1_id, user2_id)`
  - Creates entries in `conversations` and `conversation_participants` tables
  - Can send optional initial message
- **POST `/api/messages/{conversationId}/send`:**
  - Send individual messages
  - Stored in `messages` table

---

### **9. JOB COMPLETION & RATING**

#### **Rating Flow:**
- **Route: `/rate/{matchId}`**
- **File:** `/home/ccuser/the-50-dollar-app/src/app/(authenticated)/rate/[matchId]/page.tsx`
- **Type:** Client component
- **Accessible:** Only if match status = "hired" and not already rated by this user

#### **What Gets Collected:**
1. **Star Rating:** 1-5 stars
2. **Optional Comment:** Up to 500 characters
3. **Auto-Determined Fields:**
   - `match_id`: from URL param
   - `from_id`: current user ID
   - `to_id`: determined based on match:
     - If worker rating contractor: contractor's profile_id (via company join)
     - If contractor rating worker: worker's profile_id

#### **Rating Save:**
- **POST to `ratings` table:**
  ```
  {
    match_id: string,
    from_id: user.id,
    to_id: other_party_id,
    score: 1-5,
    comment: string | null,
  }
  ```
- Success → shows confirmation → redirects to `/dashboard` after 2 seconds
- Already rated → shows "Already rated" message
- Invalid match → shows error

---

### **10. KEY DATA MODELS & SUPABASE TABLES**

#### **Worker-Related Tables:**

**`profiles` table:**
- id (UUID, auth.users FK)
- type (enum: worker | contractor)
- name (string)
- phone (string)
- email (string)
- avatar_url (string)
- location (PostgreSQL point type)
- suburb (string)
- verified (boolean)
- **onboarding_completed (boolean)** ← KEY GUARD
- created_at, updated_at, last_seen_at
- ai_generated (boolean)

**`worker_profiles` table:**
- id (UUID)
- profile_id (UUID, profiles FK) UNIQUE
- trades (text array)
- experience_years (integer)
- certifications (text array)
- white_card_number (string)
- white_card_verified (boolean)
- availability (enum: full-time | casual | weekends | flexible)
- languages (text array)
- bio (text)
- voice_note_url (string)
- ai_extracted (JSONB) ← Contains: { source, created_at, skills, ... }
- created_at, updated_at

**`matches` table:**
- id (UUID)
- job_id (UUID, jobs FK)
- worker_id (UUID, profiles FK)
- status (enum: suggested | applied | accepted | rejected | **hired**)
- match_score (decimal)
- ai_summary (text)
- contractor_action (enum: pending | accepted | rejected)
- worker_action (enum: pending | accepted | rejected)
- **hired_at (timestamptz)** ← When hired
- fee_charged (boolean)
- created_at, updated_at
- UNIQUE (job_id, worker_id)

**`ratings` table:**
- id (UUID)
- match_id (UUID, matches FK)
- from_id (UUID, profiles FK)
- to_id (UUID, profiles FK)
- score (integer 1-5)
- comment (text)
- created_at

**`messages` table:**
- id (UUID)
- conversation_id (UUID, conversations FK)
- sender_id (UUID, profiles FK)
- content (text)
- created_at

**`conversations` table:**
- id (UUID)
- created_at, updated_at

**`conversation_participants` table:**
- id (UUID)
- conversation_id (UUID, conversations FK)
- profile_id (UUID, profiles FK)
- joined_at
- UNIQUE (conversation_id, profile_id)

---

### **11. SECURITY & GUARDS**

#### **Authentication Guards:**
- All routes under `/(authenticated)/**` require auth via layout check
- Middleware validates Supabase session
- CSRF protection on all POST endpoints
- Rate limiting on AI endpoints (5-10 req/15 min per user)
- Rate limiting on messaging (60 msg/15 min per IP)

#### **Authorization Guards:**
- Workers can only see their own profile
- Workers can only apply to active jobs
- Workers can only rate matches they're part of
- Workers cannot see contractor contact until hired
- RLS policies enforce data isolation (not fully visible in code review)

#### **Data Protection:**
- Passwords hashed by Supabase Auth
- Location stored as PostgreSQL point type
- Input validation & sanitization for transcripts
- CSRF tokens required for sensitive operations

---

### **12. API ENDPOINTS CALLED BY WORKERS**

| Endpoint | Method | Purpose | Auth | Rate Limit |
|----------|--------|---------|------|-----------|
| `/api/auth/verify-email` | POST | Verify email | Yes | 5/15min |
| `/api/ai/transcribe-voice` | POST | Convert speech to text | Yes | 10/15min |
| `/api/ai/parse-profile-voice` | POST | Extract profile fields from transcript | Yes | 10/15min |
| `/api/ai/voice-complete` | POST | Consolidated voice + parse + generate | Yes | 5/15min |
| `/api/geocode` | POST | Convert suburb to lat/lng | Yes | (standard) |
| `/api/match/find-matches` | POST | (Contractor only) | Yes | 10/15min |
| `/api/messages/start` | POST | Create conversation | Yes | 20/15min |
| `/api/messages/{id}/send` | POST | Send message | Yes | 60/15min |
| `/api/ratings` | POST | Submit rating | Yes | (standard) |

---

### **13. FLOW SUMMARY DIAGRAM**

```
Sign Up (/auth/signup)
    ↓
Select "Worker"
    ↓
Email + Password Auth
    ↓
Email Verification
    ↓
Worker Signup Flow (/worker/signup)
    ├─ Auth Step
    ├─ Method Selection (Type vs Voice)
    ├─ [Optional] Voice Recording & Parse
    ├─ Trade Selection
    ├─ Experience Selection
    ├─ Location Entry (+ Geocoding)
    ├─ Availability Selection
    ├─ Certifications Selection
    ├─ Review & Confirm
    └─ Save to DB (profiles + worker_profiles)
        ↓
Dashboard (/dashboard)
    ├─ View Profile CTA (/worker/profile)
    └─ Browse Jobs CTA (/worker/jobs)
        ↓
Job Browsing (/worker/jobs)
    ├─ Trade Filters
    ├─ Swipe to Apply (creates match)
    └─ View Details (bottom sheet)
        ↓
[Contractor Reviews & Hires]
    ↓
Hired Match
    ├─ Start Messaging (/messages)
    └─ Rate After Completion (/rate/{matchId})
        ↓
Dashboard Updates with Ratings
```

---

### **14. KEY FILES REFERENCE**

**Page/Route Files:**
- `/src/app/auth/signup/page.tsx` - User type selection
- `/src/app/(authenticated)/worker/signup/page.tsx` - 9-step signup flow
- `/src/app/(authenticated)/worker/profile/build/page.tsx` - Profile editor with AI generation
- `/src/app/(authenticated)/worker/jobs/page.tsx` - Job browsing
- `/src/app/(authenticated)/worker/profile/page.tsx` - Profile view
- `/src/app/(authenticated)/dashboard/page.tsx` - Dashboard (shows worker or contractor view)
- `/src/app/(authenticated)/rate/[matchId]/page.tsx` - Rating page

**Component Files:**
- `/src/app/(authenticated)/worker/signup/components/` - 8 step components
- `/src/components/VoiceRecorder.tsx` - Audio recording widget
- `/src/components/avatar-upload.tsx` - Profile avatar upload
- `/src/components/bottom-nav.tsx` - Worker bottom navigation
- `/src/components/rate-job-form.tsx` - Rating form

**Hook Files:**
- `/src/app/(authenticated)/worker/signup/hooks/useWorkerAuth.ts` - Auth state
- `/src/app/(authenticated)/worker/signup/hooks/useWorkerProfile.ts` - Profile form state
- `/src/app/(authenticated)/worker/signup/hooks/useVoiceProcessing.ts` - Voice processing

**API Routes:**
- `/src/app/api/auth/verify-email/route.ts` - Email verification
- `/src/app/api/ai/transcribe-voice/route.ts` - Whisper transcription
- `/src/app/api/ai/parse-profile-voice/route.ts` - GPT-4o-mini parsing
- `/src/app/api/ai/voice-complete/route.ts` - Consolidated voice endpoint
- `/src/app/api/ai/generate-profile/route.ts` - AI profile generation
- `/src/app/api/geocode/route.ts` - Suburb to coordinates
- `/src/app/api/messages/start/route.ts` - Start messaging
- `/src/app/api/messages/[id]/send/route.ts` - Send message
- `/src/app/api/ratings/route.ts` - Submit rating

---

This comprehensive documentation captures the complete worker user flow from signup through job completion and rating. Every screen, component, API call, and data collection point is documented with file paths, data models, and flow descriptions.