# parthuu/quant_sandbox architecture

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

- Interactive diagram: https://gitdiagram.com/parthuu/quant_sandbox
- Repository: https://github.com/parthuu/quant_sandbox

## Overview

##### Project type and purpose
- This is a sandbox backtesting tool for financial trading strategies, _not_ a full-fledged technical analysis suite.
- It provides modular components for loading data, running strategies over historical data, tracking trades, computing metrics, and visualizing results.

##### File structure
- Top level:
- main.py (orchestrator/CLI entry point)
- requirements.txt (dependency list)
- experiments/ (Jupyter notebooks for ad-hoc analysis & visuals)
- src/ (core Python modules)
- src/ modules:
- data_loader.py – fetches and preprocesses market data
- strategy.py – defines the interface and default implementations of trading strategies
- backtester.py – drives the simulation loop, calling strategy methods at each time step
- tracker.py – records orders/trades/events generated by backtester
- metrics.py – computes performance statistics (returns, drawdowns, Sharpe, etc.)
- visualizer.py – generates charts and plots from tracked data and metrics

##### README for additional context
- Emphasizes sandbox status, TODOs around modular indicators, caching, shorting.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        main["main.py"]:::entry
        Requirements["requirements.txt"]:::entry
        README["README.md"]:::entry
    end

    %% External Data Source
    DataSource["External Data Source\n(CSV/API)"]:::external

    %% Data Layer
    subgraph "Data Layer"
        DataLoader["Data Loader\n(src/data_loader.py)"]:::data
        Cache["Optional Cache"]:::data
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        Backtester["Backtester Engine\n(src/backtester.py)"]:::core
        Strategy["Strategy Plugin Interface\n(src/strategy.py)"]:::core
        Tracker["Trade Tracker\n(src/tracker.py)"]:::core
    end

    %% Post-Processing Layer
    subgraph "Post-Processing"
        Metrics["Metrics Engine\n(src/metrics.py)"]:::post
        Visualizer["Visualization Layer\n(src/visualizer.py)"]:::post
    end

    %% Experiments
    subgraph "Experiments"
        Experiments["Jupyter Notebooks\n(experiments/)"]:::entry
    end

    %% Connections
    DataSource -->|"raw_data"| DataLoader
    DataLoader -->|"price_data"| Backtester
    DataLoader -->|cache lookup| Cache
    Cache -->|cached_data| Backtester

    Backtester -->|"on_data() call"| Strategy
    Strategy -->|"generate_signals()"| Backtester

    Backtester -->|"trade_events"| Tracker
    Tracker -->|"events"| Metrics

    Backtester -->|"simulation_data"| Visualizer
    Metrics -->|"metrics_data"| Visualizer

    main --> DataLoader
    main --> Strategy
    main --> Backtester
    main --> Tracker
    main --> Metrics
    main --> Visualizer

    Experiments --> DataLoader
    Experiments --> Visualizer
    Experiments --> Metrics

    %% Click Events
    click main "https://github.com/parthuu/quant_sandbox/blob/main/main.py"
    click DataLoader "https://github.com/parthuu/quant_sandbox/blob/main/src/data_loader.py"
    click Backtester "https://github.com/parthuu/quant_sandbox/blob/main/src/backtester.py"
    click Strategy "https://github.com/parthuu/quant_sandbox/blob/main/src/strategy.py"
    click Tracker "https://github.com/parthuu/quant_sandbox/blob/main/src/tracker.py"
    click Metrics "https://github.com/parthuu/quant_sandbox/blob/main/src/metrics.py"
    click Visualizer "https://github.com/parthuu/quant_sandbox/blob/main/src/visualizer.py"
    click Experiments "https://github.com/parthuu/quant_sandbox/tree/main/experiments/"
    click Requirements "https://github.com/parthuu/quant_sandbox/blob/main/requirements.txt"
    click README "https://github.com/parthuu/quant_sandbox/blob/main/README.md"

    %% Styles
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef post fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef entry fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
