# hadda-saad/ridehailing architecture

> Architecture diagram of the GitHub repository hadda-saad/ridehailing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hadda-saad/ridehailing
- Repository: https://github.com/hadda-saad/ridehailing

## Overview

RideHailing is a Spring backend for driver/rider accounts, ride management, fare estimates, and real-time driver locations. The principal location workflow is documented as driver updates entering a queue, being processed asynchronously into history and a latest-position cache, then pushed to connected apps; current-location reads prefer the cache. The tree and README support these capabilities, but sampled source does not show the queue, cache, or WebSocket implementation or wiring, so those links are documented rather than source-verified. Other API-to-service interactions are only included where the index or excerpts support them.

Main entry points: [`src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java`](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java) (Location Service), [`src/main/java/com/ridehailing/auth/service/AuthService.java`](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/service/AuthService.java) (Account Service), [`src/main/java/com/ridehailing/location/controller/DriverLocationController.java`](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/controller/DriverLocationController.java) (Location API), [`src/main/java/com/ridehailing/auth/controller/AuthController.java`](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/controller/AuthController.java) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Accounts and Security"]
  node_auth_api["Authentication API"]
  node_auth_logic["Account Service<br/>[AuthService.java]"]
  node_users[("User Accounts<br/>[User.java]")]
  node_jwt["JWT Tokens<br/>[JwtService.java]"]
end

subgraph group_people["Driver and Rider Profiles"]
  node_driver_profiles["Driver Profiles"]
  node_rider_profiles["Rider Profiles"]
end

subgraph group_journeys["Rides and Pricing"]
  node_ride_api["Ride API"]
  node_ride_logic["Ride Management"]
  node_ride_store[("Ride Records")]
  node_price_api["Fare API"]
  node_price_logic["Fare Estimation"]
  node_price_store[("Fare Records")]
end

subgraph group_tracking["Live Location"]
  node_location_api["Location API"]
  node_producer["Location Producer"]
  node_queue["Event Queue"]
  node_consumer["Location Worker"]
  node_location_logic["Location Service"]
  node_location_store[("Location History")]
  node_latest_cache[("Latest Position Cache")]
  node_live_push["Live Updates"]
end

node_rider_app(("Rider App"))
node_driver_app(("Driver App"))
node_api["Backend API"]

node_driver_app -->|"sends positions"| node_location_api
node_location_api -.->|"enqueues update"| node_producer
node_producer -.->|"publishes event"| node_queue
node_queue -.->|"delivers event"| node_consumer
node_consumer -.->|"processes update"| node_location_logic
node_location_logic -->|"stores history"| node_location_store
node_location_logic -.->|"updates latest"| node_latest_cache
node_location_logic -.->|"broadcasts position"| node_live_push
node_live_push -.->|"pushes updates"| node_rider_app
node_rider_app -.->|"requests position"| node_location_api
node_location_api -->|"queries location"| node_location_logic
node_location_logic -.->|"checks first"| node_latest_cache
node_location_logic -.->|"falls back"| node_location_store
node_api -.->|"routes requests"| node_auth_api
node_rider_app -->|"registers or logs in"| node_auth_api
node_driver_app -->|"registers or logs in"| node_auth_api
node_auth_api -->|"delegates"| node_auth_logic
node_auth_logic -->|"reads and writes"| node_users
node_auth_logic -->|"creates token"| node_jwt
node_auth_logic -->|"registers driver"| node_driver_profiles
node_auth_logic -->|"registers rider"| node_rider_profiles
node_api -.->|"routes requests"| node_ride_api
node_rider_app -->|"requests rides"| node_ride_api
node_ride_api -->|"delegates"| node_ride_logic
node_ride_logic -.->|"reads and writes"| node_ride_store
node_api -.->|"routes requests"| node_price_api
node_rider_app -.->|"requests estimate"| node_price_api
node_price_api -->|"delegates"| node_price_logic
node_price_logic -.->|"reads and writes"| node_price_store

click node_auth_api "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/controller/AuthController.java"
click node_auth_logic "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/service/AuthService.java"
click node_users "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/model/User.java"
click node_jwt "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/security/JwtService.java"
click node_driver_profiles "https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/driver/service"
click node_rider_profiles "https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/rider/service"
click node_ride_api "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/ride/controller/RideController.java"
click node_ride_logic "https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/ride/service"
click node_ride_store "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/ride/repository/RideRepository.java"
click node_price_api "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/controller/PriceEstimateController.java"
click node_price_logic "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/service/PriceEstimateServiceImpl.java"
click node_price_store "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/repository/PriceEstimateRepository.java"
click node_location_api "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/controller/DriverLocationController.java"
click node_producer "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/LocationProducer.java"
click node_consumer "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/LocationConsumer.java"
click node_location_logic "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java"
click node_location_store "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/repository/DriverLocationRepository.java"
click node_live_push "https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/config/WebSocketConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth_api,node_auth_logic,node_users,node_jwt toneBlue
class node_driver_profiles,node_rider_profiles toneAmber
class node_ride_api,node_ride_logic,node_ride_store,node_price_api,node_price_logic,node_price_store,node_api toneMint
class node_location_api,node_producer,node_queue,node_consumer,node_location_logic,node_location_store,node_latest_cache,node_live_push toneRose
class node_rider_app,node_driver_app toneIndigo
```

## Components

### Accounts and Security

- [Authentication API](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/controller/AuthController.java): `src/main/java/com/ridehailing/auth/controller/AuthController.java`
- [Account Service](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/service/AuthService.java): `src/main/java/com/ridehailing/auth/service/AuthService.java`
- [User Accounts](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/model/User.java): `src/main/java/com/ridehailing/auth/model/User.java`
- [JWT Tokens](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/auth/security/JwtService.java): `src/main/java/com/ridehailing/auth/security/JwtService.java`

### Driver and Rider Profiles

- [Driver Profiles](https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/driver/service): `src/main/java/com/ridehailing/driver/service`
- [Rider Profiles](https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/rider/service): `src/main/java/com/ridehailing/rider/service`

### Rides and Pricing

- [Ride API](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/ride/controller/RideController.java): `src/main/java/com/ridehailing/ride/controller/RideController.java`
- [Ride Management](https://github.com/hadda-saad/ridehailing/tree/main/src/main/java/com/ridehailing/ride/service): `src/main/java/com/ridehailing/ride/service`
- [Ride Records](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/ride/repository/RideRepository.java): `src/main/java/com/ridehailing/ride/repository/RideRepository.java`
- [Fare API](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/controller/PriceEstimateController.java): `src/main/java/com/ridehailing/PriceEstimate/controller/PriceEstimateController.java`
- [Fare Estimation](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/service/PriceEstimateServiceImpl.java): `src/main/java/com/ridehailing/PriceEstimate/service/PriceEstimateServiceImpl.java`
- [Fare Records](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/PriceEstimate/repository/PriceEstimateRepository.java): `src/main/java/com/ridehailing/PriceEstimate/repository/PriceEstimateRepository.java`

### Live Location

- [Location API](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/controller/DriverLocationController.java): `src/main/java/com/ridehailing/location/controller/DriverLocationController.java`
- [Location Producer](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/LocationProducer.java): `src/main/java/com/ridehailing/location/service/LocationProducer.java`
- **Event Queue**
- [Location Worker](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/LocationConsumer.java): `src/main/java/com/ridehailing/location/service/LocationConsumer.java`
- [Location Service](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java): `src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java`
- [Location History](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/repository/DriverLocationRepository.java): `src/main/java/com/ridehailing/location/repository/DriverLocationRepository.java`
- **Latest Position Cache**
- [Live Updates](https://github.com/hadda-saad/ridehailing/blob/main/src/main/java/com/ridehailing/location/config/WebSocketConfig.java): `src/main/java/com/ridehailing/location/config/WebSocketConfig.java`

### Other components

- **Rider App**
- **Driver App**
- **Backend API**

## Connections

- Driver App → Location API: sends positions
- Location API → Location Producer: enqueues update (evidence: `src/main/java/com/ridehailing/location/controller/DriverLocationController.java`)
- Location Producer → Event Queue: publishes event
- Event Queue → Location Worker: delivers event
- Location Worker → Location Service: processes update
- Location Service → Location History: stores history (evidence: `src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java`)
- Location Service → Latest Position Cache: updates latest
- Location Service → Live Updates: broadcasts position
- Live Updates → Rider App: pushes updates
- Rider App → Location API: requests position
- Location API → Location Service: queries location (evidence: `src/main/java/com/ridehailing/location/controller/DriverLocationController.java`)
- Location Service → Latest Position Cache: checks first
- Location Service → Location History: falls back (evidence: `src/main/java/com/ridehailing/location/service/DriverLocationServiceImpl.java`)
- Backend API → Authentication API: routes requests
- Rider App → Authentication API: registers or logs in
- Driver App → Authentication API: registers or logs in
- Authentication API → Account Service: delegates (evidence: `src/main/java/com/ridehailing/auth/controller/AuthController.java`)
- Account Service → User Accounts: reads and writes (evidence: `src/main/java/com/ridehailing/auth/service/AuthService.java`)
- Account Service → JWT Tokens: creates token (evidence: `src/main/java/com/ridehailing/auth/service/AuthService.java`)
- Account Service → Driver Profiles: registers driver (evidence: `src/main/java/com/ridehailing/auth/service/AuthService.java`)
- Account Service → Rider Profiles: registers rider (evidence: `src/main/java/com/ridehailing/auth/service/AuthService.java`)
- Backend API → Ride API: routes requests
- Rider App → Ride API: requests rides
- Ride API → Ride Management: delegates (evidence: `src/main/java/com/ridehailing/ride/controller/RideController.java`)
- Ride Management → Ride Records: reads and writes
- Backend API → Fare API: routes requests
- Rider App → Fare API: requests estimate
- Fare API → Fare Estimation: delegates (evidence: `src/main/java/com/ridehailing/PriceEstimate/controller/PriceEstimateController.java`)
- Fare Estimation → Fare Records: reads and writes