# rynn-arriola/polymarket-bot architecture

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

- Interactive diagram: https://gitdiagram.com/rynn-arriola/polymarket-bot
- Repository: https://github.com/rynn-arriola/polymarket-bot

## Overview

This repository implements a sports-and-esports prediction and Polymarket trading bot. Its main workflow builds cached Elo ratings, evaluates market opportunities against model probabilities, applies risk and roster safeguards, and tracks positions for reporting and manual-trade reconciliation. Supporting branches provide historical backtesting/tuning and optional XGBoost predictions. The README is empty; relationships below rely on the source index and sampled source, so unsampled integrations and call paths are not inferred.

Main entry points: [`divergence_bot.py`](https://github.com/rynn-arriola/polymarket-bot/blob/main/divergence_bot.py) (Market bot), [`build_ratings.py`](https://github.com/rynn-arriola/polymarket-bot/blob/main/build_ratings.py) (Rating builder), [`manual_sync.py`](https://github.com/rynn-arriola/polymarket-bot/blob/main/manual_sync.py) (Manual trade sync), [`elo/params.py`](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/params.py) (Model parameters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["Ratings and models"]
  node_ratings_build["Rating builder<br/>[build_ratings.py]"]
  node_elo_engine["Elo engine<br/>[engine.py]"]
  node_elo_history["History cache<br/>[history.py]"]
  node_elo_params["Model parameters<br/>[params.py]"]
  node_basketball["Basketball Elo<br/>[basketball.py]"]
  node_esports["Esports Elo<br/>[esports.py]"]
  node_esports_players["Esports player Elo<br/>[esports_players.py]"]
  node_lol_players["LoL player Elo<br/>[lol_players.py]"]
  node_mlb["MLB Elo<br/>[mlb.py]"]
  node_soccer["Soccer Elo<br/>[soccer.py]"]
  node_tennis["Tennis Elo<br/>[tennis.py]"]
  node_injuries["Injury adjustments<br/>[injuries.py]"]
  node_rosters["Roster tracking<br/>[rosters.py]"]
  node_xgb["Live XGBoost<br/>[xgb_live.py]"]
  node_fetch_update["Data refresh<br/>[refresh_data.py]"]
  node_fetch_esports["Player data fetch"]
end

subgraph group_trading["Trading and safeguards"]
  node_bot["Market bot<br/>[divergence_bot.py]"]
  node_config["Strategy config<br/>[config.py]"]
  node_guard["API guard<br/>[api_guard.py]"]
  node_risk["Risk checks<br/>[risk.py]"]
  node_name_match["Name matching<br/>[name_match.py]"]
end

subgraph group_operations["Position operations"]
  node_db[("Position database<br/>[db.py]")]
  node_manual["Manual trade sync<br/>[manual_sync.py]"]
  node_reporting["Reports<br/>[reporting.py]"]
  node_audit["Audit reporting<br/>[audit_reporting.py]"]
end

subgraph group_research["Model research"]
  node_tune["Parameter tuning<br/>[tune.py]"]
  node_backtest["Backtesting<br/>[backtest.py]"]
  node_train["XGBoost training<br/>[train_xgb.py]"]
  node_features["XGBoost features<br/>[xgb_features.py]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_bot
node_bot -->|"reads settings"| node_config
node_bot -->|"checks API cooldown"| node_guard
node_bot -->|"checks exposure"| node_risk
node_bot -->|"matches names"| node_name_match
node_bot -->|"reads and writes"| node_db
node_bot -->|"reconciles trades"| node_manual
node_bot -->|"gets probabilities"| node_basketball
node_bot -->|"gets probabilities"| node_esports
node_bot -->|"gets probabilities"| node_mlb
node_bot -->|"gets probabilities"| node_soccer
node_bot -->|"gets probabilities"| node_tennis
node_bot -->|"applies adjustments"| node_injuries
node_bot -->|"checks roster changes"| node_rosters
node_bot -->|"gets predictions"| node_xgb
node_ratings_build -->|"builds ratings"| node_basketball
node_ratings_build -->|"builds ratings"| node_esports
node_ratings_build -->|"builds ratings"| node_esports_players
node_ratings_build -->|"builds ratings"| node_lol_players
node_ratings_build -->|"builds ratings"| node_mlb
node_ratings_build -->|"builds ratings"| node_soccer
node_ratings_build -->|"builds ratings"| node_tennis
node_ratings_build -->|"reads parameters"| node_elo_params
node_basketball -->|"fetches history"| node_elo_history
node_basketball -->|"uses engine"| node_elo_engine
node_basketball -->|"reads parameters"| node_elo_params
node_esports -->|"fetches history"| node_elo_history
node_esports -->|"uses engine"| node_elo_engine
node_esports -->|"reads parameters"| node_elo_params
node_mlb -->|"fetches history"| node_elo_history
node_mlb -->|"uses engine"| node_elo_engine
node_mlb -->|"reads parameters"| node_elo_params
node_soccer -->|"fetches history"| node_elo_history
node_soccer -->|"uses engine"| node_elo_engine
node_soccer -->|"reads parameters"| node_elo_params
node_tennis -->|"fetches history"| node_elo_history
node_tennis -->|"uses engine"| node_elo_engine
node_tennis -->|"reads parameters"| node_elo_params
node_manual -->|"stores trades"| node_db
node_manual -->|"governs API calls"| node_guard
node_manual -->|"reads settings"| node_config
node_manual -->|"uses reports"| node_reporting
node_reporting -->|"queries positions"| node_db
node_reporting -->|"reads settings"| node_config
node_audit -->|"audits reconciliation"| node_manual
node_audit -->|"reads settings"| node_config
node_audit -->|"uses API guard"| node_guard
node_fetch_update -->|"fetches player data"| node_fetch_esports

click node_bot "https://github.com/rynn-arriola/polymarket-bot/blob/main/divergence_bot.py"
click node_config "https://github.com/rynn-arriola/polymarket-bot/blob/main/config.py"
click node_guard "https://github.com/rynn-arriola/polymarket-bot/blob/main/api_guard.py"
click node_risk "https://github.com/rynn-arriola/polymarket-bot/blob/main/risk.py"
click node_name_match "https://github.com/rynn-arriola/polymarket-bot/blob/main/name_match.py"
click node_ratings_build "https://github.com/rynn-arriola/polymarket-bot/blob/main/build_ratings.py"
click node_elo_engine "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/engine.py"
click node_elo_history "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/history.py"
click node_elo_params "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/params.py"
click node_basketball "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/basketball.py"
click node_esports "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/esports.py"
click node_esports_players "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/esports_players.py"
click node_lol_players "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/lol_players.py"
click node_mlb "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/mlb.py"
click node_soccer "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/soccer.py"
click node_tennis "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/tennis.py"
click node_injuries "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/injuries.py"
click node_rosters "https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/rosters.py"
click node_xgb "https://github.com/rynn-arriola/polymarket-bot/blob/main/xgb_live.py"
click node_db "https://github.com/rynn-arriola/polymarket-bot/blob/main/db.py"
click node_manual "https://github.com/rynn-arriola/polymarket-bot/blob/main/manual_sync.py"
click node_reporting "https://github.com/rynn-arriola/polymarket-bot/blob/main/reporting.py"
click node_audit "https://github.com/rynn-arriola/polymarket-bot/blob/main/audit_reporting.py"
click node_fetch_update "https://github.com/rynn-arriola/polymarket-bot/blob/main/refresh_data.py"
click node_fetch_esports "https://github.com/rynn-arriola/polymarket-bot/blob/main/fetch_esports_players.py"
click node_tune "https://github.com/rynn-arriola/polymarket-bot/blob/main/tune.py"
click node_backtest "https://github.com/rynn-arriola/polymarket-bot/blob/main/backtest.py"
click node_train "https://github.com/rynn-arriola/polymarket-bot/blob/main/train_xgb.py"
click node_features "https://github.com/rynn-arriola/polymarket-bot/blob/main/xgb_features.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_ratings_build,node_elo_engine,node_elo_history,node_elo_params,node_basketball,node_esports,node_esports_players,node_lol_players,node_mlb,node_soccer,node_tennis,node_injuries,node_rosters,node_xgb,node_fetch_update,node_fetch_esports toneBlue
class node_bot,node_config,node_guard,node_risk,node_name_match toneAmber
class node_db,node_manual,node_reporting,node_audit toneMint
class node_tune,node_backtest,node_train,node_features toneRose
class node_operator toneIndigo
```

## Components

### Ratings and models

- [Rating builder](https://github.com/rynn-arriola/polymarket-bot/blob/main/build_ratings.py): `build_ratings.py`
- [Elo engine](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/engine.py): `elo/engine.py`
- [History cache](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/history.py): `elo/history.py`
- [Model parameters](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/params.py): `elo/params.py`
- [Basketball Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/basketball.py): `elo/basketball.py`
- [Esports Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/esports.py): `elo/esports.py`
- [Esports player Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/esports_players.py): `elo/esports_players.py`
- [LoL player Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/lol_players.py): `elo/lol_players.py`
- [MLB Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/mlb.py): `elo/mlb.py`
- [Soccer Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/soccer.py): `elo/soccer.py`
- [Tennis Elo](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/tennis.py): `elo/tennis.py`
- [Injury adjustments](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/injuries.py): `elo/injuries.py`
- [Roster tracking](https://github.com/rynn-arriola/polymarket-bot/blob/main/elo/rosters.py): `elo/rosters.py`
- [Live XGBoost](https://github.com/rynn-arriola/polymarket-bot/blob/main/xgb_live.py): `xgb_live.py`
- [Data refresh](https://github.com/rynn-arriola/polymarket-bot/blob/main/refresh_data.py): `refresh_data.py`
- [Player data fetch](https://github.com/rynn-arriola/polymarket-bot/blob/main/fetch_esports_players.py): `fetch_esports_players.py`

### Trading and safeguards

- [Market bot](https://github.com/rynn-arriola/polymarket-bot/blob/main/divergence_bot.py): `divergence_bot.py`
- [Strategy config](https://github.com/rynn-arriola/polymarket-bot/blob/main/config.py): `config.py`
- [API guard](https://github.com/rynn-arriola/polymarket-bot/blob/main/api_guard.py): `api_guard.py`
- [Risk checks](https://github.com/rynn-arriola/polymarket-bot/blob/main/risk.py): `risk.py`
- [Name matching](https://github.com/rynn-arriola/polymarket-bot/blob/main/name_match.py): `name_match.py`

### Position operations

- [Position database](https://github.com/rynn-arriola/polymarket-bot/blob/main/db.py): `db.py`
- [Manual trade sync](https://github.com/rynn-arriola/polymarket-bot/blob/main/manual_sync.py): `manual_sync.py`
- [Reports](https://github.com/rynn-arriola/polymarket-bot/blob/main/reporting.py): `reporting.py`
- [Audit reporting](https://github.com/rynn-arriola/polymarket-bot/blob/main/audit_reporting.py): `audit_reporting.py`

### Model research

- [Parameter tuning](https://github.com/rynn-arriola/polymarket-bot/blob/main/tune.py): `tune.py`
- [Backtesting](https://github.com/rynn-arriola/polymarket-bot/blob/main/backtest.py): `backtest.py`
- [XGBoost training](https://github.com/rynn-arriola/polymarket-bot/blob/main/train_xgb.py): `train_xgb.py`
- [XGBoost features](https://github.com/rynn-arriola/polymarket-bot/blob/main/xgb_features.py): `xgb_features.py`

### Other components

- **Operator**

## Connections

- Operator → Market bot: runs
- Market bot → Strategy config: reads settings (evidence: `divergence_bot.py`)
- Market bot → API guard: checks API cooldown (evidence: `divergence_bot.py`)
- Market bot → Risk checks: checks exposure (evidence: `divergence_bot.py`)
- Market bot → Name matching: matches names (evidence: `divergence_bot.py`)
- Market bot → Position database: reads and writes (evidence: `divergence_bot.py`)
- Market bot → Manual trade sync: reconciles trades (evidence: `divergence_bot.py`)
- Market bot → Basketball Elo: gets probabilities (evidence: `divergence_bot.py`)
- Market bot → Esports Elo: gets probabilities (evidence: `divergence_bot.py`)
- Market bot → MLB Elo: gets probabilities (evidence: `divergence_bot.py`)
- Market bot → Soccer Elo: gets probabilities (evidence: `divergence_bot.py`)
- Market bot → Tennis Elo: gets probabilities (evidence: `divergence_bot.py`)
- Market bot → Injury adjustments: applies adjustments (evidence: `divergence_bot.py`)
- Market bot → Roster tracking: checks roster changes (evidence: `divergence_bot.py`)
- Market bot → Live XGBoost: gets predictions (evidence: `divergence_bot.py`)
- Rating builder → Basketball Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → Esports Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → Esports player Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → LoL player Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → MLB Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → Soccer Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → Tennis Elo: builds ratings (evidence: `build_ratings.py`)
- Rating builder → Model parameters: reads parameters (evidence: `build_ratings.py`)
- Basketball Elo → History cache: fetches history (evidence: `elo/basketball.py`)
- Basketball Elo → Elo engine: uses engine (evidence: `elo/basketball.py`)
- Basketball Elo → Model parameters: reads parameters (evidence: `elo/basketball.py`)
- Esports Elo → History cache: fetches history (evidence: `elo/esports.py`)
- Esports Elo → Elo engine: uses engine (evidence: `elo/esports.py`)
- Esports Elo → Model parameters: reads parameters (evidence: `elo/esports.py`)
- MLB Elo → History cache: fetches history (evidence: `elo/mlb.py`)
- MLB Elo → Elo engine: uses engine (evidence: `elo/mlb.py`)
- MLB Elo → Model parameters: reads parameters (evidence: `elo/mlb.py`)
- Soccer Elo → History cache: fetches history (evidence: `elo/soccer.py`)
- Soccer Elo → Elo engine: uses engine (evidence: `elo/soccer.py`)
- Soccer Elo → Model parameters: reads parameters (evidence: `elo/soccer.py`)
- Tennis Elo → History cache: fetches history (evidence: `elo/tennis.py`)
- Tennis Elo → Elo engine: uses engine (evidence: `elo/tennis.py`)
- Tennis Elo → Model parameters: reads parameters (evidence: `elo/tennis.py`)
- Manual trade sync → Position database: stores trades (evidence: `manual_sync.py`)
- Manual trade sync → API guard: governs API calls (evidence: `manual_sync.py`)
- Manual trade sync → Strategy config: reads settings (evidence: `manual_sync.py`)
- Manual trade sync → Reports: uses reports (evidence: `manual_sync.py`)
- Reports → Position database: queries positions (evidence: `reporting.py`)
- Reports → Strategy config: reads settings (evidence: `reporting.py`)
- Audit reporting → Manual trade sync: audits reconciliation (evidence: `audit_reporting.py`)
- Audit reporting → Strategy config: reads settings (evidence: `audit_reporting.py`)
- Audit reporting → API guard: uses API guard (evidence: `audit_reporting.py`)
- Data refresh → Player data fetch: fetches player data (evidence: `refresh_data.py`)
