# kevinnguyen20/dcaiti-ride-pooling architecture

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

- Interactive diagram: https://gitdiagram.com/kevinnguyen20/dcaiti-ride-pooling
- Repository: https://github.com/kevinnguyen20/dcaiti-ride-pooling

## Overview

This repository implements centralized ride-pooling applications for Eclipse MOSAIC simulations. Ride orders enter the dispatcher, which tracks bookings and shuttle status, assigns compatible rides, and sends stop/route plans to vehicle applications; shuttles execute those plans and report status and completed or declined rides. Rebalancing apps manage idle shuttle movement. The README documents the wider MOSAIC traffic, cellular, and application-simulation context and the BeST Berlin scenario. Unsampled modules are represented only where the README or tree supports their role; edges are limited to relationships shown in excerpts or explicitly documented.

Main entry points: [`src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java) (Dispatcher runtime), [`src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java) (Vehicle runtime), [`src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java) (Ride pooling service), [`src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java`](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java) (Subgraph matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dispatch["Dispatch and assignment"]
  node_dispatcher["Dispatcher runtime"]
  node_service["Ride pooling service"]
  node_provider["Ride provider"]
  node_matching["Subgraph matching"]
  node_heuristics["Heuristic base"]
  node_grid["Assignment grid<br/>[Grid.java]"]
  node_serviceconfig["Service configuration"]
end

subgraph group_vehicle["Shuttle operations"]
  node_vehiclebase["Vehicle runtime"]
  node_vehicleapp["Ride pooling vehicle"]
  node_returning["Return-to-base driving"]
  node_waiting["Dropoff waiting"]
  node_vehicleconfig["Vehicle configuration"]
end

subgraph group_domain["Ride domain and messaging"]
  node_ride["Ride booking state<br/>[Ride.java]"]
  node_status["Vehicle status<br/>[VehicleStatus.java]"]
  node_bookingmsg["Booking message"]
  node_statusmsg["Status message"]
  node_stop["Vehicle stops<br/>[VehicleStop.java]"]
  node_stopevent["Stop event<br/>[StopEvent.java]"]
end

subgraph group_simulation["Simulation context"]
  node_mosaic["Eclipse MOSAIC"]
  node_best["BeST scenario"]
end

node_orders(("Ride orders"))

node_orders -.->|"supplies orders"| node_provider
node_service -->|"extends"| node_dispatcher
node_service -->|"creates provider"| node_provider
node_dispatcher -->|"fetches bookings"| node_provider
node_service -->|"assigns bookings"| node_matching
node_matching -->|"uses heuristic base"| node_heuristics
node_matching -->|"matches rides"| node_ride
node_matching -->|"evaluates shuttles"| node_status
node_dispatcher -->|"stores bookings"| node_ride
node_dispatcher -->|"tracks fleet status"| node_status
node_dispatcher -->|"sends plans"| node_bookingmsg
node_vehiclebase -->|"sends status"| node_statusmsg
node_vehiclebase -->|"receives plans"| node_bookingmsg
node_vehiclebase -->|"updates stops/routes"| node_returning
node_vehicleapp -->|"extends"| node_vehiclebase
node_statusmsg -->|"carries status"| node_status
node_bookingmsg -->|"carries rides"| node_ride
node_bookingmsg -->|"carries stops"| node_stop
node_returning -->|"notifies apps"| node_stopevent
node_stopevent -->|"references stop"| node_stop
node_service -.->|"uses configuration"| node_serviceconfig
node_vehiclebase -->|"uses configuration"| node_vehicleconfig
node_mosaic -->|"runs scenario"| node_best
node_mosaic -->|"hosts applications"| node_dispatcher
node_mosaic -->|"hosts applications"| node_vehicleapp
node_mosaic -->|"maps shuttle logic"| node_returning
node_waiting -.->|"runs as shuttle app"| node_mosaic

click node_best "https://github.com/kevinnguyen20/dcaiti-ride-pooling/tree/assignment/resources/scenarios/best-scenario"
click node_dispatcher "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java"
click node_service "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java"
click node_provider "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/RidePoolingProvider.java"
click node_matching "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java"
click node_heuristics "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/AbstractHeuristics.java"
click node_grid "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/assignment/Grid.java"
click node_vehiclebase "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java"
click node_vehicleapp "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingVehicleApp.java"
click node_returning "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/ReturningToPointOfBusinessVehicleApp.java"
click node_waiting "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/WaitingAtDropoffLocationVehicleApp.java"
click node_ride "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/Ride.java"
click node_status "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/VehicleStatus.java"
click node_bookingmsg "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/RideBookingMessage.java"
click node_statusmsg "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/VehicleStatusMessage.java"
click node_stop "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/VehicleStop.java"
click node_stopevent "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/StopEvent.java"
click node_serviceconfig "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/CRidePoolingServiceApp.java"
click node_vehicleconfig "https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/config/CAbstractRidePoolingVehicleApp.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_dispatcher,node_service,node_provider,node_matching,node_heuristics,node_grid,node_serviceconfig toneBlue
class node_vehiclebase,node_vehicleapp,node_returning,node_waiting,node_vehicleconfig toneAmber
class node_ride,node_status,node_bookingmsg,node_statusmsg,node_stop,node_stopevent toneMint
class node_mosaic,node_best toneRose
class node_orders toneIndigo
```

## Components

### Dispatch and assignment

- [Dispatcher runtime](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`
- [Ride pooling service](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`
- [Ride provider](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/RidePoolingProvider.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/RidePoolingProvider.java`
- [Subgraph matching](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java`
- [Heuristic base](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/AbstractHeuristics.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/AbstractHeuristics.java`
- [Assignment grid](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/assignment/Grid.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/assignment/Grid.java`
- [Service configuration](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/CRidePoolingServiceApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/CRidePoolingServiceApp.java`

### Shuttle operations

- [Vehicle runtime](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`
- [Ride pooling vehicle](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingVehicleApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingVehicleApp.java`
- [Return-to-base driving](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/ReturningToPointOfBusinessVehicleApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/ReturningToPointOfBusinessVehicleApp.java`
- [Dropoff waiting](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/WaitingAtDropoffLocationVehicleApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/WaitingAtDropoffLocationVehicleApp.java`
- [Vehicle configuration](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/config/CAbstractRidePoolingVehicleApp.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/config/CAbstractRidePoolingVehicleApp.java`

### Ride domain and messaging

- [Ride booking state](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/Ride.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/Ride.java`
- [Vehicle status](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/VehicleStatus.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/server/VehicleStatus.java`
- [Booking message](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/RideBookingMessage.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/RideBookingMessage.java`
- [Status message](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/VehicleStatusMessage.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/VehicleStatusMessage.java`
- [Vehicle stops](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/VehicleStop.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/VehicleStop.java`
- [Stop event](https://github.com/kevinnguyen20/dcaiti-ride-pooling/blob/assignment/src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/StopEvent.java): `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/StopEvent.java`

### Simulation context

- **Eclipse MOSAIC**
- [BeST scenario](https://github.com/kevinnguyen20/dcaiti-ride-pooling/tree/assignment/resources/scenarios/best-scenario): `resources/scenarios/best-scenario`

### Other components

- **Ride orders**

## Connections

- Ride orders → Ride provider: supplies orders
- Ride pooling service → Dispatcher runtime: extends (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`)
- Ride pooling service → Ride provider: creates provider (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`)
- Dispatcher runtime → Ride provider: fetches bookings (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`)
- Ride pooling service → Subgraph matching: assigns bookings (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`)
- Subgraph matching → Heuristic base: uses heuristic base (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java`)
- Subgraph matching → Ride booking state: matches rides (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java`)
- Subgraph matching → Vehicle status: evaluates shuttles (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/heuristics/RestrictedSubgraphMatching.java`)
- Dispatcher runtime → Ride booking state: stores bookings (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`)
- Dispatcher runtime → Vehicle status: tracks fleet status (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`)
- Dispatcher runtime → Booking message: sends plans (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingServiceApp.java`)
- Vehicle runtime → Status message: sends status (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`)
- Vehicle runtime → Booking message: receives plans (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`)
- Vehicle runtime → Return-to-base driving: updates stops/routes (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`)
- Ride pooling vehicle → Vehicle runtime: extends (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingVehicleApp.java`)
- Status message → Vehicle status: carries status (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/VehicleStatusMessage.java`)
- Booking message → Ride booking state: carries rides (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/RideBookingMessage.java`)
- Booking message → Vehicle stops: carries stops (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/messages/RideBookingMessage.java`)
- Return-to-base driving → Stop event: notifies apps (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/strategies/rebalancing/ReturningToPointOfBusinessVehicleApp.java`)
- Stop event → Vehicle stops: references stop (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/utils/vehicle/StopEvent.java`)
- Ride pooling service → Service configuration: uses configuration (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/ridepooling/RidePoolingServiceApp.java`)
- Vehicle runtime → Vehicle configuration: uses configuration (evidence: `src/main/java/com/dcaiti/mosaic/app/ridehailing/AbstractRidePoolingVehicleApp.java`)
- Eclipse MOSAIC → BeST scenario: runs scenario (evidence: `README.md`)
- Eclipse MOSAIC → Dispatcher runtime: hosts applications (evidence: `README.md`)
- Eclipse MOSAIC → Ride pooling vehicle: hosts applications (evidence: `README.md`)
- Eclipse MOSAIC → Return-to-base driving: maps shuttle logic (evidence: `README.md`)
- Dropoff waiting → Eclipse MOSAIC: runs as shuttle app
