Uber Complete Project – Professional Architecture & Flow Guide

This repository contains a full ride-booking system with:

• Main Backend Service (Uber-Spring-2025) for business logic and persistence
• Realtime WebSocket Service (Uber-Websocket-Service) for driver/passenger live events
• Frontend App (UberFrontend-master) for driver and passenger experiences

---

1) Repository Structure

Uber-Complete-Project/
├── Uber-Spring-2025/          # REST API, booking logic, Redis geo, gRPC server/client
├── Uber-Websocket-Service/    # STOMP WebSocket gateway + gRPC server/client
└── UberFrontend-master/       # Vanilla JS client (driver/passenger modes)

---

2) Tech Stack

Layer	Technology
Frontend	HTML, CSS, Vanilla JavaScript, SockJS, STOMP
Main Backend	Java 21, Spring Boot 3.5, Spring Data JPA, Validation, Redis
WebSocket Service	Java 17, Spring Boot, Spring WebSocket/STOMP
Inter-service RPC	gRPC + Protobuf
Datastores	MySQL (bookings, drivers, passengers), Redis GEO (driver:geo)
Build/Test	Gradle, JUnit

---

3) High-Level Architecture Diagram

flowchart LR
    P[Passenger UI<br/>UberFrontend-master] -->|REST /api/*| B[Uber-Spring-2025<br/>Port 8080]
    D[Driver UI<br/>UberFrontend-master] -->|REST /api/*| B
    D -->|SockJS/STOMP<br/>/ws-uber| W[Uber-Websocket-Service<br/>Port 8082]
    P -->|SockJS/STOMP<br/>/ws-uber| W

    B -->|JPA| M[(MySQL)]
    B -->|Redis GEO| R[(Redis)]

    B -->|gRPC notifyRide / cancelRideNotification<br/>verifyTripCompletion / notifyDriverCompletion<br/>Port 9091| W
    W -->|gRPC acceptRide<br/>Port 9090| B

Loading

---

4) Ride Request Lifecycle (How Requests Come and Get Handled)

Step A — Driver location updates

1. Driver UI calls POST /api/v1/location/driverlocation.
2. Backend stores driver coordinates in Redis GEO key driver:geo.

Step B — Passenger creates ride request

1. Passenger UI calls POST /api/bookings.
2. Backend creates booking with status PENDING in MySQL.
3. Backend fetches nearby drivers from Redis within ~10 km.
4. Backend calls WebSocket service over gRPC notifyRide(...) with driverIds.
5. WebSocket service publishes /topic/new-ride/{driverId} to each driver.

Step C — Driver accepts ride

1. Driver UI sends STOMP message to /app/ride-acceptance with {driverId, bookingId}.
2. WebSocket service calls backend gRPC acceptRide(...).
3. Backend validates driver availability, assigns driver, sets booking CONFIRMED.
4. Backend calls gRPC cancelRideNotification(...) for other nearby drivers.
5. WebSocket service publishes /topic/ride-cancelled/{driverId} so other driver screens remove the request.

Step D — Ride in progress and completion

1. Driver UI sends periodic live location to /app/driver-location.
2. WebSocket service broadcasts /topic/ride-location/{bookingId}.
3. Passenger UI subscribes and tracks driver movement.
4. Driver requests completion via POST /api/bookings/{id}/complete-request.
5. Backend sets REQUESTED_COMPLETION, calls gRPC verifyTripCompletion.
6. Passenger receives /topic/verify-trip/{passengerId} and confirms.
7. Passenger confirms via POST /api/bookings/{id}/complete-confirm.
8. Backend sets COMPLETED, marks driver available, and notifies driver on /topic/trip-completed/{driverId}.

---

5) Sequence Diagram (Core Ride Flow)

sequenceDiagram
    participant PassengerUI
    participant DriverUI
    participant Backend as Uber-Spring-2025
    participant Redis
    participant WS as Uber-Websocket-Service
    participant MySQL

    DriverUI->>Backend: POST /api/v1/location/driverlocation
    Backend->>Redis: GEOADD driver:geo

    PassengerUI->>Backend: POST /api/bookings
    Backend->>MySQL: Insert booking (PENDING)
    Backend->>Redis: GEOSEARCH nearby drivers
    Backend->>WS: gRPC notifyRide(driverIds, bookingId)
    WS-->>DriverUI: /topic/new-ride/{driverId}

    DriverUI->>WS: STOMP /app/ride-acceptance
    WS->>Backend: gRPC acceptRide(driverId, bookingId)
    Backend->>MySQL: Update booking (CONFIRMED + driverId)
    Backend->>WS: gRPC cancelRideNotification(otherDrivers)
    WS-->>DriverUI: /topic/ride-cancelled/{driverId}

Loading

---

6) Microservice Communication Matrix

From	To	Protocol	Contract
Backend	WebSocket Service	gRPC	RideNotificationService.notifyRide
Backend	WebSocket Service	gRPC	cancelRideNotification
Backend	WebSocket Service	gRPC	verifyTripCompletion, notifyDriverCompletion
WebSocket Service	Backend	gRPC	RideService.acceptRide
Frontend	Backend	REST	/api/bookings, /api/drivers, /api/passengers, /api/v1/location/*
Frontend	WebSocket Service	STOMP/SockJS	/app/* send + /topic/* subscribe

---

7) WebSocket/STOMP Topics & Destinations

Client Sends (/app/*)

• /app/ride-acceptance
• /app/driver-location
• /app/chat

Client Subscribes (/topic/*)

• /topic/new-ride/{driverId}
• /topic/ride-cancelled/{driverId}
• /topic/verify-trip/{passengerId}
• /topic/trip-completed/{driverId}
• /topic/ride-location/{bookingId}
• /topic/chat/{bookingId}

---

8) Booking Status State Flow

stateDiagram-v2
    [*] --> PENDING
    PENDING --> CONFIRMED: Driver accepts
    CONFIRMED --> IN_PROGRESS
    IN_PROGRESS --> REQUESTED_COMPLETION: Driver requests completion
    REQUESTED_COMPLETION --> COMPLETED: Passenger confirms
    PENDING --> CANCELLED
    CONFIRMED --> CANCELLED

Loading

---

9) Run the Full System Locally

1. Start MySQL and Redis.
2. Start backend:

   cd Uber-Spring-2025
   ./gradlew bootRun

3. Start websocket service:

   cd Uber-Websocket-Service
   ./gradlew bootRun

4. Start frontend:

   cd UberFrontend-master
   python3 -m http.server 8000

5. Open:
   • Passenger: http://localhost:8000/index.html?role=passenger&passengerId=1
   • Driver: http://localhost:8000/index.html?role=driver&driverId=1

---

10) Important Implementation Notes

• gRPC contracts are shared in src/main/proto/booking.proto in both services.
• Backend gRPC server runs on 9090 and talks to WebSocket gRPC server on 9091.
• Redis is used for driver proximity search, not long-term booking storage.
• MySQL is the source of truth for bookings, passengers, and drivers.