| # Architecture |
|
|
| This document describes the system architecture of the Quantum Hybrid Portfolio optimization platform. |
|
|
| ## Overview |
|
|
| The system consists of: |
|
|
| 1. **Backend API** (`api.py`) — Flask REST API, optimization, backtest, market data |
| 2. **Frontend** (`frontend/`) — React dashboard (EnhancedQuantumDashboard.js) |
| 3. **Core** (`core/quantum_inspired/`) — QSW optimizer, graph builder, evolution dynamics |
| 4. **Services** (`services/`) — Market data, backtest, portfolio optimizer |
|
|
| ## Data Flow |
|
|
| ``` |
| ┌─────────────────┐ HTTP ┌─────────────────┐ Python ┌──────────────────┐ |
| │ React Dashboard │ ◄──────────► │ Flask API │ ◄────────────► │ QSW Optimizer │ |
| │ (port 3000) │ proxy │ (port 5000) │ services │ (core/) │ |
| └─────────────────┘ └────────┬────────┘ └──────────────────┘ |
| │ |
| │ yfinance / cache |
| ▼ |
| ┌─────────────────┐ |
| │ Market Data │ |
| │ (services/) │ |
| └─────────────────┘ |
| ``` |
|
|
| ## Backend |
|
|
| ### API Layer (`api.py`) |
|
|
| - CORS enabled for frontend |
| - Optional `X-API-Key` authentication |
| - Structured JSON logging |
| - Prometheus metrics (`/metrics`) |
| - In-memory market data cache (TTL configurable) |
|
|
| ### Services |
|
|
| - **market_data** — Fetches prices via yfinance, returns covariance and returns |
| - **backtest** — Runs backtest with rebalancing, computes metrics |
| - **portfolio_optimizer** — Wraps QSW optimizer, applies constraints and presets |
|
|
| ### Core |
|
|
| - **quantum_walk.py** — QuantumStochasticWalkOptimizer (main QSW algorithm) |
| - **graph_builder.py** — Financial graph from returns/covariance |
| - **evolution_dynamics.py** — Quantum evolution (continuous, discrete, etc.) |
| - **stability_enhancer.py** — Turnover reduction |
|
|
| ## Frontend |
|
|
| ### Structure |
|
|
| - **App.js** — Entry, ErrorBoundary, ToastContainer |
| - **EnhancedQuantumDashboard.js** — Main dashboard (state, tabs, layout) |
| - **components/dashboard/** — Slider, MetricCard, TabButton, SectionTitle, RegimeSelector, etc. |
| - **lib/simulationEngine.js** — Synthetic market data, simulation optimization |
| - **services/api.js** — Axios client for backend API |
|
|
| ### State |
|
|
| - Data source (api vs sim) |
| - Omega, evolution time, regime, evolution method, objective |
| - Constraints, tickers, dates |
| - Optimization result, backtest result, sensitivity data |
| - Active tab, metrics view (optimization vs backtest) |
|
|
| ### API vs Simulation |
|
|
| - **API:** Calls `/api/portfolio/optimize`, `/api/market-data`, `/api/portfolio/backtest` |
| - **Simulation:** Uses `lib/simulationEngine.js` to generate data and run QSW locally |
|
|
| ## Configuration |
|
|
| - **config/qsw_config.py** — Omega, evolution time, turnover, weights |
| - **config/production_config.py** — Production settings (if used) |
| - **Environment** — FLASK_ENV, LOG_LEVEL, CACHE_TTL, API_KEY, etc. |
|
|
| ## Deployment |
|
|
| - **Docker** — Dockerfile and docker-compose for containerized run |
| - **Production** — JWT auth, rate limiting, Redis, PostgreSQL (see PRODUCTION_READINESS_PLAN.md) |
|
|
| --- |
|
|
| *Last updated: 2026-02* |
|
|
