Equity Backtester Platform

This document consolidates all backtesting platform documentation into a single, scrollable page. The materials cover architecture, data flow, core capabilities, and the technology stack. All content is view-only and hosted directly on this site.

This system is designed to support research‑grade backtesting and analysis of trading ideas across user‑supplied datasets, with a workflow that ingests data, executes strategies, simulates performance, and produces analytical outputs for review. It provides capabilities for data management, strategy execution, backtesting, statistical validation, macro and volatility analysis, and results comparison, including validations such as hit‑rate analysis, skill testing, survival analysis, and randomized entry tests to distinguish signal from noise. Typical outputs include trade logs, equity curves, summary metrics, and saved analysis artifacts suitable for visualization or export.

Quick visual

Architecture overview

Scope

This section describes the system-level architecture for the backtesting platform, derived from the current codebase structure and API surface.

System context (C4 - Context)

graph TB
  User[Research User]
  UI[Web UI]
  API[Backend Service]
  Files[Local CSV/JSON Files]
  Ext[External Data Sources]

  User --> UI
  UI --> API
  API --> Files
  Ext --> API

  Ext -. optional .-> API

Notes

• External data sources are optional and accessed via helper scripts or libraries (for example, yfinance). The core runtime uses local CSVs.

Containers (C4 - Container)

graph TB
  UI[Frontend Web App]
  API[Backend Service]
  CSV[(CSV Store: uploaded_csvs/)]
  STRAT[(Strategy Files: strategies/)]
  DEEP[(Deep Test Results: deep_test_results/)]
  MACRO[(Macro Test Results: macro_test_results/)]
  VOL[(Volatility Data/Results: backend/volatility_testing.py)]

  UI --> API
  API --> CSV
  API --> STRAT
  API --> DEEP
  API --> MACRO
  API --> VOL

Component view - Backend (C4 - Component)

graph TB
  API[Backend Application]
  DM[Data Management Endpoints]
  STRAT_M[Strategy CRUD Endpoints]
  BACKTEST[Backtest Engine]
  DEEP_TEST[Deep Testing Module]
  MACRO_TEST[Macro Testing Module]
  VOL_TEST[Volatility Testing Module]
  REL_PERF[Relative Performance Module]

  API --> DM
  API --> STRAT_M
  API --> BACKTEST
  API --> DEEP_TEST
  API --> MACRO_TEST
  API --> VOL_TEST
  API --> REL_PERF

Key backend components

• Data management: CSV upload, validation, preview, list, delete, download.
• Strategy management: save, list, fetch, delete Python strategies.
• Backtest engine: executes strategies, simulates equity curve, computes metrics.
• Deep testing: statistical tests on strategy outcomes and trade distributions.
• Macro testing: factor modeling, walk-forward validation, insights generation.
• Volatility testing: index-specific volatility analysis.
• Relative performance: ratio-based backtest between two symbols.

Primary data stores

• backend/uploaded_csvs/ for OHLCV and macro data inputs.
• backend/strategies/ for user-supplied strategy scripts.
• backend/deep_test_results/ for deep testing output.
• backend/macro_test_results/ for macro testing output.

API surface summary (high level)

• Data management endpoints for upload, validation, preview, list, delete.
• Strategy endpoints for create, list, load, and delete.
• Backtest execution endpoints (single, multi-asset, relative performance).
• Deep testing endpoints for running tests and exporting results.
• Macro testing endpoints for factor runs, results, exports, and insights.
• Volatility analysis endpoints for index testing.

Reference diagram

Data flow and processing

This section outlines the primary data flows for the platform, including backtesting, deep testing, macro testing, and volatility testing.

Flow 1: Data upload and validation

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/

  User->>UI: Select CSV file
  UI->>API: Upload dataset
  API->>FS: Store CSV file
  API-->>UI: Upload status
  UI->>API: Validate dataset
  API-->>UI: Validation result + preview

Flow 1a: Ingest data (key flow)

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/

  User->>UI: Choose dataset to ingest
  UI->>API: Upload dataset request
  API->>FS: Persist raw CSV file
  API-->>UI: Ingest success + file reference

Flow 2: Strategy backtest

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/
  participant STRAT as strategies/

  User->>UI: Choose CSV + strategy + dates
  UI->>API: Run backtest
  API->>FS: Read CSV data
  API->>STRAT: Load strategy script
  API->>API: Execute run_strategy()
  API->>API: Simulate equity + compute metrics
  API-->>UI: Trades + metrics + equity curve

Flow 2a: Compute metrics (key flow)

sequenceDiagram
  participant API as Backend Service
  participant Metrics as Metrics Engine

  API->>Metrics: Receive trades + equity curve
  Metrics->>Metrics: Compute returns, drawdown, ratios
  Metrics-->>API: Metrics summary

Flow 3: Deep testing (statistical tests)

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/
  participant STRAT as strategies/
  participant DEEP as deep_test_results/

  User->>UI: Configure deep test parameters
  UI->>API: Run deep test
  API->>FS: Load CSV data
  API->>STRAT: Load strategy script
  API->>API: Execute run_strategy()
  API->>API: Run deep testing suite
  API->>DEEP: Save results JSON
  API-->>UI: Summary + result ID

Flow 4: Macro testing

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/
  participant MACRO as macro_test_results/

  User->>UI: Select stock + macro factors
  UI->>API: Run macro test
  API->>FS: Load stock and macro CSVs
  API->>API: Build features + train model
  API->>API: Walk-forward validation
  API->>MACRO: Save results JSON
  API-->>UI: Results + insights

Flow 5: Volatility testing

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service

  User->>UI: Select index + date range
  UI->>API: Run volatility analysis
  API->>API: Run volatility analysis
  API-->>UI: Volatility results

Flow 6: Relative performance backtest

sequenceDiagram
  actor User
  participant UI as Web UI
  participant API as Backend Service
  participant FS as uploaded_csvs/
  participant STRAT as strategies/

  User->>UI: Choose stock A/B + strategy + dates
  UI->>API: Run relative performance backtest
  API->>FS: Load both CSVs
  API->>STRAT: Load strategy script
  API->>API: Build price ratio series
  API->>API: Execute run_strategy() on ratio
  API-->>UI: Trades + metrics

Data flow diagram (origins, transforms, lands)

flowchart LR
  Sources[External Market & Macro Data]
  Uploads[User Uploaded CSVs]
  Raw[Raw CSV Storage]
  Parse[Parse & Validate]
  Feature[Feature Engineering]
  Strat[Strategy Execution]
  Sim[Simulation & Metrics]
  Results[Results Storage]
  UI[Web UI Visualizations]

  Sources --> Uploads
  Uploads --> Raw
  Raw --> Parse
  Parse --> Feature
  Feature --> Strat
  Strat --> Sim
  Sim --> Results
  Results --> UI

Data persistence overview

• Inputs are stored as CSVs in backend/uploaded_csvs/.
• Strategy code is stored as Python files in backend/strategies/.
• Macro and deep testing results are stored as JSON under their respective result directories for later retrieval.

Reference diagram

Capabilities

This section summarizes the platform's capabilities based on the current backend API and frontend workflows.

Data management

• Upload CSV files for stocks, indices, and macro factors.
• Validate CSV structure (required OHLCV columns).
• Preview, list, download, and delete uploaded datasets.

Strategy management

• Save strategy scripts as Python files.
• List, load, and delete strategies.
• Execute strategies via a required run_strategy() entry point.

Backtesting

• Single-asset backtests with selectable date ranges.
• Multi-strategy backtests (up to 3 strategies per run).
• Equity curve simulation and performance metrics.
• Trades export to CSV.

Backtesting (1-to-n)

• Run a single strategy across multiple datasets in one request.
• Compare metrics across a set of symbols.
• Export consolidated trades.

Relative performance

• Ratio-based backtests between two symbols (stock A / stock B).
• Apply a strategy to the ratio series and switch holdings.

Deep testing (statistical validation)

• Run deep statistical tests over a strategy's trade set.
• Persist results for later retrieval, comparison, and export.
• Export deep-test reports as CSV.

Macro testing

• Test predictive power of macro, momentum, and volatility factors.
• Walk-forward validation and feature importance analysis.
• Save and load historical macro tests.
• Optional AI insights generation (requires API credentials).

Volatility testing

• Analyze volatility behavior for predefined indices.
• Run index-specific volatility analysis across date ranges.

Operational utilities

• Backend server manager for start/stop/status.
• Data download scripts for external data sources (optional workflow).

Tech stack

Frontend

• Web UI built with a modern JavaScript framework.
• Charting and visualization library for performance graphs.
• UI testing framework for component and interaction tests.

Backend

• Python service with an HTTP API.
• ASGI-compatible application server.
• Data processing and numerical analysis libraries.
• Machine learning and statistical modeling libraries.
• Plotting and visualization utilities for analysis output.
• HTTP client libraries for external data access.
• Environment configuration utilities.
• Process management utilities.
• Optional AI insights integration.
• Optional cloud SDK for integrations.

Data storage

• Local filesystem CSVs for inputs (backend/uploaded_csvs/).
• JSON result files for macro and deep testing.
• Strategy scripts stored as Python files (backend/strategies/).

Supporting scripts and tools

• Data download utilities for market and macro data.
• Ad-hoc research utilities for macro and volatility testing.

Runtime and deployment notes

• Local development server: React dev server and FastAPI backend.
• No database layer present in the current codebase.