Trading AI - Complete System Documentation

Version: 2.0.0
Last Updated: May 2026
Platform: Linux (Ubuntu 20.04+) with NVIDIA GPU support
Python: 3.10+
Node: 16+ (for web frontend)

System Overview
Architecture
Project Structure
Technology Stack
Setup & Installation
Core Modules
Workflows
API Reference
Data Flows
Development Guide
Troubleshooting
Deployment

System Overview

Trading AI is a professional-grade crypto futures analytics and signal generation platform designed for manual execution on Binance USD-M Futures. The system operates in analysis-only mode, meaning it generates high-conviction trade signals but never executes automated orders.

Key Characteristics

Domain: Crypto Futures (Binance USD-M Futures only)
Mode: Analysis-only (no automated trading)
Core Intelligence: Ensemble ML models (XGBoost + LSTM/PyTorch)
Signal Grades: A+, A, B, C (confidence-based)
UI Pattern: Master-Detail dashboard for efficient signal browsing
Explainability: SHAP values for feature importance
Monitoring: MLflow experiment tracking, health checks, performance metrics
Deployment: Docker + Docker Compose with GPU acceleration

Design Philosophy

Analysis-Only: All execution paths are guarded and fail-safe
Transparent Decision-Making: Every signal includes SHAP explanations
Human-in-the-Loop: Traders manually review and execute trades
Performance Tracking: Integrated journaling and analytics
Fail-Fast Safety: Clear diagnostics when systems degrade

Architecture

┌─────────────────────────────────────────────────────────────┐
│                   Frontend Dashboard (React)                 │
│          Master-Detail UI | Settings | Performance           │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│                    FastAPI Backend                            │
│  ┌─────────┬─────────┬──────────┬─────────┬─────────┐       │
│  │ Signals │Analysis │Portfolio │ Trades  │ Explain │       │
│  │ Router  │ Router  │  Router  │ Router  │ Router  │       │
│  └─────────┴─────────┴──────────┴─────────┴─────────┘       │
│           Real-time Stream Broadcast (WebSocket)             │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│           ML & Analytics Engine (Python/PyTorch)            │
│  ┌──────────────┬──────────────┬──────────────┐             │
│  │ Predictor    │ Explainer    │ Ensemble     │             │
│  │ (XGBoost)    │ (SHAP)       │ (XGB + LSTM) │             │
│  └──────────────┴──────────────┴──────────────┘             │
│  ┌──────────────┬──────────────┬──────────────┐             │
│  │ Feature      │ Regime       │ Backtest     │             │
│  │ Engineering  │ Detector     │ Engine       │             │
│  └──────────────┴──────────────┴──────────────┘             │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│            Data & Storage Layer (SQLite + FS)               │
│  ┌──────────────┬──────────────┬──────────────┐             │
│  │ Market Data  │ Model State  │ Artifacts    │             │
│  │ (OHLCV)      │ (JSON/PKL)   │ (Logs/Stats) │             │
│  └──────────────┴──────────────┴──────────────┘             │
└─────────────────────────────────────────────────────────────┘
                              ↑↓
┌─────────────────────────────────────────────────────────────┐
│              Binance Futures API (Public Data)               │
│                    Real-time & Historical                    │
└─────────────────────────────────────────────────────────────┘

Project Structure

trading_ai/
├── api/                         # FastAPI backend
│   ├── main.py                 # Application entrypoint
│   ├── schemas.py              # Pydantic request/response models
│   ├── signal_cache.py         # Signal caching layer
│   ├── analysis_cache.py       # Analysis result caching
│   └── routers/                # Endpoint route handlers
│       ├── signals.py          # /api/signals endpoints
│       ├── analysis.py         # /api/analysis endpoints
│       ├── portfolio.py        # /api/portfolio endpoints
│       ├── trades.py           # /api/trades endpoints
│       ├── explain.py          # /api/explain endpoints
│       ├── system.py           # /api/system endpoints
│       └── realtime.py         # /api/realtime (WebSocket)
│
├── web/                         # React frontend (Vite)
│   ├── src/
│   │   ├── App.jsx             # Main app component
│   │   ├── App.css             # Global styles (glassmorphism)
│   │   ├── theme.css           # Design system tokens
│   │   ├── api.js              # API client utilities
│   │   ├── pages/              # Page components (Master-Detail)
│   │   ├── components/         # Reusable UI components
│   │   └── hooks/              # Custom React hooks
│   ├── package.json
│   └── vite.config.js
│
├── models/                      # Model training & inference
│   ├── train_all.py            # Orchestrated training pass (staged gates)
│   ├── train_xgboost.py        # XGBoost training pipeline
│   ├── lstm_train.py           # LSTM/PyTorch training
│   ├── lstm_model.py           # PyTorch LSTM architecture
│   ├── predictor.py            # XGBoost inference interface
│   ├── ensemble.py             # Weighted ensemble predictor
│   ├── explainer.py            # SHAP explanation generator
│   ├── regime_detector.py      # Market regime classification
│   ├── prepare_data.py         # Data preparation utilities
│   ├── split.py                # Train/test/validation splitting
│   ├── lstm_data.py            # LSTM-specific data preparation
│   ├── test_pytorch.py         # GPU availability check
│   ├── features_*.json         # Persisted feature lists (per ticker)
│   ├── metrics_*.json          # Persisted model metrics (per ticker)
│   └── lstm_metrics_*.json     # LSTM model metrics (per ticker)
│
├── features/                    # Feature engineering pipeline
│   ├── feature_pipeline.py     # Wrapper for crypto features
│   ├── momentum_features.py    # RSI, MACD, Stoch, etc.
│   ├── volatility_features.py  # ATR, BB, VIX-like metrics
│   ├── trend_features.py       # SMA, EMA, ADX, etc.
│   ├── custom_features.py      # Domain-specific features
│   └── target.py               # Label generation (ternary)
│
├── data/                        # Market data ingestion
│   ├── fetch_all.py            # Fetch Binance data for all tickers
│   └── (crypto-specific pipelines in domains/)
│
├── domains/crypto/              # Crypto-specific implementations
│   ├── config/
│   │   ├── settings.py         # System configuration
│   │   └── universe.py         # Active trading universe (BTC, ETH, etc.)
│   ├── features/
│   │   └── pipeline.py         # Crypto feature builder
│   ├── data/
│   │   └── pipeline.py         # Data fetch/store/validate
│   └── models/
│       └── (model implementations)
│
├── backtest/                    # Backtesting engine
│   ├── run_all.py              # Execute all backtests
│   ├── engine.py               # Core backtest simulator
│   ├── metrics.py              # Performance calculations
│   └── analyst_backtest.py     # Analyst-grade validation
│
├── core/                        # Core utilities
│   ├── ml/
│   │   ├── feature_frame.py    # Feature alignment & validation
│   │   ├── labels.py           # Label mappings (signal classes)
│   │   ├── model_paths.py      # Artifact path management
│   │   └── compute.py          # CUDA device detection
│   ├── data/
│   │   └── paths.py            # Artifact directory structure
│   ├── risk/
│   │   └── (risk management utilities)
│   └── observability/
│       └── (logging & diagnostics)
│
├── monitoring/                  # Runtime monitoring & retraining
│   ├── retrain.py              # Drift detection & retraining trigger
│   ├── mlflow_tracker.py       # MLflow experiment logging
│   ├── dashboard.py            # Performance dashboard queries
│   └── healthcheck.py          # System health checks
│
├── deploy/                      # Deployment utilities
│   ├── testnet_preflight.py   # Pre-deployment validation
│   ├── journal_auto.py         # Automated journaling helper
│   └── healthcheck.py          # Operational health checks
│
├── runtime/                     # Runtime state management
│   ├── realtime.py             # WebSocket broadcaster
│   └── (state management)
│
├── artifacts/                   # Generated outputs (not in git)
│   ├── market_data/            # Historical OHLCV data
│   ├── models/                 # Trained model files (.pkl, .pt)
│   ├── state/                  # Application state (SQLite DB)
│   ├── logs/                   # Execution logs & diagnostics
│   └── reports/                # Performance & backtest reports
│
├── tests/                       # Unit & integration tests
│
├── docs/                        # Documentation
│   ├── PROJECT_DOCUMENTATION.md # Detailed technical overview
│   ├── OPERATIONS.md           # Day-to-day operations guide
│   ├── CRYPTO_FUTURES_CUTOVER.md
│   └── PLAN.md
│
├── notebooks/                   # Jupyter notebooks (research/analysis)
│
├── docker-compose.yml          # Service orchestration
├── Dockerfile                  # Main image
├── Dockerfile.api              # API-only image
├── requirements.txt            # Python dependencies
├── .env                        # Environment configuration (not in git)
└── .env.example                # Environment template

Technology Stack

Backend & Analytics

| Component | Technology | Purpose | |-----------|-----------|---------| | Web Framework | FastAPI | Async REST API + WebSocket | | ML/Deep Learning | PyTorch + CUDA | LSTM model training & inference | | Tree Boosting | XGBoost | Primary classifier | | Feature Engineering | Pandas, NumPy | Data manipulation & analysis | | Explainability | SHAP | Feature importance & explanations | | Model Tracking | MLflow | Experiment logging & versioning | | Serialization | Joblib, Pickle | Model & scaler persistence | | Database | SQLite | Market data & state storage | | Python | 3.10+ | Language |

Frontend

| Component | Technology | Purpose | |-----------|-----------|---------| | Framework | React 18 | UI rendering | | Build Tool | Vite | Fast bundling & HMR | | Styling | CSS3 | Glassmorphism + dark theme | | State | React Hooks + Context | Client-side state | | HTTP | Fetch API | REST calls | | WebSocket | Native WS API | Real-time signal updates | | Node | 16+ | Runtime |

Infrastructure & DevOps

| Component | Technology | Purpose | |-----------|-----------|---------| | Containerization | Docker | Reproducible environments | | Orchestration | Docker Compose | Multi-service management | | Acceleration | NVIDIA CUDA 11.8+ | GPU computation | | Base Image | Python 3.12 (official) | Lightweight Python runtime | | Dependency Mgmt | pip + venv | Python package isolation |

Setup & Installation

Prerequisites

OS: Ubuntu 20.04 LTS or later
GPU: NVIDIA GPU with CUDA Compute Capability 6.0+ (RTX 3060, A100, H100, etc.)
CUDA: 11.8 or later
cuDNN: 8.6 or later
Docker: 20.10+ (if using containers)
Python: 3.10 or 3.11 (3.12 for Docker)
Node: 16+ (for web development)

Local Development Setup

1. Clone the Repository

cd ~/Documents
git clone <repo-url> trading_ai
cd trading_ai

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate

3. Install Python Dependencies

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

4. Verify CUDA/PyTorch

./venv/bin/python models/test_pytorch.py
nvidia-smi

Expected output: CUDA devices listed, PyTorch recognizes GPU.

5. Configure Environment

cp .env.example .env
# Edit .env and fill in:
# - BINANCE_API_KEY (read-only recommended)
# - BINANCE_API_SECRET
# - APP_MODE=analysis_only
# - UNIVERSE=BTC-USD,ETH-USD,SOL-USD,BNB-USD

6. Install Frontend Dependencies

cd web
npm install
cd ..

7. Initialize Artifacts Directory

./venv/bin/python -c "from core.data.paths import ensure_artifact_dirs; ensure_artifact_dirs()"

Docker Deployment

1. Build Images

docker compose build

2. Start Services

docker compose up -d mlflow trading_api
docker compose ps

3. Verify Services

MLflow: http://localhost:5000
API Docs: http://localhost:8080/docs
API Endpoint: http://localhost:8080

4. Inspect Logs

docker compose logs -f trading_api
docker compose logs -f mlflow

Frontend Development

cd web
npm run dev
# Dashboard available at http://localhost:5173

Core Modules

1. Data Ingestion (`data/`, `domains/crypto/data/`)

Purpose: Fetch, validate, and store market data from Binance Futures.

Key Components:

fetch(): Retrieves OHLCV data for active tickers
store(): Persists data to SQLite + CSV
validate(): QA checks for data integrity

Command:

./venv/bin/python data/fetch_all.py

Output:

artifacts/market_data/ - CSV files per ticker
artifacts/state/state.db - SQLite database

2. Feature Engineering (`features/`, `domains/crypto/features/`)

Purpose: Generate technical indicators and ML features from raw OHLCV data.

Feature Categories:

Momentum: RSI, MACD, Stochastic, CCI, Rate of Change
Volatility: ATR, Bollinger Bands, Historical Volatility, NATR
Trend: SMA, EMA, ADX, ADXR, Supertrend, Ichimoku
Custom: Volume-weighted indicators, regime-specific features
Market Regime Detection: Classifies market states (TRENDING, RANGING, CHOPPY) using ADX, EMA slopes, ATR, and the Kaufman Efficiency Ratio.

Key Function:

from domains.crypto.features.pipeline import build_features
df = build_features("BTC-USD", dropna=True)  # Latest feature frame

Configuration: Feature selection happens during model training; stored in models/features_<TICKER>.json.

3. Model Training (`models/`)

Architecture: Two-stage ensemble

XGBoost: Fast, interpretable baseline (55% weight)
LSTM: Sequence-aware capture (45% weight)

XGBoost Pipeline

File: train_xgboost.py

Data preparation & split (walk-forward CV)
Hyperparameter tuning
Feature importance ranking
Model serialization

Output:

models/xgb_<TICKER>.pkl
models/scaler_<TICKER>.pkl
models/features_<TICKER>.json
models/metrics_<TICKER>.json

LSTM Pipeline

File: lstm_train.py + lstm_model.py

Time-series data shaping (sequences of T steps)
Normalization & augmentation
Architecture: 2-layer LSTM → Dense → Dropout → Output
Training with early stopping
GPU acceleration (CUDA)

Output:

models/<TICKER>_lstm.pt
models/lstm_metrics_<TICKER>.json

Orchestrated Training

File: train_all.py

Implements gated training pipeline:

✓ Data QA (fetch & validate)
✓ Features + Labels QA (alignment check)
✓ XGBoost baseline (walk-forward gate)
✓ LSTM training (PyTorch gate)
✓ Ensemble + trading evaluation
✓ Promotion decision

./venv/bin/python models/train_all.py

4. Signal Generation & Prediction (`models/predictor.py`, `models/ensemble.py`)

Purpose: Generate real-time trading signals with confidence grades.

Single-Model Prediction

from models.predictor import TradingPredictor

predictor = TradingPredictor("BTC-USD")
signal = predictor.predict_latest()
# Returns: {"signal": "buy" | "sell" | "neutral", "confidence": 0.95}

Ensemble Prediction

from models.ensemble import EnsemblePredictor

ensemble = EnsemblePredictor("BTC-USD")
signal = ensemble.predict_latest()
# Weighted average of XGB (55%) + LSTM (45%)

Signal Grades

Grades assigned based on ensemble confidence:

A+: Confidence ≥ 0.85 + strong secondary confirmations
A: Confidence 0.75–0.84 + good confirmations
B: Confidence 0.65–0.74 + moderate confirmations
C: Confidence < 0.65 or mixed signals

5. Explainability (`models/explainer.py`)

Purpose: Generate SHAP-based explanations for every signal.

from models.explainer import PredictionExplainer

explainer = PredictionExplainer("BTC-USD")
explanation = explainer.explain_latest()
# Returns: {
#   "shap_values": [...],
#   "feature_names": [...],
#   "base_value": 0.5,
#   "explanation_text": "..."
# }

Features Explained:

Top 5 positive (buy) drivers
Top 5 negative (sell) drivers
Feature interactions

Caching: SHAP computations cached to artifacts/shap_cache/ for performance.

6. Backtesting (`backtest/`)

Purpose: Validate signal quality against historical data.

Run All Backtests

./venv/bin/python backtest/run_all.py

Metrics Computed

Sharpe Ratio
Max Drawdown
Win Rate
Profit Factor
Total Return

Output: artifacts/reports/backtest_summary.json

7. Portfolio Management (`api/routers/portfolio.py`)

Purpose: Fetch read-only position and balance data from Binance.

Endpoints:

GET /api/portfolio/balance - Account balance
GET /api/portfolio/positions - Open positions
GET /api/portfolio/exposure - Market exposure

Safety: No write operations in analysis mode.

8. Trade Journaling (`api/routers/trades.py`, `deploy/journal_auto.py`)

Purpose: Record manual trade executions, skip reasons, and outcomes.

Journaling Columns:

Timestamp
Ticker
Signal Grade
Action (executed, skipped, missed)
Entry Price / Exit Price
PnL
Notes

Add Entry:

./venv/bin/python deploy/journal_auto.py --action executed --ticker BTC-USD --entry 45000 --exit 45500

Storage: artifacts/state/trades.db (SQLite)

9. Monitoring & Retraining (`monitoring/`)

Health Checks:

./venv/bin/python deploy/healthcheck.py

Drift Detection & Retraining:

./venv/bin/python monitoring/retrain.py

Triggers retraining if:

Model accuracy drops > 5% vs. validation baseline
Data distribution shift detected (Kolmogorov-Smirnov test)
30 days since last training

Experiment Tracking: All training runs logged to MLflow.

Workflows

Daily Operations

1. Morning Routine (6 AM UTC)

# Fetch latest market data
./venv/bin/python data/fetch_all.py

# Run health checks
./venv/bin/python deploy/healthcheck.py

# Optionally refresh models (if needed)
# ./venv/bin/python monitoring/retrain.py

2. Throughout the Day

Open dashboard at http://localhost:5173
Review /analysis page for A-grade signals
Deep-dive into signal details (SHAP explanations)
Execute trades manually via Binance UI
Log execution via dashboard or journal_auto.py
Monitor /performance page for accuracy tracking

3. End-of-Day

# Export performance report
curl http://localhost:8080/api/performance/summary > daily_report.json

# Review backtest performance
cat artifacts/reports/backtest_summary.json

Weekly Retraining

./venv/bin/python models/train_all.py

Validates:

✓ Data integrity
✓ Feature alignment
✓ Model baseline performance
✓ Ensemble performance
✓ Promotes models if passing all gates

Monthly Deep Analysis

# Backtest full month's signals
./venv/bin/python backtest/run_all.py

# Review MLflow experiments
# Visit http://localhost:5000

API Reference

Base URL

Development: http://localhost:8080
Production: https://<your-domain>

Authentication

Currently unauthenticated (analysis-only mode). Production deployments should add OAuth2 or API key authentication.

Key Endpoints

Signals

GET /api/signals?ticker=BTC-USD&limit=10 - Fetch latest signals
GET /api/signals/<signal_id> - Get signal details
POST /api/signals/<signal_id>/acknowledge - Mark signal as reviewed

Analysis

GET /api/analysis?ticker=BTC-USD - Get multi-timeframe analysis
GET /api/analysis/<ticker>/regime - Market regime classification
GET /api/analysis/<ticker>/indicators - Current technical indicators

Explanations

GET /api/explain/<ticker> - SHAP explanation for latest signal
GET /api/explain/<ticker>/history?limit=10 - Recent explanations

Portfolio (Read-Only)

GET /api/portfolio/balance - Account balance
GET /api/portfolio/positions - Open positions
GET /api/portfolio/exposure - Market exposure

Trades (Manual Journaling)

GET /api/trades?ticker=BTC-USD - Journaled trades
POST /api/trades - Record new trade
PUT /api/trades/<trade_id> - Update trade
GET /api/trades/performance - Journaling performance summary

System

GET /api/system/health - System health status
GET /api/system/metrics - Performance metrics
GET /api/system/config - Current configuration

Real-Time

WebSocket /api/realtime/signals - Live signal stream

Response Format

All responses are JSON:

{
  "success": true,
  "data": {
    ...
  },
  "error": null,
  "timestamp": "2026-05-30T14:23:45Z"
}

Error responses:

{
  "success": false,
  "data": null,
  "error": "Detailed error message",
  "timestamp": "2026-05-30T14:23:45Z"
}

Data Flows

Real-Time Signal Generation

Market Data Update
    ↓
Feature Engineering Pipeline
    ↓
Model Inference (XGBoost + LSTM)
    ↓
Ensemble Weighted Prediction
    ↓
Grade Assignment (A+, A, B, C)
    ↓
SHAP Explanation Generation
    ↓
Signal Cached in Redis/Memory
    ↓
API Broadcast via WebSocket
    ↓
Dashboard Real-Time Update
    ↓
Trader Manual Review & Execution

Training Pipeline

Raw Market Data
    ↓
Data Validation (QA Gate 1)
    ↓
Feature Alignment Check (QA Gate 2)
    ↓
Train/Val Split (Walk-Forward CV)
    ↓
XGBoost Training (Gate 3)
    ↓
LSTM Training (Gate 4)
    ↓
Ensemble Creation (Gate 5)
    ↓
Backtest Validation
    ↓
Promotion Decision
    ↓
Model Artifact Storage
    ↓
MLflow Logging

Journaling & Performance Tracking

Manual Trade Execution (Binance)
    ↓
Journal Entry via API/Dashboard
    ↓
SQLite Persistence
    ↓
Performance Calculation
    ↓
Accuracy vs. Model Prediction
    ↓
Dashboard Performance Page

Development Guide

Adding a New Feature

Create feature calculation in features/custom_features.py
Register in pipeline in domains/crypto/features/pipeline.py

Test feature generation:

from features.custom_features import my_feature
df = my_feature(ohlcv_df)
assert df["my_feature"].notna().all()

Retrain models to include new feature:
```
./venv/bin/python models/train_all.py
```

Adding a New Ticker

Update universe in domains/crypto/config/universe.py:

ACTIVE_TICKERS = ["BTC-USD", "ETH-USD", "SOL-USD", "YOUR-USD"]

Fetch data:
```
./venv/bin/python data/fetch_all.py
```
Train models:
```
./venv/bin/python models/train_all.py
```

Adding a New API Endpoint

Create router in api/routers/your_router.py:

from fastapi import APIRouter
router = APIRouter()

@router.get("/your-endpoint")
async def your_endpoint():
    return {"data": "..."}

Include in main app in api/main.py:

from api.routers import your_router
app.include_router(your_router.router, prefix="/api")

Running Tests

pytest tests/ -v
pytest tests/ --cov=.  # With coverage

Code Style

Linting: black for formatting
Type Hints: Required for all functions
Docstrings: Module-level and complex functions only
Imports: Sort alphabetically, group by stdlib/third-party/local

Troubleshooting

Common Issues

1. CUDA Not Available

Symptom: RuntimeError: CUDA is not available

Solution:

nvidia-smi  # Verify GPU driver
python -c "import torch; print(torch.cuda.is_available())"

# If false, reinstall PyTorch with CUDA:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

2. Feature Mismatch During Inference

Symptom: ValueError: Feature mismatch: expected 66 features, got 65

Solution:

Retrain models to recalculate feature list
Check models/features_<TICKER>.json matches feature pipeline
Verify no features are NaN in latest data

3. API Timeout

Symptom: TimeoutError when fetching signals

Solution:

# Increase FastAPI timeout in docker-compose.yml
# Or check for slow SHAP explanations
tail -f artifacts/logs/api.log

4. Out of Memory During Training

Symptom: RuntimeError: CUDA out of memory

Solution:

# Reduce batch size in models/train_xgboost.py or lstm_train.py
# Or use CPU-only mode:
export CUDA_VISIBLE_DEVICES=""
./venv/bin/python models/train_all.py

5. Dashboard Not Loading

Symptom: Blank page or 404

Solution:

cd web
npm run build  # Rebuild
# Check API is accessible:
curl http://localhost:8080/api/system/health

Debug Commands

# Check system health
./venv/bin/python deploy/healthcheck.py

# View model metadata
python -c "import joblib; print(joblib.load('models/xgb_BTC-USD.pkl'))"

# Trace feature building
python -c "from features.feature_pipeline import build_features; df = build_features('BTC-USD'); print(df.columns.tolist())"

# Monitor GPU usage
watch -n 1 nvidia-smi

# View API logs
docker compose logs -f trading_api

Deployment

Production Checklist

[ ] HTTPS enabled (reverse proxy / load balancer)
[ ] .env configured with production API keys (minimal permissions)
[ ] Database backups configured
[ ] Log aggregation set up
[ ] Alerting configured (model drift, API errors)
[ ] Monitoring dashboard (Grafana, Prometheus)
[ ] Rate limiting enabled on API
[ ] CORS properly configured for your domain
[ ] Secrets manager integrated (not .env files)

Docker Production Build

docker build -t trading-ai:prod -f Dockerfile .
docker run -d \
  --gpus all \
  -e APP_MODE=analysis_only \
  -e BINANCE_API_KEY=$KEY \
  -e BINANCE_API_SECRET=$SECRET \
  -p 8080:8080 \
  trading-ai:prod

Scaling Considerations

Horizontal: Deploy multiple API replicas behind load balancer
Vertical: Use larger GPU instances for training
Caching: Add Redis for signal & explanation caching
Database: Migrate SQLite to PostgreSQL for multi-node setups

Additional Resources

Detailed Architecture: See docs/PROJECT_DOCUMENTATION.md
Operations Guide: See docs/OPERATIONS.md
API Documentation: http://localhost:8080/docs (Swagger UI)
MLflow Tracking: http://localhost:5000

Support & Contact

For issues, questions, or contributions, refer to the repository's GitHub issues or contact the development team.

Last Updated: May 2026
Maintained By: Trading AI Team

Trading Ai

Trading AI - Complete System Documentation

Table of Contents

System Overview

Key Characteristics

Design Philosophy

Architecture

Project Structure

Technology Stack

Backend & Analytics

Frontend

Infrastructure & DevOps

Setup & Installation

Prerequisites

Local Development Setup

1. Clone the Repository

2. Create Virtual Environment

3. Install Python Dependencies

4. Verify CUDA/PyTorch

5. Configure Environment

6. Install Frontend Dependencies

7. Initialize Artifacts Directory

Docker Deployment

1. Build Images

2. Start Services

3. Verify Services

4. Inspect Logs

Frontend Development

Core Modules

1. Data Ingestion (data/, domains/crypto/data/)

2. Feature Engineering (features/, domains/crypto/features/)

3. Model Training (models/)

XGBoost Pipeline

LSTM Pipeline

Orchestrated Training

4. Signal Generation & Prediction (models/predictor.py, models/ensemble.py)

Single-Model Prediction

Ensemble Prediction

Signal Grades

5. Explainability (models/explainer.py)

6. Backtesting (backtest/)

Run All Backtests

Metrics Computed

7. Portfolio Management (api/routers/portfolio.py)

8. Trade Journaling (api/routers/trades.py, deploy/journal_auto.py)

9. Monitoring & Retraining (monitoring/)

Workflows

Daily Operations

1. Morning Routine (6 AM UTC)

2. Throughout the Day

3. End-of-Day

Weekly Retraining

Monthly Deep Analysis

API Reference

Base URL

Authentication

Key Endpoints

Signals

Analysis

Explanations

Portfolio (Read-Only)

Trades (Manual Journaling)

System

Real-Time

Response Format

Data Flows

Real-Time Signal Generation

Training Pipeline

Journaling & Performance Tracking

Development Guide

Adding a New Feature

Adding a New Ticker

Adding a New API Endpoint

Running Tests

Code Style

Troubleshooting

Common Issues

1. CUDA Not Available

2. Feature Mismatch During Inference

3. API Timeout

1. Data Ingestion (`data/`, `domains/crypto/data/`)

2. Feature Engineering (`features/`, `domains/crypto/features/`)

3. Model Training (`models/`)

4. Signal Generation & Prediction (`models/predictor.py`, `models/ensemble.py`)

5. Explainability (`models/explainer.py`)

6. Backtesting (`backtest/`)

7. Portfolio Management (`api/routers/portfolio.py`)

8. Trade Journaling (`api/routers/trades.py`, `deploy/journal_auto.py`)

9. Monitoring & Retraining (`monitoring/`)