The Problem

Most quant frameworks stop at generating a backtest result—a number, maybe a chart. Deciding which strategy actually performs better requires exporting results, building comparison spreadsheets, and manually tracking performance across time windows. This framework closes that loop by generating a single interactive HTML dashboard that ranks, filters, and compares every strategy tested.

What This Does

investing-algorithm-framework is a Python framework for creating, backtesting, and deploying trading strategies. It provides a full workflow: define strategies, run backtests across multiple time windows, compare them in one report, and deploy the winner. The core package (investing_algorithm_framework/) handles strategy execution, portfolio management, and reporting; the examples/ directory contains ready-made strategy templates and a large set of pre-computed backtest results.

The framework generates self-contained HTML reports with 30+ metrics (CAGR, Sharpe, Sortino, Calmar, VaR, CVaR, Max DD), equity and drawdown charts, monthly heatmaps, and benchmark comparisons. Documentation lives in docusaurus/docs/ with guides for setup, backtesting, deployment, and optimization.

How It Is Wired

Execution starts in investing_algorithm_framework/__init__.py, which re-exports the public API from domain/, app/, and services/. The app/ package contains context.py (1,418 lines) and strategy.py—the two largest files—which manage the application lifecycle and strategy orchestration. The domain/ package holds models, backtesting logic (backtesting/backtest.py), and utilities.

The import graph shows 552 internal modules with 789 edges. Two hub modules dominate: domain/__init__.py (125 modules depend on it) and __init__.py (118 dependents). Both participate in a circular import cycle (11 modules total), meaning changes to these hubs have wide blast radius and require careful testing. The services/ layer handles metrics and reporting, with services/metrics/__init__.py importing 17 modules (instability 0.85)—highly dependent on internals.

Backtests write results as JSON files to examples/batch_one/<hash>/runs/backtest_*/ with metrics.json and run.json per window. The CLI (cli/mcp_server.py) provides a management interface. The wiring for deployment targets (AWS/Azure) has not been mapped in this analysis.

How To Use It

# Clone and install
git clone https://github.com/moses-y/investing-algorithm-framework
cd investing-algorithm-framework
poetry install

# Run a backtest with an example strategy
python -m investing_algorithm_framework.cli backtest examples/tutorial/strategies/ema_crossover_rsi_filter/strategy.py

Configuration is handled through Python classes and YAML files (see examples/ and docusaurus/docs/Getting Started/application-setup.md). The README documents installation via pip install investing-algorithm-framework and scaffolding new projects. No Dockerfile is present.

Real-World Use

A typical workflow: define a strategy class with apply_strategy() and apply_portfolio_configuration() methods, register it with the framework, run a backtest across multiple time windows, then open the generated HTML report to compare it against alternatives. The examples/batch_one/ directory shows the expected output structure—each strategy hash contains parameters.json, metrics.json, and per-window run.json files.

Code Health & Issues

Static analysis found 151 issues (49 high, 102 medium) across 8 categories:

  • High – Circular imports – 11 modules in cycles, including domain/__init__.py and __init__.py. Breaking these requires extracting shared types or deferring imports.
  • High – Deep nesting – 26 instances, max depth 9, in app/strategy.py, domain/backtesting/backtest_metrics.py.
  • High – Oversized files – 6 files over 1,400 lines, notably app/context.py and app/strategy.py.
  • High – Hub modules – 8 modules with 100+ dependents; churn is high-blast-radius.
  • High – Duplicated code – 2,474 repeated 6-line blocks across 195 files.
  • Medium – Broad exception handling – 4 cases in infrastructure/repositories/repository.py.
  • Medium – High branching density – 2 files, 43 branches over 124 lines.
  • Medium – File handles without context managers – 2 cases.

SDLC: tests (676 files), CI (GitHub Actions), license, and lockfile are all present. No committed secrets detected. The docusaurus/docs/ contains pre-built HTML artifacts alongside source markdown—consider cleaning these from the repo.

The Bottom Line

A well-structured framework with serious depth in backtesting and reporting, backed by a large test suite and real documentation. The circular imports and oversized files will complicate significant refactoring, but the architecture is sound for its purpose. Best suited for teams that need a complete strategy comparison workflow rather than a bare backtesting engine.