Developer Guide

Welcome to the alpha-oracle Developer Guide. This documentation is for developers and contributors who want to understand the system architecture, set up a local development environment, extend functionality, or contribute to the project.

What This Guide Covers

This guide provides technical documentation for:

  • Getting Started: Prerequisites, local setup, and running tests
  • Architecture: System design, data flows, and module organization
  • Module Reference: Detailed documentation for each subsystem (data, strategy, execution, risk, ML)
  • Infrastructure: Docker services, database schema, Redis pub/sub patterns
  • Frontend: React dashboard architecture, WebSocket integration, component structure
  • Operations: Deployment, monitoring, troubleshooting, and production configuration
  • Extending: Writing custom strategies, data adapters, risk managers, and backtest engines
  • ADRs: Architecture Decision Records documenting key design choices

Project Overview

alpha-oracle is an AI-driven automated stock trading system designed for retail investors with accounts under $25K. It focuses on swing and position trading (no day trading) to comply with FINRA Pattern Day Trader (PDT) rules.

Key Features

  • Data Pipeline: Multi-source ingestion from IBKR, Alpha Vantage, SEC EDGAR, and FINRA
  • Strategy Engine: Pluggable strategy framework with 3 builtin strategies and ML-powered signal generation
  • Risk Management: Multi-layer risk checks including PDT guard, position limits, and circuit breakers
  • Smart Execution: Intelligent order routing (market/limit/TWAP) with execution quality tracking
  • ML Pipeline: XGBoost-based prediction with 50+ point-in-time features and model monitoring
  • Dashboard: Real-time React UI with portfolio, strategy, risk, and ML monitoring views

Tech Stack

Layer Technologies
Backend Python 3.11+, FastAPI, SQLAlchemy async, Pydantic
Databases TimescaleDB (time-series), DuckDB (analytics), Redis (cache/pub-sub)
Frontend React 18, TypeScript, TailwindCSS, Vite, Recharts
ML XGBoost, scikit-learn, Optuna (hyperparameter tuning)
Broker Interactive Brokers (IBKR) via ib-async
Observability Prometheus (metrics), Grafana (dashboards), structlog (logging)
Orchestration APScheduler (cron jobs), Redis pub/sub (events)
Testing pytest, pytest-asyncio, hypothesis (property tests)

Getting Started

  1. Prerequisites — System requirements and tools
  2. Local Development Setup — Clone, install, and run
  3. Running Tests — Test suite organization and execution

Architecture

  1. Overview — Modular monolith design and core interfaces
  2. Data Flows — Signal generation, order execution, and risk cascade
  3. Module Map — Full directory structure with descriptions

Module Reference

Detailed documentation for each subsystem (see Module Reference):

  • Core: Models, interfaces, config, database, Redis
  • Data: Adapters, feeds, storage, universe management
  • Strategy: Engine, backtesting, builtin strategies, ranking
  • Signals: Feature store, ML pipeline, model monitoring
  • Scheduling: Cron jobs for data ingestion and model retraining
  • Execution: Smart router, broker adapters, order generation
  • Risk: PDT guard, pre-trade checks, circuit breakers, kill switch
  • API: FastAPI routes, WebSocket, dependencies
  • Monitoring: Prometheus metrics, alert manager

Infrastructure

  • Database schema (TimescaleDB hypertables, DuckDB views)
  • Redis pub/sub channels and cache keys
  • Docker Compose services and networking
  • Prometheus metrics and Grafana dashboards

Frontend

  • React component architecture
  • WebSocket integration for real-time updates
  • Dashboard page structure (Portfolio, Strategies, Risk, Trades, ML)
  • Styling conventions (dark terminal aesthetic)

Operations

  • Configuration management (YAML + env vars)
  • Deployment strategies (Docker, systemd)
  • Monitoring and alerting
  • Backup and recovery
  • Troubleshooting common issues

Extending

  • Writing custom strategies (BaseStrategy interface)
  • Adding data sources (DataSourceInterface)
  • Implementing risk managers (RiskManager interface)
  • Creating backtest engines (BacktestEngine interface)

Architecture Decision Records

See ADRs for detailed context on key architectural choices:

Contributing

Contributions are welcome! Please read the Contributing Guide for:

  • Code style and conventions (Ruff, mypy)
  • Testing requirements (pytest, coverage)
  • Pull request process
  • Issue reporting guidelines

Support

Table of contents

This site uses Just the Docs, a documentation theme for Jekyll.