# jaypatel2611/quantum_traffic_route_optimization architecture

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

- Interactive diagram: https://gitdiagram.com/jaypatel2611/quantum_traffic_route_optimization
- Repository: https://github.com/jaypatel2611/quantum_traffic_route_optimization

## Overview

This is a web application for comparing vehicle-routing solutions and their environmental impact on a selected cached road network. The user selects a city and delivery scenario, optionally marks an accident segment, starts a job, watches solver convergence, then reviews route comparisons and green-impact results. The backend derives distance and travel-time matrices, applies stochastic delays, runs OR-Tools and QPSO concurrently, and exposes results and progress. The source excerpts establish these primary connections; some capabilities are evident from the tree and module names but their internal wiring is not sampled.

Main entry points: [`backend/app/presentation/api/v1/optimize_router.py`](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/api/v1/optimize_router.py) (Optimization API), [`frontend/src/App.tsx`](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/App.tsx) (Screen Router), [`frontend/src/api/client.ts`](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/api/client.ts) (API Client), [`backend/app/application/services/optimization_orchestrator.py`](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/application/services/optimization_orchestrator.py) (Job Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Scenario UI"]
  node_app["Screen Router<br/>[App.tsx]"]
  node_setup["Scenario Setup<br/>[SetupScreen.tsx]"]
  node_live["Live Run<br/>[LiveRunScreen.tsx]"]
  node_results["Route Results<br/>[ResultsScreen.tsx]"]
  node_impact["Green Impact"]
  node_state["App State<br/>[AppState.tsx]"]
  node_client["API Client<br/>[client.ts]"]
end

subgraph group_api["HTTP API"]
  node_api_main["FastAPI App<br/>[main.py]"]
  node_scenario_api["Scenario API<br/>[scenario_router.py]"]
  node_optimize_api["Optimization API<br/>[optimize_router.py]"]
  node_stream["Convergence Stream"]
end

subgraph group_geo["Road Network"]
  node_repo["Cached Graph Repo"]
  node_osmnx["Graph Loader<br/>[osmnx_client.py]"]
  node_matrix["Matrix Builder"]
  node_delay["Stochastic Delays"]
end

subgraph group_optimization["Optimization"]
  node_orchestrator["Job Orchestrator"]
  node_ortools["OR-Tools Solver"]
  node_qpso["QPSO Solver<br/>[qpso_solver.py]"]
  node_green_calc["Impact Calculator"]
  node_copert["COPERT Model<br/>[copert_model.py]"]
end

subgraph group_domain["Domain Models"]
  node_entities["Route and Node<br/>[route.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"provides state"| node_state
node_app -->|"shows"| node_setup
node_app -->|"shows"| node_live
node_app -->|"shows"| node_results
node_app -->|"shows"| node_impact
node_setup -->|"requests scenarios"| node_client
node_live -->|"starts and streams"| node_client
node_results -->|"fetches result"| node_client
node_impact -->|"fetches result"| node_client
node_client -->|"HTTP requests"| node_scenario_api
node_client -->|"HTTP requests"| node_optimize_api
node_api_main -->|"mounts router"| node_scenario_api
node_api_main -->|"mounts router"| node_optimize_api
node_scenario_api -->|"lists cities and edges"| node_repo
node_optimize_api -->|"builds matrices"| node_repo
node_repo -->|"loads cached graph"| node_osmnx
node_repo -->|"computes matrices"| node_matrix
node_optimize_api -->|"adds travel delays"| node_delay
node_optimize_api -->|"submits job"| node_orchestrator
node_orchestrator -->|"dispatches comparison"| node_ortools
node_orchestrator -->|"dispatches comparison"| node_qpso
node_optimize_api -->|"reads job state"| node_orchestrator
node_optimize_api -->|"computes impact"| node_green_calc
node_green_calc -.->|"emissions model"| node_copert
node_optimize_api -->|"opens event stream"| node_stream
node_stream -->|"reads convergence"| node_orchestrator
node_ortools -->|"produces routes"| node_entities
node_qpso -->|"produces routes"| node_entities

click node_app "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/App.tsx"
click node_setup "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/SetupScreen.tsx"
click node_live "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/LiveRunScreen.tsx"
click node_results "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/ResultsScreen.tsx"
click node_impact "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/GreenImpactScreen.tsx"
click node_state "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/state/AppState.tsx"
click node_client "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/api/client.ts"
click node_api_main "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/main.py"
click node_scenario_api "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/api/v1/scenario_router.py"
click node_optimize_api "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/api/v1/optimize_router.py"
click node_stream "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/sse/convergence_stream.py"
click node_repo "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/cached_graph_repository.py"
click node_osmnx "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/osmnx_client.py"
click node_matrix "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/distance_matrix_builder.py"
click node_delay "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/stochastic_delay_injector.py"
click node_orchestrator "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/application/services/optimization_orchestrator.py"
click node_ortools "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/or_tools_baseline.py"
click node_qpso "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/qpso_solver.py"
click node_green_calc "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/application/services/green_impact_calculator.py"
click node_copert "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/copert_model.py"
click node_entities "https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/domain/entities/route.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_app,node_setup,node_live,node_results,node_impact,node_state,node_client,node_user toneBlue
class node_api_main,node_scenario_api,node_optimize_api,node_stream toneAmber
class node_repo,node_osmnx,node_matrix,node_delay toneMint
class node_orchestrator,node_ortools,node_qpso,node_green_calc,node_copert toneRose
class node_entities toneIndigo
```

## Components

### Scenario UI

- [Screen Router](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scenario Setup](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/SetupScreen.tsx): `frontend/src/screens/SetupScreen.tsx`
- [Live Run](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/LiveRunScreen.tsx): `frontend/src/screens/LiveRunScreen.tsx`
- [Route Results](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/ResultsScreen.tsx): `frontend/src/screens/ResultsScreen.tsx`
- [Green Impact](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/screens/GreenImpactScreen.tsx): `frontend/src/screens/GreenImpactScreen.tsx`
- [App State](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/state/AppState.tsx): `frontend/src/state/AppState.tsx`
- [API Client](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### HTTP API

- [FastAPI App](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/main.py): `backend/app/main.py`
- [Scenario API](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/api/v1/scenario_router.py): `backend/app/presentation/api/v1/scenario_router.py`
- [Optimization API](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/api/v1/optimize_router.py): `backend/app/presentation/api/v1/optimize_router.py`
- [Convergence Stream](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/presentation/sse/convergence_stream.py): `backend/app/presentation/sse/convergence_stream.py`

### Road Network

- [Cached Graph Repo](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/cached_graph_repository.py): `backend/app/infrastructure/geospatial/cached_graph_repository.py`
- [Graph Loader](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/osmnx_client.py): `backend/app/infrastructure/geospatial/osmnx_client.py`
- [Matrix Builder](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/distance_matrix_builder.py): `backend/app/infrastructure/geospatial/distance_matrix_builder.py`
- [Stochastic Delays](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/geospatial/stochastic_delay_injector.py): `backend/app/infrastructure/geospatial/stochastic_delay_injector.py`

### Optimization

- [Job Orchestrator](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/application/services/optimization_orchestrator.py): `backend/app/application/services/optimization_orchestrator.py`
- [OR-Tools Solver](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/or_tools_baseline.py): `backend/app/infrastructure/algorithms/or_tools_baseline.py`
- [QPSO Solver](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/qpso_solver.py): `backend/app/infrastructure/algorithms/qpso_solver.py`
- [Impact Calculator](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/application/services/green_impact_calculator.py): `backend/app/application/services/green_impact_calculator.py`
- [COPERT Model](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/infrastructure/algorithms/copert_model.py): `backend/app/infrastructure/algorithms/copert_model.py`

### Domain Models

- [Route and Node](https://github.com/jaypatel2611/quantum_traffic_route_optimization/blob/main/backend/app/domain/entities/route.py): `backend/app/domain/entities/route.py`

### Other components

- **User**

## Connections

- User → Screen Router: uses
- Screen Router → App State: provides state
- Screen Router → Scenario Setup: shows
- Screen Router → Live Run: shows
- Screen Router → Route Results: shows
- Screen Router → Green Impact: shows
- Scenario Setup → API Client: requests scenarios
- Live Run → API Client: starts and streams
- Route Results → API Client: fetches result
- Green Impact → API Client: fetches result
- API Client → Scenario API: HTTP requests
- API Client → Optimization API: HTTP requests
- FastAPI App → Scenario API: mounts router
- FastAPI App → Optimization API: mounts router
- Scenario API → Cached Graph Repo: lists cities and edges
- Optimization API → Cached Graph Repo: builds matrices
- Cached Graph Repo → Graph Loader: loads cached graph
- Cached Graph Repo → Matrix Builder: computes matrices
- Optimization API → Stochastic Delays: adds travel delays
- Optimization API → Job Orchestrator: submits job
- Job Orchestrator → OR-Tools Solver: dispatches comparison
- Job Orchestrator → QPSO Solver: dispatches comparison
- Optimization API → Job Orchestrator: reads job state
- Optimization API → Impact Calculator: computes impact
- Impact Calculator → COPERT Model: emissions model
- Optimization API → Convergence Stream: opens event stream
- Convergence Stream → Job Orchestrator: reads convergence
- OR-Tools Solver → Route and Node: produces routes
- QPSO Solver → Route and Node: produces routes