# hiteshshaw/trafficweave architecture

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

- Interactive diagram: https://gitdiagram.com/hiteshshaw/trafficweave
- Repository: https://github.com/hiteshshaw/trafficweave

## Overview

TrafficWeave is a browser-based vehicle-routing optimization simulator. A user selects a city and routing controls in the app; the app initializes graph and solver state, runs an optimizer or tournament, and presents routes, convergence, and benchmark results in map and lab views. The core separates road-path computation, route decoding, and multi-objective scoring from optimization algorithms. The README also describes mapping, algorithm comparisons, and a routing-systems lab. Edges reflect the excerpts, SOURCE INDEX references, or README; some UI-to-subsystem details are necessarily limited by unsampled component bodies.

Main entry points: [`src/App.tsx`](https://github.com/hiteshshaw/trafficweave/blob/main/src/App.tsx) (App Controller), [`src/core/algorithms/benchmarkSuite.ts`](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/benchmarkSuite.ts) (Benchmark Suite), [`src/core/algorithms/tournamentRunner.ts`](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/tournamentRunner.ts) (Tournament Runner), [`src/core/formulations/decoder.ts`](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/formulations/decoder.ts) (Route Decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application UI"]
  node_app["App Controller<br/>[App.tsx]"]
  node_fleet["Fleet Controls"]
  node_map["Leaflet Map<br/>[RealLeafletMap.tsx]"]
  node_citymap["City Map<br/>[CityMapCanvas.tsx]"]
end

subgraph group_network["Road Network"]
  node_graphgen["City Graphs<br/>[graphGenerator.ts]"]
  node_traffic["Traffic Engine<br/>[trafficEngine.ts]"]
  node_paths["Shortest Paths<br/>[shortestPath.ts]"]
end

subgraph group_optimization["Optimization Core"]
  node_decoder["Route Decoder<br/>[decoder.ts]"]
  node_cost["Cost Evaluator"]
  node_qpso["Quantum PSO<br/>[qpso.ts]"]
  node_qga["Quantum GA<br/>[qga.ts]"]
  node_classicalpso["Classical PSO<br/>[classicalPso.ts]"]
  node_classicalga["Classical GA<br/>[classicalGa.ts]"]
  node_annealing["Simulated Annealing"]
  node_savings["Clarke-Wright<br/>[clarkeWright.ts]"]
  node_exact["Exact Solver<br/>[exactSolver.ts]"]
  node_runner["Tournament Runner"]
end

subgraph group_evaluation["Evaluation Labs"]
  node_tournament["Tournament Arena"]
  node_suite["Benchmark Suite<br/>[benchmarkSuite.ts]"]
  node_benchmark["Benchmark Lab<br/>[BenchmarkLab.tsx]"]
  node_scalability["Scalability Graphs"]
  node_quantumlab["Quantum Routing Lab"]
end

subgraph group_insights["Results &amp; Guidance"]
  node_visualizer["Quantum Visualizer"]
  node_convergence["Convergence Chart"]
  node_theory["Theory Guide<br/>[TheoryGuide.tsx]"]
  node_beforeafter["Before &amp; After"]
  node_deliverables["Deliverables"]
  node_sound["Sound Effects<br/>[soundEffects.ts]"]
end

node_user(("Operator"))

node_user -->|"operates"| node_app
node_app -->|"initializes graph"| node_graphgen
node_app -->|"renders"| node_tournament
node_app -->|"renders"| node_map
node_app -->|"renders"| node_citymap
node_app -->|"renders"| node_fleet
node_app -->|"renders"| node_quantumlab
node_app -->|"renders"| node_benchmark
node_app -->|"renders"| node_theory
node_app -->|"renders"| node_beforeafter
node_app -->|"renders"| node_deliverables
node_app -->|"constructs solver"| node_qpso
node_app -->|"constructs solver"| node_classicalpso
node_app -->|"constructs solver"| node_qga
node_app -->|"constructs solver"| node_classicalga
node_app -->|"constructs runner"| node_runner
node_map -->|"uses routing"| node_paths
node_fleet -->|"updates weights"| node_cost
node_tournament -->|"runs"| node_runner
node_benchmark -->|"runs trials"| node_suite
node_suite -->|"benchmarks"| node_qpso
node_suite -->|"benchmarks"| node_qga
node_suite -->|"benchmarks"| node_classicalpso
node_suite -->|"benchmarks"| node_classicalga
node_suite -->|"benchmarks"| node_annealing
node_suite -->|"benchmarks"| node_savings
node_suite -->|"benchmarks"| node_exact
node_suite -->|"generates stress cases"| node_scalability
node_runner -->|"dispatches"| node_qpso
node_runner -->|"dispatches"| node_qga
node_runner -->|"dispatches"| node_classicalpso
node_runner -->|"dispatches"| node_classicalga
node_runner -->|"dispatches"| node_annealing
node_runner -->|"dispatches"| node_savings
node_qpso -->|"decodes positions"| node_decoder
node_qpso -->|"scores routes"| node_cost
node_qga -->|"decodes positions"| node_decoder
node_qga -->|"scores routes"| node_cost
node_decoder -->|"queries paths"| node_paths
node_decoder -->|"computes emissions"| node_exact
node_cost -->|"consumes route plan"| node_decoder
node_exact -->|"builds distance matrix"| node_paths
node_exact -->|"evaluates routes"| node_cost
node_benchmark -->|"compares optimum"| node_exact
node_visualizer -.->|"displays state"| node_app
node_convergence -.->|"displays history"| node_app
node_quantumlab -->|"plays feedback"| node_sound
node_beforeafter -->|"plays feedback"| node_sound

click node_app "https://github.com/hiteshshaw/trafficweave/blob/main/src/App.tsx"
click node_fleet "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/FleetControlPanel.tsx"
click node_map "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/RealLeafletMap.tsx"
click node_citymap "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/CityMapCanvas.tsx"
click node_graphgen "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/graphGenerator.ts"
click node_traffic "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/trafficEngine.ts"
click node_paths "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/shortestPath.ts"
click node_decoder "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/formulations/decoder.ts"
click node_cost "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/formulations/vrpCostEvaluator.ts"
click node_qpso "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/qpso.ts"
click node_qga "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/qga.ts"
click node_classicalpso "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/classicalPso.ts"
click node_classicalga "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/classicalGa.ts"
click node_annealing "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/simulatedAnnealing.ts"
click node_savings "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/clarkeWright.ts"
click node_exact "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/exactSolver.ts"
click node_runner "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/tournamentRunner.ts"
click node_tournament "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/TournamentArena.tsx"
click node_suite "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/benchmarkSuite.ts"
click node_benchmark "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/BenchmarkLab.tsx"
click node_scalability "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/scalabilityGraphGen.ts"
click node_quantumlab "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/QuantumInnovationsLab.tsx"
click node_visualizer "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/QuantumVisualizer.tsx"
click node_convergence "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/ConvergenceChart.tsx"
click node_theory "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/TheoryGuide.tsx"
click node_beforeafter "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/BeforeVsAfterScreen.tsx"
click node_deliverables "https://github.com/hiteshshaw/trafficweave/blob/main/src/components/DeliverablesModal.tsx"
click node_sound "https://github.com/hiteshshaw/trafficweave/blob/main/src/core/audio/soundEffects.ts"

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_fleet,node_map,node_citymap toneBlue
class node_graphgen,node_traffic,node_paths toneAmber
class node_decoder,node_cost,node_qpso,node_qga,node_classicalpso,node_classicalga,node_annealing,node_savings,node_exact,node_runner toneMint
class node_tournament,node_suite,node_benchmark,node_scalability,node_quantumlab toneRose
class node_visualizer,node_convergence,node_theory,node_beforeafter,node_deliverables,node_sound,node_user toneIndigo
```

## Components

### Application UI

- [App Controller](https://github.com/hiteshshaw/trafficweave/blob/main/src/App.tsx): `src/App.tsx`
- [Fleet Controls](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/FleetControlPanel.tsx): `src/components/FleetControlPanel.tsx`
- [Leaflet Map](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/RealLeafletMap.tsx): `src/components/RealLeafletMap.tsx`
- [City Map](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/CityMapCanvas.tsx): `src/components/CityMapCanvas.tsx`

### Road Network

- [City Graphs](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/graphGenerator.ts): `src/core/graph/graphGenerator.ts`
- [Traffic Engine](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/trafficEngine.ts): `src/core/graph/trafficEngine.ts`
- [Shortest Paths](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/shortestPath.ts): `src/core/graph/shortestPath.ts`

### Optimization Core

- [Route Decoder](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/formulations/decoder.ts): `src/core/formulations/decoder.ts`
- [Cost Evaluator](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/formulations/vrpCostEvaluator.ts): `src/core/formulations/vrpCostEvaluator.ts`
- [Quantum PSO](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/qpso.ts): `src/core/algorithms/qpso.ts`
- [Quantum GA](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/qga.ts): `src/core/algorithms/qga.ts`
- [Classical PSO](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/classicalPso.ts): `src/core/algorithms/classicalPso.ts`
- [Classical GA](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/classicalGa.ts): `src/core/algorithms/classicalGa.ts`
- [Simulated Annealing](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/simulatedAnnealing.ts): `src/core/algorithms/simulatedAnnealing.ts`
- [Clarke-Wright](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/clarkeWright.ts): `src/core/algorithms/clarkeWright.ts`
- [Exact Solver](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/exactSolver.ts): `src/core/algorithms/exactSolver.ts`
- [Tournament Runner](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/tournamentRunner.ts): `src/core/algorithms/tournamentRunner.ts`

### Evaluation Labs

- [Tournament Arena](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/TournamentArena.tsx): `src/components/TournamentArena.tsx`
- [Benchmark Suite](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/algorithms/benchmarkSuite.ts): `src/core/algorithms/benchmarkSuite.ts`
- [Benchmark Lab](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/BenchmarkLab.tsx): `src/components/BenchmarkLab.tsx`
- [Scalability Graphs](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/graph/scalabilityGraphGen.ts): `src/core/graph/scalabilityGraphGen.ts`
- [Quantum Routing Lab](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/QuantumInnovationsLab.tsx): `src/components/QuantumInnovationsLab.tsx`

### Results & Guidance

- [Quantum Visualizer](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/QuantumVisualizer.tsx): `src/components/QuantumVisualizer.tsx`
- [Convergence Chart](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/ConvergenceChart.tsx): `src/components/ConvergenceChart.tsx`
- [Theory Guide](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/TheoryGuide.tsx): `src/components/TheoryGuide.tsx`
- [Before & After](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/BeforeVsAfterScreen.tsx): `src/components/BeforeVsAfterScreen.tsx`
- [Deliverables](https://github.com/hiteshshaw/trafficweave/blob/main/src/components/DeliverablesModal.tsx): `src/components/DeliverablesModal.tsx`
- [Sound Effects](https://github.com/hiteshshaw/trafficweave/blob/main/src/core/audio/soundEffects.ts): `src/core/audio/soundEffects.ts`

### Other components

- **Operator**

## Connections

- Operator → App Controller: operates (evidence: `src/App.tsx`)
- App Controller → City Graphs: initializes graph (evidence: `src/App.tsx`)
- App Controller → Tournament Arena: renders (evidence: `src/App.tsx`)
- App Controller → Leaflet Map: renders (evidence: `src/App.tsx`)
- App Controller → City Map: renders (evidence: `src/App.tsx`)
- App Controller → Fleet Controls: renders (evidence: `src/App.tsx`)
- App Controller → Quantum Routing Lab: renders (evidence: `src/App.tsx`)
- App Controller → Benchmark Lab: renders (evidence: `src/App.tsx`)
- App Controller → Theory Guide: renders (evidence: `src/App.tsx`)
- App Controller → Before & After: renders (evidence: `src/App.tsx`)
- App Controller → Deliverables: renders (evidence: `src/App.tsx`)
- App Controller → Quantum PSO: constructs solver (evidence: `src/App.tsx`)
- App Controller → Classical PSO: constructs solver (evidence: `src/App.tsx`)
- App Controller → Quantum GA: constructs solver (evidence: `src/App.tsx`)
- App Controller → Classical GA: constructs solver (evidence: `src/App.tsx`)
- App Controller → Tournament Runner: constructs runner (evidence: `src/App.tsx`)
- Leaflet Map → Shortest Paths: uses routing (evidence: `src/components/RealLeafletMap.tsx`)
- Fleet Controls → Cost Evaluator: updates weights (evidence: `src/components/FleetControlPanel.tsx`)
- Tournament Arena → Tournament Runner: runs (evidence: `src/components/TournamentArena.tsx`)
- Benchmark Lab → Benchmark Suite: runs trials (evidence: `src/components/BenchmarkLab.tsx`)
- Benchmark Suite → Quantum PSO: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Quantum GA: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Classical PSO: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Classical GA: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Simulated Annealing: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Clarke-Wright: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Exact Solver: benchmarks (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Benchmark Suite → Scalability Graphs: generates stress cases (evidence: `src/core/algorithms/benchmarkSuite.ts`)
- Tournament Runner → Quantum PSO: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Tournament Runner → Quantum GA: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Tournament Runner → Classical PSO: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Tournament Runner → Classical GA: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Tournament Runner → Simulated Annealing: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Tournament Runner → Clarke-Wright: dispatches (evidence: `src/core/algorithms/tournamentRunner.ts`)
- Quantum PSO → Route Decoder: decodes positions (evidence: `src/core/algorithms/qpso.ts`)
- Quantum PSO → Cost Evaluator: scores routes (evidence: `src/core/algorithms/qpso.ts`)
- Quantum GA → Route Decoder: decodes positions (evidence: `src/core/algorithms/qga.ts`)
- Quantum GA → Cost Evaluator: scores routes (evidence: `src/core/algorithms/qga.ts`)
- Route Decoder → Shortest Paths: queries paths (evidence: `src/core/formulations/decoder.ts`)
- Route Decoder → Exact Solver: computes emissions (evidence: `src/core/formulations/decoder.ts`)
- Cost Evaluator → Route Decoder: consumes route plan (evidence: `src/core/formulations/vrpCostEvaluator.ts`)
- Exact Solver → Shortest Paths: builds distance matrix (evidence: `src/core/algorithms/exactSolver.ts`)
- Exact Solver → Cost Evaluator: evaluates routes (evidence: `src/core/algorithms/exactSolver.ts`)
- Benchmark Lab → Exact Solver: compares optimum (evidence: `src/components/BenchmarkLab.tsx`)
- Quantum Visualizer → App Controller: displays state (evidence: `src/App.tsx`)
- Convergence Chart → App Controller: displays history (evidence: `src/App.tsx`)
- Quantum Routing Lab → Sound Effects: plays feedback (evidence: `src/components/QuantumInnovationsLab.tsx`)
- Before & After → Sound Effects: plays feedback (evidence: `src/components/BeforeVsAfterScreen.tsx`)
