Skip to content

Backend Service — Design Document

Overview

Central API gateway for the TradAI platform. Orchestrates backtest execution, proxies requests to downstream services (Strategy Service, Data Collection), and manages strategy catalog and promotion workflows.

Architecture

3-Layer Pattern

src/tradai/backend/
├── api/                       # Presentation layer
│   ├── routes.py              # Core backtest endpoints
│   ├── catalog_routes.py      # Strategy catalog endpoints
│   ├── operations_routes.py   # Strategy operations (deploy, rollback)
│   ├── promotion_routes.py    # Strategy promotion workflow
│   ├── proxy_routes.py        # Proxy to Strategy/Data services
│   ├── auth_guard.py          # Authentication middleware
│   ├── schemas.py             # Request/response Pydantic models
│   ├── dependencies.py        # FastAPI dependency injection
│   └── websocket.py           # WebSocket for real-time updates
├── core/                      # Business logic
│   ├── service.py             # BacktestService (submit, status, results)
│   ├── orchestration.py       # Backtest execution orchestration
│   ├── entities.py            # Domain entities (BacktestJob, etc.)
│   ├── equity_service.py      # Equity curve calculations
│   ├── equity_entities.py     # Equity-specific entities
│   ├── catalog_service.py     # Strategy catalog operations
│   ├── catalog_entities.py    # Catalog entities
│   ├── operations_entities.py # Operations entities
│   ├── strategy_operations.py # Deploy, rollback, version management
│   ├── repositories.py        # Repository protocols (interfaces)
│   ├── settings.py            # Service configuration
│   ├── ws_token.py            # WebSocket token management
│   └── websocket/             # WebSocket handlers
└── infrastructure/            # External adapters
    ├── executor_factory.py    # Creates backtest executors
    ├── local.py               # Local (Freqtrade subprocess) executor
    ├── sqs.py                 # SQS-based executor (AWS production)
    └── memory.py              # In-memory executor (testing)

Backtest Execution Flow

Client → Backend API → Executor Factory
                           ├── LocalExecutor    (--local mode)
                           ├── SQSExecutor      (production: SQS → Step Functions → ECS)
                           └── MemoryExecutor   (tests)

Production flow (SQS): 1. Client submits backtest via POST /api/v1/backtests 2. Backend creates DynamoDB job record, sends SQS message 3. SQS triggers Lambda → Step Functions workflow 4. Step Functions: EnsureData → RunBacktest (ECS) → ProcessResults 5. Results stored in DynamoDB + S3, status updated via WebSocket

See BACKTEST_DESIGN.md in the service source directory for the detailed backtest architecture.

Dependencies

Libraries Used

  • tradai-common: Entities (BacktestJob, BacktestResult), DynamoDB repositories, SQS client, health checks, FastAPI utilities, WebSocket support
  • tradai-data: Data availability checks
  • tradai-strategy: Strategy metadata validation

External Services

  • Strategy Service: Proxied for backtest execution, strategy config, MLflow operations
  • Data Collection: Proxied for data sync and freshness
  • DynamoDB: Job tracking and result storage
  • SQS: Backtest job queue (production)
  • S3: Backtest result artifacts
  • MLflow: Experiment tracking (via Strategy Service)

Consumed By

  • CLI: tradai backtest, tradai strategy commands
  • Frontend: TradAI UI (via REST + WebSocket)
  • Lambdas: update-status, backtest-consumer

Key Design Decisions

  1. Executor pattern — Abstract executor interface with Local/SQS/Memory implementations. Allows same API for dev (local Freqtrade) and production (AWS pipeline).
  2. Gateway pattern — Backend proxies to downstream services rather than calling them directly from CLI. Simplifies auth, logging, and service discovery.
  3. WebSocket for status — Real-time backtest progress updates via WebSocket, avoiding polling.
  4. DynamoDB for jobs — Chosen over PostgreSQL for job tracking due to serverless scaling and pay-per-request pricing.

Configuration

Variable Description Default
BACKEND_HOST Server host 0.0.0.0
BACKEND_PORT Server port 8000
BACKEND_STRATEGY_SERVICE_URL Strategy service URL http://localhost:8003
BACKEND_DATA_COLLECTION_URL Data collection URL http://localhost:8002
BACKEND_MLFLOW_TRACKING_URI MLflow URL http://localhost:5001
BACKEND_SQS_QUEUE_URL SQS queue for backtest jobs — (production only)
BACKEND_DYNAMODB_TABLE DynamoDB table name — (production only)

API Reference

See Backend README for complete endpoint documentation.