# mrphillip007/polymarketbacktest architecture

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

- Interactive diagram: https://gitdiagram.com/mrphillip007/polymarketbacktest
- Repository: https://github.com/mrphillip007/polymarketbacktest

## Overview

This repository is a research and backtesting pipeline for Polymarket crypto Up/Down markets, not a live trading system. Its main workflow gathers market metadata, archived Polymarket data and Binance candles; builds per-second panels and fair-probability inputs; then evaluates trading rules and reports results. Separate branches investigate favorite-entry strategies, 5-minute markets, TWAP modeling, liquidity, incidents and forward testing. The README documents the broad run order; source excerpts are partial, so some data handoffs are documented rather than verified in implementation.

Main entry points: [`alib.py`](https://github.com/mrphillip007/polymarketbacktest/blob/main/alib.py) (Shared utilities), [`pull.py`](https://github.com/mrphillip007/polymarketbacktest/blob/main/pull.py) (Market downloads), [`favlib.py`](https://github.com/mrphillip007/polymarketbacktest/blob/main/favlib.py) (Favorite features), [`forward.py`](https://github.com/mrphillip007/polymarketbacktest/blob/main/forward.py) (Forward test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Market data"]
  node_market_pull["Market downloads<br/>[pull.py]"]
  node_range_reader["Parquet ranges<br/>[rng.py]"]
  node_five_min_pull["5m downloads<br/>[pull5m.py]"]
  node_candle_download["1s candles<br/>[binance1s.py]"]
end

subgraph group_features["Panels and models"]
  node_panel_builder["Panel builder<br/>[panel.py]"]
  node_common_library["Shared utilities<br/>[alib.py]"]
  node_twap_model["TWAP v2 model<br/>[twap2.py]"]
end

subgraph group_strategies["Strategy research"]
  node_descriptive["Market description<br/>[a_desc.py]"]
  node_model_checks["Model checks<br/>[a_proxy.py]"]
  node_calibration["Entry calibration<br/>[a_calib.py]"]
  node_market_strategy["Fair-value strategy<br/>[a_strat.py]"]
  node_incident_analysis["Incident analysis<br/>[a_incidents.py]"]
  node_favorite_features["Favorite features<br/>[favlib.py]"]
  node_favorite_research["Favorite experiments<br/>[a_fav5m.py]"]
  node_trigger_strategy["Trigger entries<br/>[a_trigger.py]"]
  node_five_min_strategy["5m comparison<br/>[a_5m.py]"]
  node_flow_analysis["Trade-flow analysis<br/>[a_flow.py]"]
  node_day_stop["Daily stop rules<br/>[a_daystop.py]"]
  node_liquidity_sim["Liquidity simulation<br/>[a_liquidity.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_forward_test["Forward test<br/>[forward.py]"]
  node_parameter_study["Parameter studies<br/>[param_study.py]"]
  node_factor_study["Favorite factors<br/>[fav_factors.py]"]
  node_robustness["Robustness checks<br/>[robust_1usd.py]"]
end

node_researcher(("Researcher"))
node_gamma{{"Gamma API"}}
node_archive{{"Pendulum archive"}}
node_binance{{"Binance data"}}

node_researcher -->|"runs downloads"| node_market_pull
node_researcher -->|"runs downloads"| node_candle_download
node_researcher -->|"builds panels"| node_panel_builder
node_researcher -->|"runs analyses"| node_descriptive
node_researcher -->|"runs test"| node_forward_test
node_market_pull -->|"fetches metadata"| node_gamma
node_market_pull -->|"reads hourly data"| node_archive
node_market_pull -->|"uses reader"| node_range_reader
node_five_min_pull -->|"reuses downloader"| node_market_pull
node_candle_download -->|"downloads candles"| node_binance
node_panel_builder -.->|"uses market data"| node_market_pull
node_panel_builder -.->|"uses candles"| node_candle_download
node_panel_builder -.->|"uses utilities"| node_common_library
node_twap_model -->|"uses utilities"| node_common_library
node_twap_model -->|"uses features"| node_favorite_features
node_descriptive -->|"uses utilities"| node_common_library
node_model_checks -->|"uses utilities"| node_common_library
node_calibration -->|"uses utilities"| node_common_library
node_market_strategy -->|"uses utilities"| node_common_library
node_incident_analysis -->|"runs strategy"| node_market_strategy
node_incident_analysis -->|"uses utilities"| node_common_library
node_favorite_features -->|"uses utilities"| node_common_library
node_favorite_research -->|"uses utilities"| node_common_library
node_favorite_research -->|"filters incidents"| node_incident_analysis
node_trigger_strategy -->|"uses features"| node_favorite_features
node_five_min_strategy -->|"uses features"| node_favorite_features
node_five_min_strategy -->|"applies stops"| node_day_stop
node_flow_analysis -->|"uses features"| node_favorite_features
node_day_stop -->|"uses features"| node_favorite_features
node_liquidity_sim -->|"reads archive ranges"| node_range_reader
node_liquidity_sim -->|"uses archive paths"| node_market_pull
node_forward_test -->|"updates metadata"| node_market_pull
node_forward_test -->|"updates candles"| node_candle_download
node_forward_test -->|"rebuilds panels"| node_panel_builder
node_forward_test -->|"evaluates rules"| node_favorite_features
node_forward_test -->|"applies stops"| node_day_stop
node_parameter_study -->|"uses utilities"| node_common_library
node_factor_study -->|"uses utilities"| node_common_library
node_robustness -->|"uses utilities"| node_common_library

click node_market_pull "https://github.com/mrphillip007/polymarketbacktest/blob/main/pull.py"
click node_range_reader "https://github.com/mrphillip007/polymarketbacktest/blob/main/rng.py"
click node_five_min_pull "https://github.com/mrphillip007/polymarketbacktest/blob/main/pull5m.py"
click node_candle_download "https://github.com/mrphillip007/polymarketbacktest/blob/main/binance1s.py"
click node_panel_builder "https://github.com/mrphillip007/polymarketbacktest/blob/main/panel.py"
click node_common_library "https://github.com/mrphillip007/polymarketbacktest/blob/main/alib.py"
click node_twap_model "https://github.com/mrphillip007/polymarketbacktest/blob/main/twap2.py"
click node_descriptive "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_desc.py"
click node_model_checks "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_proxy.py"
click node_calibration "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_calib.py"
click node_market_strategy "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_strat.py"
click node_incident_analysis "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_incidents.py"
click node_favorite_features "https://github.com/mrphillip007/polymarketbacktest/blob/main/favlib.py"
click node_favorite_research "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_fav5m.py"
click node_trigger_strategy "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_trigger.py"
click node_five_min_strategy "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_5m.py"
click node_flow_analysis "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_flow.py"
click node_day_stop "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_daystop.py"
click node_liquidity_sim "https://github.com/mrphillip007/polymarketbacktest/blob/main/a_liquidity.py"
click node_forward_test "https://github.com/mrphillip007/polymarketbacktest/blob/main/forward.py"
click node_parameter_study "https://github.com/mrphillip007/polymarketbacktest/blob/main/param_study.py"
click node_factor_study "https://github.com/mrphillip007/polymarketbacktest/blob/main/fav_factors.py"
click node_robustness "https://github.com/mrphillip007/polymarketbacktest/blob/main/robust_1usd.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_market_pull,node_range_reader,node_five_min_pull,node_candle_download toneBlue
class node_panel_builder,node_common_library,node_twap_model toneAmber
class node_descriptive,node_model_checks,node_calibration,node_market_strategy,node_incident_analysis,node_favorite_features,node_favorite_research,node_trigger_strategy,node_five_min_strategy,node_flow_analysis,node_day_stop,node_liquidity_sim,node_gamma toneMint
class node_forward_test,node_parameter_study,node_factor_study,node_robustness toneRose
class node_researcher,node_archive,node_binance toneIndigo
```

## Components

### Market data

- [Market downloads](https://github.com/mrphillip007/polymarketbacktest/blob/main/pull.py): `pull.py`
- [Parquet ranges](https://github.com/mrphillip007/polymarketbacktest/blob/main/rng.py): `rng.py`
- [5m downloads](https://github.com/mrphillip007/polymarketbacktest/blob/main/pull5m.py): `pull5m.py`
- [1s candles](https://github.com/mrphillip007/polymarketbacktest/blob/main/binance1s.py): `binance1s.py`

### Panels and models

- [Panel builder](https://github.com/mrphillip007/polymarketbacktest/blob/main/panel.py): `panel.py`
- [Shared utilities](https://github.com/mrphillip007/polymarketbacktest/blob/main/alib.py): `alib.py`
- [TWAP v2 model](https://github.com/mrphillip007/polymarketbacktest/blob/main/twap2.py): `twap2.py`

### Strategy research

- [Market description](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_desc.py): `a_desc.py`
- [Model checks](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_proxy.py): `a_proxy.py`
- [Entry calibration](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_calib.py): `a_calib.py`
- [Fair-value strategy](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_strat.py): `a_strat.py`
- [Incident analysis](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_incidents.py): `a_incidents.py`
- [Favorite features](https://github.com/mrphillip007/polymarketbacktest/blob/main/favlib.py): `favlib.py`
- [Favorite experiments](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_fav5m.py): `a_fav5m.py`
- [Trigger entries](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_trigger.py): `a_trigger.py`
- [5m comparison](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_5m.py): `a_5m.py`
- [Trade-flow analysis](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_flow.py): `a_flow.py`
- [Daily stop rules](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_daystop.py): `a_daystop.py`
- [Liquidity simulation](https://github.com/mrphillip007/polymarketbacktest/blob/main/a_liquidity.py): `a_liquidity.py`

### Evaluation

- [Forward test](https://github.com/mrphillip007/polymarketbacktest/blob/main/forward.py): `forward.py`
- [Parameter studies](https://github.com/mrphillip007/polymarketbacktest/blob/main/param_study.py): `param_study.py`
- [Favorite factors](https://github.com/mrphillip007/polymarketbacktest/blob/main/fav_factors.py): `fav_factors.py`
- [Robustness checks](https://github.com/mrphillip007/polymarketbacktest/blob/main/robust_1usd.py): `robust_1usd.py`

### Other components

- **Researcher**
- **Gamma API**
- **Pendulum archive**
- **Binance data**

## Connections

- Researcher → Market downloads: runs downloads (evidence: `README.md`)
- Researcher → 1s candles: runs downloads (evidence: `README.md`)
- Researcher → Panel builder: builds panels (evidence: `README.md`)
- Researcher → Market description: runs analyses (evidence: `README.md`)
- Researcher → Forward test: runs test (evidence: `README.md`)
- Market downloads → Gamma API: fetches metadata (evidence: `pull.py`)
- Market downloads → Pendulum archive: reads hourly data (evidence: `README.md`)
- Market downloads → Parquet ranges: uses reader (evidence: `pull.py`)
- 5m downloads → Market downloads: reuses downloader (evidence: `pull5m.py`)
- 1s candles → Binance data: downloads candles (evidence: `README.md`)
- Panel builder → Market downloads: uses market data
- Panel builder → 1s candles: uses candles
- Panel builder → Shared utilities: uses utilities
- TWAP v2 model → Shared utilities: uses utilities (evidence: `twap2.py`)
- TWAP v2 model → Favorite features: uses features (evidence: `twap2.py`)
- Market description → Shared utilities: uses utilities (evidence: `a_desc.py`)
- Model checks → Shared utilities: uses utilities (evidence: `a_proxy.py`)
- Entry calibration → Shared utilities: uses utilities (evidence: `a_calib.py`)
- Fair-value strategy → Shared utilities: uses utilities (evidence: `a_strat.py`)
- Incident analysis → Fair-value strategy: runs strategy (evidence: `a_incidents.py`)
- Incident analysis → Shared utilities: uses utilities (evidence: `a_incidents.py`)
- Favorite features → Shared utilities: uses utilities (evidence: `favlib.py`)
- Favorite experiments → Shared utilities: uses utilities (evidence: `a_fav5m.py`)
- Favorite experiments → Incident analysis: filters incidents (evidence: `a_fav5m.py`)
- Trigger entries → Favorite features: uses features (evidence: `a_trigger.py`)
- 5m comparison → Favorite features: uses features (evidence: `a_5m.py`)
- 5m comparison → Daily stop rules: applies stops (evidence: `a_5m.py`)
- Trade-flow analysis → Favorite features: uses features (evidence: `a_flow.py`)
- Daily stop rules → Favorite features: uses features (evidence: `a_daystop.py`)
- Liquidity simulation → Parquet ranges: reads archive ranges (evidence: `a_liquidity.py`)
- Liquidity simulation → Market downloads: uses archive paths (evidence: `a_liquidity.py`)
- Forward test → Market downloads: updates metadata (evidence: `forward.py`)
- Forward test → 1s candles: updates candles (evidence: `forward.py`)
- Forward test → Panel builder: rebuilds panels (evidence: `forward.py`)
- Forward test → Favorite features: evaluates rules (evidence: `forward.py`)
- Forward test → Daily stop rules: applies stops (evidence: `forward.py`)
- Parameter studies → Shared utilities: uses utilities (evidence: `param_study.py`)
- Favorite factors → Shared utilities: uses utilities (evidence: `fav_factors.py`)
- Robustness checks → Shared utilities: uses utilities (evidence: `robust_1usd.py`)
