# alvin20082003/quantum-retina-x architecture

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

- Interactive diagram: https://gitdiagram.com/alvin20082003/quantum-retina-x
- Repository: https://github.com/alvin20082003/quantum-retina-x

## Overview

QuantumRetina-X is a retinal diabetic-retinopathy grading system with a web interface, an inference API, and a research workflow for training and evaluating ViT and hybrid ViT–quantum models. The user flow is image upload, preprocessing, model inference, and a result containing severity, risk and recommendation information, with Grad-CAM and TCAV-derived explanations. The graph also preserves dataset preparation, model variants, experiment metrics and plotting. The README is empty; unsampled links are omitted where the source index alone does not establish a call.

Main entry points: [`backend/main.py`](https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py) (Prediction API), [`models/hybrid.py`](https://github.com/alvin20082003/quantum-retina-x/blob/main/models/hybrid.py) (Hybrid ViT–VQC), [`training/train.py`](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/train.py) (Model training), [`training/lowdata_experiment.py`](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/lowdata_experiment.py) (Low-data study)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Clinical interface"]
  node_web_app["Upload and results UI<br/>[App.tsx]"]
end

subgraph group_inference["Inference and explanations"]
  node_api["Prediction API<br/>[main.py]"]
  node_transforms["Image transforms<br/>[transforms.py]"]
  node_gradcam["Grad-CAM overlays<br/>[main.py]"]
  node_tcav_results["TCAV and DME results<br/>[main.py]"]
end

subgraph group_models["Model architecture"]
  node_vit["ViT classifier<br/>[backbone.py]"]
  node_hybrid["Hybrid ViT–VQC<br/>[hybrid.py]"]
  node_quantum["Quantum layer<br/>[quantum.py]"]
  node_vqc_only["VQC-only variant<br/>[vqc_only.py]"]
end

subgraph group_research["Training and evaluation"]
  node_data_loaders["APTOS data loaders<br/>[loaders.py]"]
  node_training["Model training<br/>[train.py]"]
  node_lowdata["Low-data study"]
  node_cross_dataset["Cross-dataset studies<br/>[cross_dataset.py]"]
  node_evaluation["Model evaluation<br/>[eval_hybrid.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_plots["Experiment plots"]
end

subgraph group_foundation["Shared foundations"]
  node_config["Configuration<br/>[config.py]"]
  node_seed["Reproducible seeding<br/>[seed.py]"]
  node_logger["Experiment logger<br/>[logger.py]"]
end

node_clinician(("Clinician"))

node_clinician -->|"uploads image"| node_web_app
node_web_app -.->|"requests prediction"| node_api
node_api -->|"preprocesses image"| node_transforms
node_api -->|"runs baseline"| node_vit
node_api -->|"runs hybrid"| node_hybrid
node_api -->|"generates overlay"| node_gradcam
node_api -->|"derives result details"| node_tcav_results
node_hybrid -->|"calls quantum layer"| node_quantum
node_vqc_only -->|"calls quantum layer"| node_quantum
node_data_loaders -->|"builds transforms"| node_transforms
node_training -->|"loads batches"| node_data_loaders
node_training -->|"trains baseline"| node_vit
node_training -->|"computes scores"| node_metrics
node_lowdata -->|"builds transforms"| node_transforms
node_lowdata -->|"trains baseline"| node_vit
node_lowdata -->|"trains hybrid"| node_hybrid
node_lowdata -->|"computes scores"| node_metrics
node_lowdata -->|"logs results"| node_logger
node_cross_dataset -->|"evaluates hybrid"| node_hybrid
node_cross_dataset -->|"computes scores"| node_metrics
node_evaluation -->|"loads evaluation data"| node_data_loaders
node_evaluation -->|"evaluates model"| node_hybrid
node_evaluation -->|"computes scores"| node_metrics
node_evaluation -->|"logs results"| node_logger
node_training -->|"loads settings"| node_config
node_training -->|"sets seed"| node_seed
node_plots -->|"uses dataset loaders"| node_data_loaders
node_plots -->|"plots hybrid results"| node_hybrid
node_plots -->|"loads settings"| node_config

click node_web_app "https://github.com/alvin20082003/quantum-retina-x/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py"
click node_transforms "https://github.com/alvin20082003/quantum-retina-x/blob/main/data/transforms.py"
click node_gradcam "https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py"
click node_tcav_results "https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py"
click node_vit "https://github.com/alvin20082003/quantum-retina-x/blob/main/models/backbone.py"
click node_hybrid "https://github.com/alvin20082003/quantum-retina-x/blob/main/models/hybrid.py"
click node_quantum "https://github.com/alvin20082003/quantum-retina-x/blob/main/models/quantum.py"
click node_vqc_only "https://github.com/alvin20082003/quantum-retina-x/blob/main/models/vqc_only.py"
click node_data_loaders "https://github.com/alvin20082003/quantum-retina-x/blob/main/data/loaders.py"
click node_training "https://github.com/alvin20082003/quantum-retina-x/blob/main/training/train.py"
click node_lowdata "https://github.com/alvin20082003/quantum-retina-x/blob/main/training/lowdata_experiment.py"
click node_cross_dataset "https://github.com/alvin20082003/quantum-retina-x/blob/main/training/cross_dataset.py"
click node_evaluation "https://github.com/alvin20082003/quantum-retina-x/blob/main/eval_hybrid.py"
click node_metrics "https://github.com/alvin20082003/quantum-retina-x/blob/main/training/metrics.py"
click node_plots "https://github.com/alvin20082003/quantum-retina-x/blob/main/generate_all_plots.py"
click node_config "https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/config.py"
click node_seed "https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/seed.py"
click node_logger "https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/logger.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_web_app toneBlue
class node_api,node_transforms,node_gradcam,node_tcav_results toneAmber
class node_vit,node_hybrid,node_quantum,node_vqc_only toneMint
class node_data_loaders,node_training,node_lowdata,node_cross_dataset,node_evaluation,node_metrics,node_plots toneRose
class node_config,node_seed,node_logger,node_clinician toneIndigo
```

## Components

### Clinical interface

- [Upload and results UI](https://github.com/alvin20082003/quantum-retina-x/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Inference and explanations

- [Prediction API](https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py): `backend/main.py`
- [Image transforms](https://github.com/alvin20082003/quantum-retina-x/blob/main/data/transforms.py): `data/transforms.py`
- [Grad-CAM overlays](https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py): `backend/main.py`
- [TCAV and DME results](https://github.com/alvin20082003/quantum-retina-x/blob/main/backend/main.py): `backend/main.py`

### Model architecture

- [ViT classifier](https://github.com/alvin20082003/quantum-retina-x/blob/main/models/backbone.py): `models/backbone.py`
- [Hybrid ViT–VQC](https://github.com/alvin20082003/quantum-retina-x/blob/main/models/hybrid.py): `models/hybrid.py`
- [Quantum layer](https://github.com/alvin20082003/quantum-retina-x/blob/main/models/quantum.py): `models/quantum.py`
- [VQC-only variant](https://github.com/alvin20082003/quantum-retina-x/blob/main/models/vqc_only.py): `models/vqc_only.py`

### Training and evaluation

- [APTOS data loaders](https://github.com/alvin20082003/quantum-retina-x/blob/main/data/loaders.py): `data/loaders.py`
- [Model training](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/train.py): `training/train.py`
- [Low-data study](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/lowdata_experiment.py): `training/lowdata_experiment.py`
- [Cross-dataset studies](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/cross_dataset.py): `training/cross_dataset.py`
- [Model evaluation](https://github.com/alvin20082003/quantum-retina-x/blob/main/eval_hybrid.py): `eval_hybrid.py`
- [Evaluation metrics](https://github.com/alvin20082003/quantum-retina-x/blob/main/training/metrics.py): `training/metrics.py`
- [Experiment plots](https://github.com/alvin20082003/quantum-retina-x/blob/main/generate_all_plots.py): `generate_all_plots.py`

### Shared foundations

- [Configuration](https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/config.py): `utils/config.py`
- [Reproducible seeding](https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/seed.py): `utils/seed.py`
- [Experiment logger](https://github.com/alvin20082003/quantum-retina-x/blob/main/utils/logger.py): `utils/logger.py`

### Other components

- **Clinician**

## Connections

- Clinician → Upload and results UI: uploads image (evidence: `frontend/src/App.tsx`)
- Upload and results UI → Prediction API: requests prediction
- Prediction API → Image transforms: preprocesses image (evidence: `backend/main.py`)
- Prediction API → ViT classifier: runs baseline (evidence: `backend/main.py`)
- Prediction API → Hybrid ViT–VQC: runs hybrid (evidence: `backend/main.py`)
- Prediction API → Grad-CAM overlays: generates overlay (evidence: `backend/main.py`)
- Prediction API → TCAV and DME results: derives result details (evidence: `backend/main.py`)
- Hybrid ViT–VQC → Quantum layer: calls quantum layer (evidence: `models/hybrid.py`)
- VQC-only variant → Quantum layer: calls quantum layer (evidence: `models/vqc_only.py`)
- APTOS data loaders → Image transforms: builds transforms (evidence: `data/loaders.py`)
- Model training → APTOS data loaders: loads batches (evidence: `training/train.py`)
- Model training → ViT classifier: trains baseline (evidence: `training/train.py`)
- Model training → Evaluation metrics: computes scores (evidence: `training/train.py`)
- Low-data study → Image transforms: builds transforms (evidence: `training/lowdata_experiment.py`)
- Low-data study → ViT classifier: trains baseline (evidence: `training/lowdata_experiment.py`)
- Low-data study → Hybrid ViT–VQC: trains hybrid (evidence: `training/lowdata_experiment.py`)
- Low-data study → Evaluation metrics: computes scores (evidence: `training/lowdata_experiment.py`)
- Low-data study → Experiment logger: logs results (evidence: `training/lowdata_experiment.py`)
- Cross-dataset studies → Hybrid ViT–VQC: evaluates hybrid (evidence: `training/cross_dataset.py`)
- Cross-dataset studies → Evaluation metrics: computes scores (evidence: `training/cross_dataset.py`)
- Model evaluation → APTOS data loaders: loads evaluation data (evidence: `eval_hybrid.py`)
- Model evaluation → Hybrid ViT–VQC: evaluates model (evidence: `eval_hybrid.py`)
- Model evaluation → Evaluation metrics: computes scores (evidence: `eval_hybrid.py`)
- Model evaluation → Experiment logger: logs results (evidence: `eval_hybrid.py`)
- Model training → Configuration: loads settings (evidence: `training/train.py`)
- Model training → Reproducible seeding: sets seed (evidence: `training/train.py`)
- Experiment plots → APTOS data loaders: uses dataset loaders (evidence: `generate_all_plots.py`)
- Experiment plots → Hybrid ViT–VQC: plots hybrid results (evidence: `generate_all_plots.py`)
- Experiment plots → Configuration: loads settings (evidence: `generate_all_plots.py`)
