# aykan2004/quantbet architecture

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

- Interactive diagram: https://gitdiagram.com/aykan2004/quantbet
- Repository: https://github.com/aykan2004/quantbet
- Video tour (about a minute): https://gitdiagram.com/aykan2004/quantbet/video

## Overview

Quantbet is a soccer 1X2 research and paper-trading pipeline. Its live workflow scans upcoming fixtures, obtains recent team form and bookmaker odds, builds model inputs, estimates calibrated outcome probabilities, filters and sizes candidate bets, and records selected bets with feature snapshots. Later, settlement grades pending bets; nightly retraining can consume newly settled snapshots alongside historical replay data. Separate research paths train and evaluate the model, compare it with a Poisson baseline, and backtest against historical odds. The README documents these capabilities; some module wiring is inferred only where it explicitly describes the workflow.

Main entry points: [`quantbet/cli.py`](https://github.com/aykan2004/quantbet/blob/main/quantbet/cli.py) (Command interface), [`quantbet/slip.py`](https://github.com/aykan2004/quantbet/blob/main/quantbet/slip.py) (Live bet slip), [`quantbet/train.py`](https://github.com/aykan2004/quantbet/blob/main/quantbet/train.py) (Train and calibrate), [`quantbet/backtest.py`](https://github.com/aykan2004/quantbet/blob/main/quantbet/backtest.py) (Historical backtest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_research["Research Data"]
  node_dataset_builder["Historical data builder<br/>[build_dataset.py]"]
  node_training_data["Training matches"]
  node_historical_odds["Historical odds set"]
end

subgraph group_modeling["Modeling"]
  node_features["Feature engine<br/>[features.py]"]
  node_trainer["Train and calibrate<br/>[train.py]"]
  node_model["Outcome model<br/>[model.py]"]
  node_model_file["Model weights"]
  node_mappings["Model mappings<br/>[mappings.json]"]
end

subgraph group_paper["Paper Trading"]
  node_cli["Command interface<br/>[cli.py]"]
  node_slip["Live bet slip<br/>[slip.py]"]
  node_api_client["API clients<br/>[api_client.py]"]
  node_strategy["EV and staking<br/>[strategy.py]"]
  node_ledger[("Paper ledger<br/>[ledger.py]")]
  node_settlement["Bet settlement<br/>[settlement.py]"]
  node_retraining["Experience replay<br/>[retrain.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_baseline["Poisson baseline<br/>[baselines.py]"]
  node_backtest["Historical backtest<br/>[backtest.py]"]
  node_report["Ledger report<br/>[report.py]"]
end

node_user(("Operator"))
node_cron(("Nightly cron"))
node_stats_api["Football stats API"]
node_odds_api["Odds API"]

node_user -->|"runs commands"| node_cli
node_cron -.->|"runs nightly jobs"| node_cli
node_cli -->|"dispatches slip"| node_slip
node_cli -->|"dispatches training"| node_trainer
node_cli -->|"dispatches backtest"| node_backtest
node_cli -->|"dispatches baseline"| node_baseline
node_cli -->|"dispatches settlement"| node_settlement
node_cli -->|"dispatches retraining"| node_retraining
node_cli -->|"dispatches report"| node_report
node_dataset_builder -->|"fetches fixtures"| node_stats_api
node_dataset_builder -->|"fetches historical odds"| node_odds_api
node_dataset_builder -->|"writes dataset"| node_historical_odds
node_trainer -->|"reads matches"| node_training_data
node_trainer -->|"uses features"| node_features
node_trainer -->|"trains network"| node_model
node_trainer -->|"writes weights"| node_model_file
node_trainer -->|"writes mappings"| node_mappings
node_slip -->|"requests fixture data"| node_api_client
node_api_client -->|"fetches form and fixtures"| node_stats_api
node_api_client -->|"fetches live odds"| node_odds_api
node_slip -->|"builds inputs"| node_features
node_slip -->|"requests probabilities"| node_model
node_slip -->|"loads weights"| node_model_file
node_slip -->|"loads mappings"| node_mappings
node_slip -->|"filters and sizes bets"| node_strategy
node_slip -->|"records selected bets"| node_ledger
node_settlement -->|"looks up results"| node_api_client
node_settlement -->|"grades pending bets"| node_ledger
node_retraining -->|"reads and marks bets"| node_ledger
node_retraining -->|"samples replay matches"| node_training_data
node_retraining -->|"updates weights"| node_model_file
node_backtest -->|"reads odds and results"| node_historical_odds
node_backtest -->|"trains and evaluates"| node_model
node_backtest -->|"loads mappings"| node_mappings
node_backtest -->|"simulates bet selection"| node_strategy
node_baseline -->|"fits and evaluates"| node_training_data
node_report -->|"reads history"| node_ledger

click node_cli "https://github.com/aykan2004/quantbet/blob/main/quantbet/cli.py"
click node_dataset_builder "https://github.com/aykan2004/quantbet/blob/main/quantbet/build_dataset.py"
click node_training_data "https://github.com/aykan2004/quantbet/blob/main/data/soccer_data_full.csv"
click node_historical_odds "https://github.com/aykan2004/quantbet/blob/main/data/historical_dataset_2024.json"
click node_features "https://github.com/aykan2004/quantbet/blob/main/quantbet/features.py"
click node_trainer "https://github.com/aykan2004/quantbet/blob/main/quantbet/train.py"
click node_model "https://github.com/aykan2004/quantbet/blob/main/quantbet/model.py"
click node_model_file "https://github.com/aykan2004/quantbet/blob/main/models/soccer_model_full.pth"
click node_mappings "https://github.com/aykan2004/quantbet/blob/main/models/mappings.json"
click node_baseline "https://github.com/aykan2004/quantbet/blob/main/quantbet/baselines.py"
click node_backtest "https://github.com/aykan2004/quantbet/blob/main/quantbet/backtest.py"
click node_report "https://github.com/aykan2004/quantbet/blob/main/quantbet/report.py"
click node_slip "https://github.com/aykan2004/quantbet/blob/main/quantbet/slip.py"
click node_api_client "https://github.com/aykan2004/quantbet/blob/main/quantbet/api_client.py"
click node_strategy "https://github.com/aykan2004/quantbet/blob/main/quantbet/strategy.py"
click node_ledger "https://github.com/aykan2004/quantbet/blob/main/quantbet/ledger.py"
click node_settlement "https://github.com/aykan2004/quantbet/blob/main/quantbet/settlement.py"
click node_retraining "https://github.com/aykan2004/quantbet/blob/main/quantbet/retrain.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_dataset_builder,node_training_data,node_historical_odds toneBlue
class node_features,node_trainer,node_model,node_model_file,node_mappings toneAmber
class node_cli,node_slip,node_api_client,node_strategy,node_ledger,node_settlement,node_retraining,node_stats_api,node_odds_api toneMint
class node_baseline,node_backtest,node_report toneRose
class node_user,node_cron toneIndigo
```

## Components

### Research Data

- [Historical data builder](https://github.com/aykan2004/quantbet/blob/main/quantbet/build_dataset.py): `quantbet/build_dataset.py`
- [Training matches](https://github.com/aykan2004/quantbet/blob/main/data/soccer_data_full.csv): `data/soccer_data_full.csv`
- [Historical odds set](https://github.com/aykan2004/quantbet/blob/main/data/historical_dataset_2024.json): `data/historical_dataset_2024.json`

### Modeling

- [Feature engine](https://github.com/aykan2004/quantbet/blob/main/quantbet/features.py): `quantbet/features.py`
- [Train and calibrate](https://github.com/aykan2004/quantbet/blob/main/quantbet/train.py): `quantbet/train.py`
- [Outcome model](https://github.com/aykan2004/quantbet/blob/main/quantbet/model.py): `quantbet/model.py`
- [Model weights](https://github.com/aykan2004/quantbet/blob/main/models/soccer_model_full.pth): `models/soccer_model_full.pth`
- [Model mappings](https://github.com/aykan2004/quantbet/blob/main/models/mappings.json): `models/mappings.json`

### Paper Trading

- [Command interface](https://github.com/aykan2004/quantbet/blob/main/quantbet/cli.py): `quantbet/cli.py`
- [Live bet slip](https://github.com/aykan2004/quantbet/blob/main/quantbet/slip.py): `quantbet/slip.py`
- [API clients](https://github.com/aykan2004/quantbet/blob/main/quantbet/api_client.py): `quantbet/api_client.py`
- [EV and staking](https://github.com/aykan2004/quantbet/blob/main/quantbet/strategy.py): `quantbet/strategy.py`
- [Paper ledger](https://github.com/aykan2004/quantbet/blob/main/quantbet/ledger.py): `quantbet/ledger.py`
- [Bet settlement](https://github.com/aykan2004/quantbet/blob/main/quantbet/settlement.py): `quantbet/settlement.py`
- [Experience replay](https://github.com/aykan2004/quantbet/blob/main/quantbet/retrain.py): `quantbet/retrain.py`

### Evaluation

- [Poisson baseline](https://github.com/aykan2004/quantbet/blob/main/quantbet/baselines.py): `quantbet/baselines.py`
- [Historical backtest](https://github.com/aykan2004/quantbet/blob/main/quantbet/backtest.py): `quantbet/backtest.py`
- [Ledger report](https://github.com/aykan2004/quantbet/blob/main/quantbet/report.py): `quantbet/report.py`

### Other components

- **Operator**
- **Nightly cron**
- **Football stats API**
- **Odds API**

## Connections

- Operator → Command interface: runs commands
- Nightly cron → Command interface: runs nightly jobs
- Command interface → Live bet slip: dispatches slip
- Command interface → Train and calibrate: dispatches training
- Command interface → Historical backtest: dispatches backtest
- Command interface → Poisson baseline: dispatches baseline
- Command interface → Bet settlement: dispatches settlement
- Command interface → Experience replay: dispatches retraining
- Command interface → Ledger report: dispatches report
- Historical data builder → Football stats API: fetches fixtures
- Historical data builder → Odds API: fetches historical odds
- Historical data builder → Historical odds set: writes dataset
- Train and calibrate → Training matches: reads matches
- Train and calibrate → Feature engine: uses features
- Train and calibrate → Outcome model: trains network
- Train and calibrate → Model weights: writes weights
- Train and calibrate → Model mappings: writes mappings
- Live bet slip → API clients: requests fixture data
- API clients → Football stats API: fetches form and fixtures
- API clients → Odds API: fetches live odds
- Live bet slip → Feature engine: builds inputs
- Live bet slip → Outcome model: requests probabilities
- Live bet slip → Model weights: loads weights
- Live bet slip → Model mappings: loads mappings
- Live bet slip → EV and staking: filters and sizes bets
- Live bet slip → Paper ledger: records selected bets
- Bet settlement → API clients: looks up results
- Bet settlement → Paper ledger: grades pending bets
- Experience replay → Paper ledger: reads and marks bets
- Experience replay → Training matches: samples replay matches
- Experience replay → Model weights: updates weights
- Historical backtest → Historical odds set: reads odds and results
- Historical backtest → Outcome model: trains and evaluates
- Historical backtest → Model mappings: loads mappings
- Historical backtest → EV and staking: simulates bet selection
- Poisson baseline → Training matches: fits and evaluates
- Ledger report → Paper ledger: reads history