---
created: 2026-03-12
source: Rivet
tags: [agent-archive, rivet]
---

# RateRight — Comprehensive Gap Analysis

**Date:** 2025-07-18
**Purpose:** Drive the complete product rebuild from Flask web app → Uber-like mobile-first construction marketplace
**Business Model:** Contractors pay $50 flat fee per hire. Workers pay nothing, keep 100% of their rate.
**Current State:** Flask/Python web app with job posting, contracts, payments (Stripe), messaging, ratings, WHS safety, availability/scheduling, gamification, dispute resolution, notifications.

---

## Table of Contents

1. [Misclicks / Accidental Actions](#1-misclicks--accidental-actions)
2. [Worker Availability](#2-worker-availability)
3. [Contractor-Side Gaps](#3-contractor-side-gaps)
4. [Matching Gaps](#4-matching-gaps)
5. [Trust & Safety](#5-trust--safety)
6. [Communication Gaps](#6-communication-gaps)
7. [Payment Gaps](#7-payment-gaps)
8. [Scalability Gaps](#8-scalability-gaps)
9. [Competitive Comparison](#9-competitive-comparison)
10. [Mobile / App Gaps](#10-mobile--app-gaps)
11. [Summary: Priority Matrix](#11-summary-priority-matrix)

---

## 1. Misclicks / Accidental Actions

### GAP 1.1 — No grace period after worker accepts a job
- **The problem:** In the proposed Uber-like "accept with one tap" flow, a worker could accidentally accept a job they don't want (pocket tap, wrong job, misread details). The current codebase (`booking_routes.py`) has a confirm flow (PENDING → CONFIRMED) but no undo window once confirmed. There's no concept of a "grace period" or "cooling off."
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Worker is committed to a job they can't do. Contractor thinks they have a worker. Cancellation damages trust on both sides. Worker may just no-show instead of figuring out how to cancel.
- **The solution:**
  - **5-minute grace period** after accepting — worker can tap "Undo" with zero consequences
  - After grace period, cancellation counts against reliability score
  - Confirmation screen: "You're accepting [Job Title] at [Location] for [Date]. Confirm?" (Uber uses a swipe, not a tap, to prevent accidental accepts)
  - Use **swipe-to-accept** or **hold-to-accept** instead of single tap (friction = good here)
  - Push notification: "You accepted [Job]. Not right? Undo within 5 minutes"
- **Priority:** 🔴 **MUST-HAVE for launch** — Without this, accidental accepts will be one of the top support issues from day one

### GAP 1.2 — Contractor accidentally hires the wrong person
- **The problem:** If matching becomes instant/automated, contractor could get matched with wrong worker, or tap "Hire" on wrong profile in a list. Current system uses applications → contract creation, which has friction (good). But the Uber-like flow removes that friction.
- **The impact:** ⭐⭐⭐⭐ (4/5) — $50 fee potentially charged, wrong worker shows up on site, awkward for everyone, support tickets.
- **The solution:**
  - **Confirmation screen** before hire: Show worker photo, name, trade, rating, rate — "Hire [Name] for $X/hr? $50 booking fee applies."
  - **5-minute cancellation window** after hire — full refund of $50 fee, no penalty
  - After window: $50 is non-refundable but worker gets notified of cancellation (no penalty to contractor's first 2 cancellations, then warnings)
  - Show recent hire history so contractor doesn't accidentally re-hire someone they had issues with
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 1.3 — Accidental job posting
- **The problem:** Someone starts creating a job post, accidentally submits it incomplete or doesn't mean to post it. Current system requires multiple fields (title, description, category, location, budget, WHS requirements) which provides friction. But "3-tap posting" means less friction = more accidents.
- **The impact:** ⭐⭐⭐ (3/5) — Workers see and apply to ghost jobs. Wastes everyone's time. If $50 is charged on post (not on hire), contractor loses money.
- **The solution:**
  - **Draft state** — jobs start as drafts, require explicit "Post Job" confirmation
  - "Review your job posting" summary screen before going live
  - Jobs can be **deleted within 15 minutes** of posting with no consequence
  - After 15 minutes, if workers have already applied, job goes to "Cancelled" state (not deleted) so workers see it was cancelled
  - **Never charge $50 on post** — only charge on successful hire (see Payment Gaps)
- **Priority:** 🟡 **SHOULD-HAVE for launch** — Lower risk than accept/hire misclicks

### GAP 1.4 — No undo/cancel flow exists at all
- **The problem:** The current codebase has booking cancellation (`cancel_booking`) but no concept of grace periods, undo windows, or consequence-free cancellation timeframes. The cancel endpoint just changes status and notifies the other party.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Every cancel is treated the same whether it's 30 seconds or 30 hours after. This is unfair.
- **The solution:**
  - Implement tiered cancellation system:
    - **0-5 minutes:** Free cancel, no record, no notification to other party
    - **5 min - 2 hours:** Free cancel, notification sent, recorded but no penalty
    - **2-12 hours before job start:** Cancel allowed, recorded, soft warning
    - **<2 hours before job start:** Cancel allowed but counts as "late cancel" — affects reliability score
    - **After job started:** Cannot cancel — must go through dispute resolution
  - Display cancellation policy clearly before every accept/hire
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 1.5 — Consequences of cancellation are undefined
- **The problem:** What happens to ratings, fees, and standing when someone cancels? The current system has no cancellation penalty framework.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Without consequences, people will cancel freely. With too harsh consequences, people won't use the platform (fear of commitment).
- **The solution:**
  - **Reliability Score** (separate from star rating): 0-100%, visible on profile
    - Starts at 100%
    - Late cancels reduce it: -5% per late cancel
    - No-shows reduce it: -15% per no-show
    - Completing jobs restores it: +1% per completed job
    - Below 70%: Account flagged, fewer matches
    - Below 50%: Account suspended, must appeal
  - Star ratings are ONLY for completed jobs (not affected by cancellations)
  - $50 fee: Refunded if cancel within grace period. Refunded if worker cancels. Non-refundable if contractor cancels after grace period (they can get a credit for next hire instead)
- **Priority:** 🔴 **MUST-HAVE for launch**

---

## 2. Worker Availability

### GAP 2.1 — No real-time availability toggle
- **The problem:** Current system has an Availability model with date/time slots and a WorkerSchedulePreferences model with working days/hours. This is calendar-based (good for recurring schedules) but **doesn't support a simple "I'm available RIGHT NOW" toggle** — the Uber equivalent of going online/offline.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Workers who aren't working today get pinged for jobs and ignore them. Contractors think workers are available when they're not. Match quality degrades. Ghost workers pollute the matching pool.
- **The solution:**
  - **Three-state toggle** on worker home screen:
    - 🟢 **Available** — I'm ready to work, show me jobs
    - 🟡 **Available later** — I'm free from [time] today
    - 🔴 **Not available** — Don't show me anything
  - Default to 🔴 every morning (opt-in, not opt-out) — workers must actively go "online"
  - Calendar-based availability for future days (existing system is good, keep it)
  - **Auto-offline** after 8 hours if no activity (prevent stale "online" status)
  - Show contractors how many workers are currently 🟢 in their area
- **Priority:** 🔴 **MUST-HAVE for launch** — Core to the Uber-like experience

### GAP 2.2 — No-show handling is missing
- **The problem:** Worker accepts a job, contractor is expecting them on site, worker just... doesn't show up. There's no no-show detection, no automated response, no backup matching. The current system has booking statuses (PENDING, CONFIRMED, IN_PROGRESS, etc.) but no "NO_SHOW" status or detection mechanism.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Contractor's entire day is wasted. They lose money (project delayed). They lose trust in the platform. This is the #1 complaint in construction labour hire.
- **The solution:**
  - **Check-in system:** Worker must "Check In" within 30 minutes of job start time (GPS-verified at job location)
  - If no check-in by start time + 15 min: Push notification to worker "Are you on your way?"
  - If no check-in by start time + 30 min: Alert contractor "Worker hasn't checked in. Would you like to find a replacement?"
  - If no check-in by start time + 60 min: Auto-mark as NO_SHOW
  - **Consequences for no-show:**
    - Reliability score: -15%
    - First no-show: Warning
    - Second no-show: 7-day suspension
    - Third no-show: Account review/permanent suspension
  - **Backup matching:** Offer contractor instant re-matching with available workers (prioritised queue — workers who can start within 1 hour)
  - **Refund:** Full $50 fee refund to contractor on confirmed no-show
- **Priority:** 🔴 **MUST-HAVE for launch** — Construction sites lose $1000s per hour waiting. This must work.

### GAP 2.3 — Worker cancellation after accepting
- **The problem:** Worker accepted yesterday, but today they don't want to go (got a better offer, feeling lazy, personal issues). Current cancel endpoint exists but has no time-based rules or consequences.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Same as no-show but slightly less bad because contractor gets notice.
- **The solution:**
  - Tiered cancellation (see GAP 1.4)
  - If cancelling <12 hours before start: Platform automatically offers to find replacement worker
  - Worker must provide reason (dropdown): "Personal emergency", "Illness", "Transport issue", "Got another job", "Other"
  - Reasons tracked for pattern detection (consistently cancelling for "got another job" = warning)
  - Sick: No penalty if worker provides medical certificate within 48 hours (upload photo in app)
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 2.4 — Worker gets sick mid-job
- **The problem:** Worker is on site, feels unwell, needs to leave. No protocol exists in the system for mid-job termination due to illness.
- **The impact:** ⭐⭐⭐ (3/5) — Contractor needs to handle it directly. Platform doesn't assist.
- **The solution:**
  - "Report Issue" button in active job view: Options include "Feeling unwell", "Safety concern", "Need to leave"
  - If worker reports sick mid-job:
    - Time tracked up to departure (worker gets paid for hours worked)
    - No penalty to reliability score if medical cert provided
    - Contractor offered replacement matching for remaining duration
    - Job status goes to "PAUSED" not "CANCELLED"
  - WHS compliance: Document the incident (required under WHS Act 2011)
- **Priority:** 🟡 **SHOULD-HAVE for launch**

### GAP 2.5 — Availability system is too complex for tradies
- **The problem:** The current WorkerSchedulePreferences model has Google Calendar sync, Outlook sync, buffer times, min/max advance booking windows. This is over-engineered for construction workers who just want to say "yeah I can work tomorrow." Most tradies will never set up calendar sync.
- **The impact:** ⭐⭐⭐ (3/5) — Workers won't bother setting availability → they appear unavailable → they don't get matches → they leave the platform.
- **The solution:**
  - **Simple first, advanced optional:**
    - Default: Daily toggle (🟢/🔴) — takes 1 second
    - Optional: Weekly schedule template ("I usually work Mon-Fri 6am-3pm") — auto-applies toggle
    - Advanced: Calendar sync for power users
  - **Smart defaults:** If worker has completed 5+ jobs, suggest a schedule based on their history
  - **Nudge notifications:** "Are you available tomorrow?" push at 7pm each evening
- **Priority:** 🔴 **MUST-HAVE for launch** (the simple toggle, not the advanced features)

---

## 3. Contractor-Side Gaps

### GAP 3.1 — No "urgent/same-day" job type
- **The problem:** Construction sites often need someone TODAY — a worker called in sick, they need an extra pair of hands for a pour, etc. The current job model has no urgency field or fast-matching flow. All jobs go through the same post → apply → review → hire pipeline.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — If RateRight can't fill same-day requests, it's useless for the most valuable use case. This is where the $50 fee is most justified.
- **The solution:**
  - **"Urgent" job type** with separate flow:
    - Contractor taps "I need someone NOW"
    - Selects trade, location (auto-detected GPS), hours needed, rate
    - System broadcasts to all 🟢 Available workers within radius
    - First worker to accept gets the job (Uber model)
    - If no accept within 15 minutes: Expand radius, increase visibility
    - If no accept within 30 minutes: Notify contractor "No workers available right now. We'll keep trying and notify you."
  - **"Scheduled" job type** (existing flow, improved):
    - For jobs starting tomorrow or later
    - Workers can apply, contractor reviews and selects
    - More deliberate, less urgent
  - Urgent jobs should be visually distinct (🔴 badge, different color, pushed to top of worker feed)
- **Priority:** 🔴 **MUST-HAVE for launch** — This IS the core product differentiator

### GAP 3.2 — Contractor cancellation has no clear rules
- **The problem:** Contractor posts a job, gets a worker matched, then wants to cancel. Maybe the project got delayed, rain day, changed their mind. Current system allows cancellation but no rules around timing, fees, or worker compensation.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Worker blocked out their day and loses income. If this happens repeatedly, workers leave the platform.
- **The solution:**
  - **Cancellation tiers:**
    - Before any worker accepts: Free cancel, no consequence
    - After worker accepts, >24 hours before start: Cancel allowed, $50 fee non-refundable (but can be credited to next hire)
    - After worker accepts, <24 hours before start: Cancel allowed, $50 fee non-refundable, worker receives $50 compensation (minimum 2-hour equivalent pay is industry standard in construction)
    - After job started: Cannot cancel through platform. Must go through dispute resolution.
  - Worker compensation for late cancellation is critical for trust. Even if it's a small amount, it shows the platform cares about workers.
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 3.3 — No "worker isn't performing" mid-job escalation
- **The problem:** Contractor hired a worker who showed up but isn't doing the job properly — slow, incompetent, attitude problem. No in-app mechanism to handle this beyond the post-job rating system and dispute resolution.
- **The impact:** ⭐⭐⭐ (3/5) — Contractor is stuck paying for bad work. The only option is to let them finish and leave a bad review, or fire them and deal with the consequences.
- **The solution:**
  - **"Report Issue" button** during active job:
    - "Worker quality concern" — triggers a record, resolved at end of job via ratings
    - "Worker safety concern" — immediate escalation, platform contacts both parties
    - "Worker hasn't arrived" — no-show flow
    - "Worker left early" — early departure tracking
  - For quality concerns: Contractor can note the issue in real-time (photo evidence encouraged). This is factored into dispute resolution if the worker disputes the rating.
  - **Contractor can end the job early** — worker gets paid for hours worked, contractor rates the job, both parties can dispute
- **Priority:** 🟡 **SHOULD-HAVE for launch** — Complex to build, but important for trust

### GAP 3.4 — No handling for "no workers available"
- **The problem:** Contractor posts a job but there are no workers available in the area (or none with the right trade). The system returns empty results. Contractor gets frustrated and leaves.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — This is the marketplace chicken-and-egg problem manifested. Early on, this WILL happen frequently.
- **The solution:**
  - **Never show "No results"** — always show something:
    - "3 workers are available nearby, but not in your exact trade. View anyway?"
    - "No workers available right now. We'll notify you when someone becomes available." (Waitlist)
    - "Expand your search to [neighbouring suburbs]?"
  - **Waitlist system:** Job stays active, workers get notified when they come online
  - **SMS blast** to registered-but-offline workers in the area: "A contractor needs a [trade] in [suburb] today. Interested?"
  - **Show estimated wait time:** "Typically, workers in [suburb] respond within 15 minutes" (like Uber's "Finding your driver")
  - Long-term: Predict demand patterns and nudge workers to be available at peak times
- **Priority:** 🔴 **MUST-HAVE for launch** — The UX for "no results" is critical for retention

### GAP 3.5 — Contractor doesn't pay
- **The problem:** Worker completes the job but contractor doesn't pay them. The current system has Stripe payments and escrow-like flow, but worker payment depends on contractor action.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Workers not getting paid is a platform killer. One bad experience and the worker (and all their mates) are gone.
- **The solution:**
  - **Pre-authorized payment hold:** When contractor hires a worker, Stripe holds the estimated amount (or at minimum, the $50 fee + estimated day's pay based on rate × estimated hours)
  - Worker logs hours → Contractor approves hours → Payment auto-releases
  - If contractor doesn't approve within 48 hours → Auto-release based on worker's logged hours (contractor can dispute within 7 days for refund)
  - **Future (insurance model):** RateRight guarantees payment to worker, then recovers from contractor. This is the ultimate trust builder but requires capital.
  - For launch: At minimum, the $50 fee should be charged upfront (on hire, not on post). Worker payment should be facilitated through platform, not left to contractor goodwill.
- **Priority:** 🔴 **MUST-HAVE for launch** (the payment hold + auto-release mechanism)

---

## 4. Matching Gaps

### GAP 4.1 — Location matching is text-based, not GPS
- **The problem:** Current system matches on `location` as a text string (e.g., `job.location.ilike(f'%{location}%')`). This is suburb name matching, not geographic matching. A worker in "Parramatta" won't match with a job in "North Parramatta" or "Granville" (5 min away). The matching algorithm checks `worker.location.lower() == job.location.lower()` — exact string match.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Broken matching is broken product. Workers 2km away won't show up because they typed their suburb differently.
- **The solution:**
  - **GPS-based matching:** Store lat/lng for both workers and jobs
  - Worker location: Real-time GPS from their phone (when online/available)
  - Job location: Geocoded from address, or pin-drop on map
  - Match by distance: Calculate haversine distance, sort by proximity
  - **Show estimated travel time** (Google Maps API): "25 min drive" is more useful than "15 km away"
  - Default radius: 30km (roughly 30-40 min drive in metro Sydney/Melbourne)
  - Allow contractor to set max radius: "I need someone within 30 minutes"
  - Allow worker to set max travel distance in preferences
- **Priority:** 🔴 **MUST-HAVE for launch** — Text-based matching fundamentally doesn't work for a location-based marketplace

### GAP 4.2 — No transport mode consideration
- **The problem:** Some workers don't have a car. They rely on public transport, which dramatically changes their effective radius. A job 15km away might be 20 min by car but 90 min by train+bus.
- **The impact:** ⭐⭐⭐ (3/5) — Workers accept jobs they can't realistically get to on time. Or workers with cars are shown the same jobs as workers on public transport.
- **The solution:**
  - Worker profile: "How do you get to work?" — Car / Public transport / Motorbike / Bicycle
  - Adjust effective matching radius based on transport mode:
    - Car: 30km default
    - Public transport: 15km default (or calculate using transit API)
    - Bicycle: 10km default
  - Job listing: "Own transport required: Yes/No" (already exists in Job model as `own_transport_required`)
  - Show workers estimated travel time based on their transport mode
- **Priority:** 🟡 **SHOULD-HAVE for launch** — Good for match quality but not blocking

### GAP 4.3 — Skill verification is self-reported
- **The problem:** Workers self-declare their trade ("I'm a steelfixer"). There's no verification that they can actually do the work. The current User model has `primary_trade` and `secondary_trade` as free-text fields. Anyone can write anything.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Contractor hires a "steelfixer" who can't tie reo. Safety risk on site. Bad reviews but the damage is done.
- **The solution:**
  - **Tiered verification system:**
    - **Level 0 — Unverified:** Self-declared trade. Shown with "Unverified" badge.
    - **Level 1 — ID Verified:** Identity confirmed (photo ID upload + selfie match). Trade still self-declared.
    - **Level 2 — License Verified:** Trade license/White Card uploaded and verified (manual review initially, OCR/API later). Shown with ✅ badge.
    - **Level 3 — Platform Verified:** Completed 5+ jobs with 4+ star average in that trade on RateRight. Shown with ⭐ badge.
  - Contractors can filter by verification level
  - **Mandatory for launch:** Level 1 (ID) to accept any job. Level 2 (License/White Card) to accept jobs that require it.
  - Long-term: Skills test or video portfolio review
  - **White Card verification:** Workers upload photo of card, admin verifies card number against state registry. NSW is moving to digital White Cards which could be API-verified in future.
- **Priority:** 🔴 **MUST-HAVE for launch** (at least Level 1 + White Card upload)

### GAP 4.4 — Rating system cold start problem
- **The problem:** New workers and contractors have zero ratings. Nobody wants to be the first to hire an unrated worker. Nobody wants to work for an unrated contractor. The current matching algorithm gives 20% weight to ratings — new users score 0 on this dimension.
- **The impact:** ⭐⭐⭐⭐ (4/5) — New users can't get their first job, get frustrated, leave. Platform growth stalls.
- **The solution:**
  - **"New to RateRight" badge** — positive framing, not negative (not "Unrated" but "New")
  - **Introductory rate discount** — new workers can offer a 10% lower rate for first 3 jobs to attract contractors
  - **Profile completeness score** replaces ratings for new users: Photo, bio, trade details, certifications, portfolio photos = higher match score
  - **Reference from outside platform:** Workers can add references from previous employers (phone number for verification)
  - **Guaranteed match:** First 5 jobs, RateRight manually helps match (concierge onboarding for early users)
  - **Matching algorithm adjustment:** For new users, replace rating weight with profile completeness + verification level
  - **"Try a new worker" incentive for contractors:** "$25 off your next hire when you rate a new worker" (their first 3 hires of new workers get 50% off the $50 fee)
- **Priority:** 🔴 **MUST-HAVE for launch** — You're launching with 100% new users. This is DAY ONE problem.

### GAP 4.5 — Matching algorithm is too basic
- **The problem:** Current matching (`matching/routes.py`) uses a simple scoring: trade match (40%), location (20%), rating (20%), experience (20%). This is static, not contextual. Doesn't consider urgency, worker response speed, historical match success, time of day, or contractor preferences.
- **The impact:** ⭐⭐⭐ (3/5) — Suboptimal matches reduce satisfaction for both sides.
- **The solution:**
  - Phase 1 (launch): Keep it simple but add:
    - Distance-based scoring (GPS) replacing text location match
    - Availability-based scoring (is worker 🟢 right now?)
    - Response time scoring (workers who accept fast get priority)
  - Phase 2: Add ML-based matching:
    - Historical success: Workers who've been re-hired by same contractor score higher
    - Cancel/no-show probability: Workers with high reliability score rank higher
    - Time-of-day patterns: Worker is usually available on Tuesdays → boost for Tuesday jobs
  - Phase 3: Full recommendation engine with A/B testing
- **Priority:** 🟡 **Phase 1 MUST-HAVE, Phase 2-3 nice-to-have**

---

## 5. Trust & Safety

### GAP 5.1 — Identity verification doesn't exist
- **The problem:** Current User model stores `abn_number` and `white_card_number` but there's no verification flow. Anyone can type any ABN or White Card number. No photo ID check. No selfie verification.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Fake profiles, identity fraud, safety risk on construction sites, legal liability for RateRight.
- **The solution:**
  - **Mandatory for all users:**
    - Email verification ✅ (exists)
    - Phone verification via SMS OTP (doesn't exist)
    - ABN verification via ABR API (free, government API — validates ABN is active and matches business name)
  - **Mandatory for workers:**
    - Photo ID upload (driver's license or passport)
    - Selfie verification (take a selfie that matches the ID photo — use a service like Onfido, Veriff, or OCR Labs which is Australian)
    - White Card upload + number verification (for construction workers)
  - **Mandatory for contractors:**
    - Business verification: ABN + business name match
    - At least one completed project or reference to activate account
  - **Nice-to-have:**
    - Police check integration (national police check API)
    - Working with children check (if applicable)
  - Use **OCR Labs** (Australian company) or **Onfido** for ID verification — both handle Australian documents
- **Priority:** 🔴 **MUST-HAVE for launch** — Non-negotiable for construction industry trust

### GAP 5.2 — White Card / license verification is manual at best
- **The problem:** The safety routes check `white_card_verified` as a boolean flag but there's no automated verification. Someone sets it to true and it's trusted. White Cards are state-issued and different formats across states.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Workers without valid White Cards on construction sites = illegal + dangerous + $10K+ fines for the contractor.
- **The solution:**
  - **Photo upload of White Card** with OCR to extract card number, name, expiry
  - **Manual verification** initially (admin reviews uploaded cards — takes 24 hours)
  - Cross-reference with state safety regulators where possible:
    - NSW SafeWork: Digital White Card program underway
    - VIC WorkSafe: Verify via their portal
    - QLD WHSQ: Online verification available
  - **Expiry tracking:** Auto-notify workers 30 days before White Card expires. Disable matching if expired.
  - **Trade license verification:** Electricians, plumbers, gasfitters etc. need specific licenses. Build trade-specific verification for licensed trades.
  - Store verification status with expiry date, not just boolean
- **Priority:** 🔴 **MUST-HAVE for launch** (photo upload + manual review minimum)

### GAP 5.3 — Insurance and liability framework is incomplete
- **The problem:** User model has `public_liability_insurance` (boolean), `public_liability_amount`, `workers_comp_insurance`, `insurance_expiry_date`. But there's no verification, no minimum requirements, and RateRight's own liability as a platform is undefined.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — If a worker gets hurt on site and has no insurance, who's liable? If property gets damaged, who pays? This is a legal minefield.
- **The solution:**
  - **For workers:**
    - Public liability insurance: Recommended but not required for general labourers, REQUIRED for licensed trades
    - Upload insurance certificate, admin verifies (or API with major insurers)
    - Workers' comp: Platform must be clear that workers are INDEPENDENT CONTRACTORS, not employees (sham contracting risk — see below)
  - **For contractors:**
    - Must have site insurance that covers all workers on site
    - Platform should display: "As the PCBU (Person Conducting Business or Undertaking), you are responsible for worker safety under WHS Act 2011"
  - **For RateRight:**
    - Clear Terms of Service: RateRight is a marketplace, not a labour hire company or employer
    - Legal advice needed on: Does facilitating the match create any employer obligation?
    - Platform liability insurance (professional indemnity + public liability)
    - **Sham contracting risk:** If RateRight controls too much of the work relationship (rate, hours, how work is done), workers could be classified as employees, not contractors. The ICA (Independent Contractor Agreement) template in the codebase helps, but the Uber-like UX (accept jobs, GPS check-in, platform-controlled matching) could blur the line. **Get legal advice on this.**
  - **Disclaimer on every contract:** Both parties acknowledge the independent contractor relationship
- **Priority:** 🔴 **MUST-HAVE for launch** — Legal risk is existential. Get proper legal advice.

### GAP 5.4 — Dispute resolution is too basic
- **The problem:** Current dispute system (`contract_dispute/routes.py`) only has mutual "agree to resolve" — both parties click agree, dispute resolved. No actual resolution mechanism. No mediation. No evidence collection. No escalation path.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Real disputes (hours worked, quality of work, payment) need actual resolution, not just "both agree."
- **The solution:**
  - **Tiered dispute resolution:**
    - **Tier 1 — In-app discussion:** Both parties chat about the issue. Resolution proposed by each side. If they agree → resolved.
    - **Tier 2 — Platform mediation:** RateRight support reviews evidence (photos, time logs, messages). Makes a recommendation within 48 hours.
    - **Tier 3 — External mediation:** For disputes over $500, offer connection to NSW Fair Trading or equivalent state body. Or use an online dispute resolution service.
  - **Evidence collection:** During active jobs, encourage both parties to log progress photos. These become evidence in disputes.
  - **Financial resolution options:**
    - Full payment to worker
    - Partial payment (platform suggests based on hours confirmed)
    - Full refund to contractor
    - Split (50/50 or custom)
  - **Timeline:** All disputes must be raised within 7 days of job completion
- **Priority:** 🟡 **SHOULD-HAVE for launch** (Tier 1 at minimum, Tier 2 within 3 months)

### GAP 5.5 — No harassment / behavior reporting
- **The problem:** No mechanism for reporting harassment, inappropriate behavior, unsafe conditions, or abuse. Construction sites have well-documented culture issues. Workers (especially women and minorities entering the trade) need protection.
- **The impact:** ⭐⭐⭐⭐ (4/5) — One bad experience with no recourse = worker leaves and tells everyone. Legal exposure for platform.
- **The solution:**
  - **Report button** accessible at all times during active job: "Report a safety concern" or "Report behavior"
  - Categories: Harassment, discrimination, unsafe conditions, verbal abuse, physical threat, sexual harassment
  - Reports go to dedicated queue (not just general support)
  - **Zero tolerance policy:** Verified harassment = permanent ban. No warnings.
  - **Anonymous reporting option** — workers shouldn't fear retaliation
  - Response time SLA: All safety reports reviewed within 4 hours during business hours
  - Keep records for potential legal proceedings
- **Priority:** 🔴 **MUST-HAVE for launch** — Legal obligation under WHS Act + moral imperative

### GAP 5.6 — Worker safety on site
- **The problem:** Once a worker arrives at a site, the platform loses visibility. If something goes wrong (injury, dangerous conditions), there's no quick way to raise an alarm or get help.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Worker safety is paramount. A serious injury with no platform safety net is catastrophic for the worker AND the platform's reputation.
- **The solution:**
  - **Emergency SOS button** in the app (always visible during active job)
    - Tapping it: Shares GPS location + contacts emergency services (000) + notifies RateRight support + notifies emergency contact set in profile
  - **Safety check-ins:** For long jobs (>4 hours), prompt worker "Everything going OK?" every 4 hours
  - **Pre-job safety brief:** Mandatory WHS checklist before starting work (already partially built in safety routes — make it mobile-friendly and fast)
  - **Emergency contact field** in worker profile (mandatory)
  - **Site safety rating:** After each job, worker rates site safety (anonymous, shown to future workers)
- **Priority:** 🟡 **SHOULD-HAVE for launch** (Emergency SOS is MUST-HAVE, rest can follow)

---

## 6. Communication Gaps

### GAP 6.1 — In-app messaging exists but has gaps
- **The problem:** Messaging system exists (`messages/routes.py`) with text + file attachments, but it's API-only with no real-time component (no WebSocket/SSE). Messages are polled via API. No read receipts. No typing indicators. No message templates for common scenarios.
- **The impact:** ⭐⭐⭐ (3/5) — Slow messaging means people exchange phone numbers and communicate off-platform. Once off-platform, the platform loses value and control.
- **The solution:**
  - **Real-time messaging** via WebSocket (Socket.IO or Pusher/Ably)
  - **Read receipts** — contractor needs to know worker saw the message
  - **Quick-reply templates:** "On my way", "Running 15 min late", "Arrived on site", "Job complete"
  - **Phone number masking:** Show a proxy number so parties can call/text without sharing personal numbers (like Uber's masked calling)
  - **Auto-messages from platform:** "Worker is on their way (ETA 25 min)", "Worker has checked in at the site", "Job has been completed"
  - Keep communication in-app as much as possible for dispute evidence
- **Priority:** 🟡 **SHOULD-HAVE for launch** — Basic messaging works, real-time is important but not blocking

### GAP 6.2 — Hours dispute has no resolution mechanism
- **The problem:** Worker logs 8 hours, contractor says they only worked 6. Time tracking exists (`hours_routes.py`, `time_tracking_service`) but relies on manual entry. No GPS-based or clock-in/clock-out automated tracking. When there's a disagreement, it's word vs. word.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Payment disputes over hours are the #1 dispute type in construction. Without evidence, these are unresolvable.
- **The solution:**
  - **Clock-in / Clock-out** with GPS verification:
    - Worker taps "Start work" → GPS confirms they're at job site → Clock starts
    - Worker taps "End work" → GPS confirms → Clock stops
    - Break tracking: "Start break" / "End break" buttons
    - Generates automatic timesheet
  - **Contractor confirmation:** Contractor gets a notification to confirm hours at end of each day
  - If contractor doesn't confirm within 24 hours → Worker's logged hours are auto-approved
  - **Photo evidence:** Worker can take timestamped progress photos throughout the day (GPS + time embedded)
  - **Manual override:** Both parties can edit with reason (all edits logged and visible to both)
  - This becomes the source of truth for payment calculation
- **Priority:** 🔴 **MUST-HAVE for launch** — Without this, every payment is a potential dispute

### GAP 6.3 — Job completion requires both-party confirmation but flow is unclear
- **The problem:** Current system has `completion_status` on contracts and requires both parties to rate before marking complete. But the actual "is this job done?" confirmation is buried in the rating flow, not a distinct action. What if the contractor says "not done" but the worker says "done"?
- **The impact:** ⭐⭐⭐ (3/5) — Ambiguous completion state holds up payments and ratings.
- **The solution:**
  - **Explicit completion flow:**
    1. Worker taps "Mark job complete"
    2. Contractor gets notification: "Worker says the job is complete. Confirm?"
    3. Contractor taps "Confirm" or "Not complete — [reason]"
    4. If confirmed → Both parties rate → Payment releases
    5. If "Not complete" → Platform mediates (what's remaining? Photo evidence?)
  - **Auto-complete:** If contractor doesn't respond to completion confirmation within 48 hours → Auto-confirmed
  - For multi-day jobs: Daily sign-off + final completion
- **Priority:** 🟡 **SHOULD-HAVE for launch**

---

## 7. Payment Gaps

### GAP 7.1 — When the $50 fee gets charged is undefined
- **The problem:** The business model says "$50 per hire" but the codebase doesn't clearly define WHEN this is charged. Is it when the job is posted? When a worker is matched? When the worker accepts? When work begins?
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — This is the revenue model. Getting it wrong means either: (a) charging too early and refunding constantly, or (b) charging too late and people gaming the system.
- **The solution:**
  - **Charge on successful match/hire** — when contractor confirms the worker and the worker accepts:
    - Pre-auth the $50 when contractor posts a job (card on file required)
    - Capture the $50 when worker accepts and grace period expires (5 minutes)
    - If job is cancelled within grace period → release pre-auth
    - If worker no-shows → full refund
    - If contractor cancels after grace → credit toward next hire (not cash refund — retains revenue)
  - **Never charge on post** — too early, too many refunds
  - **Never charge on completion** — too late, contractor may ghost
  - **Display clearly:** "A $50 booking fee will be charged when your worker confirms"
- **Priority:** 🔴 **MUST-HAVE for launch** — This is your revenue. Nail it.

### GAP 7.2 — Worker payment flow is undefined
- **The problem:** The current system implies contractors pay workers directly (the platform just facilitates the connection). But there's Stripe Connect integration on the User model (`stripe_account_id`, `stripe_onboarding_complete`, `stripe_payouts_enabled`). The intent seems to be platform-facilitated payments, but it's not fully built.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — If workers don't get paid reliably through the platform, the platform adds no value. If it's direct contractor→worker payment, the platform is just a job board.
- **The solution:**
  - **Phase 1 (Launch — MVP):**
    - Workers set their hourly/daily rate
    - Platform shows contractor the total cost estimate (rate × hours + $50 fee)
    - **Payment facilitated through platform** but not escrowed:
      - Contractor pays worker directly (bank transfer, cash on site) — platform tracks but doesn't handle the money
      - $50 fee charged to contractor via Stripe
      - Worker confirms payment received in app
    - This is simpler but has trust issues
  - **Phase 2 (3-6 months):**
    - **Full payment through platform:**
      - Contractor's card charged: (worker rate × confirmed hours) + $50 fee
      - Worker gets paid via Stripe Connect to their bank account within 2-3 business days
      - Platform takes $50, passes through the rest
    - This requires Stripe Connect marketplace setup (already started based on User model)
    - More trust, more control, better dispute resolution
  - **Phase 3 (6-12 months):**
    - **Instant payout** for workers (Stripe Instant Payouts — worker gets money same day)
    - This is a HUGE competitive advantage for attracting workers
  - **Recommendation:** Skip Phase 1. Go straight to Phase 2. Platform-facilitated payment is essential for the Uber-like experience and trust.
- **Priority:** 🔴 **MUST-HAVE for launch** — At minimum Phase 1, ideally Phase 2

### GAP 7.3 — Refund policy doesn't exist
- **The problem:** No defined refund policy for the $50 fee under various scenarios.
- **The impact:** ⭐⭐⭐⭐ (4/5) — Support will be flooded with "I want my money back" without clear policies.
- **The solution:**
  - **Clear refund matrix:**

    | Scenario | $50 Refund? | Worker Compensated? |
    |----------|-------------|---------------------|
    | Cancel within 5-min grace | ✅ Full refund | No (they weren't counting on it) |
    | Contractor cancels >24h before | ❌ Credit for next hire | No |
    | Contractor cancels <24h before | ❌ No refund | ✅ Minimum compensation |
    | Worker no-shows | ✅ Full refund | No |
    | Worker cancels >24h before | ✅ Full refund | No |
    | Worker cancels <24h before | ✅ Full refund | No |
    | Both complete job normally | ❌ Fee earned | ✅ Full payment |
    | Dispute (resolved in contractor's favor) | ✅ Full refund | Partial/no payment |
    | Dispute (resolved in worker's favor) | ❌ Fee earned | ✅ Full payment |

  - Display refund policy in FAQ and at point of purchase
  - Automate refunds where possible (no manual intervention)
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 7.4 — GST handling is unclear
- **The problem:** Australian GST is 10%. The $50 fee needs to include or exclude GST. Worker payments may or may not include GST depending on whether the worker is GST-registered (User model has `gst_registered` boolean). Invoicing requirements are unclear.
- **The impact:** ⭐⭐⭐⭐ (4/5) — ATO compliance is not optional. Getting this wrong = audits, fines, angry accountants.
- **The solution:**
  - **$50 fee:** Should be $50 including GST ($45.45 + $4.55 GST). RateRight must be GST registered and issue a Tax Invoice for every $50 fee.
  - **Worker rates:** Workers set their rate. If they're GST-registered, their invoices to contractors include GST. If not, no GST.
  - **Platform responsibilities:**
    - Issue Tax Invoice for the $50 fee to contractor
    - If platform facilitates payment: Issue RCTI (Recipient Created Tax Invoice) on behalf of the worker, or provide the worker's invoice to the contractor
    - Track GST on all transactions for BAS reporting
  - **Display:** Show rates as "ex-GST" or "inc-GST" clearly. Construction industry typically works ex-GST.
  - **ABN verification:** Already have ABN field — verify it's active via ABR API. If ABN is invalid, block user from transacting.
  - **Stripe integration:** Stripe can handle GST calculation and invoice generation via Stripe Tax
  - **Consult an accountant** — tax compliance is complex and must be right from day one
- **Priority:** 🔴 **MUST-HAVE for launch** — Legal requirement

---

## 8. Scalability Gaps

### GAP 8.1 — System architecture won't scale beyond ~500 concurrent users
- **The problem:** Current stack is Flask (synchronous, single-threaded by default), SQLite or PostgreSQL (unclear), no caching layer, no CDN, no async task queue. The matching algorithm queries ALL workers for each match request. Notifications are polled via API every 30 seconds.
- **The impact:** ⭐⭐⭐ (3/5) — Won't be a problem at launch (10-100 users) but will become critical at 1000+ users. More importantly, the architecture decisions made now determine how painful scaling will be later.
- **The solution:**
  - **For launch (10-100 users):**
    - Flask + PostgreSQL + Gunicorn with 4 workers = fine
    - Add Redis for caching frequently-accessed data (available workers, job listings)
    - Add Celery for background tasks (notifications, email, matching)
  - **For 1000 users:**
    - Move matching to a background service with PostGIS for geo-queries
    - WebSocket server for real-time messaging and notifications (separate from main app)
    - CDN for static assets
    - Database read replicas
  - **For 10,000+ users:**
    - Microservices: Matching service, Payment service, Notification service, Chat service
    - Consider rewriting hot paths in a faster language (Go, Rust) or using managed services
    - Geographic sharding (Sydney cluster, Melbourne cluster, etc.)
  - **Key decision: Should the rebuild be Flask or something else?**
    - If going mobile-first with React Native or Flutter → Build a proper REST API (FastAPI is a better choice than Flask for new builds — async, auto-docs, faster)
    - If sticking with web → Next.js or similar for the frontend
- **Priority:** 🟢 **NICE-TO-HAVE for launch** (but make architecture decisions that don't block future scaling)

### GAP 8.2 — No strategy for seeding a new city
- **The problem:** RateRight works in one city at a time. You can't launch "nationally" because the marketplace needs density. But how do you launch in a new city when you have zero workers and zero contractors there?
- **The impact:** ⭐⭐⭐⭐ (4/5) — Growth will be limited to one metro area without a seeding strategy.
- **The solution:**
  - **Phase 1: Sydney (or one metro area) only**
    - Focus ALL effort on one city
    - Don't even show other cities in the app
    - Build density: Target 50 workers and 20 contractors as minimum viable marketplace
  - **Seeding playbook for new cities:**
    1. **Supply first (workers):** Partner with TAFE/training centres, attend construction job fairs, post on Gumtree/Facebook construction groups. Offer "$100 sign-up bonus for first 50 workers" (cost: $5,000 per city).
    2. **Demand next (contractors):** Door-to-door to construction sites. Offer first 3 hires free ($50 fee waived). Target small-to-medium builders who struggle to find casual labour.
    3. **Events:** "RateRight Launch BBQ" at a local pub near construction areas. Sign up workers and contractors face-to-face.
    4. **Geo-fence the launch:** Only activate matching in the new city once you have 20+ workers and 10+ contractors registered.
  - **Chicken-and-egg tactics (from marketplace playbook):**
    - **Single-player mode:** Make the app useful for workers even without contractors (job alerts from other platforms, skill badges, portfolio builder)
    - **Fake it til you make it:** Manually match the first 50 jobs (concierge service). Call workers, confirm availability, text contractors. The tech automates later; the match quality matters now.
    - **Anchor tenant:** Sign one large builder who needs 10+ workers/week. They provide consistent demand; you recruit workers to fill their needs.
- **Priority:** 🟡 **SHOULD-HAVE for launch** (strategy needed, execution comes later)

### GAP 8.3 — No analytics or marketplace health metrics
- **The problem:** Current analytics routes exist but it's unclear what's tracked. For a marketplace, you NEED to monitor supply/demand balance in real-time.
- **The impact:** ⭐⭐⭐ (3/5) — Flying blind = can't identify problems before users complain.
- **The solution:**
  - **Key metrics dashboard:**
    - **Supply:** Active workers (🟢 today), by trade, by area
    - **Demand:** Jobs posted today, urgent vs scheduled, by trade, by area
    - **Match rate:** % of jobs that get matched within 1 hour
    - **Fill rate:** % of posted jobs that get completed
    - **Time-to-match:** Average minutes from post to worker accepting
    - **No-show rate:** % of accepted jobs where worker doesn't show
    - **Cancellation rate:** % by each side, with timing breakdown
    - **NPS/satisfaction:** Post-job rating averages
    - **Revenue:** $50 fees collected, refunds issued, net revenue
  - **Alerts:** Auto-alert if supply drops below threshold in any area ("Only 2 workers available in Western Sydney — consider recruitment push")
- **Priority:** 🟡 **SHOULD-HAVE for launch** (basic metrics; full dashboard in month 2)

---

## 9. Competitive Comparison

### Uber — What to steal
| Feature | Uber Does It | RateRight Should Do |
|---------|-------------|-------------------|
| **One-tap request** | ✅ Rider taps destination, confirms pickup | ✅ Contractor selects trade + location, confirms |
| **Real-time GPS matching** | ✅ Nearest available driver | ✅ Nearest available worker with right trade |
| **ETA display** | ✅ "Driver arriving in 3 min" | ✅ "Worker can start in 25 min" (if urgent) |
| **Surge pricing** | ✅ Dynamic based on demand | ❌ Not for launch. Workers set their own rate. |
| **Driver rating after trip** | ✅ Mandatory 1-5 stars | ✅ Mandatory rating after job completion |
| **Swipe to accept** | ✅ Prevents accidental accepts | ✅ Must implement |
| **Cancellation fees** | ✅ Charged after grace period | ✅ Must implement (see GAP 1.4) |
| **Masked phone numbers** | ✅ Proxy calling | 🟡 Should implement for privacy/safety |
| **In-app navigation** | ✅ Google Maps integration | ✅ Show worker directions to job site |
| **Payment auto-deducted** | ✅ No cash handling | ✅ Must have (see GAP 7.2) |

### Airtasker — What to steal
| Feature | Airtasker Does It | RateRight Should Do |
|---------|-------------------|-------------------|
| **Task posting** | ✅ Free to post, pay on completion | ✅ Free to post, $50 on hire |
| **Bidding/quoting** | ✅ Workers bid on tasks | ❌ Not for construction — too slow. Instant matching. |
| **Escrow payment** | ✅ Airtasker holds money until completion | ✅ Yes (Phase 2) |
| **Insurance coverage** | ✅ Airtasker Insurance for tasks up to $X | 🟡 Consider for v2 |
| **Reviews visible before hire** | ✅ Full review history | ✅ Already planned |
| **Cancellation fee** | ✅ 5% fee for late cancel | ✅ Implement tiered cancellation |
| **Mobile app** | ✅ Native iOS + Android | ✅ Must have |
| **Categories** | ✅ Hundreds of task types | ✅ Focus on construction trades only (sharper value prop) |

### Hipages — What to steal
| Feature | Hipages Does It | RateRight Should Do |
|---------|----------------|-------------------|
| **License verification** | ✅ Checks ABN + trade licenses | ✅ Must implement (see GAP 5.2) |
| **Up to 3 tradies matched** | ✅ Customer gets 3 quotes | ❌ For urgent: 1 match (Uber model). For scheduled: show top 3-5. |
| **Tradie profile with photos** | ✅ Portfolio of past work | ✅ Portfolio already partially built. Make it mobile-first. |
| **Lead-based pricing** | ✅ Tradies pay per lead ($15-50) | ❌ RateRight charges contractor, not worker. Key differentiator. |
| **Job management tools** | ✅ Quote, invoice, schedule | 🟡 Future feature — keep initial scope tight |
| **Verified badges** | ✅ License + insurance verified | ✅ Must implement tiered verification |

### Workmate/Sidekicker — What to steal (MOST RELEVANT COMPETITORS)
| Feature | Sidekicker Does It | RateRight Should Do |
|---------|-------------------|-------------------|
| **Shift-based matching** | ✅ Workers grab shifts | ✅ Exactly this model for urgent jobs |
| **Worker vetting** | ✅ Interview + verification before activation | 🟡 Lighter touch for scale, but minimum ID verification |
| **Timesheet management** | ✅ In-app clock-in/clock-out | ✅ Must implement (see GAP 6.2) |
| **Payment through platform** | ✅ Sidekicker pays workers directly | ✅ Phase 2 goal |
| **Native mobile app** | ✅ Separate worker and hirer apps | 🟡 Consider: Single app with role-based views vs two apps. One app is simpler to build and maintain. |
| **SEEK integration** | ✅ $20M investment from SEEK | 🟡 Future: syndicate job posts to Seek/Indeed |

### Yakka Labour — What to steal (CLOSEST COMPETITOR IN CONSTRUCTION)
| Feature | Yakka Does It | RateRight Should Do |
|---------|--------------|-------------------|
| **Construction-specific** | ✅ Focused on construction + hospitality | ✅ RateRight should be EVEN MORE focused (construction only) |
| **Shift management** | ✅ Post and fill shifts in minutes | ✅ Core feature |
| **Verified workers** | ✅ Local, verified | ✅ Must match or exceed |
| **Timesheet + payment** | ✅ In-app | ✅ Must match |
| **Both iOS + Android** | ✅ Native apps | ✅ Must have |

### Key Competitive Insights:
1. **Yakka Labour is the #1 direct competitor** — they do construction labour hire with an app. RateRight must differentiate through: simpler UX (fewer taps), lower contractor cost ($50 flat vs percentage), worker-friendly model (keep 100% of rate).
2. **No competitor has nailed the "Uber for tradies" instant-matching UX** — they all still rely on posting → applying → reviewing. This is RateRight's opportunity.
3. **Sidekicker is the model to study for operations** — they've scaled to $20M+ in funding. Their shift-based, payment-through-platform approach is what RateRight should build toward.
4. **Hipages/ServiceSeeking are NOT direct competitors** — they're for homeowners hiring tradies for one-off jobs. RateRight is for builders hiring casual labour. Different market.

---

## 10. Mobile / App Gaps

### GAP 10.1 — PWA vs Native App decision
- **The problem:** Current app is a Flask web app with HTML templates. No mobile app exists. The "Uber-like" experience REQUIRES a mobile app. Decision needed: PWA or native?
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Wrong choice here affects everything: development speed, user experience, push notifications, GPS reliability, offline capability, app store presence.
- **The solution:**
  - **Recommendation: React Native (or Flutter) for native apps**
  - Why NOT PWA:
    - Push notifications on iOS are still unreliable for PWAs (only since iOS 16.4, requires user to add to home screen first — most won't)
    - Background GPS tracking (for worker check-in verification) doesn't work in PWAs
    - Camera access for document uploads is limited
    - No app store presence = lower trust for tradies ("if it's not in the App Store, it's not real")
    - Construction workers are not tech-savvy — "download the app" is easier to explain than "go to website, tap share, tap add to home screen"
  - Why React Native over pure native:
    - One codebase for iOS + Android (80% code sharing)
    - Faster development (1 team, not 2)
    - JavaScript ecosystem is large — easier to hire
    - Expo framework makes push notifications, GPS, camera trivially easy
  - **Architecture:**
    - Mobile app (React Native) = the primary user interface
    - Backend API (FastAPI or Flask-RESTful) = serves the mobile app
    - Web app = admin dashboard only (or a simplified version for contractors who prefer desktop)
  - **Timeline consideration:** React Native MVP can be built in 8-12 weeks by a small team (2-3 developers)
- **Priority:** 🔴 **MUST-HAVE for launch** — This IS the product

### GAP 10.2 — Push notifications don't exist
- **The problem:** Current notification system (`notifications/routes.py`) is API-polling based — client checks for new notifications every 30 seconds. No push notifications to mobile devices. For an Uber-like experience, workers NEED instant push notifications for new job matches.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — Without push notifications, the "instant matching" flow doesn't work. Worker has to have the app open and actively checking. That's not how construction workers use their phones.
- **The solution:**
  - **Firebase Cloud Messaging (FCM)** for Android push notifications
  - **Apple Push Notification Service (APNs)** for iOS push notifications
  - **Expo Push Notifications** (if using Expo/React Native) — abstracts both FCM and APNs
  - **Critical push notifications:**
    - "New job match: [Trade] at [Location] — Accept now!" (time-sensitive, high priority)
    - "Your worker is on their way (ETA 25 min)"
    - "Job starting in 1 hour — don't forget!"
    - "Worker marked job complete — confirm and pay"
    - "You have a new message from [Name]"
  - **Notification preferences:** Let users control what they get notified about (but default everything ON)
  - **Sound/vibration:** Use distinct notification sounds for job matches vs messages vs reminders
  - **Rich notifications:** Show job details in the notification itself (trade, location, rate, hours) so worker can decide without opening the app
- **Priority:** 🔴 **MUST-HAVE for launch** — Non-negotiable

### GAP 10.3 — Offline capability for construction sites
- **The problem:** Construction sites often have poor mobile signal. Workers may be in basements, tunnels, or remote sites. If the app requires constant internet, workers can't check in, log hours, or communicate.
- **The impact:** ⭐⭐⭐ (3/5) — Annoying but not blocking for most urban construction. More critical for regional/rural sites.
- **The solution:**
  - **Offline-first for critical actions:**
    - Clock-in/clock-out: Queue locally, sync when online
    - Time entries: Save locally, sync when connection returns
    - Messages: Queue outgoing messages, deliver when online
    - Job details: Cache accepted job details for offline viewing
  - **NOT needed offline:**
    - Job searching/matching (needs real-time data)
    - Payment processing
    - New job posting
  - **Implementation:** Use React Native's built-in async storage + background sync
  - **Visual indicator:** Show "📶 Offline — data will sync when connected" banner
- **Priority:** 🟡 **SHOULD-HAVE for launch** (basic offline for clock-in; full offline v2)

### GAP 10.4 — GPS and location services
- **The problem:** Current app has no GPS functionality. Location is a text field. For the Uber-like experience, you need real-time GPS for: worker location (when online), job site location, distance calculation, check-in verification, travel time estimation.
- **The impact:** ⭐⭐⭐⭐⭐ (5/5) — GPS is foundational to the entire matching experience.
- **The solution:**
  - **Worker side:**
    - Request GPS permission on signup (explain why: "So we can match you with nearby jobs")
    - When worker goes 🟢 Available: Track location in background (low-power mode, update every 5 min)
    - When worker accepts a job: Track more frequently for ETA calculation
    - When worker arrives at site: Geofence check-in (within 200m of job location = auto check-in option)
  - **Contractor side:**
    - Job posting: Auto-detect current location OR enter address → geocode to lat/lng
    - Show worker location on map after match (like watching your Uber approach)
  - **Privacy:**
    - Workers can see exactly when their location is being shared
    - Location sharing stops when worker goes 🔴 offline
    - Don't store historical location data beyond 7 days
    - Show clear privacy policy about location data
  - **Tech:** React Native's expo-location + Google Maps/Mapbox for display + PostGIS for distance queries on backend
- **Priority:** 🔴 **MUST-HAVE for launch**

### GAP 10.5 — Camera for document uploads
- **The problem:** Workers need to upload: White Card photo, driver's license, insurance certificates, profile photo, portfolio/work photos, progress photos during jobs. Current system has file upload (`file_upload.py` model) but no mobile-optimized camera flow.
- **The impact:** ⭐⭐⭐ (3/5) — Clunky document upload = workers abandon onboarding.
- **The solution:**
  - **Native camera integration:** Open camera directly for document captures (not "choose from gallery" — take a new photo)
  - **Document scanning mode:** Auto-crop, perspective correction for cards/certificates (like most banking apps)
  - **Auto-OCR:** Extract text from White Card, driver's license (name, number, expiry)
  - **Compress before upload:** Construction workers often have limited data plans. Compress images to 500KB before uploading.
  - **Progress during upload:** Show upload progress bar with retry on failure
  - React Native: expo-camera + expo-image-manipulator handles all of this
- **Priority:** 🟡 **SHOULD-HAVE for launch** (basic camera upload is MUST-HAVE, OCR is nice-to-have)

---

## 11. Summary: Priority Matrix

### 🔴 MUST-HAVE for Launch (Build These First)

| # | Gap | What to Build |
|---|-----|--------------|
| 1.1 | No grace period after accept | 5-min undo window + swipe-to-accept |
| 1.2 | Accidental hire | Confirmation screen + cancellation window |
| 1.4 | No undo/cancel flow | Tiered cancellation system with time-based rules |
| 1.5 | Undefined consequences | Reliability score system |
| 2.1 | No real-time availability | Three-state toggle (Available/Later/Offline) |
| 2.2 | No no-show handling | Check-in system + backup matching + consequences |
| 2.3 | Worker cancel after accept | Tiered cancellation + replacement matching |
| 3.1 | No urgent/same-day jobs | "Need someone NOW" flow with broadcast matching |
| 3.2 | Contractor cancel rules | Tiered cancellation with worker compensation |
| 3.4 | No workers available | Waitlist + expanded search + notifications |
| 3.5 | Contractor doesn't pay | Pre-auth payment hold + auto-release |
| 4.1 | Text-based location | GPS matching with distance/travel time |
| 4.3 | Self-reported skills | Tiered verification (ID + White Card minimum) |
| 4.4 | Rating cold start | "New" badge + profile completeness + incentives |
| 5.1 | No identity verification | ID upload + selfie + ABN verification |
| 5.2 | No White Card verification | Photo upload + manual review + expiry tracking |
| 5.3 | Insurance/liability unclear | Clear framework + legal advice + disclaimers |
| 5.5 | No harassment reporting | Report button + zero tolerance + response SLA |
| 6.2 | Hours disputes | GPS clock-in/out + contractor confirmation |
| 7.1 | $50 fee timing | Charge on hire (after grace period) |
| 7.2 | Worker payment undefined | Platform-facilitated payment via Stripe Connect |
| 7.3 | No refund policy | Clear refund matrix for all scenarios |
| 7.4 | GST unclear | Proper GST handling + Tax Invoices |
| 10.1 | No mobile app | React Native (iOS + Android) |
| 10.2 | No push notifications | FCM + APNs via Expo |
| 10.4 | No GPS | Full location services integration |

**Total must-haves: 27 items**

### 🟡 SHOULD-HAVE for Launch (Build Within 3 Months)

| # | Gap | What to Build |
|---|-----|--------------|
| 1.3 | Accidental job post | Draft state + review screen + 15-min delete |
| 2.4 | Sick mid-job | Report issue flow + WHS documentation |
| 2.5 | Availability too complex | Simplify to daily toggle + optional schedule |
| 3.3 | Worker performance mid-job | Report issue + early termination flow |
| 4.2 | No transport consideration | Transport mode in profile + radius adjustment |
| 4.5 | Basic matching algorithm | Add distance/availability/response time scoring |
| 5.4 | Basic dispute resolution | Tiered mediation system |
| 5.6 | Worker safety on site | Emergency SOS button + safety check-ins |
| 6.1 | No real-time messaging | WebSocket messaging + quick replies |
| 6.3 | Unclear completion flow | Explicit completion confirmation + auto-confirm |
| 8.2 | No city seeding strategy | Seeding playbook + launch plan |
| 8.3 | No marketplace metrics | Health dashboard with key metrics |
| 10.3 | No offline capability | Offline clock-in + cached job details |
| 10.5 | Camera for documents | Native camera + document scan + compression |

**Total should-haves: 14 items**

### 🟢 NICE-TO-HAVE (Build in 6-12 Months)

| # | Gap | What to Build |
|---|-----|--------------|
| 8.1 | Scalability architecture | Microservices, Redis, Celery, PostGIS |
| - | ML-based matching | Historical success, cancel prediction |
| - | Instant payouts | Stripe Instant Payouts for workers |
| - | Surge pricing | Dynamic pricing based on demand |
| - | Calendar sync | Google/Outlook calendar integration |
| - | Police check integration | Automated background checks |
| - | Multi-city auto-scaling | Geographic sharding, regional dashboards |
| - | SEEK/Indeed syndication | Post jobs to external boards |
| - | Platform insurance | Airtasker-style task insurance |
| - | Video portfolio | Workers upload work videos |

---

## Key Decisions Needed Before Building

1. **Tech stack for rebuild:** React Native + FastAPI recommended. Need to decide.
2. **Single app or two apps?** One app with worker/contractor role switching is simpler. Sidekicker has two apps. Uber has one. **Recommendation: One app.**
3. **Payment through platform or direct?** Phase 2 (through platform) is strongly recommended for launch. Need to decide.
4. **Legal structure:** Is RateRight a marketplace or a labour hire agency? This affects everything from insurance to tax obligations. **Get legal advice before building.**
5. **Sham contracting risk:** The more control RateRight exerts (rates, matching, check-in), the closer it looks like an employment relationship. **Get employment law advice.**
6. **Geographic launch city:** Sydney is the obvious choice (largest construction market). Confirm.
7. **Minimum viable marketplace:** What's the minimum number of workers and contractors needed before "launching"? **Recommendation: 50 workers + 20 contractors in launch area.**

---

## What the Best Apps Do for UX (Research Summary)

### Common patterns across Uber, Sidekicker, Yakka, Airtasker:

1. **Onboarding is 3-5 screens max** — name, trade, location, photo, done. Verification can happen after signup (don't block the first experience).
2. **Home screen shows ONE thing** — for workers: "Available jobs near you" or "Go online." For contractors: "Post a job" or "Your active jobs." No clutter.
3. **Match flow is visual** — worker profile card with photo, name, rating, trade, distance. Swipe or tap to accept/reject.
4. **Progress tracking is real-time** — both parties can see: "Worker is on the way" → "Worker arrived" → "Job in progress" → "Job complete"
5. **Notifications are the primary engagement tool** — not the app itself. Workers check the app when they get a notification, not by habit.
6. **Payment is invisible** — it just happens. No invoicing, no chasing. Job ends, money moves.
7. **Ratings are quick** — 1-5 stars + optional comment. Takes 10 seconds. Don't ask 4 different rating categories (current system asks for overall, quality, communication, safety — too many for casual workers).
8. **The map is everything** — Uber's most iconic screen is the map. Workers should see a map of available jobs. Contractors should see a map of available workers.

### Construction-specific UX patterns (from Yakka, Sidekicker):

1. **Shift-based, not project-based** — workers think in shifts (today, tomorrow), not projects (3-week job). Even multi-day jobs should be presented as a series of shifts.
2. **Early morning push notifications** — construction starts at 6-7 AM. Job notifications should go out at 5-6 AM. Respect that tradies start early.
3. **Simple timesheet** — just start time, end time, break time. One tap each. No complex hourly logging.
4. **Weather integration** — show weather for job location. Rain = potential cancellation on outdoor sites. Help both parties plan.
5. **Tool/PPE checklist** — before accepting a job, worker sees: "Bring: Hard hat, steel caps, hi-vis, own tools." Reduces on-site surprises.

---

*This analysis was generated on 2025-07-18 and should be reviewed against the latest market conditions and codebase changes before implementation.*