Skip to content

Strategy Service — Design Document

Overview

Strategy execution engine for the TradAI platform. Runs backtests via Freqtrade, manages strategy configurations, handles hyperparameter optimization, and integrates with MLflow for experiment tracking and model promotion.

Architecture

3-Layer Pattern

src/tradai/strategy_service/
├── api/                          # Presentation layer
│   ├── routes.py                 # Core backtest/strategy endpoints
│   ├── config_routes.py          # Strategy configuration management
│   ├── hyperopt_routes.py        # Hyperparameter optimization endpoints
│   ├── model_routes.py           # MLflow model management endpoints
│   ├── promotion_routes.py       # Strategy promotion workflow
│   ├── registration_routes.py    # Strategy registration endpoints
│   ├── challenge_routes.py       # Strategy challenge/validation endpoints
│   ├── mappers.py                # DTO ↔ domain entity mapping
│   ├── schemas/                  # Request/response Pydantic schemas
│   └── dependencies.py           # FastAPI dependency injection
├── core/                         # Business logic
│   ├── service.py                # StrategyService (backtest execution)
│   ├── backtest_service.py       # Backtest-specific logic
│   ├── hyperopt_service.py       # Hyperparameter optimization
│   ├── hyperopt/                 # Hyperopt sub-modules
│   ├── optuna_handler.py         # Optuna integration for optimization
│   ├── promotion_service.py      # Model promotion pipeline
│   ├── registration_service.py   # Strategy registration
│   ├── challenge_service.py      # Strategy validation challenges
│   ├── model_upload_service.py   # Model artifact upload to MLflow
│   ├── shadow_trading_service.py # Shadow/paper trading
│   ├── shadow_trading_repository.py # Shadow trading interface
│   ├── credentials.py            # Exchange credential management
│   ├── entities.py               # Domain entities
│   └── settings.py               # Service configuration
└── infrastructure/               # External adapters
    └── shadow_test_repository.py # Shadow trading implementation

Module Responsibilities

Module Purpose
core/service.py Core strategy execution — runs Freqtrade, collects results
core/backtest_service.py Backtest orchestration with config generation
core/hyperopt_service.py Hyperparameter search (Freqtrade hyperopt + Optuna)
core/promotion_service.py Promote strategy versions through staging → production
core/registration_service.py Register strategies in the platform catalog
core/challenge_service.py Validate strategies against benchmark criteria
core/shadow_trading_service.py Paper trading for strategy validation

Dependencies

Libraries Used

  • tradai-common: LoggerMixin, health checks, FastAPI utilities, configuration
  • tradai-strategy: TradAIStrategy base class, metadata, validation, linting
  • Freqtrade: Backtesting engine (called as subprocess or library)
  • MLflow: Experiment tracking and model registry

External Services

  • MLflow: Experiment logging, model registry, artifact storage
  • Freqtrade: Backtesting engine (embedded)
  • ArcticDB: Market data access (via tradai-data adapters)

Consumed By

  • Backend service: Proxies all strategy operations
  • ECS tasks: Runs as container in AWS Step Functions backtest pipeline
  • CLI: tradai strategy backtest, tradai strategy lint

Key Design Decisions

  1. Freqtrade as engine — Uses Freqtrade's battle-tested backtesting engine rather than building custom. Strategies extend TradAIStrategy which extends Freqtrade's IStrategy.
  2. Dual optimization — Supports both Freqtrade's built-in hyperopt and Optuna for flexible parameter optimization.
  3. Promotion pipeline — Strategies progress through registered → staged → promoted states with validation gates at each step.
  4. Shadow trading — Paper trading support for validating strategies against live market data before deployment.

Configuration

Variable Description Default
STRATEGY_SERVICE_HOST Server host 0.0.0.0
STRATEGY_SERVICE_PORT Server port 8003
STRATEGY_SERVICE_MLFLOW_TRACKING_URI MLflow URL http://localhost:5000
STRATEGY_SERVICE_STRATEGIES_DIR Strategy packages directory strategies/
STRATEGY_SERVICE_USER_DATA_DIR Freqtrade user_data directory user_data/

API Reference

See Strategy Service README for complete endpoint documentation.