# greek1606/qubench architecture

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

- Interactive diagram: https://gitdiagram.com/greek1606/qubench
- Repository: https://github.com/greek1606/qubench

## Overview

QuBench lets users upload ECG image datasets, configure preprocessing and feature/model choices, validate and estimate a run, then compare classical and quantum benchmarks on the same features. Results support progress monitoring, per-image diagnosis, and a cross-run leaderboard. The README documents core pipeline stages and capabilities beyond the sampled source; those are represented at the existing backend/core directory where individual module wiring was not visible.

Main entry points: [`backend/main.py`](https://github.com/greek1606/qubench/blob/main/backend/main.py) (HTTP routes), [`frontend/src/App.jsx`](https://github.com/greek1606/qubench/blob/main/frontend/src/App.jsx) (Wizard state), [`backend/core`](https://github.com/greek1606/qubench/tree/main/backend/core) (Benchmark orchestration), [`frontend/src/api.js`](https://github.com/greek1606/qubench/blob/main/frontend/src/api.js) (REST client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["User workflow"]
  node_app["Wizard state<br/>[App.jsx]"]
  node_upload["Dataset upload<br/>[Upload.jsx]"]
  node_configure["Run setup<br/>[Configure.jsx]"]
  node_benchmark_ui["Benchmark view"]
  node_diagnose_ui["Diagnosis view<br/>[Diagnose.jsx]"]
  node_leaderboard_ui["Leaderboard view<br/>[Leaderboard.jsx]"]
  node_api_client["REST client<br/>[api.js]"]
end

subgraph group_api["API and jobs"]
  node_api["HTTP routes<br/>[main.py]"]
  node_validation["Config validation<br/>[validate.py]"]
  node_jobs["Background jobs<br/>[jobs.py]"]
  node_store[("JSON storage<br/>[store.py]")]
  node_contracts["Run contracts<br/>[contracts.py]"]
end

subgraph group_pipeline["Dataset pipeline"]
  node_ingest["Image ingestion<br/>[ingest.py]"]
  node_preprocess["Image preprocessing<br/>[preprocess.py]"]
  node_features["Embedding and projection"]
end

subgraph group_results["Models and results"]
  node_benchmark["Benchmark orchestration"]
  node_classical["Classical models"]
  node_quantum["Quantum models<br/>[models_quantum.py]"]
  node_checkpoints["Model checkpoints<br/>[checkpoint.py]"]
  node_prediction["Single-image prediction"]
end

node_user(("Researcher"))

node_user -->|"uses"| node_app
node_app -->|"shows"| node_upload
node_app -->|"shows"| node_configure
node_app -->|"shows"| node_benchmark_ui
node_app -->|"shows"| node_diagnose_ui
node_app -->|"shows"| node_leaderboard_ui
node_upload -->|"uploads"| node_api_client
node_configure -->|"configures"| node_api_client
node_benchmark_ui -->|"polls"| node_api_client
node_diagnose_ui -->|"requests"| node_api_client
node_leaderboard_ui -->|"requests"| node_api_client
node_api_client -->|"sends REST"| node_api
node_api -->|"ingests upload"| node_ingest
node_api -->|"saves dataset"| node_store
node_api -->|"validates config"| node_validation
node_api -->|"builds config"| node_contracts
node_api -->|"submits run"| node_jobs
node_jobs -->|"runs benchmark"| node_benchmark
node_benchmark -->|"processes images"| node_preprocess
node_benchmark -->|"extracts features"| node_features
node_benchmark -->|"fits classical"| node_classical
node_benchmark -->|"fits quantum"| node_quantum
node_benchmark -->|"saves models"| node_checkpoints
node_jobs -->|"saves run"| node_store
node_api -->|"reads runs"| node_store
node_api -->|"requests prediction"| node_prediction
node_api -->|"loads model"| node_checkpoints
node_prediction -->|"prepares image"| node_preprocess

click node_app "https://github.com/greek1606/qubench/blob/main/frontend/src/App.jsx"
click node_upload "https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Upload.jsx"
click node_configure "https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Configure.jsx"
click node_benchmark_ui "https://github.com/greek1606/qubench/tree/main/frontend/src/pages"
click node_diagnose_ui "https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Diagnose.jsx"
click node_leaderboard_ui "https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Leaderboard.jsx"
click node_api_client "https://github.com/greek1606/qubench/blob/main/frontend/src/api.js"
click node_api "https://github.com/greek1606/qubench/blob/main/backend/main.py"
click node_validation "https://github.com/greek1606/qubench/blob/main/backend/validate.py"
click node_jobs "https://github.com/greek1606/qubench/blob/main/backend/jobs.py"
click node_store "https://github.com/greek1606/qubench/blob/main/backend/store.py"
click node_contracts "https://github.com/greek1606/qubench/blob/main/backend/core/contracts.py"
click node_ingest "https://github.com/greek1606/qubench/blob/main/backend/core/ingest.py"
click node_preprocess "https://github.com/greek1606/qubench/blob/main/backend/core/preprocess.py"
click node_features "https://github.com/greek1606/qubench/tree/main/backend/core"
click node_benchmark "https://github.com/greek1606/qubench/tree/main/backend/core"
click node_classical "https://github.com/greek1606/qubench/blob/main/backend/core/models_classical.py"
click node_quantum "https://github.com/greek1606/qubench/blob/main/backend/core/models_quantum.py"
click node_checkpoints "https://github.com/greek1606/qubench/blob/main/backend/core/checkpoint.py"
click node_prediction "https://github.com/greek1606/qubench/tree/main/backend/core"

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_upload,node_configure,node_benchmark_ui,node_diagnose_ui,node_leaderboard_ui,node_api_client toneBlue
class node_api,node_validation,node_jobs,node_store,node_contracts toneAmber
class node_ingest,node_preprocess,node_features toneMint
class node_benchmark,node_classical,node_quantum,node_checkpoints,node_prediction toneRose
class node_user toneIndigo
```

## Components

### User workflow

- [Wizard state](https://github.com/greek1606/qubench/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Dataset upload](https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Upload.jsx): `frontend/src/pages/Upload.jsx`
- [Run setup](https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Configure.jsx): `frontend/src/pages/Configure.jsx`
- [Benchmark view](https://github.com/greek1606/qubench/tree/main/frontend/src/pages): `frontend/src/pages`
- [Diagnosis view](https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Diagnose.jsx): `frontend/src/pages/Diagnose.jsx`
- [Leaderboard view](https://github.com/greek1606/qubench/blob/main/frontend/src/pages/Leaderboard.jsx): `frontend/src/pages/Leaderboard.jsx`
- [REST client](https://github.com/greek1606/qubench/blob/main/frontend/src/api.js): `frontend/src/api.js`

### API and jobs

- [HTTP routes](https://github.com/greek1606/qubench/blob/main/backend/main.py): `backend/main.py`
- [Config validation](https://github.com/greek1606/qubench/blob/main/backend/validate.py): `backend/validate.py`
- [Background jobs](https://github.com/greek1606/qubench/blob/main/backend/jobs.py): `backend/jobs.py`
- [JSON storage](https://github.com/greek1606/qubench/blob/main/backend/store.py): `backend/store.py`
- [Run contracts](https://github.com/greek1606/qubench/blob/main/backend/core/contracts.py): `backend/core/contracts.py`

### Dataset pipeline

- [Image ingestion](https://github.com/greek1606/qubench/blob/main/backend/core/ingest.py): `backend/core/ingest.py`
- [Image preprocessing](https://github.com/greek1606/qubench/blob/main/backend/core/preprocess.py): `backend/core/preprocess.py`
- [Embedding and projection](https://github.com/greek1606/qubench/tree/main/backend/core): `backend/core`

### Models and results

- [Benchmark orchestration](https://github.com/greek1606/qubench/tree/main/backend/core): `backend/core`
- [Classical models](https://github.com/greek1606/qubench/blob/main/backend/core/models_classical.py): `backend/core/models_classical.py`
- [Quantum models](https://github.com/greek1606/qubench/blob/main/backend/core/models_quantum.py): `backend/core/models_quantum.py`
- [Model checkpoints](https://github.com/greek1606/qubench/blob/main/backend/core/checkpoint.py): `backend/core/checkpoint.py`
- [Single-image prediction](https://github.com/greek1606/qubench/tree/main/backend/core): `backend/core`

### Other components

- **Researcher**

## Connections

- Researcher → Wizard state: uses
- Wizard state → Dataset upload: shows
- Wizard state → Run setup: shows
- Wizard state → Benchmark view: shows
- Wizard state → Diagnosis view: shows
- Wizard state → Leaderboard view: shows
- Dataset upload → REST client: uploads
- Run setup → REST client: configures
- Benchmark view → REST client: polls
- Diagnosis view → REST client: requests
- Leaderboard view → REST client: requests
- REST client → HTTP routes: sends REST
- HTTP routes → Image ingestion: ingests upload
- HTTP routes → JSON storage: saves dataset
- HTTP routes → Config validation: validates config
- HTTP routes → Run contracts: builds config
- HTTP routes → Background jobs: submits run
- Background jobs → Benchmark orchestration: runs benchmark
- Benchmark orchestration → Image preprocessing: processes images
- Benchmark orchestration → Embedding and projection: extracts features
- Benchmark orchestration → Classical models: fits classical
- Benchmark orchestration → Quantum models: fits quantum
- Benchmark orchestration → Model checkpoints: saves models
- Background jobs → JSON storage: saves run
- HTTP routes → JSON storage: reads runs
- HTTP routes → Single-image prediction: requests prediction
- HTTP routes → Model checkpoints: loads model
- Single-image prediction → Image preprocessing: prepares image