# krrishkumar125/ridewave-real-time-ride-matching-system architecture

> Architecture diagram of the GitHub repository krrishkumar125/ridewave-real-time-ride-matching-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krrishkumar125/ridewave-real-time-ride-matching-system
- Repository: https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system

## Overview

##### Project Type & Purpose
- RideWave is a monolithic, real-time backend service for ride-hailing. It exposes both HTTP REST endpoints (via Express) and WebSocket channels (via Socket.IO) to match passengers with drivers using geospatial data stored in Redis and persistent data in MongoDB.

##### File Structure
- Top-level files:
- package.json / package-lock.json – Node.js dependencies & scripts
- Readme.md – project overview
- src/index.js – application entry point: starts Express HTTP server + Socket.IO
- src/routes/ – defines HTTP routes (auth, booking, driver, passenger)
- src/controllers/ – orchestrates incoming requests / socket events
- src/services/ – business logic (booking matching, location lookups, auth flows)
- src/repository/ – data-access layer for MongoDB (via Mongoose models) and Redis (via geo and key–value)
- src/models/ – Mongoose schemas: user, booking
- src/utils/ – DB connectors (Mongo, Redis), distance calculation
- src/public/ – static frontend (driver.html) served by Express
- src/middlewares/ – JWT auth (ready for future use)

##### README Insights
- Tech stack: Node.js/Express, MongoDB, Redis (GEO), Socket.IO
- Key features: real-time socket events (`newBooking`, `rideConfirmed`, `removeBooking`), geospatial proximity matching, Redis caching & indexing, JWT authentication.
- System overview hints at layered architecture and heavy reliance on Redis GEO commands for performance.

##### Main Components
a. External Clients
– Passenger app (HTTP + WebSocket)
– Driver app (HTTP + WebSocket)
b. API Layer (Express)
– HTTP Server (routes → controllers)
– WebSocket Server (socket events handler in index.js)
c. Controller Layer
– authController, bookingController, driverController, passengerController
d. Service Layer
– authService (JWT), bookingService (lifecycle), driverService, passengerService, locationService (distance & geospatial logic)
e. Repository / Data Access
– MongoDB via bookingRepository.js & driverRepository.js & Mongoose models
– Redis via redisClient.js & GEO operations (driver socketId map, proximity search)
f. Data Stores & External Systems
– MongoDB (persistent storage for users & bookings)
– Redis (caching, driver ↔ socketId map, GEO indexing)
g. Static File Server
– Serves src/public/driver.html for driver UI (optional)

##### Relationships & Data Flows
- HTTP Request Flow:
Client → Express Router → Controller → Service → Repository → MongoDB → Service → Controller → Response → Client
- WebSocket Flow (e.g., newBooking):
Passenger emits `newBooking` → Socket.IO handler (index.js) → bookingController → bookingService:
- Save booking in MongoDB & push to Redis GEO index
- Query Redis GEO to find nearest drivers
- Emit `rideRequest` to matched driver sockets
- Redis GEO & Key–Value:
– driverService updates driver location & socketId in Redis
– bookingService issues GEORADIUS queries
- Middleware:
– authMiddleware enforces JWT validation on protected HTTP routes

##### Architectural Patterns & Principles
- Layered Architecture (Router → Controller → Service → Repository → Database)
- Separation of Concerns (e.g., controllers don’t access DB directly)
- Repository Pattern abstracts data stores (Mongo vs Redis)
- Event-Driven via WebSockets for real-time updates
- Caching & Geospatial Indexing in Redis for performance
- JWT-based authentication (middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    PassengerApp["Passenger App"]:::external
    DriverApp["Driver App"]:::external

    %% Server
    Server["HTTP & WebSocket Server"]:::server

    %% Inside Server
    subgraph "API Layer"
        AuthRoutes["Auth Routes"]:::layer
        BookingRoutes["Booking Routes"]:::layer
        DriverRoutes["Driver Routes"]:::layer
        PassengerRoutes["Passenger Routes"]:::layer
    end

    subgraph "Controller Layer"
        AuthController["Auth Controller"]:::layer
        BookingController["Booking Controller"]:::layer
        DriverController["Driver Controller"]:::layer
        PassengerController["Passenger Controller"]:::layer
    end

    subgraph "Service Layer"
        AuthService["Auth Service"]:::layer
        BookingService["Booking Service"]:::layer
        DriverService["Driver Service"]:::layer
        PassengerService["Passenger Service"]:::layer
        LocationService["Location Service"]:::layer
        ServicesIndex["Services Index"]:::layer
    end

    subgraph "Repository Layer"
        BookingRepo["Booking Repository"]:::layer
        DriverRepo["Driver Repository"]:::layer
    end

    subgraph "Utilities & Middleware"
        AuthMiddleware["JWT Auth Middleware"]:::layer
        DBConnector["MongoDB Connector"]:::layer
        RedisClientUtil["Redis Client & GEO Helper"]:::layer
        DistanceUtil["Distance Calculation Util"]:::layer
    end

    subgraph "Static File Server"
        DriverUI["Driver UI (driver.html)"]:::layer
    end

    %% Data Stores
    MongoDB["MongoDB"]:::db
    Redis["Redis (GEO & KV)"]:::db

    %% Connections: Clients to Server
    PassengerApp -->|HTTP/WebSocket| Server
    DriverApp -->|HTTP/WebSocket| Server

    %% Server to Layers
    Server -->|handles HTTP| AuthRoutes
    Server -->|handles HTTP| BookingRoutes
    Server -->|handles HTTP| DriverRoutes
    Server -->|handles HTTP| PassengerRoutes
    Server -->|serves static| DriverUI
    Server -->|uses middleware| AuthMiddleware

    %% Routes to Controllers
    AuthRoutes -->|"calls"| AuthController
    BookingRoutes -->|"calls"| BookingController
    DriverRoutes -->|"calls"| DriverController
    PassengerRoutes -->|"calls"| PassengerController

    %% Controllers to Services
    AuthController -->|"uses"| AuthService
    BookingController -->|"uses"| BookingService
    DriverController -->|"uses"| DriverService
    PassengerController -->|"uses"| PassengerService

    %% Services to Repository
    AuthService -->|"queries"| BookingRepo
    BookingService -->|"queries"| BookingRepo
    BookingService -->|"queries"| DriverRepo
    DriverService -->|"queries"| DriverRepo
    LocationService -->|"performs GEO"| DriverRepo

    %% Services Utilities
    AuthService -->|JWT flows| AuthMiddleware
    BookingService -->|distance logic| DistanceUtil
    DriverService -->|updates geo| RedisClientUtil
    LocationService -->|DB connect| DBConnector

    %% Repository to Data Stores
    BookingRepo -->|"CRUD"| MongoDB
    BookingRepo -->|"cache & GEO"| Redis
    DriverRepo -->|"cache & GEO"| Redis

    %% Legend & Style
    classDef external fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
    classDef server fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
    classDef layer fill:#FFF9C4,stroke:#F9A825,stroke-width:2px
    classDef db fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px

    %% Click Events
    click Server "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/index.js"
    click AuthRoutes "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/routes/authRoutes.js"
    click BookingRoutes "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/routes/bookingRoutes.js"
    click DriverRoutes "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/routes/driverRoutes.js"
    click PassengerRoutes "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/routes/passengerRoutes.js"
    click AuthController "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/controllers/authController.js"
    click BookingController "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/controllers/bookingController.js"
    click DriverController "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/controllers/driverController.js"
    click PassengerController "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/controllers/passengerController.js"
    click AuthService "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/authService.js"
    click BookingService "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/bookingService.js"
    click DriverService "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/driverService.js"
    click PassengerService "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/passengerService.js"
    click LocationService "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/locationService.js"
    click ServicesIndex "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/services/index.js"
    click BookingRepo "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/repository/bookingRepository.js"
    click DriverRepo "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/repository/driverRepository.js"
    click DBConnector "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/utils/db.js"
    click RedisClientUtil "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/utils/redisClient.js"
    click DistanceUtil "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/utils/distance.js"
    click AuthMiddleware "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/middlewares/authMiddleware.js"
    click DriverUI "https://github.com/krrishkumar125/ridewave-real-time-ride-matching-system/blob/master/src/public/driver.html"
```
