# gaurav-git7/syrus-quantum architecture

> Architecture diagram of the GitHub repository gaurav-git7/syrus-quantum, 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/gaurav-git7/syrus-quantum
- Repository: https://github.com/gaurav-git7/syrus-quantum

## Overview

Quantum Portfolio Optimiser is an interactive portfolio-selection product: users choose assets, portfolio size, risk and rules, then submit a job and review QAOA against classical baselines, including out-of-sample and noise results. The documented runtime stages are market estimation, candidate screening, constrained QUBO construction, solving, and evaluation; the UI also exposes a benchmark study. Edges follow explicit README descriptions or sampled caller references. Several modules and API internals are unsampled, so their undocumented internal wiring is omitted.

Main entry points: [`qpo/pipeline.py`](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/pipeline.py) (Run pipeline), [`experiments/run_study.py`](https://github.com/gaurav-git7/syrus-quantum/blob/main/experiments/run_study.py) (Study runner), [`web/src/App.jsx`](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/App.jsx) (App shell), [`qpo/problem.py`](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/problem.py) (Constraints and QUBO)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_app["App shell<br/>[App.jsx]"]
  node_config["Run configuration<br/>[ConfigPanel.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_results["Results view<br/>[Results.jsx]"]
  node_charts["Result charts<br/>[Charts.jsx]"]
  node_study_tab["Study tab<br/>[StudyTab.jsx]"]
end

subgraph group_service["Job service"]
  node_job_api["Job API<br/>[main.py]"]
  node_pipeline["Run pipeline<br/>[pipeline.py]"]
end

subgraph group_portfolio["Portfolio modeling"]
  node_market[("Market data<br/>[data.py]")]
  node_screening["Asset screening<br/>[screening.py]"]
  node_problem["Constraints and QUBO<br/>[problem.py]"]
end

subgraph group_solvers["Solvers and evaluation"]
  node_qaoa["QAOA solver<br/>[qaoa.py]"]
  node_classical["Classical solvers<br/>[classical.py]"]
  node_metrics["Metrics and landscape<br/>[metrics.py]"]
  node_noise["Noise simulation<br/>[noise.py]"]
end

subgraph group_study["Benchmark study"]
  node_study_runner["Study runner<br/>[run_study.py]"]
  node_study_results["Study results<br/>[study.json]"]
end

node_investor(("Investor"))

node_investor -->|"uses"| node_app
node_app -->|"renders"| node_config
node_app -->|"requests through"| node_api_client
node_app -->|"renders"| node_results
node_app -->|"renders"| node_study_tab
node_results -->|"renders"| node_charts
node_api_client -->|"HTTP requests"| node_job_api
node_job_api -->|"runs jobs"| node_pipeline
node_pipeline -->|"loads estimates"| node_market
node_pipeline -->|"screens assets"| node_screening
node_pipeline -->|"builds problem"| node_problem
node_pipeline -->|"runs baselines"| node_classical
node_pipeline -->|"runs QAOA"| node_qaoa
node_pipeline -->|"computes metrics"| node_metrics
node_pipeline -->|"evaluates noise"| node_noise
node_qaoa -->|"consumes QUBO"| node_problem
node_classical -->|"solves constraints"| node_problem
node_metrics -->|"evaluates solutions"| node_problem
node_study_tab -->|"loads study"| node_api_client
node_study_runner -->|"uses market data"| node_market
node_study_runner -->|"builds cases"| node_problem
node_study_runner -->|"benchmarks baselines"| node_classical
node_study_runner -->|"benchmarks circuits"| node_qaoa
node_study_runner -->|"benchmarks noise"| node_noise
node_study_runner -->|"writes results"| node_study_results

click node_app "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/App.jsx"
click node_config "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/ConfigPanel.jsx"
click node_api_client "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/api.js"
click node_results "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/Results.jsx"
click node_charts "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/Charts.jsx"
click node_study_tab "https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/StudyTab.jsx"
click node_job_api "https://github.com/gaurav-git7/syrus-quantum/blob/main/api/main.py"
click node_pipeline "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/pipeline.py"
click node_market "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/data.py"
click node_screening "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/screening.py"
click node_problem "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/problem.py"
click node_qaoa "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/qaoa.py"
click node_classical "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/classical.py"
click node_metrics "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/metrics.py"
click node_noise "https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/noise.py"
click node_study_runner "https://github.com/gaurav-git7/syrus-quantum/blob/main/experiments/run_study.py"
click node_study_results "https://github.com/gaurav-git7/syrus-quantum/blob/main/results/study.json"

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_config,node_api_client,node_results,node_charts,node_study_tab toneBlue
class node_job_api,node_pipeline toneAmber
class node_market,node_screening,node_problem toneMint
class node_qaoa,node_classical,node_metrics,node_noise toneRose
class node_study_runner,node_study_results,node_investor toneIndigo
```

## Components

### Web interface

- [App shell](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/App.jsx): `web/src/App.jsx`
- [Run configuration](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/ConfigPanel.jsx): `web/src/components/ConfigPanel.jsx`
- [API client](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/api.js): `web/src/api.js`
- [Results view](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/Results.jsx): `web/src/components/Results.jsx`
- [Result charts](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/Charts.jsx): `web/src/components/Charts.jsx`
- [Study tab](https://github.com/gaurav-git7/syrus-quantum/blob/main/web/src/components/StudyTab.jsx): `web/src/components/StudyTab.jsx`

### Job service

- [Job API](https://github.com/gaurav-git7/syrus-quantum/blob/main/api/main.py): `api/main.py`
- [Run pipeline](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/pipeline.py): `qpo/pipeline.py`

### Portfolio modeling

- [Market data](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/data.py): `qpo/data.py`
- [Asset screening](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/screening.py): `qpo/screening.py`
- [Constraints and QUBO](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/problem.py): `qpo/problem.py`

### Solvers and evaluation

- [QAOA solver](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/qaoa.py): `qpo/qaoa.py`
- [Classical solvers](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/classical.py): `qpo/classical.py`
- [Metrics and landscape](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/metrics.py): `qpo/metrics.py`
- [Noise simulation](https://github.com/gaurav-git7/syrus-quantum/blob/main/qpo/noise.py): `qpo/noise.py`

### Benchmark study

- [Study runner](https://github.com/gaurav-git7/syrus-quantum/blob/main/experiments/run_study.py): `experiments/run_study.py`
- [Study results](https://github.com/gaurav-git7/syrus-quantum/blob/main/results/study.json): `results/study.json`

### Other components

- **Investor**

## Connections

- Investor → App shell: uses (evidence: `README.md`)
- App shell → Run configuration: renders (evidence: `web/src/App.jsx`)
- App shell → API client: requests through (evidence: `web/src/App.jsx`)
- App shell → Results view: renders (evidence: `web/src/App.jsx`)
- App shell → Study tab: renders (evidence: `web/src/App.jsx`)
- Results view → Result charts: renders (evidence: `web/src/components/Results.jsx`)
- API client → Job API: HTTP requests (evidence: `README.md`)
- Job API → Run pipeline: runs jobs (evidence: `README.md`)
- Run pipeline → Market data: loads estimates (evidence: `qpo/pipeline.py`)
- Run pipeline → Asset screening: screens assets (evidence: `README.md`)
- Run pipeline → Constraints and QUBO: builds problem (evidence: `README.md`)
- Run pipeline → Classical solvers: runs baselines (evidence: `qpo/pipeline.py`)
- Run pipeline → QAOA solver: runs QAOA (evidence: `qpo/pipeline.py`)
- Run pipeline → Metrics and landscape: computes metrics (evidence: `README.md`)
- Run pipeline → Noise simulation: evaluates noise (evidence: `README.md`)
- QAOA solver → Constraints and QUBO: consumes QUBO (evidence: `qpo/qaoa.py`)
- Classical solvers → Constraints and QUBO: solves constraints (evidence: `qpo/classical.py`)
- Metrics and landscape → Constraints and QUBO: evaluates solutions (evidence: `qpo/metrics.py`)
- Study tab → API client: loads study (evidence: `web/src/components/StudyTab.jsx`)
- Study runner → Market data: uses market data (evidence: `experiments/run_study.py`)
- Study runner → Constraints and QUBO: builds cases (evidence: `experiments/run_study.py`)
- Study runner → Classical solvers: benchmarks baselines (evidence: `experiments/run_study.py`)
- Study runner → QAOA solver: benchmarks circuits (evidence: `experiments/run_study.py`)
- Study runner → Noise simulation: benchmarks noise (evidence: `README.md`)
- Study runner → Study results: writes results (evidence: `experiments/run_study.py`)
