# is3unicologne/urban-mobility-simulation architecture

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

- Interactive diagram: https://gitdiagram.com/is3unicologne/urban-mobility-simulation
- Repository: https://github.com/is3unicologne/urban-mobility-simulation

## Overview

Urban-mobility-simulation is a discrete-event platform for studying ride-hailing, shared mobility, public transport, charging infrastructure, and mobility markets. A configured run builds its simulation context and world, creates demand, then lets users seek service alternatives that operators search and allocate; vehicles execute trips and operations while metrics track outcomes. The graph preserves documented service and charging branches. Edges are limited to relationships visible in excerpts or the README; unsampled wiring is not inferred.

Main entry points: [`simulation/simulation.py`](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/simulation.py) (Simulation Runner), [`simulation/operator/operator.py`](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/operator.py) (Service Operators), [`simulation/operator/search_engine.py`](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/search_engine.py) (Search Engines), [`simulation/world/world.py`](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/world.py) (World)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Run Core"]
  node_config["Scenario Configuration<br/>[configuration.py]"]
  node_runner["Simulation Runner<br/>[simulation.py]"]
  node_context["Simulation Context"]
end

subgraph group_demand["Demand And Users"]
  node_world["World<br/>[world.py]"]
  node_demandfactory["Demand Factory<br/>[demand_factory.py]"]
  node_user["User Agent<br/>[user.py]"]
end

subgraph group_services["Mobility Services"]
  node_request["Transport Request"]
  node_mobilitysearch["Mobility Search"]
  node_operators["Service Operators<br/>[operator.py]"]
  node_ridehail["Ride-Hailing Service"]
  node_shared["Shared Mobility Service"]
  node_public["Public Transport"]
  node_search["Search Engines<br/>[search_engine.py]"]
  node_alternative["Trip Alternatives"]
  node_allocation["Vehicle Allocation"]
end

subgraph group_execution["Fleet And Operations"]
  node_fleet["Vehicle Fleets<br/>[vehicle_fleet.py]"]
  node_vehicle["Vehicles<br/>[vehicle.py]"]
  node_route["Routes And Transit<br/>[route.py]"]
  node_charging["Charging Infrastructure"]
  node_operations["Operations Management<br/>[operations.py]"]
  node_market["Mobility Markets<br/>[auction.py]"]
end

subgraph group_insight["Metrics And Visualization"]
  node_metrics["Metrics Tracking<br/>[metrics_tracker.py]"]
  node_visualization["Live Visualization"]
  node_rl["Reinforcement Learning<br/>[env.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures"| node_config
node_config -->|"configures"| node_runner
node_runner -->|"creates"| node_context
node_runner -->|"creates"| node_world
node_runner -->|"starts demand"| node_demandfactory
node_runner -->|"creates"| node_metrics
node_context -.->|"simulation state"| node_world
node_demandfactory -.->|"generates demand"| node_world
node_world -.->|"serves users"| node_user
node_user -->|"creates request"| node_request
node_mobilitysearch -->|"queries operators"| node_operators
node_operators -->|"selects engine"| node_search
node_search -->|"returns options"| node_alternative
node_operators -.->|"specializes as"| node_ridehail
node_operators -.->|"specializes as"| node_shared
node_operators -.->|"specializes as"| node_public
node_ridehail -.->|"uses search"| node_search
node_shared -.->|"uses search"| node_search
node_public -.->|"uses search"| node_search
node_allocation -.->|"allocates vehicles"| node_fleet
node_fleet -->|"registers vehicle"| node_vehicle
node_vehicle -->|"traverses route"| node_route
node_operations -.->|"manages fleet"| node_fleet
node_operations -.->|"manages charging"| node_charging
node_market -.->|"coordinates services"| node_operators
node_metrics -->|"feeds dashboard"| node_visualization
node_rl -->|"controls simulation"| node_runner

click node_config "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/helper/configuration/configuration.py"
click node_runner "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/simulation.py"
click node_context "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/context/simulation_context.py"
click node_world "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/world.py"
click node_demandfactory "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/demand/demand_factory.py"
click node_user "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/agent/user/user.py"
click node_request "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/data_transfer_object/transport_request.py"
click node_mobilitysearch "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/mobility_search_engine.py"
click node_operators "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/operator.py"
click node_ridehail "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/ride_hailing_operator.py"
click node_shared "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/shared_mobility_operator.py"
click node_public "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/public_transit_operator.py"
click node_search "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/search_engine.py"
click node_alternative "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/data_transfer_object/transportation_alternative.py"
click node_allocation "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/vehicle_allocation_engine.py"
click node_fleet "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/vehicle_fleet.py"
click node_vehicle "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/vehicle/vehicle.py"
click node_route "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/infrastructure/route.py"
click node_charging "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/infrastructure/charging_stations/charging_infastructure.py"
click node_operations "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/operations_management/operations.py"
click node_market "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/markets/auction.py"
click node_metrics "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/metrics/metrics_tracker.py"
click node_visualization "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/visualization/visualization_manager.py"
click node_rl "https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/rl/env.py"

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_config,node_runner,node_context toneBlue
class node_world,node_demandfactory,node_user toneAmber
class node_request,node_mobilitysearch,node_operators,node_ridehail,node_shared,node_public,node_search,node_alternative,node_allocation toneMint
class node_fleet,node_vehicle,node_route,node_charging,node_operations,node_market toneRose
class node_metrics,node_visualization,node_rl,node_researcher toneIndigo
```

## Components

### Run Core

- [Scenario Configuration](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/helper/configuration/configuration.py): `simulation/helper/configuration/configuration.py`
- [Simulation Runner](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/simulation.py): `simulation/simulation.py`
- [Simulation Context](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/context/simulation_context.py): `simulation/context/simulation_context.py`

### Demand And Users

- [World](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/world.py): `simulation/world/world.py`
- [Demand Factory](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/demand/demand_factory.py): `simulation/world/demand/demand_factory.py`
- [User Agent](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/agent/user/user.py): `simulation/agent/user/user.py`

### Mobility Services

- [Transport Request](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/data_transfer_object/transport_request.py): `simulation/operator/data_transfer_object/transport_request.py`
- [Mobility Search](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/mobility_search_engine.py): `simulation/world/mobility_search_engine.py`
- [Service Operators](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/operator.py): `simulation/operator/operator.py`
- [Ride-Hailing Service](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/ride_hailing_operator.py): `simulation/operator/ride_hailing_operator.py`
- [Shared Mobility Service](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/shared_mobility_operator.py): `simulation/operator/shared_mobility_operator.py`
- [Public Transport](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/public_transit_operator.py): `simulation/operator/public_transit_operator.py`
- [Search Engines](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/search_engine.py): `simulation/operator/search_engine.py`
- [Trip Alternatives](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/data_transfer_object/transportation_alternative.py): `simulation/operator/data_transfer_object/transportation_alternative.py`
- [Vehicle Allocation](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/vehicle_allocation_engine.py): `simulation/operator/vehicle_allocation_engine.py`

### Fleet And Operations

- [Vehicle Fleets](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/vehicle_fleet.py): `simulation/operator/vehicle_fleet.py`
- [Vehicles](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/vehicle/vehicle.py): `simulation/vehicle/vehicle.py`
- [Routes And Transit](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/infrastructure/route.py): `simulation/infrastructure/route.py`
- [Charging Infrastructure](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/infrastructure/charging_stations/charging_infastructure.py): `simulation/infrastructure/charging_stations/charging_infastructure.py`
- [Operations Management](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/operator/operations_management/operations.py): `simulation/operator/operations_management/operations.py`
- [Mobility Markets](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/world/markets/auction.py): `simulation/world/markets/auction.py`

### Metrics And Visualization

- [Metrics Tracking](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/simulation/metrics/metrics_tracker.py): `simulation/metrics/metrics_tracker.py`
- [Live Visualization](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/visualization/visualization_manager.py): `visualization/visualization_manager.py`
- [Reinforcement Learning](https://github.com/is3unicologne/urban-mobility-simulation/blob/develop/rl/env.py): `rl/env.py`

### Other components

- **Researcher**

## Connections

- Researcher → Scenario Configuration: configures (evidence: `README.md`)
- Scenario Configuration → Simulation Runner: configures (evidence: `simulation/simulation.py`)
- Simulation Runner → Simulation Context: creates (evidence: `simulation/simulation.py`)
- Simulation Runner → World: creates (evidence: `simulation/simulation.py`)
- Simulation Runner → Demand Factory: starts demand (evidence: `simulation/simulation.py`)
- Simulation Runner → Metrics Tracking: creates (evidence: `simulation/simulation.py`)
- Simulation Context → World: simulation state
- Demand Factory → World: generates demand
- World → User Agent: serves users
- User Agent → Transport Request: creates request (evidence: `simulation/agent/user/user.py`)
- Mobility Search → Service Operators: queries operators (evidence: `simulation/world/mobility_search_engine.py`)
- Service Operators → Search Engines: selects engine (evidence: `simulation/operator/search_engine.py`)
- Search Engines → Trip Alternatives: returns options (evidence: `simulation/operator/ride_hailing_search_engine.py`)
- Service Operators → Ride-Hailing Service: specializes as
- Service Operators → Shared Mobility Service: specializes as
- Service Operators → Public Transport: specializes as
- Ride-Hailing Service → Search Engines: uses search
- Shared Mobility Service → Search Engines: uses search
- Public Transport → Search Engines: uses search
- Vehicle Allocation → Vehicle Fleets: allocates vehicles
- Vehicle Fleets → Vehicles: registers vehicle (evidence: `simulation/vehicle/vehicle.py`)
- Vehicles → Routes And Transit: traverses route (evidence: `simulation/vehicle/vehicle.py`)
- Operations Management → Vehicle Fleets: manages fleet
- Operations Management → Charging Infrastructure: manages charging
- Mobility Markets → Service Operators: coordinates services
- Metrics Tracking → Live Visualization: feeds dashboard (evidence: `visualization/visualization_manager.py`)
- Reinforcement Learning → Simulation Runner: controls simulation (evidence: `rl/env.py`)