# pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge architecture

> Architecture diagram of the GitHub repository pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge
- Repository: https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge

## Overview

Quantum Courier solves CVRP with a cluster-first, route-second workflow: load an instance, partition customers by a capacity-aware angular sweep, solve each cluster’s TSP with SamplingVQE, and assemble, score, save, and optionally visualize the routes. The repository also contains a separate QAOA TSP implementation and exact CVRP solvers. The main workflow is verified from sampled source; the README documents the dual-backend capability, but the sampled main entry point invokes VQE only.

Main entry points: [`main.py`](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/main.py) (Run orchestration), [`utils/data_loader.py`](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/data_loader.py) (Instance loader), [`utils/metrics.py`](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/metrics.py) (Route metrics), [`utils/solution_storage.py`](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/solution_storage.py) (Solution writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CVRP Workflow"]
  node_main["Run orchestration<br/>[main.py]"]
  node_loader["Instance loader<br/>[data_loader.py]"]
  node_sweep["Sweep clustering<br/>[clustering.py]"]
  node_distance["Distance mapping<br/>[distance.py]"]
end

subgraph group_quantum["TSP Backends"]
  node_vqe["SamplingVQE<br/>[tsp_solver.py]"]
  node_qaoa["QAOA backend"]
end

subgraph group_outputs["Results and Views"]
  node_metrics["Route metrics<br/>[metrics.py]"]
  node_storage["Solution writer"]
  node_csv["Run results"]
  node_solutionfiles["Instance solutions<br/>[result.csv]"]
  node_visualization["Route visualization<br/>[visualization.py]"]
end

subgraph group_exact["Exact Solvers"]
  node_bruteforce["Brute-force CVRP"]
  node_subsetexact["Subset-DP CVRP"]
end

node_user(("Instance requester"))

node_user -->|"requests run"| node_main
node_main -->|"loads instance"| node_loader
node_main -->|"clusters customers"| node_sweep
node_main -->|"builds matrices"| node_distance
node_main -->|"solves cluster TSP"| node_vqe
node_main -->|"scores and logs"| node_metrics
node_main -->|"writes routes"| node_storage
node_main -->|"plots routes"| node_visualization
node_bruteforce -->|"loads instance"| node_loader
node_subsetexact -->|"loads instance"| node_loader
node_metrics -->|"appends metrics"| node_csv
node_storage -->|"writes solution"| node_solutionfiles

click node_main "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/main.py"
click node_loader "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/data_loader.py"
click node_sweep "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/clustering.py"
click node_distance "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/distance.py"
click node_vqe "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/tsp_solver.py"
click node_qaoa "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/_clustering_qaoa.py"
click node_metrics "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/metrics.py"
click node_storage "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/solution_storage.py"
click node_csv "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/results/all_run_results.csv"
click node_solutionfiles "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/results/instance_1/result.csv"
click node_visualization "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/visualization.py"
click node_bruteforce "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/exact_solver/bruteforce_optimizer.py"
click node_subsetexact "https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/exact_solver/instance4_exact_solver.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_main,node_loader,node_sweep,node_distance toneBlue
class node_vqe,node_qaoa toneAmber
class node_metrics,node_storage,node_csv,node_solutionfiles,node_visualization,node_user toneMint
class node_bruteforce,node_subsetexact toneRose
```

## Components

### CVRP Workflow

- [Run orchestration](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/main.py): `main.py`
- [Instance loader](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/data_loader.py): `utils/data_loader.py`
- [Sweep clustering](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/clustering.py): `utils/clustering.py`
- [Distance mapping](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/distance.py): `utils/distance.py`

### TSP Backends

- [SamplingVQE](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/tsp_solver.py): `utils/tsp_solver.py`
- [QAOA backend](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/_clustering_qaoa.py): `utils/_clustering_qaoa.py`

### Results and Views

- [Route metrics](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/metrics.py): `utils/metrics.py`
- [Solution writer](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/solution_storage.py): `utils/solution_storage.py`
- [Run results](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/results/all_run_results.csv): `results/all_run_results.csv`
- [Instance solutions](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/results/instance_1/result.csv): `results/instance_1/result.csv`
- [Route visualization](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/visualization.py): `utils/visualization.py`

### Exact Solvers

- [Brute-force CVRP](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/exact_solver/bruteforce_optimizer.py): `utils/exact_solver/bruteforce_optimizer.py`
- [Subset-DP CVRP](https://github.com/pouliotalexis/quantum-queb-hackers---quantumct-rtrc-qbraid-challenge/blob/main/utils/exact_solver/instance4_exact_solver.py): `utils/exact_solver/instance4_exact_solver.py`

### Other components

- **Instance requester**

## Connections

- Instance requester → Run orchestration: requests run
- Run orchestration → Instance loader: loads instance
- Run orchestration → Sweep clustering: clusters customers
- Run orchestration → Distance mapping: builds matrices
- Run orchestration → SamplingVQE: solves cluster TSP
- Run orchestration → Route metrics: scores and logs
- Run orchestration → Solution writer: writes routes
- Run orchestration → Route visualization: plots routes
- Brute-force CVRP → Instance loader: loads instance
- Subset-DP CVRP → Instance loader: loads instance
- Route metrics → Run results: appends metrics
- Solution writer → Instance solutions: writes solution