Ride Management System Documentation

Overview

This app now features a comprehensive ride management system similar to Uber, handling both collector (customer) and customer (Rider) roles with distinct color themes and full ride flow tracking.

Color Themes

collector Role (customer)

• Primary Color: amber-600 (#d97706)
• Secondary Color: amber-50 to amber-200 for backgrounds
• Use Case: customers requesting raddi pickup services

customer Role (Rider)

• Primary Color: emerald-600 (#059669)
• Secondary Color: emerald-50 to emerald-200 for backgrounds
• Use Case: customers collecting raddi from customers

Architecture

State Management

1. Auth Slice (authSlice.tsx)

• Stores user authentication token
• NEW: Stores user role ('collector' | 'customer')
• Actions:
  • login(token): Store auth token
  • setRole(role): Set user role
  • setuser(userData): Store user data
  • logout(): Clear all auth data

2. Ride Slice (rideSlice.tsx)

Manages the complete ride lifecycle with the following states:

Ride Statuses:

• idle - No active ride
• searching - collector searching for customer
• pending - Order placed, waiting for acceptance
• accepted - customer accepted the order
• on_way - customer heading to pickup location
• arrived - customer arrived at pickup
• picked_up - Items picked up
• completed - Ride completed
• cancelled - Ride cancelled

Actions:

• createOrder() - collector creates a new order
• acceptOrder() - customer accepts an order
• updatecustomerLocation() - Update customer's real-time location
• updatecollectorLocation() - Update collector's location
• setRideStatus() - Update ride status
• completeRide() - Mark ride as completed
• cancelRide() - Cancel the ride
• resetRide() - Reset to initial state

User Flows

collector (customer) Flow

1. Initial State (idle)

   • User sees map with their current location
   • "Request Pickup" button visible at bottom

2. Request Pickup

   • Bottom sheet appears with form:
     • Pickup address
     • Approximate weight (kg)
   • Submit triggers createOrder action
   • Status changes to pending

3. Waiting for customer (pending)

   • "Finding a customer..." message displayed
   • Can cancel the order
   • Socket listening for customer acceptance

4. customer Accepted (accepted)

   • Toast notification: "Order Accepted!"
   • customer name and ETA displayed
   • Map shows customer's location
   • Route drawn between collector and customer

5. customer On Way (on_way)

   • Real-time updates of customer location
   • Route updates dynamically
   • Status: "customer on the way"

6. customer Arrived (arrived)

   • Notification: "customer has arrived"
   • Can contact customer

7. Items Picked Up (picked_up)

   • Notification: "Items picked up"
   • Tracking continues if customer moves

8. Ride Completed (completed)

   • Success notification
   • Ride details displayed
   • Auto-reset after 3 seconds

customer (Rider) Flow

1. Available for Orders (idle)

   • Map shows customer's current location
   • "Waiting for orders..." status
   • Location tracked in background

2. New Order Received

   • Modal appears with order details:
     • customer name
     • Pickup address
     • Approximate weight
     • Distance
   • Options: Accept or Reject

3. Order Accepted (accepted)

   • Order info card displayed on map
   • customer location visible
   • "Start Navigation" button
   • Route drawn to customer

4. Navigate to customer (on_way)

   • Real-time location sent to customer every 10 seconds
   • "Mark as Arrived" button visible
   • Route updates

5. Arrived at Pickup (arrived)

   • Status updated
   • customer notified
   • "Pick Up Items" button

6. Items Picked Up (picked_up)

   • Status updated
   • "Complete Ride" button visible

7. Ride Completed (completed)

   • Success notification
   • Auto-reset after 2 seconds
   • Ready for next order

Socket Events

Emitted by Client

collector Events:

• makeRaddiOrder - Create new pickup request

  {
    customerId: number,
    pickupLatitude: number,
    pickupLongitude: number,
    pickupAddress: string,
    approximateRaddiInKg: string
  }

• cancelOrder - Cancel pending order

customer Events:

• acceptOrder - Accept incoming order

  {
    orderId: string,
    customerId: string,
    customerName: string
  }

• rejectOrder - Reject incoming order
• updatecustomerLocation - Send location update

  {
    orderId: string,
    latitude: number,
    longitude: number
  }

• updateRideStatus - Update ride status

  {
    orderId: string,
    status: string
  }

Received by Client

collector Receives:

• orderCreated - Confirmation of order creation
• orderAccepted - customer accepted order
• customerLocationUpdate - Real-time customer location
• rideStatusUpdate - Status changes
• orderCancelled - Order was cancelled

customer Receives:

• newOrderAvailable - New order notification
• orderCancelledBycustomer - customer cancelled

Components

collectorRideScreen

• Main screen for collectors
• Handles order creation and tracking
• Shows real-time customer location
• Displays ride status
• Color theme: Amber

customerRideScreen

• Main screen for customers
• Receives and displays incoming orders
• Order accept/reject modal
• Status update buttons
• Real-time location broadcasting
• Color theme: Emerald

LiveMap

• Displays interactive map
• Shows markers for collector/customer locations
• Draws route between locations
• Auto-fits map to show all markers
• Uses OSRM for routing
• Fallback to straight line if routing fails

Navigation

Authenticated Navigation

• Role-based routing
• collectors see: Home | Activity | Request | Account
• customers see: Home | Activity | Orders | Account
• Tab bar color adapts to role
• Initial route: "Ride" (role-specific screen)

Real-Time Features

Location Tracking

• Continuous GPS updates
• Permission handling
• 10-second intervals during active rides
• Background location updates

Map Updates

• Real-time marker movement
• Dynamic route recalculation
• Smooth animations
• Auto-zoom to fit all markers

Theme Integration

All screens adapt based on user role:

• Home Screen: Role-specific labels and colors
• Profile Screen: Role-specific banner color
• Navigation: Role-specific active color
• Ride Screens: Complete theme integration

Best Practices

Performance

• Location updates throttled to 10 seconds
• Socket listeners cleaned up on unmount
• Map animations optimized
• Efficient state updates

Error Handling

• Permission denied fallback
• Socket disconnection handling
• Location unavailable fallback
• Network error notifications

User Experience

• Clear status indicators
• Toast notifications for all events
• Loading states
• Smooth transitions
• Intuitive button placement

Future Enhancements

1. In-App Chat: Communication between collector and customer
2. Rating System: Rate completed rides
3. Payment Integration: In-app payment processing
4. Ride History: View past rides
5. Push Notifications: Background notifications
6. ETA Calculation: Real-time arrival estimates
7. Multiple Orders: customers handle multiple orders
8. Order Queue: collectors see available customers
9. Price Estimation: Automatic pricing
10. Analytics: Dashboard with ride statistics

Testing Checklist

• collector can create order
• customer receives order notification
• customer can accept/reject orders
• Real-time location updates work
• Map shows correct markers
• Route drawing works
• Status updates propagate correctly
• Toast notifications appear
• Cancel functionality works
• Ride completion works
• Color themes correct for both roles
• Navigation works correctly
• Socket reconnection handling
• Permission handling
• Error scenarios handled

Dependencies

{
  "@react-navigation/bottom-tabs": "Tab navigation",
  "react-native-maps": "Map display and markers",
  "lucide-react-native": "Icons",
  "react-native-alert-notification": "Toast notifications",
  "@reduxjs/toolkit": "State management",
  "socket.io-client": "Real-time communication"
}

File Structure

src/
├── store/
│   ├── store.tsx (Redux store configuration)
│   └── slices/
│       ├── authSlice.tsx (Auth + Role)
│       ├── rideSlice.tsx (Ride state management)
│       └── socketSlice.tsx (Socket connection)
├── screens/
│   └── authenticated/
│       ├── collectorRideScreen.tsx (collector ride flow)
│       ├── customerRideScreen.tsx (customer ride flow)
│       ├── Home.tsx (Role-aware home)
│       └── Profile.tsx (Role-aware profile)
├── components/
│   ├── LiveMap.tsx (Enhanced map)
│   ├── Header.tsx
│   └── BottomSheet.tsx
├── navigation/
│   └── authenticated.tsx (Role-based navigation)
└── services/
    └── socketService.tsx (Socket.io client)

Summary

This comprehensive ride management system provides:

• ✅ Full ride lifecycle tracking (8 states)
• ✅ Real-time location updates
• ✅ Role-based UI/UX (collector/customer)
• ✅ Dynamic color theming
• ✅ Socket-based communication
• ✅ Interactive map with routing
• ✅ Notifications and status updates
• ✅ Complete state management
• ✅ Professional user experience

The system is production-ready and follows industry best practices for ride-hailing applications.