How to Clone Lyft

Create a Lyft-style ride-hailing app called RideRoute using Next.js (App Router), Tailwind, Prisma + SQLite, with the Google Maps Platform (or Mapbox) for maps and routing. Scope it to scheduled + on-demand rides in a single town so the marketplace is achievable.

## What to build
A two-sided rides marketplace: riders request/schedule rides, a dispatch service assigns nearby drivers, both sides see a live map, fares are charged on completion and the platform takes a commission.
Scope realism: instant on-demand needs driver liquidity you won't have on day one, so make scheduled rides first-class - they can be assigned ahead of time and are far more forgiving than live matching.

## Screens
- Landing page: hero, how-it-works, driver signup CTA
- Rider book-a-ride: map with pickup/destination autocomplete, Now/Schedule toggle, fare + ETA estimate, ride-type selector, Request
- Rider active ride: live driver position, driver card, ETA, share link, cancel
- Rider history: receipts with route and fare breakdown, plus a post-ride rating modal
- Driver dashboard: online/offline, incoming request with countdown accept/decline, active trip with navigation handoff and status buttons, earnings
- Admin dispatch console: live map of drivers + rides, manual reassign, fare/zone config, and a scheduled-rides queue

## Prisma schema
User (id, name, role, rating, phone, cardToken), Driver (userId, carMake, carModel, plate, isOnline, currentLat, currentLng, lastSeen), Ride (id, riderId, driverId, status, pickupLat, pickupLng, dropoffLat, dropoffLng, scheduledFor, fareCents, commissionCents, distanceM, requestedAt, completedAt), Rating (rideId, fromUser, toUser, stars, comment)

## Real-time & dispatch logic (this is the hard part - make it work)
- Live locations: drivers POST their position on an interval; push updates to the rider's active ride via WebSocket (Socket.IO) or polling for the MVP
- Matching: on request/scheduled time, query nearest online drivers (haversine for the MVP, Redis GEOSEARCH later) and offer one at a time with an expiry; first accept wins; re-offer on timeout
- Concurrency: an Offer row guards each assignment so two drivers can never accept the same ride - lock the ride row when an accept comes in and reject the loser
- Fare: base + perKm*distance + perMin*duration from the Routes API; commission split server-side and stored on the ride
- Status machine: requested → assigned → arriving → in_progress → completed; enforce valid transitions; charge card on completion (mock Stripe Connect)
- Scheduled rides: a job triggers matching at the scheduled time minus a lead window; if no driver accepts, mark no_driver and notify the rider

## Acceptance
- A request finds and offers to a real nearby driver; accepting assigns the ride and starts live tracking
- A second driver accepting the same ride is rejected cleanly
- A scheduled ride is assigned at its time, or marked no_driver with a rider notification
- A completed ride produces a receipt with the correct fare and commission split

## Style
Friendly and trustworthy: magenta-pink #E91E63 primary, clean rounded cards, map-dominant layouts, prominent driver trust cues. Mobile-first; rider and driver are phone-shaped, admin is desktop.

Seed: 6 demo drivers placed on the town map, 10 completed rides with receipts, one scheduled ride pending assignment, one ride currently in progress for the dispatch console, and a demo rider with a saved card.

Build a production-quality Lyft-style ride-hailing marketplace, scoped to one city with scheduled + on-demand rides. The matching engine, ride state machine and payments must be server-authoritative and real-time; this is the genuinely hard part, so treat it as the core.

## Stack
- Next.js 14 App Router + TypeScript + Tailwind + shadcn/ui for rider, driver and admin web apps (React Native later for production)
- PostgreSQL + PostGIS via Prisma; Redis (geospatial + pub/sub) for live driver locations and matching
- Google Maps Platform (Routes, Directions, Places) for ETAs and navigation - the maps API the real-time core depends on; Mapbox is the swap-in alternative
- WebSockets (a dedicated gateway, e.g. Socket.IO, or managed Ably) for live updates; BullMQ for offer timeouts, scheduled-ride triggers and payouts
- Stripe Connect for marketplace payments (hold fare, take commission, pay out drivers)

## Core design: the dispatch state machine
Model a Ride as an explicit state machine: requested → offered → assigned → arriving → in_progress → completed | cancelled | no_driver. Define allowed transitions in one place (lib/dispatch/stateMachine.ts) and reject invalid ones. The matching loop: on request (or scheduled trigger), GEOSEARCH nearby online drivers, offer to the best one with a TTL, on accept lock the ride in a transaction, on timeout/decline re-offer the next. Idempotent and concurrency-safe - two drivers must never accept the same ride.

## Real-time & payments (server-authoritative)
- Driver locations: written to Redis (GEOADD) with a short TTL; broadcast to the assigned rider only via room-scoped WebSocket events; never expose all drivers' raw positions
- Fares computed from the Routes API distance/duration server-side; surge is a zone multiplier read from config, not the client
- Payment captured on completion via Stripe Connect with the commission as the application fee; payouts batched by a queue job
- Every state transition is a transaction; assignment uses a row lock so concurrent accepts can't double-book

## Schema
users, drivers (current location in Redis, profile in PG), rides (geom points, status, fare/commission, scheduled_for), offers (ride_id, driver_id, expires_at, outcome), ratings, payouts (ledger). GiST indexes on geometry; btree on rides(status, scheduled_for), offers(ride_id).

## Implementation order
1. Schema + auth + seed (one city, 6 drivers, demo rider) + the ride state machine with unit tests on transitions
2. Maps integration: fare/ETA estimate, route geometry, places autocomplete
3. Matching service: GEOSEARCH + offer loop + concurrency-safe accept (write the double-accept test first)
4. Rider flow: request/schedule, live tracking via WebSocket, cancellation
5. Driver app: online toggle, location pings, offer accept/decline, trip lifecycle, earnings
6. Payments: Stripe Connect capture + commission + payouts
7. Admin dispatch console + surge zones + scheduled-ride triggers

## Quality bar
- A ride can never be assigned to two drivers (prove it with a concurrent test)
- Live tracking reconnects gracefully; stale driver locations expire
- Fares and commission are computed only on the server; the client never sets a price

Start with step 1; show me the ride state machine, its transition map, and the double-accept test before continuing.

Design the complete UI for a Lyft-style ride-hailing app called RideRoute (rider, driver and admin views). React + Tailwind + shadcn/ui + lucide-react, with a maps embed. Aesthetic: friendly and trustworthy - magenta-pink #E91E63 primary, clean rounded cards, map-dominant layouts, generous whitespace, prominent trust cues (driver photo, rating, plate).

## Screens

### 1. Rider - book a ride (main screen)
- Full-bleed map with a centered pickup pin and a route line to the destination
- Bottom sheet: pickup and destination inputs with autocomplete, a Now / Schedule toggle (reveals a date-time picker), ride-type cards (Standard, XL, Premium with prices), a fare + ETA summary, and a big Request Ride button

### 2. Rider - active ride
- Live map with the driver's car icon approaching the pickup, route drawn
- Driver card: photo, name, star rating, car make/model and plate, message and call icons
- Status strip ('Arriving in 3 min'), share-trip link, and a cancel button
- A status timeline showing the ride moving through assigned → arriving → in progress → completed

### 3. Driver - dashboard
- Top: a large online/offline toggle with today's earnings
- Incoming request card: pickup/dropoff, distance, fare, a circular countdown timer, Accept (pink) / Decline buttons
- Active trip panel: navigation handoff button, rider info, and Picked Up / Complete Trip buttons
- Earnings tab: weekly total, per-ride breakdown, tips, payout status

### 4. Rider - history & receipts
- List of past rides (date, route thumbnail, fare); a receipt detail with map, fare breakdown (base, distance, time, fees), and a re-book button
- A post-ride rating modal: 5 stars, optional tip chips, and a comment box

### 5. Admin - dispatch console
- Live map showing all driver icons (online/on-trip color coded) and active ride routes
- Side panel: list of active rides with statuses, a manual reassign action, and fare/zone configuration with a surge-zone editor
- A scheduled-rides queue showing upcoming bookings and their assignment status

### 6. Empty & error states
- Rider 'no drivers available right now' state with a retry and a 'schedule for later' suggestion
- Driver offline state and an 'offer expired' toast
- A trip-cancelled confirmation and a 'searching for a driver' loading state with a pulsing pickup pin

Fully responsive, mobile-first (rider and driver apps are phone-shaped; admin is desktop). Fill everything with realistic data: a town map, 6 drivers with photos and cars, a current trip in progress, a scheduled ride in the queue, and 10 past receipts.

Build a ride-hailing app (Lyft model) called RideRoute, scoped to scheduled and on-demand rides in one town so the two-sided marketplace is achievable.

## Entities
- User: name, role (rider/driver/admin), rating, phone, cardToken
- Driver: user reference, carMake, carModel, plate, isOnline, currentLat, currentLng, lastSeen
- Ride: rider reference, driver reference, status (requested/assigned/arriving/inProgress/completed/cancelled), pickupLat, pickupLng, dropoffLat, dropoffLng, scheduledFor (optional), fareCents, commissionCents, distanceM, requestedAt, completedAt
- Offer: ride reference, driver reference, expiresAt, outcome (accepted/declined/expired)
- Rating: ride reference, fromUser, toUser, stars, comment

## Roles
- Rider: books rides (now or scheduled), tracks the assigned driver live, pays on completion, rates the driver
- Driver: goes online, accepts/declines ride offers, runs the trip, sees earnings
- Admin: dispatch console with a live map of drivers and rides, manual reassignment, fare and surge-zone configuration

## Pages
1. Rider book-a-ride: map with pickup/destination, Now/Schedule toggle, fare and ETA estimate, ride-type selector, request button
2. Rider active ride: live map of the approaching driver, driver card (name, rating, car, plate), ETA, share link, cancel
3. Rider history: past rides with route and fare-breakdown receipts, and a post-ride rating modal
4. Driver dashboard: online/offline toggle, incoming offer with countdown accept/decline, active trip with status buttons, earnings summary
5. Admin dispatch console: live map, active-ride list, manual reassign, fare/zone settings, scheduled-rides queue

## Rules
- Matching: on request or at a scheduled time, offer the ride to the nearest online drivers one at a time with an expiry; first to accept is assigned; never assign one ride to two drivers
- Fare = base + per-km + per-minute; platform keeps a commission, driver gets the remainder; charged on completion and recorded on the ride
- A ride follows a strict status machine; cancellation rules differ before and after assignment
- If no driver accepts a scheduled ride, mark it no-driver and notify the rider to retry
- After completion, rider and driver can each rate the other once, updating the other's average rating

## Scope note
- Keep it to one town; scheduled rides are first-class because they can be assigned ahead of time without the day-one driver liquidity that instant on-demand demands
- Real-time live tracking is the hard part - rely on a maps provider for routing and ETAs rather than building it

## Look & feel
Friendly, trustworthy ride-hailing style: magenta-pink primary, clean rounded cards, map-dominant layouts, clear trust cues (driver photo, rating, plate). Mobile-first; rider and driver are phone-shaped, admin is desktop.

Seed: 6 demo drivers placed on a town map, 10 completed rides with receipts, one scheduled ride pending assignment, one ride in progress, and a demo rider with a saved card so the active-ride and dispatch screens both look alive.