RideFlow Documentation

RideFlow is a full-featured ride booking platform built with React, TypeScript, and Supabase. This guide walks you through installation, configuration, deployment, and day-to-day operation — in that order.

Key Capabilities

Application Routes

Prerequisites

Before you begin, make sure you have the following installed on your system.

Install & Run

Get RideFlow running locally in under 5 minutes.

Step 1: Clone & Install

# Clone the repository
git clone <YOUR_GIT_URL>
cd <YOUR_PROJECT_NAME>

# Install dependencies
npm install

Step 2: Configure Environment

Create a .env file in the project root with your Supabase credentials:

# Required — Supabase connection
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
VITE_SUPABASE_PROJECT_ID=your-project-id

See Environment Variables for the full list including demo mode toggles.

Step 3: Start the Dev Server

npm run dev

# App is now running at http://localhost:5173

Step 4: Run the Setup Wizard

On first launch, RideFlow automatically redirects to /setup. Complete the 7-step wizard to create your admin account and configure the platform. See Setup Wizard for details.

Project Structure

src/
├── components/
│   ├── admin/          # Admin panel components
│   │   ├── drivers/    # Driver management sub-components
│   │   └── settings/   # Settings tabs (8 tabs)
│   ├── booking/        # Booking flow components (40+ files)
│   ├── driver/         # Driver portal components
│   │   └── onboarding/ # Driver onboarding wizard
│   ├── setup/          # Setup wizard guard
│   ├── auth/           # Authentication components
│   ├── account/        # User account components (loyalty, payments)
│   └── ui/             # Shared UI components (shadcn/ui)
├── contexts/           # React contexts (Auth, Language, SystemSettings)
├── hooks/              # Custom React hooks (30+ hooks)
├── i18n/               # Internationalization (en, es, fr, de)
├── integrations/       # Supabase client & auto-generated types
├── pages/              # Page components
│   └── admin/          # 16 admin pages
├── types/              # TypeScript type definitions
└── utils/              # Utility functions (demo, calendar, receipt, nav)

supabase/
├── functions/          # 25+ Edge functions
├── migrations/         # Database migration files
└── config.toml         # Supabase configuration

docs/                   # This documentation

Setup Wizard

On first launch, RideFlow redirects all routes to a 7-step setup wizard at /setup. This ensures every installation is properly configured before going live.

How It Works

1. The SetupGuard component wraps all routes in App.tsx
2. The useSetupCheck hook queries the setup_completed flag from system_settings
3. If setup is NOT complete, all routes redirect to /setup
4. Once complete, /setup redirects to /auth

Setup Steps

Re-Running Setup

DELETE FROM system_settings WHERE key = 'setup_completed';
-- Optionally remove all admin roles to re-trigger wizard
DELETE FROM user_roles WHERE role = 'admin';

Build & Deploy

Create a production build and deploy it to your hosting provider.

Step 1: Build for Production

# Build the app (output goes to /dist)
npm run build

# Preview the production build locally
npm run preview

The dist/ folder contains static files that can be served from any hosting provider.

Step 2: Choose a Hosting Provider

Step 3: Set Environment Variables

Configure the same VITE_* variables from your .env in your hosting provider's dashboard. These are baked into the build at compile time.

Step 4: Deploy Backend

If self-hosting, deploy the database migrations and edge functions:

# Link to your Supabase project
npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF

# Apply database schema
npx supabase db push

# Deploy all edge functions
supabase functions deploy

See Self-Hosting Guide for detailed infrastructure setup.

Environment Variables

All frontend configuration is done via .env variables prefixed with VITE_. These are embedded at build time.

Required Variables

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=your-anon-key
VITE_SUPABASE_PROJECT_ID=your-project-id

Demo Mode Variables (All Optional)

VITE_DEMO_MODE=false          # Master toggle (must be true for any demo feature)
VITE_DEMO_BANNER=true         # Show "Demo Mode Active" banner
VITE_DEMO_SEED_DATA=true      # Auto-seed demo accounts on quick login
VITE_DEMO_WATERMARK=false     # Overlay translucent "DEMO" text
VITE_DEMO_QUICK_LOGIN=true    # Show quick-access demo login buttons
VITE_DEMO_MOCK_PAYMENTS=false # Simulate payments without real gateways
VITE_DEMO_MOCK_MAPS=false     # Use mock map data (no API key needed)
VITE_DEMO_NOTIFICATIONS=false # Show demo notification toasts
VITE_DEMO_AI_CHATBOT=true     # Enable AI chatbot in demo mode
VITE_DEMO_ANALYTICS=false     # Populate admin dashboard with sample data

See Demo / Test Mode for detailed descriptions and recommended configurations.

Backend Secrets

Edge functions require API keys stored securely as Supabase secrets. These are never exposed to the browser.

Setting Secrets

supabase secrets set GOOGLE_MAPS_API_KEY=your-key
supabase secrets set RESEND_API_KEY=your-key
supabase secrets set VAPID_PUBLIC_KEY=your-key
supabase secrets set VAPID_PRIVATE_KEY=your-key
supabase secrets set VAPID_SUBJECT=mailto:your@email.com

Integrations

RideFlow integrates with several third-party services. All are optional — the app functions in demo mode without any API keys.

Maps: Google Maps

Required APIs: Maps JavaScript, Places, Directions, Geocoding, Distance Matrix. API key stored as a secret, loaded via get-maps-config edge function. Usage tracked in map_api_usage table with quota alerts.

When VITE_DEMO_MOCK_MAPS=true, mock route data is used instead — no API key needed.

Maps: Mapbox

Alternative/fallback to Google Maps. Used for driver dashboard map and route visualization. Required scopes: Styles, Geocoding, Directions, Fonts, Tilesets.

Email: Resend

Store RESEND_API_KEY as a backend secret. HTML email templates include responsive design, brand colors (from system_settings), dynamic company name, and CTAs. Used by: booking emails, reminders, document notifications, driver application alerts.

Voice: ElevenLabs

Voice announcements for driver notifications. Store ELEVENLABS_API_KEY as a backend secret. Used via useVoiceAnnouncements hook.

Payments: Stripe

1. Configure in Admin → Settings → Integrations (test/live mode toggle)
2. Add webhook endpoint: /functions/v1/stripe-webhook
3. Events: payment_intent.succeeded, payment_intent.payment_failed, charge.refunded

Payments: PayPal

1. Configure in Admin → Settings → Integrations
2. Set IPN URL: /functions/v1/paypal-webhook
3. Handles: Completed, Pending, Failed/Denied, Refunded/Reversed

Demo / Test Mode

RideFlow supports a comprehensive demo/test mode controlled by 10 environment variables. The master toggle VITE_DEMO_MODE must be true for any demo feature to activate.

What Each Toggle Controls

Recommended Configurations

Full Demo (trade shows, client demos)

VITE_DEMO_MODE=true
VITE_DEMO_BANNER=true
VITE_DEMO_WATERMARK=true
VITE_DEMO_QUICK_LOGIN=true
VITE_DEMO_SEED_DATA=true
VITE_DEMO_MOCK_PAYMENTS=true
VITE_DEMO_MOCK_MAPS=true
VITE_DEMO_NOTIFICATIONS=true
VITE_DEMO_AI_CHATBOT=true
VITE_DEMO_ANALYTICS=true

Testing Mode (developer testing with real APIs)

VITE_DEMO_MODE=true
VITE_DEMO_BANNER=true
VITE_DEMO_QUICK_LOGIN=true
VITE_DEMO_SEED_DATA=true
VITE_DEMO_MOCK_PAYMENTS=false
VITE_DEMO_MOCK_MAPS=false

Production

VITE_DEMO_MODE=false
# All other demo vars are ignored when master toggle is off

Demo Accounts

Available when VITE_DEMO_MODE=true:

Demo Data Seeding

The setup-demo-users edge function is idempotent and creates: 3 user accounts with profiles, admin role assignment, a driver record with 4.8★ rating, 5 shifts, 3 demo bookings, 4 earnings records, and 1 zone.

Booking Flow

A streamlined 3-step process optimized for conversion. Each step has a loading skeleton for perceived performance.

Step 1: Location & Service

Component: Step1Location.tsx

• Pickup & Dropoff: Address autocomplete via Google Maps Places API, with additional stops (up to 3)
• Saved Locations: Quick-select dropdown for logged-in users
• Service Type: Hourly or Flat-rate
• Transfer Type: One-way, Return, or Return (New Ride)
• Date & Time: Smart time picker with surge pricing indicators and business hours enforcement
• Passengers / Luggage / Child Seats / Flight Number / Notes
• Map Preview: Route visualization with distance and duration
• Traffic Alerts: Real-time traffic condition banners

Step 2: Vehicle Selection

Component: Step2Vehicle.tsx

• Dynamic Pricing: Base price + per-km rate with pricing rules applied
• Categories: Sedan, SUV, Van, Luxury (configurable)
• Capacity Filtering: Only vehicles that fit passengers/luggage
• Favorites, Comparison Drawer, Smart Fare Suggestions, Surge Alerts

Step 3: Payment & Confirmation

Component: Step3Payment.tsx

• Payment Methods: Card (Stripe), PayPal, Bank Transfer
• Promo Codes, Billing Details, Price Breakdown, Order Summary
• Deposit Requirement: Configurable percentage (default 30%)
• Guest Email: Required for non-authenticated bookings

Post-Booking

• Confirmation Page: Booking reference, calendar export (ICS/Google/Outlook), receipt download
• Email Notification: Branded email via send-booking-email edge function
• Real-time Status: Timeline visualization + live tracking
• Loyalty Points: Automatically earned on completed rides

Guest Bookings

Users can book rides without creating an account. Email is required in Step 3 for confirmation. The booking is created with user_id = NULL. The booking reference allows tracking without login at /track.

Vehicle Selection

Vehicle Schema

Pricing Hooks

• useVehiclePricing — Total price from distance + rules + surge
• useDynamicPricing — Time/distance/zone/vehicle pricing rules
• useSurgePricing — Real-time demand-based surge multipliers

Payment Methods

All gateways are configured in Admin → Settings → Integrations with test/live mode toggles. Users can save and verify payment methods in their account. Demo mock payments available via VITE_DEMO_MOCK_PAYMENTS=true.

Fees & Surcharges

All fees are transparent and shown in the price breakdown before booking confirmation.

Price Breakdown Example

Base Fare                    $45.00
Distance (12.3 km × $1.50)   $18.45
Booking Fee                   $5.00
Toll Charges                  $3.50
Airport Charges               $8.00
───────────────────────────────────
Subtotal                     $79.95
Promo Code (SAVE10 -10%)     -$7.99
Tax (VAT 20%)                $14.39
───────────────────────────────────
Total                        $86.35

Promo Codes

Percentage-based discounts validated via validate_promo_code database function. Features: date range validity, global + per-user usage limits, minimum booking amount. Usage tracked via promo_code_uses table.

Recurring Bookings

Users set up automatic recurring rides with frequency options: Daily, Weekly, Weekdays, Custom (specific days). The generate-recurring-bookings edge function runs daily to create upcoming bookings from templates.

Ride Sharing

Users can split ride costs with other passengers via email invitation.

1. Booking owner enters recipient email and cost split percentage
2. Email sent with unique share token
3. Recipient accepts/declines at /share/:token
4. Counter-proposals supported

Real-time Tracking

Live Driver Location

When a driver is assigned, users track the driver's location at /track:

• Position updates every 10 seconds via Supabase Realtime
• Interactive Leaflet map centered on pickup, with "Waiting for driver location…" overlay until GPS data arrives
• Estimated arrival time via calculate-eta edge function
• Booking status timeline, contact buttons (call/message driver), traffic alerts, AI live chat widget

Booking Statuses

Notifications

Channels

• In-App: Bell icon with unread badge counter
• Email: Via Resend with branded HTML templates
• SMS: Configurable phone notifications
• Push: Browser push (VAPID-based)
• Voice: ElevenLabs announcements for drivers

Automatic triggers fire on: booking status changes, driver assignment, driver arrival (ETA ≤5 min), ride start/completion. User preferences stored in notification_preferences table.

User Account

Loyalty & Rewards

Rider Loyalty Points

Points are earned from ride completions, referrals, and promotions. Balance and history shown via LoyaltyPointsSection in the Account page.

AI Booking Chatbot

Floating AI assistant on the booking page for natural language booking guidance. Context-aware (receives current booking state), renders Markdown responses, powered by built-in AI models (no API key required). Controllable via VITE_DEMO_AI_CHATBOT.

A separate LiveChatWidget is available on the tracking page, contextually aware of the current booking.

Driver Onboarding

Application Process

The BecomeDriverDialog opens a 3-step wizard:

1. Personal Information: Name, email, phone
2. License Details: License number, expiry date
3. Agreement: Terms of service + background check consent

Onboarding Statuses

Driver Dashboard

Mobile-optimized dashboard at /driver with pull-to-refresh.

• Availability Toggle: Switch Available/Offline status
• Map View: All pickup locations with Mapbox
• List View: Pickups sorted by ETA urgency (red ≤5min, amber ≤10min, green >10min)
• Active Ride Card: Live timer, route details
• Urgent Pickup FAB: Floating button for imminent pickups
• Today's Earnings: Real-time summary with commission breakdown
• Geofence Indicator: Zone entry/exit alerts

Shift Management

Shifts link drivers to zones with date/time ranges. Statuses: scheduled → active (checked in) → completed (checked out) or missed. Admin creates shifts in /admin/scheduling. Drivers see their shifts with check-in/out capability.

Earnings & Commission

Fully automated commission system that deducts a configurable percentage from every completed ride.

How Commission Works

1. Admin sets rate: Commission % in Admin → Settings → Booking Policies (e.g., 15%)
2. Ride completes: The auto_record_driver_earning_on_completion trigger fires
3. Earnings calculated: Calls record_driver_earning_with_commission()
4. Record created: gross_amount, commission_rate, commission_amount, net amount
5. Summary updated: Driver's total/monthly earnings auto-updated

Earnings Breakdown

Rider Paid (Gross Fare):    $50.00
Commission Rate:             15%
Service Fee (Deduction):    -$7.50
─────────────────────────────────
Driver Net Pay:              $42.50

The DriverEarningsTracker component shows the visual "Rider Paid → Service Fee → You Earned" flow with per-ride detail and earning types (ride, tip, bonus, adjustment).

Driver Bonuses

Bonus types: milestone, performance, referral, and seasonal. Each has amount, rides_required, progress tracking, and validity dates. Stored in driver_bonuses table.

Document Management

Drivers upload license, insurance, and vehicle registration documents via DriverDocumentPortal. Documents go through a verification workflow (pending → verified/rejected). Expiring documents trigger alerts via check-expiring-documents edge function.

Location Tracking

Driver GPS coordinates are updated in real-time via DriverLocationTracker. Updates broadcast to riders through Supabase Realtime. The DriverRouteMap component shows the route from current location to pickup/dropoff.

Navigation Integration

Deep links to Google Maps, Waze, and Apple Maps for turn-by-turn navigation. The navigation button opens the user's preferred mapping app with the destination pre-filled.

Admin Dashboard

The dashboard at /admin shows real-time KPIs: today's bookings, active rides, revenue, pending tasks. Includes stat cards, traffic heatmap, driver deployment widget, pending documents, and API quota alerts.

Bookings Management

Full CRUD at /admin/bookings with search, filter (status, date range, vehicle), server-side pagination. Actions: assign driver, update status, modify details, process refund, view payment status.

Driver Management

Manage drivers at /admin/drivers. View applications at /admin/driver-applications. Review documents at /admin/document-review. Features: add/edit driver, performance cards, smart assignment, document verification, expiring document alerts.

Vehicle Management

CRUD for vehicles at /admin/vehicles. Configure: name, category, capacity, pricing (base + per-km + hourly), features, images, display order, active/inactive status.

Pricing Rules

Rule types: time-based (peak hours), distance-based (tiers), zone-based (surcharges), vehicle-specific. Each rule has multiplier, flat fee, priority, day/time constraints. Test with the Price Calculator at /admin/calculator.

Commission Settings

Configure the platform's revenue share from each completed ride.

Navigate to Admin → Settings → Booking Policies:

• Commission Rate (%): 0–100%, step: 0.5%. Default: 15%.
• Booking Fee: Fixed platform fee per booking
• Cancellation Fee: Charged for late cancellations

Rate changes take effect immediately for new completions. Already-completed rides retain their original rate. All changes logged in the Audit Log.

Zones & Routes

Zone Management

Zones at /admin/zones: geographic areas with name, description, multiplier, active status. Used for zone-based pricing rules and driver shift assignments.

Route Management

Routes at /admin/routes: predefined origin-destination pairs with base price, estimated distance/duration, origin/destination zone links, display order.

Revenue & Analytics

Revenue dashboard at /admin/revenue with charts, booking volume trends, driver performance, payment method breakdown, and commission revenue tracking.

• Total Revenue — Sum of completed booking fares
• Commission Revenue — Platform's share from all rides
• Driver Payouts — Net amounts paid to drivers
• Booking Fees — Total platform booking fees

Admin Settings (8 Tabs)

All settings stored in system_settings table with audit logging.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (React + Vite)                   │
├─────────────────────────────────────────────────────────────────┤
│  Booking Flow │ Driver Portal │ Admin Panel │ User Account       │
│  AI Chatbot   │ Setup Wizard  │ PWA Support │ i18n (18 languages)│
│  Loyalty      │ Features Page │ Demo Mode   │ Commission System  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Backend (Supabase)                            │
├─────────────────────────────────────────────────────────────────┤
│  Auth (GoTrue) │ Database (PostgreSQL) │ Edge Functions (Deno)   │
│  Storage       │ Realtime (WebSockets) │ Secrets (API Keys)      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     External Integrations                        │
├─────────────────────────────────────────────────────────────────┤
│  Google Maps │ Mapbox │ Resend (Email) │ ElevenLabs (Voice)     │
│  Stripe      │ PayPal │ Bank Transfer                           │
└─────────────────────────────────────────────────────────────────┘
          

Data Flow

1. User Action: User interacts with the React frontend
2. API Call: Supabase client sends request to database or edge function
3. RLS Check: Row Level Security verifies access permissions
4. Database Operation: Data is read/written to PostgreSQL
5. Triggers: Database triggers fire (notifications, earnings, commission, ratings)
6. Realtime: Changes broadcast to subscribed clients via WebSockets
7. UI Update: React components re-render via TanStack Query

Key Design Patterns

• SECURITY DEFINER functions: has_role(), get_user_roles() bypass RLS to prevent recursive policy checks
• Enum-based access: Roles stored in separate user_roles table
• Upsert patterns: Settings and demo data use ON CONFLICT for idempotency
• Edge Functions: All sensitive operations (payments, emails, API keys) are server-side
• Commission triggers: Automatic calculation on ride completion
• Dynamic branding: CSS custom properties applied from database at runtime

Tech Stack

Frontend

Backend

Database Schema

20+ tables with RLS. Key tables summarized below.

Core Tables

Financial Tables

Supporting Tables

Edge Functions

30+ serverless functions running on the Deno runtime. Deployed via supabase functions deploy.

Communication

AI & Intelligence

Maps & Location

Payments & Webhooks

Administration

RPC Functions

Realtime Channels

Supabase Realtime is used for: booking status/driver location updates, driver availability changes, notification delivery, system settings changes (brand colors, currency).

const channel = supabase
  .channel(`booking-${bookingId}`)
  .on('postgres_changes', {
    event: 'UPDATE',
    schema: 'public',
    table: 'bookings',
    filter: `id=eq.${bookingId}`,
  }, (payload) => {
    updateDriverMarker(payload.new.driver_location_lat, payload.new.driver_location_lng);
    updateBookingStatus(payload.new.status);
  })
  .subscribe();

Authentication

Supported Methods

• Email/Password: Standard registration and login with Zod validation
• Google OAuth: Cloud-managed or self-hosted Supabase OAuth (auto-detected)
• Apple OAuth: Cloud-managed or self-hosted Supabase OAuth (auto-detected)
• X (Twitter) OAuth: Direct Supabase OAuth only
• Facebook OAuth: Direct Supabase OAuth only
• Password Reset: ForgotPasswordDialog with email link flow

Auth Context

AuthContext provides: user, session, loading, isCloud, signIn, signUp, signInWithSocialProvider (Google/Apple/Twitter/Facebook), signOut. Profile auto-creation via handle_new_user trigger. The isCloud flag auto-detects the hosting environment for OAuth routing.

Role-Based Access

Frontend hook: useUserRoles() returns roles, isAdmin, isModerator, hasRole(), loading.

RLS & Security

All 20+ tables use Row Level Security. Common patterns:

• User-owned: auth.uid() = user_id
• Admin ALL: has_role(auth.uid(), 'admin')
• Public read: is_active = true or USING (true)
• Driver-owned: Subquery matching drivers.user_id = auth.uid()
• Setup exception: NOT EXISTS (SELECT 1 FROM user_roles WHERE role = 'admin')

PWA Support

• Service worker (public/sw.js) for offline caching
• Web app manifest with icons (192x192, 512x512)
• InstallPromptBanner for install promotion
• Dedicated /install page with platform-specific instructions
• vite-plugin-pwa for build-time manifest generation

Multi-language

18 languages via LanguageContext: English, Spanish, French, German, Arabic (RTL), Hindi, Italian, Japanese, Korean, Dutch, Polish, Portuguese, Russian, Swedish, Thai, Turkish, and Chinese. User preference stored in profiles.language_preference. Languages are managed from the languages database table with activation toggles and translation completeness tracking.

Translation Overrides: Admins can override any translation key per-language via the translation_overrides table. The Bulk Translation Manager in Admin Settings allows batch translation using the translate-batch edge function.

Theming & Branding

Theme management uses next-themes. HSL-based design tokens in index.css. User preference stored in profiles.theme_preference (light/dark/system).

Dynamic Branding: The SystemSettingsContext reads brand colors from the database and applies them as CSS custom properties at runtime. Primary color, accent color, logos, and favicon are all configurable from Admin → Settings → Appearance without code changes.

Self-Hosting Overview

RideFlow can be self-hosted on your own infrastructure for full data sovereignty, customization, cost control, and regulatory compliance.

┌─────────────────────────────────────────────────────────────────┐
│                     Your Infrastructure                          │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────────┐     ┌──────────────────────────────────┐   │
│  │   Frontend App   │     │         Supabase Instance        │   │
│  │  (Static Files)  │────▶│  (Self-hosted or Supabase.com)   │   │
│  │  Vercel/Netlify/  │     │  PostgreSQL + Auth + Edge Funcs  │   │
│  │  Docker/S3+CF    │     │  + Realtime + Storage            │   │
│  └──────────────────┘     └──────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
          

System Requirements

Authentication & OAuth

RideFlow supports two OAuth environments. The app auto-detects which path to use at runtime — no code changes required.

How It Works

Self-Hosted OAuth Setup

1. Open your Supabase Dashboard → Authentication → Providers
2. Enable Google and/or Apple
3. Enter your Client ID and Client Secret (from Google Cloud Console / Apple Developer Portal)
4. Set the Redirect URL to https://<your-supabase-url>/auth/v1/callback
5. In RideFlow Admin Settings → Integrations, toggle on the providers you configured

Deploy Options

Static File Hosting

After npm run build, deploy the dist/ folder to any static hosting provider: Vercel, Netlify, AWS S3+CloudFront, or Docker with nginx.

Docker Example

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80

Database Migration

# Login and link to your project
npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF

# Push all migrations
npx supabase db push

CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA extensions;

Then edit migration files: gen_random_bytes → extensions.gen_random_bytes

Edge Functions Deployment

# Deploy all functions at once
supabase functions deploy

# Deploy a specific function
supabase functions deploy send-booking-email

See Edge Functions for the full list with required secrets.

Storage Setup

Create 4 storage buckets:

Security Hardening

Troubleshooting

CORS Errors

Verify edge function CORS headers include your domain. Check API allowed origins.

Auth Not Working

Verify SUPABASE_URL and key. Check email confirmation settings. Verify redirect URLs.

RLS Permission Denied

Ensure user is authenticated. Test policies with role impersonation. Check has_role() function.

Edge Functions 500 Errors

Check logs: supabase functions logs [name]. Verify all secrets are set.

Maps Not Loading

Verify GOOGLE_MAPS_API_KEY secret. Enable required APIs in Google Cloud. Check referrer restrictions. Or enable VITE_DEMO_MOCK_MAPS=true for testing.

Commission Not Applied

Verify the auto_record_driver_earning_on_completion trigger exists. Check booking_policies.commissionPercentage in system_settings. Ensure booking has driver_id and total_price.

Upgrade Guide

Follow these steps to update RideFlow to any newer version. The same procedure applies regardless of your current version.

Step 1 — Download the New Version

Replace your project files with the target release. Keep your .env file separate — do not overwrite it.

# If using Git
git fetch origin
git checkout vX.X.X

# Or download the release archive and extract over your project directory

Step 2 — Install Dependencies

npm install
# or: bun install

Step 3 — Update Environment Variables

Compare your existing .env with the new .env.example and add any new variables. Check the Changelog for details on what was added in each version.

Step 4 — Install the Supabase CLI

If you don't already have the Supabase CLI installed locally:

npm i supabase

Step 5 — Log In to Supabase

npx supabase login

This opens a browser window to authenticate with your Supabase account. You only need to do this once per machine.

Step 6 — Link Your Project

npx supabase link --project-ref YOUR_SUPABASE_PROJECT_ID

Step 7 — Apply Database Migrations

This pushes all pending migration files to your database. New tables, columns, functions, triggers, and RLS policies will be applied automatically.

npx supabase db push

Step 8 — Deploy Edge Functions

This deploys all edge functions (new and updated) to your Supabase project:

npx supabase functions deploy

Step 9 — Build & Deploy the Frontend

# Build the production bundle
npm run build

# Test locally before deploying to production
npm run dev

# Deploy to your hosting provider — examples:

# Vercel
npx vercel --prod

# Netlify
npx netlify deploy --prod --dir=dist

# Firebase Hosting
npx firebase deploy --only hosting

# Any static host / VPS — upload the dist/ folder
scp -r dist/* user@your-server:/var/www/rideflow/

The npm run build command generates a dist/ folder with static files. Deploy this folder to your hosting provider (Vercel, Netlify, Firebase, VPS, etc.).

Step 10 — Verify

After upgrading, check the following:

• ✅ Application loads without console errors
• ✅ Booking flow works end-to-end (create → confirm → track)
• ✅ Admin dashboard loads with all sections accessible
• ✅ Driver login and dashboard function correctly
• ✅ Existing data (bookings, drivers, users) is intact
• ✅ Footer version matches the target release

Quick Reference — Full Command Sequence

Copy and run this complete sequence for a typical upgrade:

# 1. Get the new version
git fetch origin && git checkout vX.X.X

# 2. Install dependencies
npm install

# 3. Install Supabase CLI (if not already installed)
npm i supabase

# 4. Log in (one-time per machine)
npx supabase login

# 5. Link project (skip if already linked)
npx supabase link --project-ref YOUR_SUPABASE_PROJECT_ID

# 6. Apply database migrations
npx supabase db push

# 7. Deploy edge functions
npx supabase functions deploy

# 8. Build frontend
npm run build

# 9. Deploy frontend (pick your host)
npx vercel --prod          # Vercel
# npx netlify deploy --prod --dir=dist   # Netlify
# npx firebase deploy --only hosting     # Firebase

Changelog

Track all version updates, new features, and improvements to RideFlow.