RiderFlow

Real-Time Ride Dispatch System

A scalable, event-driven ride-sharing backend inspired by Uber — built with Node.js, Redis, Kafka, and Socket.io.

---

✨ Key Highlights

Feature	Description
⚡ Real-Time Updates	Live ride status via Socket.io WebSockets
📍 Geo-Based Matching	Nearest driver search using Redis GEO indexing
🔄 Event-Driven	Asynchronous ride processing with Apache Kafka
🔐 Secure Auth	JWT-based authentication & role middleware
🧱 Scalable Design	Modular, layered architecture built for scale

---

🏗️ System Architecture

Client (Postman / App)
        │
        ▼
Node.js API (Express)
        │
        ▼
Kafka  ──── Ride Request Published to Topic
        │
        ▼
Kafka Consumer Service
        │
        ▼
Redis GEO ──── Nearest Driver Search
        │
        ▼
PostgreSQL (via Prisma ORM)
        │
        ▼
Socket.io ──── Real-Time Push to Rider & Driver

---

🔁 Ride Lifecycle

Rider requests ride
      │
      ▼
Ride event published to Kafka
      │
      ▼
Consumer processes event asynchronously
      │
      ▼
Redis GEO finds nearest available driver
      │
      ▼
Driver assigned → saved to DB
      │
      ▼
Socket.io sends real-time notification

MATCHED → ACCEPTED → IN_PROGRESS → COMPLETED

---

🛠️ Tech Stack

Layer	Technology
Backend	Node.js, Express
Database	PostgreSQL (Prisma ORM)
Real-Time	Socket.io
Caching / Geo Search	Redis (GEO commands)
Event Streaming	Apache Kafka + Zookeeper
Authentication	JWT
Dev Tools	Docker, Nodemon

---

📁 Project Structure

backend/
├── src/
│   ├── config/           # Redis & Kafka configuration
│   ├── controllers/      # Route controllers (request/response)
│   ├── services/         # Core business logic
│   ├── repositories/     # Database access layer (Prisma)
│   ├── routes/           # Express route definitions
│   ├── middleware/        # Auth & role-based access control
│   ├── sockets/          # Socket.io event handlers
│   ├── kafka/            # Kafka producer & consumer
│   ├── utils/            # Helper utilities
│   ├── validators/       # Zod schema validators
│   ├── app.js
│   └── server.js
├── prisma/
│   └── schema.prisma
├── docker-compose.yml
└── .env

---

⚙️ Setup & Installation

1. Clone the Repository

git clone https://github.com/Dhanush-1213/riderflow-distributed-system.git
cd riderflow-distributed-system/backend

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the backend/ directory:

PORT=5000
DATABASE_URL=your_postgres_connection_url
JWT_SECRET=your_jwt_secret_key

4. Start Infrastructure (Docker)

docker compose up -d

This spins up:

• 🟥 Redis — GEO-based driver caching
• 📦 Kafka — event streaming broker
• 🔗 Zookeeper — Kafka coordination service

5. Run the Backend

npm run dev

The server starts at http://localhost:5000.

---

📡 API Reference

🔐 Authentication

Method	Endpoint	Description
POST	/api/auth/login	Login and receive JWT token

🚗 Driver

Method	Endpoint	Description
PATCH	/api/driver/online	Set driver status to online
PATCH	/api/driver/location	Update driver's geo-location

🧍 Rider

Method	Endpoint	Description
POST	/api/rides/request	Request a new ride

🔄 Ride Lifecycle

Method	Endpoint	Description
PATCH	/api/rides/:id/accept	Driver accepts ride
PATCH	/api/rides/:id/start	Driver starts ride
PATCH	/api/rides/:id/complete	Mark ride as completed

---

🔌 Real-Time Socket Events

Event	Direction	Description
new_ride_request	→ Driver	New ride request dispatched
ride_accepted	→ Rider	Driver has accepted the ride
ride_started	→ Rider	Ride is now in progress
ride_completed	→ Rider & Driver	Ride successfully completed

---

🎬 Demo Flow

1. Driver goes online          →  PATCH /api/driver/online
2. Driver updates location     →  PATCH /api/driver/location
3. Rider requests a ride       →  POST  /api/rides/request
4. Kafka processes the event   →  Async consumer kicks in
5. Redis finds nearest driver  →  GEO radius search
6. Driver receives request     →  Socket.io: new_ride_request
7. Driver accepts              →  PATCH /api/rides/:id/accept
8. Rider gets notified         →  Socket.io: ride_accepted
9. Ride starts & completes     →  PATCH start → complete

---

🧠 Key Concepts Demonstrated

• Event-Driven Architecture — Decoupled services communicate via Kafka topics
• Real-Time Systems — WebSocket-based live updates using Socket.io
• Geo-Spatial Queries — Redis GEO commands for nearest-driver matching
• Distributed Design — Kafka enables async, scalable request processing
• Layered Architecture — Clean separation of controllers, services, and repositories

---

🔮 Future Improvements

• Microservices decomposition (split into independent services)
• API Gateway for unified routing and rate limiting
• Load balancing across multiple Node.js instances
• Monitoring & observability with Prometheus + Grafana
• Deployment on AWS ECS / Kubernetes
• Ride fare estimation & surge pricing logic
• Driver ratings and feedback system

---

👨‍💻 Author

Dhanush
B.Tech CSE (AI & ML) — PES University

---

_{Built with ❤️ to demonstrate real-world distributed systems design}