# pmorissette/bt architecture

> Architecture diagram of the GitHub repository pmorissette/bt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmorissette/bt
- Repository: https://github.com/pmorissette/bt

## Overview

##### Project Type and Purpose
- bt is a Python library/framework for flexible backtesting of quantitative trading strategies.
- It is not a full‐stack web app but a modular, reusable codebase that lets users define, run, and analyze backtests using Algos, AlgoStacks, and Node trees.

##### File Structure Analysis
Top-level directories and files:
- bt/                    ← core package
– core.py              ← Strategy, Node, AlgoStack definitions
– algos.py             ← prebuilt algorithm components
– backtest.py          ← Backtest runner and Result objects
– __init__.py          ← package exports
- tests/                 ← unit and regression tests
- examples/              ← runnable examples (.py, .ipynb)
- docs/                  ← Sphinx documentation, themes, notebooks
- CI config (.github/)   ← build, deploy, regression workflows
- setup.py, pyproject.toml, Makefile ← build & development setup

##### Key Architectural Concepts from README
– Tree Structure: hierarchies of Nodes, each with its own price index
– Algorithm Stacks: modular Algo components that can be composed
– Backtest Engine: orchestrates data, executes Algos, builds Results
– Charting/Reporting: post-run visualization functions

##### Main Components
A. User Layer
- User Code / Example Notebooks
- Strategy Definitions (Algo stacks, Node trees)
B. bt API Layer
- bt.core
– Node & Tree
– Algo & AlgoStack
- bt.algos (prebuilt logic blocks)
- bt.backtest.Backtest & Result
C. Data Layer
- Data Ingestion (pandas, ffn)
- Price Indices per Node
D. Execution Engine
- Backtest runner: iterates over time, invokes Algos on Nodes
E. Output Layer
- Results object: statistics, metrics
- Charting module: plotting functions
F. External Dependencies
- numpy, pandas, ffn
- Matplotlib or other plotting libs
G. Supporting Infrastructure
- Tests (pytest)
- Documentation (Sphinx)
- CI/CD (.github workflows)

##### Relationships and Data Flows
- From bt API to Data Layer (request price data).
- From Data Layer into Execution Engine (feed time‐series data to Algos).
- Execution Engine updates Node states and produces Results.
- Results flow into Charting/Reporting modules for visualization back to User.
- Tests verify each module; CI automates build, test, deploy.

##### Architectural Patterns and Principles
– Modular composition: Algos and AlgoStacks as pluggable strategy blocks
– Tree/hierarchical processing: each Node processes its AlgoStack
– Layered design: clear separation between API, engine, data, and output

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Layer"
        U1["Example Notebooks & Scripts"]:::docs
        U2["User Strategy Definitions"]:::user
    end

    subgraph "API Layer"
        A1["bt/core.py<br/>Node & AlgoStack"]:::core
        A2["bt/algos.py<br/>Prebuilt Algos"]:::core
        A3["bt/backtest.py<br/>Backtest & Result"]:::core
        A4["bt/__init__.py<br/>Package Exports"]:::core
    end

    subgraph "Data Layer"
        D1["pyproject.toml / setup.py<br/>External Dependencies"]:::data
        D2(("Price Indices<br/>(pandas, ffn)")):::data
    end

    subgraph "Execution Engine"
        E1["Backtest Runner<br/>Backtest.run()"]:::engine
    end

    subgraph "Output Layer"
        O1["Result Object<br/>Statistics & Metrics"]:::output
        O2["Charting & Reporting"]:::output
    end

    subgraph "Support Infrastructure"
        S1["tests/"]:::infra
        S2[".github/workflows/"]:::infra
        S3["Makefile, setup.py,<br/>pyproject.toml, MANIFEST.in"]:::infra
        S4["docs/source/"]:::docs
    end

    U1 -->|"defines Strategy"| A2
    U1 -->|uses| A1
    U2 -->|builds AlgoStack| A1
    A2 -->|plug into| A1
    A1 -->|"Backtest.run()"| E1
    E1 -->|requests data| D2
    D1 -->|provides libs| D2
    E1 -->|instantiates| O1
    O1 -->|provides data| O2
    O2 -->|visualizes results| U1
    S1 -->|tests| A1
    S1 -->|tests| A2
    S1 -->|tests| A3
    S2 -->|CI/CD| S1
    S4 -->|docs| U1

    classDef core fill:#D0E6FF,stroke:#0B69A3,color:#084B8A,stroke-width:1px;
    classDef data fill:#DFFFE0,stroke:#3C7C17,color:#2F5D05,stroke-width:1px;
    classDef engine fill:#FFEFD5,stroke:#E18E00,color:#A66000,stroke-width:1px;
    classDef output fill:#FFE4E1,stroke:#E06666,color:#A80000,stroke-width:1px;
    classDef docs fill:#F5F5F5,stroke:#CCCCCC,color:#666666,stroke-width:1px;
    classDef user fill:#FFF5E1,stroke:#E8B800,color:#C79100,stroke-width:1px;
    classDef infra fill:#F0F0FF,stroke:#8A8AE3,color:#4A4AA8,stroke-width:1px;

    click U1 "https://github.com/pmorissette/bt/tree/master/examples/"
    click U2 "https://github.com/pmorissette/bt/tree/master/examples/"
    click A1 "https://github.com/pmorissette/bt/blob/master/bt/core.py"
    click A2 "https://github.com/pmorissette/bt/blob/master/bt/algos.py"
    click A3 "https://github.com/pmorissette/bt/blob/master/bt/backtest.py"
    click A4 "https://github.com/pmorissette/bt/blob/master/bt/__init__.py"
    click D1 "https://github.com/pmorissette/bt/blob/master/pyproject.toml"
    click D1 "https://github.com/pmorissette/bt/blob/master/setup.py"
    click S1 "https://github.com/pmorissette/bt/tree/master/tests/"
    click S2 "https://github.com/pmorissette/bt/tree/master/.github/workflows/"
    click S3 "https://github.com/pmorissette/bt/tree/master/Makefile"
    click S3 "https://github.com/pmorissette/bt/blob/master/setup.py"
    click S3 "https://github.com/pmorissette/bt/blob/master/pyproject.toml"
    click S3 "https://github.com/pmorissette/bt/blob/master/MANIFEST.in"
    click S4 "https://github.com/pmorissette/bt/tree/master/docs/source/"
```
