# vaidik04/q-transit-nexus architecture

> Architecture diagram of the GitHub repository vaidik04/q-transit-nexus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vaidik04/q-transit-nexus
- Repository: https://github.com/vaidik04/q-transit-nexus

## Overview

Q-Transit Nexus is a transportation digital twin and optimization system. Its documented core loop models network conditions, predicts future traffic, computes routing and control decisions, applies them to the simulation, and measures outcomes; the dashboard presents operational state and results. The repository also contains a separate backend digital-twin/orchestration stack and a 137ML prediction package. The graph reflects documented workflows and indexed imports; several subsystem internals and dashboard-to-API wiring were not sampled, so those connections are omitted.

Main entry points: [`backend/orchestrator.py`](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/orchestrator.py) (Cycle Orchestrator), [`simulation/state_manager.py`](https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/state_manager.py) (Twin State Contract), [`backend/modules/at_dqpso.py`](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/at_dqpso.py) (Adaptive Routing), [`backend/modules/network_engine.py`](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/network_engine.py) (Urban Network)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Dashboard"]
  node_dashboard["Operations Dashboard<br/>[App.jsx]"]
  node_dashboard_views["Map and Panels"]
end

subgraph group_service["Backend Services"]
  node_backend_entry["Backend Entry<br/>[main.py]"]
  node_api_routes["API Routes"]
  node_orchestrator["Cycle Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_simulation["Digital Twin"]
  node_network["Urban Network<br/>[network_engine.py]"]
  node_twin["Backend Digital Twin"]
  node_state["Twin State Contract<br/>[state_manager.py]"]
  node_scenarios["Scenario Runs"]
  node_actuation["Route and Signal Control<br/>[route_applier.py]"]
  node_sim_metrics["Simulation Metrics<br/>[metrics.py]"]
end

subgraph group_intelligence["Prediction and Optimization"]
  node_traffic_prediction["Traffic Prediction"]
  node_ml_pipeline["137ML Prediction"]
  node_feature_engineering["Feature Engineering"]
  node_optimization["Adaptive Routing<br/>[at_dqpso.py]"]
  node_optimizer_core["Optimization Algorithms"]
  node_benchmarks["Algorithm Benchmarks<br/>[benchmarks.py]"]
end

subgraph group_domain["Transport Intelligence"]
  node_transit["Transit Intelligence"]
  node_ev["EV Charging<br/>[ev_intelligence.py]"]
  node_emergency["Emergency Priority"]
  node_explainability["Decision Explanations<br/>[explainability.py]"]
  node_trust["Trust Ledger<br/>[trust_layer.py]"]
end

node_operator(("Operator"))

node_operator -->|"operates"| node_dashboard
node_dashboard -->|"renders"| node_dashboard_views
node_backend_entry -->|"initializes"| node_orchestrator
node_backend_entry -->|"registers"| node_api_routes
node_orchestrator -->|"creates"| node_network
node_orchestrator -->|"creates"| node_twin
node_twin -->|"uses"| node_network
node_orchestrator -->|"creates"| node_traffic_prediction
node_orchestrator -->|"creates"| node_optimization
node_orchestrator -->|"creates"| node_transit
node_orchestrator -->|"creates"| node_ev
node_orchestrator -->|"creates"| node_emergency
node_orchestrator -->|"creates"| node_explainability
node_orchestrator -->|"creates"| node_trust
node_orchestrator -->|"advances"| node_twin
node_orchestrator -->|"applies routes"| node_optimization
node_orchestrator -->|"records reasons"| node_explainability
node_orchestrator -->|"records audit"| node_trust
node_traffic_prediction -->|"uses"| node_network
node_ml_pipeline -->|"includes"| node_feature_engineering
node_feature_engineering -.->|"builds features for"| node_ml_pipeline
node_network -.->|"provides graph"| node_optimizer_core
node_optimization -.->|"uses algorithms"| node_optimizer_core
node_benchmarks -->|"compares algorithms"| node_optimizer_core
node_state -->|"reads telemetry from"| node_twin
node_scenarios -->|"registers incidents"| node_state
node_scenarios -->|"applies reroutes"| node_actuation
node_scenarios -->|"measures outcomes"| node_sim_metrics
node_state -->|"supplies twin state"| node_ml_pipeline
node_state -->|"supplies twin state"| node_optimization
node_state -->|"exposes state to"| node_api_routes
node_optimization -->|"sends route decisions"| node_actuation
node_actuation -->|"changes network state"| node_state
node_sim_metrics -.->|"reports results to"| node_dashboard

click node_dashboard "https://github.com/vaidik04/q-transit-nexus/blob/main/dashboard/src/App.jsx"
click node_dashboard_views "https://github.com/vaidik04/q-transit-nexus/tree/main/dashboard/src/components"
click node_backend_entry "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/main.py"
click node_api_routes "https://github.com/vaidik04/q-transit-nexus/tree/main/backend/api"
click node_orchestrator "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/orchestrator.py"
click node_network "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/network_engine.py"
click node_twin "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/simulation_engine.py"
click node_state "https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/state_manager.py"
click node_scenarios "https://github.com/vaidik04/q-transit-nexus/tree/main/simulation/scenarios"
click node_actuation "https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/route_applier.py"
click node_sim_metrics "https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/metrics.py"
click node_traffic_prediction "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/traffic_prediction.py"
click node_ml_pipeline "https://github.com/vaidik04/q-transit-nexus/tree/main/137ML/prediction"
click node_feature_engineering "https://github.com/vaidik04/q-transit-nexus/blob/main/137ML/prediction/feature_engineering.py"
click node_optimization "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/at_dqpso.py"
click node_optimizer_core "https://github.com/vaidik04/q-transit-nexus/tree/main/optimization"
click node_benchmarks "https://github.com/vaidik04/q-transit-nexus/blob/main/optimization/benchmarks.py"
click node_transit "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/transit_intelligence.py"
click node_ev "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/ev_intelligence.py"
click node_emergency "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/emergency_priority.py"
click node_explainability "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/explainability.py"
click node_trust "https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/trust_layer.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_dashboard,node_dashboard_views toneBlue
class node_backend_entry,node_api_routes,node_orchestrator toneAmber
class node_network,node_twin,node_state,node_scenarios,node_actuation,node_sim_metrics toneMint
class node_traffic_prediction,node_ml_pipeline,node_feature_engineering,node_optimization,node_optimizer_core,node_benchmarks toneRose
class node_transit,node_ev,node_emergency,node_explainability,node_trust,node_operator toneIndigo
```

## Components

### Dashboard

- [Operations Dashboard](https://github.com/vaidik04/q-transit-nexus/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Map and Panels](https://github.com/vaidik04/q-transit-nexus/tree/main/dashboard/src/components): `dashboard/src/components`

### Backend Services

- [Backend Entry](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/main.py): `backend/main.py`
- [API Routes](https://github.com/vaidik04/q-transit-nexus/tree/main/backend/api): `backend/api`
- [Cycle Orchestrator](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/orchestrator.py): `backend/orchestrator.py`

### Digital Twin

- [Urban Network](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/network_engine.py): `backend/modules/network_engine.py`
- [Backend Digital Twin](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/simulation_engine.py): `backend/modules/simulation_engine.py`
- [Twin State Contract](https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/state_manager.py): `simulation/state_manager.py`
- [Scenario Runs](https://github.com/vaidik04/q-transit-nexus/tree/main/simulation/scenarios): `simulation/scenarios`
- [Route and Signal Control](https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/route_applier.py): `simulation/route_applier.py`
- [Simulation Metrics](https://github.com/vaidik04/q-transit-nexus/blob/main/simulation/metrics.py): `simulation/metrics.py`

### Prediction and Optimization

- [Traffic Prediction](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/traffic_prediction.py): `backend/modules/traffic_prediction.py`
- [137ML Prediction](https://github.com/vaidik04/q-transit-nexus/tree/main/137ML/prediction): `137ML/prediction`
- [Feature Engineering](https://github.com/vaidik04/q-transit-nexus/blob/main/137ML/prediction/feature_engineering.py): `137ML/prediction/feature_engineering.py`
- [Adaptive Routing](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/at_dqpso.py): `backend/modules/at_dqpso.py`
- [Optimization Algorithms](https://github.com/vaidik04/q-transit-nexus/tree/main/optimization): `optimization`
- [Algorithm Benchmarks](https://github.com/vaidik04/q-transit-nexus/blob/main/optimization/benchmarks.py): `optimization/benchmarks.py`

### Transport Intelligence

- [Transit Intelligence](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/transit_intelligence.py): `backend/modules/transit_intelligence.py`
- [EV Charging](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/ev_intelligence.py): `backend/modules/ev_intelligence.py`
- [Emergency Priority](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/emergency_priority.py): `backend/modules/emergency_priority.py`
- [Decision Explanations](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/explainability.py): `backend/modules/explainability.py`
- [Trust Ledger](https://github.com/vaidik04/q-transit-nexus/blob/main/backend/modules/trust_layer.py): `backend/modules/trust_layer.py`

### Other components

- **Operator**

## Connections

- Operator → Operations Dashboard: operates
- Operations Dashboard → Map and Panels: renders (evidence: `dashboard/src/App.jsx`)
- Backend Entry → Cycle Orchestrator: initializes (evidence: `backend/main.py`)
- Backend Entry → API Routes: registers (evidence: `backend/main.py`)
- Cycle Orchestrator → Urban Network: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Backend Digital Twin: creates (evidence: `backend/orchestrator.py`)
- Backend Digital Twin → Urban Network: uses (evidence: `backend/modules/simulation_engine.py`)
- Cycle Orchestrator → Traffic Prediction: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Adaptive Routing: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Transit Intelligence: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → EV Charging: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Emergency Priority: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Decision Explanations: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Trust Ledger: creates (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Backend Digital Twin: advances (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Adaptive Routing: applies routes (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Decision Explanations: records reasons (evidence: `backend/orchestrator.py`)
- Cycle Orchestrator → Trust Ledger: records audit (evidence: `backend/orchestrator.py`)
- Traffic Prediction → Urban Network: uses (evidence: `backend/modules/traffic_prediction.py`)
- 137ML Prediction → Feature Engineering: includes (evidence: `137ML/prediction/inference.py`)
- Feature Engineering → 137ML Prediction: builds features for (evidence: `137ML/prediction/feature_engineering.py`)
- Urban Network → Optimization Algorithms: provides graph
- Adaptive Routing → Optimization Algorithms: uses algorithms
- Algorithm Benchmarks → Optimization Algorithms: compares algorithms (evidence: `optimization/benchmarks.py`)
- Twin State Contract → Backend Digital Twin: reads telemetry from (evidence: `simulation/state_manager.py`)
- Scenario Runs → Twin State Contract: registers incidents (evidence: `simulation/scenarios/accident.py`)
- Scenario Runs → Route and Signal Control: applies reroutes (evidence: `simulation/scenarios/accident.py`)
- Scenario Runs → Simulation Metrics: measures outcomes (evidence: `simulation/scenarios/accident.py`)
- Twin State Contract → 137ML Prediction: supplies twin state
- Twin State Contract → Adaptive Routing: supplies twin state
- Twin State Contract → API Routes: exposes state to
- Adaptive Routing → Route and Signal Control: sends route decisions
- Route and Signal Control → Twin State Contract: changes network state
- Simulation Metrics → Operations Dashboard: reports results to
