# noah-sokol/kalshi-mlb-predictions architecture

> Architecture diagram of the GitHub repository noah-sokol/kalshi-mlb-predictions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noah-sokol/kalshi-mlb-predictions
- Repository: https://github.com/noah-sokol/kalshi-mlb-predictions

## Overview

This is an MLB prediction-market system: daily runs turn game and market data into calibrated win probabilities, qualify positive edges, size suggested wagers, and track results. The graph retains the separate historical training/backtest and live recommendation workflows, plus explanations and reporting. README documentation supplies several workflow links where source excerpts were not provided; these are shown at the documented subsystem level. The sampled source confirms feature construction, edge filtering and Kelly sizing, and bet-log behavior.

Main entry points: [`update.py`](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/update.py) (Daily runner), [`pipeline.py`](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/pipeline.py) (Model training), [`src/tracking/bet_tracker.py`](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/tracking/bet_tracker.py) (Bet tracking), [`src/edge/edge_detector.py`](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/edge_detector.py) (Edge detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data ingestion"]
  node_schedule["MLB schedule<br/>[mlb_api.py]"]
  node_fangraphs["FanGraphs stats<br/>[fangraphs.py]"]
  node_statcast["Statcast stats<br/>[statcast.py]"]
  node_boxscores["Game boxscores<br/>[mlb_boxscores.py]"]
  node_odds["Market odds<br/>[odds_api.py]"]
  node_kalshi["Kalshi markets<br/>[kalshi_client.py]"]
  node_historical["Historical odds"]
end

subgraph group_model["Modeling"]
  node_features["Game features<br/>[game_features.py]"]
  node_bullpen["Bullpen features<br/>[bullpen.py]"]
  node_park["Park factors<br/>[park_factors.py]"]
  node_training["Model training<br/>[pipeline.py]"]
  node_modelscore["Win probability model<br/>[pipeline.py]"]
  node_explain["Bet explanations<br/>[explain.py]"]
end

subgraph group_decision["Bet decisions"]
  node_daily["Daily runner<br/>[update.py]"]
  node_edge["Edge detection<br/>[edge_detector.py]"]
  node_kelly["Kelly sizing<br/>[kelly.py]"]
  node_backtest["Strategy backtest<br/>[backtest.py]"]
end

subgraph group_tracking["Tracking"]
  node_betrecord["Record actual bet<br/>[record_bet.py]"]
  node_tracker["Bet tracking<br/>[bet_tracker.py]"]
  node_log[("Bet log<br/>[bets_log.csv]")]
  node_excel["Excel tracker<br/>[export_excel.py]"]
end

node_user(("Operator"))

node_user -->|"runs"| node_daily
node_daily -->|"fetches games"| node_schedule
node_daily -->|"fetches stats"| node_fangraphs
node_daily -->|"fetches stats"| node_statcast
node_daily -->|"fetches results"| node_boxscores
node_daily -->|"fetches lines"| node_odds
node_daily -->|"builds features"| node_features
node_features -->|"reads factors"| node_park
node_daily -->|"scores games"| node_modelscore
node_modelscore -->|"uses trained model"| node_training
node_daily -->|"finds edges"| node_edge
node_edge -->|"gets prices"| node_kalshi
node_edge -->|"requests sizing"| node_kelly
node_training -.->|"merges lines"| node_historical
node_training -->|"builds training data"| node_features
node_daily -->|"logs picks"| node_tracker
node_tracker -->|"reads and writes"| node_log
node_daily -->|"exports tracker"| node_excel
node_user -->|"records wager"| node_betrecord
node_betrecord -->|"records actual"| node_tracker
node_tracker -.->|"fills outcomes"| node_boxscores
node_backtest -.->|"uses closing lines"| node_historical
node_backtest -.->|"evaluates model"| node_training
node_daily -.->|"explains picks"| node_explain

click node_daily "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/update.py"
click node_schedule "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/mlb_api.py"
click node_fangraphs "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/fangraphs.py"
click node_statcast "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/statcast.py"
click node_boxscores "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/mlb_boxscores.py"
click node_odds "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/odds_api.py"
click node_kalshi "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/kalshi_client.py"
click node_historical "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/historical_odds_parser.py"
click node_features "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/game_features.py"
click node_bullpen "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/bullpen.py"
click node_park "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/park_factors.py"
click node_training "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/pipeline.py"
click node_modelscore "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/pipeline.py"
click node_explain "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/explain.py"
click node_edge "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/edge_detector.py"
click node_kelly "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/kelly.py"
click node_betrecord "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/record_bet.py"
click node_tracker "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/tracking/bet_tracker.py"
click node_log "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/data/bets_log.csv"
click node_excel "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/export_excel.py"
click node_backtest "https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/backtest.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_schedule,node_fangraphs,node_statcast,node_boxscores,node_odds,node_kalshi,node_historical toneBlue
class node_features,node_bullpen,node_park,node_training,node_modelscore,node_explain toneAmber
class node_daily,node_edge,node_kelly,node_backtest toneMint
class node_betrecord,node_tracker,node_log,node_excel toneRose
class node_user toneIndigo
```

## Components

### Data ingestion

- [MLB schedule](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/mlb_api.py): `src/data/mlb_api.py`
- [FanGraphs stats](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/fangraphs.py): `src/data/fangraphs.py`
- [Statcast stats](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/statcast.py): `src/data/statcast.py`
- [Game boxscores](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/mlb_boxscores.py): `src/data/mlb_boxscores.py`
- [Market odds](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/odds_api.py): `src/data/odds_api.py`
- [Kalshi markets](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/kalshi_client.py): `src/data/kalshi_client.py`
- [Historical odds](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/data/historical_odds_parser.py): `src/data/historical_odds_parser.py`

### Modeling

- [Game features](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/game_features.py): `src/features/game_features.py`
- [Bullpen features](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/bullpen.py): `src/features/bullpen.py`
- [Park factors](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/features/park_factors.py): `src/features/park_factors.py`
- [Model training](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/pipeline.py): `pipeline.py`
- [Win probability model](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/pipeline.py): `pipeline.py`
- [Bet explanations](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/explain.py): `src/edge/explain.py`

### Bet decisions

- [Daily runner](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/update.py): `update.py`
- [Edge detection](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/edge_detector.py): `src/edge/edge_detector.py`
- [Kelly sizing](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/edge/kelly.py): `src/edge/kelly.py`
- [Strategy backtest](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/backtest.py): `backtest.py`

### Tracking

- [Record actual bet](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/record_bet.py): `record_bet.py`
- [Bet tracking](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/src/tracking/bet_tracker.py): `src/tracking/bet_tracker.py`
- [Bet log](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/data/bets_log.csv): `data/bets_log.csv`
- [Excel tracker](https://github.com/noah-sokol/kalshi-mlb-predictions/blob/main/export_excel.py): `export_excel.py`

### Other components

- **Operator**

## Connections

- Operator → Daily runner: runs
- Daily runner → MLB schedule: fetches games
- Daily runner → FanGraphs stats: fetches stats
- Daily runner → Statcast stats: fetches stats
- Daily runner → Game boxscores: fetches results
- Daily runner → Market odds: fetches lines
- Daily runner → Game features: builds features
- Game features → Park factors: reads factors
- Daily runner → Win probability model: scores games
- Win probability model → Model training: uses trained model
- Daily runner → Edge detection: finds edges
- Edge detection → Kalshi markets: gets prices
- Edge detection → Kelly sizing: requests sizing
- Model training → Historical odds: merges lines
- Model training → Game features: builds training data
- Daily runner → Bet tracking: logs picks
- Bet tracking → Bet log: reads and writes
- Daily runner → Excel tracker: exports tracker
- Operator → Record actual bet: records wager
- Record actual bet → Bet tracking: records actual
- Bet tracking → Game boxscores: fills outcomes
- Strategy backtest → Historical odds: uses closing lines
- Strategy backtest → Model training: evaluates model
- Daily runner → Bet explanations: explains picks