QuantumAlpha

AI-Driven Quantitative Trading Platform

QuantumAlpha is a quantitative trading platform built as a set of Flask services: an API gateway, a data service, an AI engine, a risk service, and an execution service, each independently deployable behind a shared Docker image. It's paired with a React web dashboard and a React Native mobile app. The AI engine trains, versions, and serves forecasting models and reinforcement-learning agents directly through its own API, rather than sitting as a disconnected library.

Table of Contents

• Overview
• Project Structure
• Feature Status
• Technology Stack
• Architecture
• Installation and Setup
• Running the Stack
• API Surface
• Testing
• CI/CD Pipeline
• Documentation
• Contributing
• License

Overview

QuantumAlpha demonstrates a quantitative trading workflow across a real, runnable set of services. The data, AI engine, risk, and execution services are each deployed as their own separate Flask app/container, while portfolio management and the trading engine run in-process inside the API gateway rather than as their own services. Despite running in its own container, the AI engine is not an isolated or disconnected piece: its model lifecycle (create, train, validate, tune, evaluate, version, predict, ensemble, monitor) is genuinely implemented for LSTM, GRU, CNN, and Transformer networks (TensorFlow/Keras), for Ridge, Random Forest, and Gradient Boosting models (scikit-learn), and for reinforcement-learning agents (tabular Q-learning, plus PPO, DQN, A2C, SAC via Stable-Baselines3), and it's called over HTTP by both the risk service (for AI-adjusted portfolio valuations) and the execution service (for executing trades directly from a model's prediction).

Project Structure

QuantumAlpha/
├── code/
│   ├── backend/
│   │   ├── api/                  # API gateway (Flask): auth, portfolio, trading,
│   │   │                         # admin, system endpoints
│   │   ├── data_service/         # Separate Flask app: market and alternative data
│   │   ├── execution_service/    # Separate Flask app: orders, broker adapter
│   │   ├── risk_service/         # Separate Flask app: VaR, stress testing, position sizing
│   │   ├── portfolio_service/    # In-process module (imported by the API gateway)
│   │   ├── trading_engine/       # In-process module (imported by the API gateway)
│   │   ├── analytics_service/    # Performance attribution, factor analysis
│   │   ├── compliance_service/   # Compliance monitoring, regulatory reporting
│   │   ├── common/               # Shared auth, database, messaging, monitoring
│   │   └── tests/                # Backend test suite (pytest)
│   ├── ai_models/
│   │   ├── api/                  # Separate Flask app: app factory, routes (Flask blueprints),
│   │   │                         # service container, WSGI entry point
│   │   ├── core/                 # Settings, exceptions, logging, cache, background jobs
│   │   ├── data/                 # Data service client, feature engineering
│   │   ├── models/               # Deep (LSTM, GRU, CNN, Transformer) and classical models
│   │   ├── training/             # Trainer, walk-forward validation, tuning
│   │   ├── evaluation/           # Metrics, backtesting
│   │   ├── inference/            # Predictions, ensemble, signals, explainability
│   │   ├── registry/             # Versioned model registry
│   │   ├── rl/                   # Trading environment, agents, RL service
│   │   ├── monitoring/           # Drift detection, performance tracking, metrics
│   │   ├── persistence/          # Prediction and signal store
│   │   ├── engine/               # Compatibility shim for ai_models.engine.app:app
│   │   ├── Dockerfile            # Standalone AI engine image
│   │   └── tests/                # AI engine test suite (pytest)
│   └── Dockerfile.service        # Shared image; APP_MODULE build arg selects the service
├── web-frontend/                 # React (Vite) dashboard
├── mobile-frontend/              # React Native app
├── infrastructure/               # Docker, Kubernetes, Terraform, monitoring
├── scripts/                      # Setup, run, test, and deploy scripts
├── docs/                         # Documentation (this directory)
└── README.md

Feature Status

Application tier (wired and tested)

Component	Details
API gateway	Flask app exposing /api/auth, /api/portfolio, /api/trade, /api/admin, and /api/system routes, plus /health. Portfolio management and the trading engine run in-process here rather than as separate services.
Data service	Separately-deployed Flask app for market data and alternative data, backed by PostgreSQL, InfluxDB (time series), MongoDB (alternative data), and Redis.
AI engine	Separately-deployed Flask app with a real model lifecycle: create, train, validate (walk-forward), tune, evaluate, version and promote, predict (single, batch, ensemble), and delete for LSTM, GRU, CNN, and Transformer networks (TensorFlow/Keras) and Ridge, Random Forest, and Gradient Boosting models (scikit-learn), plus reinforcement-learning agents (tabular Q-learning, PPO, DQN, A2C, SAC via Stable-Baselines3). Also generates trading signals and monitors drift and live accuracy. Routes live in api/routes/ (Flask blueprints for system, models, predictions, signals, and RL) so the HTTP layer and the service classes underneath it are exercised by the same tests. Called over HTTP by both the risk service and the execution service (see below) - not an isolated piece despite running in its own container.
Risk service	Separately-deployed Flask app for Value at Risk, Expected Shortfall, Sharpe ratio, stress testing (historical, Monte Carlo, sensitivity, and custom scenarios), risk-based position sizing, portfolio-level risk alerts, and an online-learning risk updater. Every route validates its input against a schema before reaching the calculator classes, and calls the method that schema's fields actually match. Calls the AI engine for AI-adjusted portfolio valuations.
Execution service	Separately-deployed Flask app for order management, execution strategies, and a broker adapter. The adapter is a generic HTTP client against a configurable broker.url; Alpaca API key fields exist in configuration, but there's no Alpaca-specific SDK integration. Calls the AI engine to execute trades directly from a model's prediction.
Messaging	Kafka producer and consumer classes (via confluent-kafka) in the shared common module, now added to requirements.txt. alpaca-trade-api and pika are also listed there but aren't imported anywhere in the codebase.
Auth	JWT sessions via Flask-JWT-Extended, with MFA-related fields on the user model. The signing key falls back to a placeholder default if SECRET_KEY is unset, with no check that rejects the placeholder in production.
Compliance and analytics	In-process modules (imported by the API gateway, not separately deployed) for compliance monitoring, regulatory reporting, performance attribution, and factor analysis.
Web dashboard	React app (JavaScript) with Redux Toolkit for state, Material-UI for components, and Recharts for charts.
Mobile app	React Native app (a mix of TypeScript and JavaScript) with React Navigation, Zustand for state, and react-native-chart-kit for charts.

Technology Stack

Area	Technology
Backend services	Python 3.11, Flask, Gunicorn
Auth	Flask-JWT-Extended, MFA-related user model fields
Data layer	PostgreSQL, MongoDB, InfluxDB, Redis
Messaging	Kafka (confluent-kafka)
ML / RL	TensorFlow/Keras (LSTM, GRU, CNN, Transformer), scikit-learn (Ridge, Random Forest, Gradient Boosting), Stable-Baselines3 (PPO, DQN, A2C, SAC), tabular Q-learning
Web frontend	React 18, Redux Toolkit, Material-UI, Recharts, Vite
Mobile frontend	React Native, TypeScript and JavaScript, React Navigation, Zustand, react-native-chart-kit
Infrastructure	Docker, Docker Compose, Kubernetes, Terraform
Monitoring	Prometheus, Grafana, Elasticsearch, Kibana
CI/CD	GitHub Actions
Testing	pytest (backend and AI engine), Jest (web and mobile)

Architecture

Clients
  ├── web-frontend (React)               ── HTTP/JSON ──┐
  └── mobile-frontend (React Native)     ── HTTP/JSON ──┤
                                                        ▼
API Gateway (Flask)
  /api/auth · /api/portfolio · /api/trade · /api/admin · /api/system
  Runs the portfolio_service and trading_engine modules in-process.

Separately-deployed services (each its own Flask app, same shared Docker image)
  data-service     market data, alternative data, feature engineering
  ai-engine        model lifecycle (deep and classical forecasters, signals, RL agents)
  risk-service     VaR, stress testing, position sizing, online learning
  execution-service order management, execution strategies, broker adapter

Data layer
  PostgreSQL · MongoDB · InfluxDB · Redis · Kafka

See docs/ARCHITECTURE.md for detail.

Installation and Setup

Prerequisites: Python 3.11+, Node.js 18+, and Docker (for the full multi-service stack).

git clone https://github.com/quantsingularity/QuantumAlpha.git
cd QuantumAlpha

# Backend (installs dependencies shared by all Flask services)
cd code/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# AI engine (core dependencies plus TensorFlow, PyTorch, Stable-Baselines3)
pip install -r ../ai_models/requirements-ml.txt

# Web frontend
cd ../../web-frontend
npm install

# Mobile frontend
cd ../mobile-frontend
npm install

For an automated setup:

git clone https://github.com/quantsingularity/QuantumAlpha.git
cd QuantumAlpha
./scripts/setup_env.sh
docker-compose -f infrastructure/docker-compose.yml up

Full, environment-specific instructions are in docs/INSTALLATION.md.

Running the Stack

# Full stack, including Postgres, MongoDB, InfluxDB, Redis, Kafka, and every service
docker-compose -f infrastructure/docker-compose.yml up

# Or, run an individual Flask service directly (from code/, venv active)
APP_MODULE=backend.data_service.app:app python -m flask run --port 8081
APP_MODULE=backend.risk_service.app:app python -m flask run --port 8083
APP_MODULE=backend.execution_service.app:app python -m flask run --port 8084
DATA_SERVICE_URL=http://localhost:8081 python -m ai_models   # serves http://0.0.0.0:8082

# API gateway (from code/backend, venv active)
python -m api.main                 # serves http://0.0.0.0:8080

# Web dashboard (from web-frontend)
npm run dev

# Mobile app (from mobile-frontend)
npm start

See docs/USAGE.md and docs/CONFIGURATION.md.

API Surface

Each service exposes its own /health check.

Service	Highlights
API gateway	/api/auth/{register,login,logout,me}, /api/portfolio, /api/portfolio/positions, /api/trade/order, /api/trade/orders, /api/admin/users, /api/system/status
Data service	/api/market-data/{symbol}, /api/alternative-data/{source}, /api/features/{symbol}, /api/data-sources
AI engine	/api/catalog, /api/models (GET, POST), /api/models/{id} (GET, PUT, DELETE), /api/models/{id}/{train,evaluate,validate,tune,versions,explain}, /api/models/{id}/versions/{v} (DELETE) and /promote (POST), /api/models/{id}/predictions/{symbol}, /api/models/{id}/{performance,reconcile,drift,health}, /api/train-model, /api/predict (POST and GET /api/predict/{model_id}/{symbol}), /api/predict/batch, /api/predict/ensemble, /api/generate-signals, /api/signals, /api/jobs, /api/rl/algorithms, /api/rl/models (GET, POST), /api/rl/models/{id} (GET, PUT, DELETE), /api/rl/train, /api/rl/act; also /ready and /metrics
Risk service	/api/risk-metrics, /api/stress-test, /api/calculate-position, /api/portfolio-risk, /api/risk-alerts, /api/portfolio-value-prediction (calls the AI engine)
Execution service	/api/orders, /api/orders/{id}/cancel, /api/execution-strategies, /api/brokers, /api/brokers/{id}/accounts, /api/trade-from-signal, /api/trade-from-model (calls the AI engine)

Full request and response shapes are in docs/API.md.

Testing

# Backend (from code/backend)
pytest

# AI engine (from code/ai_models)
pytest

# Web (from web-frontend)
npm test

# Mobile (from mobile-frontend)
npm test

The mobile app also has an e2e/ directory for end-to-end tests. The backend suite covers 8 test files across the services; the AI engine suite covers 7.

CI/CD Pipeline

GitHub Actions (.github/workflows/cicd.yml) runs three jobs on push, pull request, and manual dispatch:

Job	Depends on	What it does
Code Quality Checks	-	Python formatter checks (autoflake, black) and a repository-wide Prettier check
Backend Tests	Code Quality Checks	Runs the pytest suite with coverage and uploads the coverage report as an artifact
Frontend Build	Code Quality Checks	Installs dependencies and produces the production web build (no test step)

CI builds the AI engine image and smoke tests its /health endpoint, but there is currently no CI job that runs the AI engine or mobile app test suites.

Documentation

Document	Contents
docs/README.md	Documentation index
docs/ARCHITECTURE.md	System architecture
docs/API.md	REST API reference
docs/INSTALLATION.md	Setup for all components
docs/CONFIGURATION.md	Environment variables and config
docs/USAGE.md	Running and using the platform
docs/CLI.md	Helper scripts reference
docs/FEATURE_MATRIX.md	Feature status, implemented vs planned
docs/ML_MODEL_PERFORMANCE.md	Model evaluation methodology
docs/TROUBLESHOOTING.md	Common issues and fixes
docs/CONTRIBUTING.md	Contribution guide
docs/examples/	Worked examples

Contributing

See docs/CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.