Ridex - Advanced Ride-Hailing Platform

Ridex is a full-stack ride-hailing application designed to simulate the core functionalities of platforms like Uber. It connects users (riders) with captains (drivers) in real-time, facilitating seamless ride booking, tracking, and management. Built with the MERN stack (MongoDB, Express.js, React, Node.js) and powered by Socket.io for real-time communication and Mapbox for geospatial services.

🚀 Features

👤 User (Rider) Features

Authentication: Secure Sign Up and Login using JWT.
Location Search: Auto-complete location search for pickup and dropoff points powered by Mapbox.
Fare Estimation: View estimated fares for different vehicle types (Car, Auto, Bike) before booking.
Ride Booking: Request a ride and wait for a captain to accept.
Real-time Tracking: Track the captain's location on the map in real-time as they approach.
Ride Details: View captain's details (name, vehicle info) and OTP for ride verification.
Live Route Display: See the route from pickup to dropoff with markers and polylines.
Ride Status Updates: Real-time notifications when ride is accepted, started, and finished.
Payment: (UI Only) View fare and payment options.

🚗 Captain (Driver) Features

Authentication: Secure Sign Up and Login with vehicle details.
Real-time Location Sharing: Automatically share location with the backend every 10 seconds.
Ride Requests: Receive real-time ride requests with pickup/dropoff details and fare.
Ride Management: Accept or ignore ride requests.
Navigation: View the route to the pickup location and destination on the map.
OTP Verification: Secure ride start mechanism using a 6-digit OTP provided by the user.
Status Updates: Update ride status (accepted, started, finished).
Profile Dashboard: View personal stats and earnings (UI ready).

🛠️ Technical Features

Real-time Communication: Socket.io integration for instant updates between User and Captain:
- Ride Request notifications
- Ride acceptance
- Captain location updates
- Ride start/finish events
Geospatial Services: Mapbox API integration for:
- Forward Geocoding (Address to Coordinates).
- Distance and Duration calculation.
- Auto-complete suggestions.
- Route plotting with Directions API (Polyline).
- Live user location tracking.
Security:
- BCrypt for password hashing.
- JWT (JSON Web Tokens) for secure authentication and authorization.
- Middleware for protecting routes (User & Captain specific, or combined).
- Token blacklisting on logout.
Responsive UI: Mobile-first design using Tailwind CSS.
Animations: Smooth UI transitions using GSAP (GreenSock Animation Platform).
Error Handling: Comprehensive error handling on both frontend and backend.
Data Validation: Express Validator for request validation.

🏗️ Tech Stack

Frontend

Framework: React.js 18+ (Vite)
Styling: Tailwind CSS
Routing: React Router DOM v6
State Management: React Context API (UserContext, CaptainContext, SocketContext)
Maps: Mapbox GL JS, React Map GL
Real-time: Socket.io Client
Animations: GSAP (GreenSock Animation Platform)
HTTP Client: Axios
Icons: Lucide React, Remix Icon
Build Tool: Vite

Backend

Runtime: Node.js
Framework: Express.js
Database: MongoDB with Mongoose ODM
Real-time: Socket.io
Maps: Mapbox API (via Axios)
Validation: Express Validator
Authentication: JSON Web Token (JWT), BCrypt
Dev Tools: Nodemon, dotenv

📂 Project Structure

Ridex/
├── Backend/                 # Node.js/Express Backend
│   ├── controllers/         # Request handlers
│   │   ├── captain.controller.js
│   │   ├── maps.controller.js
│   │   ├── ride.controller.js
│   │   └── user.controller.js
│   ├── db/                  # Database connection
│   │   └── db.js
│   ├── middlewares/         # Auth and validation middlewares
│   │   └── auth.middleware.js
│   ├── models/              # Mongoose models
│   │   ├── blacklist.model.js
│   │   ├── captain.model.js
│   │   ├── ride.model.js
│   │   └── user.model.js
│   ├── routes/              # API routes
│   │   ├── captain.routes.js
│   │   ├── maps.routes.js
│   │   ├── ride.routes.js
│   │   └── user.route.js
│   ├── services/            # Business logic
│   │   ├── captain.service.js
│   │   ├── maps.service.js
│   │   ├── ride.service.js
│   │   └── user.service.js
│   ├── socket.js            # Socket.io configuration
│   ├── app.js               # Express app setup
│   ├── server.js            # Server entry point
│   └── Readme.md            # Backend API documentation
│
└── frontend/                # React Frontend
    ├── src/
    │   ├── components/      # Reusable UI components
    │   │   ├── CaptainDetails.jsx
    │   │   ├── ConfirmRide.jsx
    │   │   ├── DriverDetails.jsx
    │   │   ├── FinishRide.jsx
    │   │   ├── LocationSearchPanel.jsx
    │   │   ├── Map.jsx
    │   │   ├── RidePopup.jsx
    │   │   ├── StartRide.jsx
    │   │   └── VehiclePanel.jsx
    │   ├── context/         # Context providers
    │   │   ├── Captaincontext.jsx
    │   │   ├── SocketContext.jsx
    │   │   └── UserContext.jsx
    │   ├── pages/           # Application pages
    │   │   ├── CaptainHome.jsx
    │   │   ├── CaptainLogin.jsx
    │   │   ├── CaptainRiding.jsx
    │   │   ├── CaptainSignup.jsx
    │   │   ├── Home.jsx
    │   │   ├── Ride.jsx
    │   │   ├── Start.jsx
    │   │   ├── UserLogin.jsx
    │   │   └── UserSignup.jsx
    │   ├── App.jsx          # Main component & routing
    │   └── main.jsx         # Entry point
    └── ...

🏛️ Architecture

High-Level Overview

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│   User UI   │ ◄─────► │   Backend    │ ◄─────► │  Captain UI  │
│   (React)   │         │  (Express)   │         │   (React)    │
└─────────────┘         └──────────────┘         └──────────────┘
       │                        │                        │
       │                        │                        │
       ▼                        ▼                        ▼
┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│  Socket.io  │ ◄─────► │  Socket.io   │ ◄─────► │  Socket.io   │
│   Client    │         │   Server     │         │    Client    │
└─────────────┘         └──────────────┘         └──────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │   MongoDB    │
                        │   Database   │
                        └──────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  Mapbox API  │
                        └──────────────┘

Request Flow

User/Captain authenticates via login (JWT issued)
Socket connection established on successful login
User searches locations (Mapbox autocomplete)
User requests ride → Backend notifies nearby Captains
Captain accepts ride → User receives notification
Captain starts ride (OTP verification) → User updated
Real-time location shared throughout the ride
Captain finishes ride → Both parties notified

⚙️ Installation & Setup

Prerequisites

Node.js (v14 or higher)
MongoDB (Local or Atlas)
Mapbox Account (for API Key) - Get it here

1. Clone the Repository

git clone <repository-url>
cd Ridex

2. Backend Setup

Navigate to the backend directory:
```
cd Backend
```
Install dependencies:
```
npm install
```

Create a .env file in the Backend directory:

PORT=4000
MONGO_URI=your_mongodb_connection_string
JWT_SECRET_KEY=your_jwt_secret
MAPBOX_API_KEY=your_mapbox_access_token

Start the server:
```
npm start
# OR for development with nodemon
npm run dev
```
The backend will run on http://localhost:4000

3. Frontend Setup

Navigate to the frontend directory:
```
cd ../frontend
```
Install dependencies:
```
npm install
```

Create a .env file in the frontend directory:

VITE_BASE_URL=http://localhost:4000
VITE_MAPBOX_API_KEY=your_mapbox_access_token

Start the development server:
```
npm run dev
```
The frontend will run on http://localhost:5173

🔐 Environment Variables

Backend (.env)

Variable	Description	Example
`PORT`	Server port	`4000`
`MONGO_URI`	MongoDB connection string	`mongodb://localhost:27017/ridex`
`JWT_SECRET_KEY`	Secret key for JWT signing	`your_secret_key`
`MAPBOX_API_KEY`	Mapbox public token	`pk.ey...`

Frontend (.env)

Variable	Description	Example
`VITE_BASE_URL`	Backend API URL	`http://localhost:4000`
`VITE_MAPBOX_API_KEY`	Mapbox public token	`pk.ey...`

🗺️ API Documentation

For detailed API documentation, please refer to the Backend README.

Key Endpoints

User: /user/register, /user/login, /user/profile, /user/logout
Captain: /captain/register, /captain/login, /captain/profile, /captain/logout
Maps: /maps/get-coordinates, /maps/get-distance-time, /maps/get-suggestions
Rides: /rides/create, /rides/getfare, /rides/confirm-ride, /rides/start, /rides/finish

💾 Database Models

User Model

{
  fullName: { firstName, lastName },
  email: String (unique),
  password: String (hashed),
  socketId: String
}

Captain Model

{
  fullName: { firstName, lastName },
  email: String (unique),
  password: String (hashed),
  socketId: String,
  status: 'active' | 'inactive',
  vehicle: {
    color, plate, capacity, vehicleType: 'car' | 'motorcycle' | 'auto'
  },
  location: { ltd, lng }
}

Ride Model

{
  user: ObjectId (ref: User),
  captain: ObjectId (ref: Captain),
  pickup: String,
  dropoff: String,
  fare: Number,
  status: 'pending' | 'accepted' | 'ongoing' | 'completed' | 'cancelled',
  duration: Number,
  distance: Number,
  pickupLocation: { ltd, lng },
  dropoffLocation: { ltd, lng },
  otp: String (6-digit, select: false)
}

Blacklist Token Model

{
  token: String,
  createdAt: Date (expires after 24h)
}

📡 Real-time Events

Socket.io Events

Event	Emitter	Listener	Data	Description
`join`	Client	Server	`{ userType, userId }`	User/Captain joins socket room
`update-location-captain`	Captain	Server	`{ userId, location }`	Captain shares location
`new-ride`	Server	Captain	Ride details	Notify captain of new ride request
`ride-accepted`	Server	User	Ride details	Notify user ride was accepted
`ride-started`	Server	User	Ride details	Notify user ride has started
`ride-finished`	Server	User & Captain	Ride details	Notify both ride is complete

🚀 Key Features Implementation

1. Real-time Captain Location

Captain's browser sends location every 10 seconds
Backend updates captain's location in MongoDB
Location used to find nearby captains for ride requests

2. Ride Matching Algorithm

When user creates ride, backend finds captains within radius
Uses Haversine formula to calculate distance
Notifies all nearby captains via Socket.io

3. OTP Security

6-digit OTP generated on ride creation
Stored with select: false in database
Captain must verify OTP to start ride
Protects against unauthorized ride starts

4. Dynamic Map Integration

Mapbox GL with custom controls
Green marker for pickup, red for dropoff
Route polyline drawn using Directions API
Auto-centering and bounds fitting
Live location tracking with blue dot

🔮 Future Enhancements

🐛 Known Issues

Map may require location permission reload on first visit
Socket reconnection on network drop needs improvement
Captain location updates pause when browser tab is inactive

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the project
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

Mapbox for geospatial services
Socket.io for real-time communication
MongoDB for database
Inspired by ride-hailing platforms like Uber and Lyft

Built with ❤️ using the MERN Stack

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
Backend		Backend
frontend		frontend
.gitignore		.gitignore
Readme.md		Readme.md

Folders and files

Latest commit

History

Repository files navigation

Ridex - Advanced Ride-Hailing Platform

📋 Table of Contents

🚀 Features

👤 User (Rider) Features

🚗 Captain (Driver) Features

🛠️ Technical Features

🏗️ Tech Stack

Frontend

Backend

📂 Project Structure

🏛️ Architecture

High-Level Overview

Request Flow

⚙️ Installation & Setup

Prerequisites

1. Clone the Repository

2. Backend Setup

3. Frontend Setup

🔐 Environment Variables

Backend (.env)

Frontend (.env)

🗺️ API Documentation

Key Endpoints

💾 Database Models

User Model

Captain Model

Ride Model

Blacklist Token Model

📡 Real-time Events

Socket.io Events

🚀 Key Features Implementation

1. Real-time Captain Location

2. Ride Matching Algorithm

3. OTP Security

4. Dynamic Map Integration

🔮 Future Enhancements

🐛 Known Issues

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages