HotRide - Ride Sharing Mobile App

A full-stack ride-sharing application built with React Native (Expo) and Python (FastAPI).

Project Structure

HotRide/
├── backend/          # FastAPI backend with MongoDB
└── mobile/           # React Native (Expo) mobile app

Stage 1: Authentication System ✅

Features Implemented

Backend (FastAPI + MongoDB):

• ✅ Email/Phone + Password authentication
• ✅ Google OAuth integration
• ✅ Apple Sign In integration
• ✅ JWT token generation and validation
• ✅ Password hashing with bcrypt
• ✅ MongoDB user storage
• ✅ CORS configuration for Expo

Frontend (React Native + Expo):

• ✅ Login screen with email/phone + password
• ✅ Google OAuth button (fully functional)
• ✅ Apple Sign In button (fully functional)
• ✅ Form validation
• ✅ Error handling with toast notifications
• ✅ Secure token storage with Expo SecureStore
• ✅ Navigation with Expo Router
• ✅ State management with Zustand

Stage 2: Registration & Verification ✅

Features Implemented

Backend (FastAPI + MongoDB):

• ✅ User registration endpoint
• ✅ Email verification with 6-digit codes
• ✅ Phone verification with SMS (Twilio)
• ✅ Profile setup endpoint
• ✅ Email service with SMTP
• ✅ SMS service integration
• ✅ JWT authentication middleware
• ✅ Update profile endpoint (authenticated)

Frontend (React Native + Expo):

• ✅ Sign up / Registration screen
• ✅ Email verification screen with 6-digit code input
• ✅ Phone verification screen with 6-digit code input
• ✅ Profile setup screen with photo upload
• ✅ Edit profile screen with photo upload
• ✅ Enable location screen with map view
• ✅ Location permission handling (expo-location)
• ✅ Map integration with driver markers (react-native-maps)
• ✅ Location-based booking button (disabled without location)
• ✅ Image picker integration (expo-image-picker)
• ✅ Complete registration flow
• ✅ Terms & Conditions acceptance
• ✅ Read-only email and phone display

Stage 3: Ride Booking ✅

Features Implemented

Backend (FastAPI + MongoDB):

• ✅ Booking model and schema
• ✅ Create booking endpoint (authenticated)
• ✅ Get user bookings (ride history)
• ✅ Get specific booking details
• ✅ Update booking status
• ✅ Cancel booking endpoint
• ✅ Fare calculation (25 PESOS per km base fare)
• ✅ MongoDB booking collection with indexes

Frontend (React Native + Expo):

• ✅ Booking screen with interactive map
• ✅ Destination search with geocoding
• ✅ Distance calculation (Haversine formula)
• ✅ Estimated time calculation
• ✅ Base fare calculation (25 PESOS/km)
• ✅ Gratuity/tip system (slider + percentage buttons)
• ✅ Total fare display (base + gratuity)
• ✅ Notes for driver input
• ✅ Ride history screen
• ✅ Booking list with status badges
• ✅ Pull-to-refresh ride history
• ✅ Empty state for no rides
• ✅ @react-native-community/slider integration

Stage 4: Ride Tracking & Communication ✅

Features Implemented

Backend (FastAPI + MongoDB):

• ✅ Booking status updates (pending, accepted, in_progress, completed, cancelled)
• ✅ Cancel booking with notification support
• ✅ Booking details endpoint for tracking
• ✅ Driver assignment to bookings

Frontend (React Native + Expo):

• ✅ Ride Tracking Screen - Real-time driver location on map
• ✅ Live Driver Location - Simulated GPS updates every 3 seconds
• ✅ ETA Calculation - Dynamic time updates as driver approaches
• ✅ Route Visualization - Line connecting driver to user location
• ✅ Driver Profile Display - Name, rating, vehicle, license plate
• ✅ Call Driver - Direct phone call functionality
• ✅ Chat with Driver - Real-time messaging interface
• ✅ Share Ride - Share ride details via phone's share sheet
• ✅ Cancel Ride - Cancel booking with driver notification
• ✅ Map Auto-fit - Automatically adjusts to show both markers
• ✅ Status Updates - "Your rider is on the way" with countdown

Stage 5: Finding Driver & Advertisements ✅

Features Implemented

Frontend (React Native + Expo):

• ✅ Finding Driver Screen - Waiting screen while searching for drivers
• ✅ Advertisement Modal - Full-screen ads with countdown timer
• ✅ Ad Timing Logic - Display ad for 10 seconds every 2 minutes
• ✅ Ad Auto-dismiss - Automatically closes after 10 seconds
• ✅ Manual Close - X button to close ad early
• ✅ Countdown Display - Shows remaining seconds on ad
• ✅ CTA Button - "Learn More" button with external link support
• ✅ Search Timer - Shows elapsed time while finding driver
• ✅ Next Update Countdown - Shows time until next ad
• ✅ Status Tips - Helpful information while waiting
• ✅ Cancel During Search - Cancel booking while finding driver
• ✅ Driver Found Simulation - Auto-navigates after 15 seconds (demo)

Quick Start

Backend Setup

1. Navigate to backend directory:

cd backend

2. Create virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure .env file (see backend/README.md)

5. Start MongoDB (local or MongoDB Atlas)

6. Run server:

cd app
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at http://localhost:8000

Mobile App Setup

1. Navigate to mobile directory:

cd mobile

2. Install dependencies:

npm install

3. Configure .env file (see mobile/README.md)

4. Start Expo:

npm start

5. Run on device:

• Press i for iOS
• Press a for Android
• Scan QR code for physical device

Technology Stack

Backend

• Python 3.10+
• FastAPI
• MongoDB (Motor - async driver)
• JWT authentication
• bcrypt password hashing
• Google OAuth verification
• Apple Sign In verification

Frontend

• React Native 0.73
• Expo ~50.0
• Expo Router (file-based routing)
• NativeWind (Tailwind CSS)
• Zustand (state management)
• Axios (API calls)
• Expo SecureStore (secure storage)
• Expo Location (location permissions)
• React Native Maps (map integration)
• Google Sign In SDK
• Apple Authentication SDK

Development Notes

Environment Variables

Backend (.env):

• MONGODB_URI - MongoDB connection string
• JWT_SECRET - Secret for JWT signing
• GOOGLE_CLIENT_ID - Google OAuth client ID
• APPLE_CLIENT_ID - Apple bundle identifier
• CORS_ORIGINS - Allowed CORS origins
• SMTP_HOST - SMTP server host (e.g., smtp.gmail.com)
• SMTP_PORT - SMTP server port (e.g., 587)
• SMTP_USERNAME - SMTP username/email
• SMTP_PASSWORD - SMTP password/app password
• SMTP_FROM_EMAIL - Sender email address
• SMTP_FROM_NAME - Sender display name
• TWILIO_ACCOUNT_SID - Twilio account SID
• TWILIO_AUTH_TOKEN - Twilio auth token
• TWILIO_PHONE_NUMBER - Twilio phone number
• FRONTEND_URL - Frontend URL for email links

Frontend (.env):

• EXPO_PUBLIC_API_URL - Backend API URL
• EXPO_PUBLIC_GOOGLE_CLIENT_ID - Google OAuth client ID
• EXPO_PUBLIC_APPLE_CLIENT_ID - Apple bundle identifier

Google Maps Configuration

For iOS:

1. Get Google Maps API key from Google Cloud Console
2. Enable Maps SDK for iOS
3. Add API key to mobile/app.json under ios.config.googleMapsApiKey

For Android:

1. Get Google Maps API key from Google Cloud Console
2. Enable Maps SDK for Android
3. Add API key to mobile/app.json under android.config.googleMaps.apiKey
4. Add SHA-1 certificate fingerprint to Google Cloud Console

Location Permissions:

• iOS: Automatically configured via expo-location plugin
• Android: Permissions added to app.json (ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION)
• Users are prompted to enable location after profile setup

Network Configuration

For mobile testing on same network:

• Use your machine's local IP in EXPO_PUBLIC_API_URL
• Example: http://192.168.1.5:8000/api
• Find IP: ipconfig (Windows) or ifconfig (Mac/Linux)

API Endpoints

Authentication

• POST /api/auth/login - Email/Phone + Password login
• POST /api/auth/google - Google OAuth authentication
• POST /api/auth/apple - Apple Sign In authentication

Registration & Verification (Stage 2)

• POST /api/auth/register - Register new user
• POST /api/auth/verify-email - Verify email with code
• POST /api/auth/resend-email-code - Resend email verification code
• POST /api/auth/send-phone-code - Send phone verification SMS
• POST /api/auth/verify-phone - Verify phone with code
• POST /api/auth/profile-setup - Update profile information
• PUT /api/auth/update-profile - Update authenticated user's profile (requires Bearer token)

Ride Booking (Stage 3)

• POST /api/bookings/create - Create new ride booking (requires Bearer token)
• GET /api/bookings/my-bookings - Get user's booking history (requires Bearer token)
• GET /api/bookings/{booking_id} - Get specific booking details (requires Bearer token)
• PUT /api/bookings/{booking_id}/status - Update booking status (requires Bearer token)
• DELETE /api/bookings/{booking_id} - Cancel booking (requires Bearer token)

API documentation available at: http://localhost:8000/docs

Testing

Manual Testing

1. Start backend server
2. Start mobile app
3. Try logging in with:
   • Email + password
   • Google account
   • Apple ID (iOS only)

Test User

For development, you can create a test user directly in MongoDB:

db.users.insertOne({
  email: "test@example.com",
  password_hash: "$2b$12$...", // Use backend to hash: "password123"
  oauth_provider: "email",
  is_active: true,
  is_email_verified: false,
  is_phone_verified: false,
  created_at: new Date(),
  updated_at: new Date()
})

Next Steps (Stage 2)

• User registration with email/phone
• Profile setup screen (full name, photo)
• Email verification
• Phone verification with SMS
• Forgot password flow
• Password reset functionality

Stage 3 & Beyond

• Home screen with map
• Ride booking
• Driver features
• Payment integration
• Ratings and reviews
• Push notifications

Documentation

Detailed documentation available in:

• backend/README.md - Backend setup and API docs
• mobile/README.md - Mobile app setup and features

License

Private project - All rights reserved

Support

For issues or questions, please refer to the documentation or create an issue in the repository.