# hamilton2959/uber-application architecture

> Architecture diagram of the GitHub repository hamilton2959/uber-application, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamilton2959/uber-application
- Repository: https://github.com/hamilton2959/uber-application

## Overview

This repository implements a ride-hailing backend split into ride, matching, and location services. A rider submits a request; Ride Service persists it, estimates the fare, and publishes a request event. Matching Service finds and scores nearby drivers through Location Service, then publishes a match event that Ride Service uses to update the ride. Ride Service also supports lookup, cancellation, starting, and completion. The excerpts show the core calls and Redis geospatial behavior; some Kafka and database wiring is known only from the source index and event documentation.

Main entry points: [`ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java) (Ride lifecycle), [`matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java) (Driver selection), [`location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java`](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java) (Location search), [`ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java`](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java) (Ride API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ride["Ride management"]
  node_ride_api["Ride API"]
  node_ride_ops["Ride lifecycle<br/>[RideService.java]"]
  node_ride_request["Ride request<br/>[RideRequest.java]"]
  node_ride_response["Ride response<br/>[RideResponse.java]"]
  node_ride_model["Ride state<br/>[Ride.java]"]
  node_ride_status["Lifecycle statuses<br/>[RideStatus.java]"]
  node_ride_db[("Ride database")]
  node_ride_consumer["Match event handler"]
  node_requested_event["Ride request event"]
  node_ride_matched_schema["Match event schema"]
end

subgraph group_match["Driver matching"]
  node_match_consumer["Request event handler"]
  node_matching["Driver selection"]
  node_location_client["Location client"]
  node_matched_event["Match event"]
  node_matching_driver["Nearby driver data"]
  node_matching_request_event["Request event schema"]
end

subgraph group_location["Driver locations"]
  node_location_api["Location API"]
  node_location_ops["Location search"]
  node_location_request["Location update data"]
  node_location_driver["Nearby driver result"]
end

subgraph group_infra["Shared infrastructure"]
  node_redis[("Redis geospatial store<br/>[RedisConfig.java]")]
  node_kafka["Kafka topics"]
end

node_rider(("Rider or driver"))

node_rider -->|"requests or manages"| node_ride_api
node_ride_api -->|"calls"| node_ride_ops
node_ride_api -->|"accepts"| node_ride_request
node_ride_ops -->|"creates and updates"| node_ride_model
node_ride_ops -->|"reads and writes"| node_ride_db
node_ride_ops -->|"uses"| node_ride_request
node_ride_ops -->|"returns"| node_ride_response
node_ride_ops -->|"sets"| node_ride_status
node_ride_ops -->|"publishes"| node_requested_event
node_ride_ops -->|"sends request"| node_kafka
node_kafka -->|"delivers request"| node_match_consumer
node_match_consumer -->|"dispatches"| node_matching
node_match_consumer -->|"deserializes"| node_matching_request_event
node_matching -->|"queries nearby drivers"| node_location_client
node_location_client -->|"requests nearby drivers"| node_location_api
node_location_api -->|"calls"| node_location_ops
node_location_ops -->|"searches and updates"| node_redis
node_location_ops -->|"uses for updates"| node_location_request
node_location_ops -->|"returns nearby results"| node_location_driver
node_location_client -->|"returns driver data"| node_matching_driver
node_matching -->|"scores drivers"| node_matching_driver
node_matching -->|"creates"| node_matched_event
node_matching -->|"sends match"| node_kafka
node_kafka -->|"delivers match"| node_ride_consumer
node_ride_consumer -->|"updates assigned driver"| node_ride_ops
node_ride_consumer -->|"deserializes"| node_ride_matched_schema
node_ride_model -->|"stores status"| node_ride_status

click node_ride_api "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java"
click node_ride_ops "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java"
click node_ride_request "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/dto/RideRequest.java"
click node_ride_response "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/dto/RideResponse.java"
click node_ride_model "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/model/Ride.java"
click node_ride_status "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/model/RideStatus.java"
click node_ride_db "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/repository/RideRepository.java"
click node_ride_consumer "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java"
click node_match_consumer "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java"
click node_matching "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java"
click node_location_client "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/client/LocationServiceClient.java"
click node_matched_event "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/event/RideMatchedEvent.java"
click node_matching_driver "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/dto/NearByDriverResponse.java"
click node_location_api "https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/controller/LocationController.java"
click node_location_ops "https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java"
click node_location_request "https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/dto/DriverLocationRequest.java"
click node_location_driver "https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/dto/NearByDriverResponse.java"
click node_redis "https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/config/RedisConfig.java"
click node_requested_event "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/event/RideRequestedEvent.java"
click node_matching_request_event "https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/event/RideRequestedEvent.java"
click node_ride_matched_schema "https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/event/RideMatchedEvent.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_ride_api,node_ride_ops,node_ride_request,node_ride_response,node_ride_model,node_ride_status,node_ride_db,node_ride_consumer,node_requested_event,node_ride_matched_schema toneBlue
class node_match_consumer,node_matching,node_location_client,node_matched_event,node_matching_driver,node_matching_request_event toneAmber
class node_location_api,node_location_ops,node_location_request,node_location_driver toneMint
class node_redis,node_kafka toneRose
class node_rider toneIndigo
```

## Components

### Ride management

- [Ride API](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java): `ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java`
- [Ride lifecycle](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java): `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`
- [Ride request](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/dto/RideRequest.java): `ride-service/src/main/java/com/hamilton/rideservice/dto/RideRequest.java`
- [Ride response](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/dto/RideResponse.java): `ride-service/src/main/java/com/hamilton/rideservice/dto/RideResponse.java`
- [Ride state](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/model/Ride.java): `ride-service/src/main/java/com/hamilton/rideservice/model/Ride.java`
- [Lifecycle statuses](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/model/RideStatus.java): `ride-service/src/main/java/com/hamilton/rideservice/model/RideStatus.java`
- [Ride database](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/repository/RideRepository.java): `ride-service/src/main/java/com/hamilton/rideservice/repository/RideRepository.java`
- [Match event handler](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java): `ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java`
- [Ride request event](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/event/RideRequestedEvent.java): `ride-service/src/main/java/com/hamilton/rideservice/event/RideRequestedEvent.java`
- [Match event schema](https://github.com/hamilton2959/uber-application/blob/master/ride-service/src/main/java/com/hamilton/rideservice/event/RideMatchedEvent.java): `ride-service/src/main/java/com/hamilton/rideservice/event/RideMatchedEvent.java`

### Driver matching

- [Request event handler](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java): `matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java`
- [Driver selection](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java): `matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`
- [Location client](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/client/LocationServiceClient.java): `matching-service/src/main/java/com/hamilton/matchingservice/client/LocationServiceClient.java`
- [Match event](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/event/RideMatchedEvent.java): `matching-service/src/main/java/com/hamilton/matchingservice/event/RideMatchedEvent.java`
- [Nearby driver data](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/dto/NearByDriverResponse.java): `matching-service/src/main/java/com/hamilton/matchingservice/dto/NearByDriverResponse.java`
- [Request event schema](https://github.com/hamilton2959/uber-application/blob/master/matching-service/src/main/java/com/hamilton/matchingservice/event/RideRequestedEvent.java): `matching-service/src/main/java/com/hamilton/matchingservice/event/RideRequestedEvent.java`

### Driver locations

- [Location API](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/controller/LocationController.java): `location-service/src/main/java/com/hamilton/locationservice/controller/LocationController.java`
- [Location search](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java): `location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java`
- [Location update data](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/dto/DriverLocationRequest.java): `location-service/src/main/java/com/hamilton/locationservice/dto/DriverLocationRequest.java`
- [Nearby driver result](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/dto/NearByDriverResponse.java): `location-service/src/main/java/com/hamilton/locationservice/dto/NearByDriverResponse.java`

### Shared infrastructure

- [Redis geospatial store](https://github.com/hamilton2959/uber-application/blob/master/location-service/src/main/java/com/hamilton/locationservice/config/RedisConfig.java): `location-service/src/main/java/com/hamilton/locationservice/config/RedisConfig.java`
- **Kafka topics**

### Other components

- **Rider or driver**

## Connections

- Rider or driver → Ride API: requests or manages (evidence: `ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java`)
- Ride API → Ride lifecycle: calls (evidence: `ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java`)
- Ride API → Ride request: accepts (evidence: `ride-service/src/main/java/com/hamilton/rideservice/controller/RideController.java`)
- Ride lifecycle → Ride state: creates and updates (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Ride database: reads and writes (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Ride request: uses (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Ride response: returns (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Lifecycle statuses: sets (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Ride request event: publishes (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Ride lifecycle → Kafka topics: sends request (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideService.java`)
- Kafka topics → Request event handler: delivers request (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java`)
- Request event handler → Driver selection: dispatches (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java`)
- Request event handler → Request event schema: deserializes (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/RideEventConsumer.java`)
- Driver selection → Location client: queries nearby drivers (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`)
- Location client → Location API: requests nearby drivers (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/client/LocationServiceClient.java`)
- Location API → Location search: calls (evidence: `location-service/src/main/java/com/hamilton/locationservice/controller/LocationController.java`)
- Location search → Redis geospatial store: searches and updates (evidence: `location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java`)
- Location search → Location update data: uses for updates (evidence: `location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java`)
- Location search → Nearby driver result: returns nearby results (evidence: `location-service/src/main/java/com/hamilton/locationservice/service/LocationService.java`)
- Location client → Nearby driver data: returns driver data (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/client/LocationServiceClient.java`)
- Driver selection → Nearby driver data: scores drivers (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`)
- Driver selection → Match event: creates (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`)
- Driver selection → Kafka topics: sends match (evidence: `matching-service/src/main/java/com/hamilton/matchingservice/service/MatchingService.java`)
- Kafka topics → Match event handler: delivers match (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java`)
- Match event handler → Ride lifecycle: updates assigned driver (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java`)
- Match event handler → Match event schema: deserializes (evidence: `ride-service/src/main/java/com/hamilton/rideservice/service/RideEventConsumer.java`)
- Ride state → Lifecycle statuses: stores status (evidence: `ride-service/src/main/java/com/hamilton/rideservice/model/Ride.java`)