# kyleskom/nba-machine-learning-sports-betting architecture

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

- Interactive diagram: https://gitdiagram.com/kyleskom/nba-machine-learning-sports-betting
- Repository: https://github.com/kyleskom/nba-machine-learning-sports-betting

## Overview

This repository is an NBA betting prediction application. Its primary workflow gathers current team statistics and a schedule, obtains sportsbook odds or accepts manual odds, constructs matchup features, runs moneyline and totals models, then reports probabilities, expected value, and optional Kelly sizing. A separate historical-data workflow stores team statistics and odds, builds game datasets, and trains models. The README also documents a Flask interface for browsing outputs. Relationships for unsampled training and web internals are limited to documented capabilities; the excerpts do not establish their detailed runtime calls.

Main entry points: [`main.py`](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/main.py) (Prediction Orchestrator), [`src/Process-Data/Create_Games.py`](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Create_Games.py) (Game Dataset Builder), [`src/Predict/NN_Runner.py`](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/NN_Runner.py) (Neural Net Inference), [`src/Predict/XGBoost_Runner.py`](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/XGBoost_Runner.py) (XGBoost Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live Predictions"]
  node_main["Prediction Orchestrator<br/>[main.py]"]
  node_tools["NBA Data Utilities<br/>[tools.py]"]
  node_oddsprovider["Live Odds Provider<br/>[SbrOddsProvider.py]"]
  node_features["Matchup Features<br/>[main.py]"]
end

subgraph group_data["Data Preparation"]
  node_dict["Team Indexes<br/>[Dictionaries.py]"]
  node_teamfetch["Team Stats Ingest<br/>[Get_Data.py]"]
  node_teamdb[("Team Stats Store<br/>[TeamData.sqlite]")]
  node_oddsfetch["Historical Odds Ingest<br/>[Get_Odds_Data.py]"]
  node_oddsdb[("Odds Store<br/>[OddsData.sqlite]")]
  node_rest["Rest-Day Processing<br/>[Add_Days_Rest.py]"]
  node_gamebuilder["Game Dataset Builder<br/>[Create_Games.py]"]
  node_dataset[("Training Dataset<br/>[dataset.sqlite]")]
end

subgraph group_models["Models and Betting"]
  node_nnrunner["Neural Net Inference<br/>[NN_Runner.py]"]
  node_xgbrunner["XGBoost Inference<br/>[XGBoost_Runner.py]"]
  node_nnmodels["Neural Net Models"]
  node_xgbmodels["XGBoost Models"]
  node_expected["Expected Value<br/>[Expected_Value.py]"]
  node_kelly["Kelly Sizing<br/>[Kelly_Criterion.py]"]
  node_training["Model Training"]
end

subgraph group_web["Web Interface"]
  node_flaskapp["Flask Application<br/>[app.py]"]
  node_webclient["Web UI<br/>[app.js]"]
end

node_user(("User"))
node_stats[("NBA Stats API")]
node_sportsbooks[("Sportsbook Odds")]
node_webuser(("Browser User"))

node_user -->|"requests predictions"| node_main
node_main -->|"fetches odds"| node_oddsprovider
node_oddsprovider -->|"reads odds"| node_sportsbooks
node_main -->|"fetches stats"| node_stats
node_main -->|"uses data helpers"| node_tools
node_main -->|"builds matchups"| node_features
node_tools -->|"uses team indexes"| node_dict
node_main -->|"runs selected model"| node_nnrunner
node_main -->|"runs selected model"| node_xgbrunner
node_nnrunner -->|"loads models"| node_nnmodels
node_xgbrunner -->|"loads models"| node_xgbmodels
node_nnrunner -->|"calculates value"| node_expected
node_nnrunner -->|"calculates stakes"| node_kelly
node_xgbrunner -->|"calculates value"| node_expected
node_xgbrunner -->|"calculates stakes"| node_kelly
node_main -->|"prints results"| node_user
node_teamfetch -->|"requests stats"| node_stats
node_teamfetch -->|"parses responses"| node_tools
node_teamfetch -->|"stores daily stats"| node_teamdb
node_oddsfetch -->|"collects odds"| node_sportsbooks
node_oddsfetch -->|"stores odds"| node_oddsdb
node_rest -.->|"adds rest data"| node_teamdb
node_gamebuilder -->|"reads stats"| node_teamdb
node_gamebuilder -->|"reads odds"| node_oddsdb
node_gamebuilder -->|"writes games"| node_dataset
node_gamebuilder -->|"uses season indexes"| node_dict
node_training -->|"trains from"| node_dataset
node_training -->|"saves trained models"| node_nnmodels
node_training -->|"saves trained models"| node_xgbmodels
node_webuser -->|"browses outputs"| node_webclient
node_webclient -.->|"uses application"| node_flaskapp

click node_main "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/main.py"
click node_tools "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/tools.py"
click node_oddsprovider "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/DataProviders/SbrOddsProvider.py"
click node_features "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/main.py"
click node_nnrunner "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/NN_Runner.py"
click node_xgbrunner "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/XGBoost_Runner.py"
click node_nnmodels "https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/Models/NN_Models"
click node_xgbmodels "https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/Models/XGBoost_Models"
click node_expected "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Expected_Value.py"
click node_kelly "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Kelly_Criterion.py"
click node_dict "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Dictionaries.py"
click node_teamfetch "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Get_Data.py"
click node_teamdb "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/TeamData.sqlite"
click node_oddsfetch "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Get_Odds_Data.py"
click node_oddsdb "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/OddsData.sqlite"
click node_rest "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Add_Days_Rest.py"
click node_gamebuilder "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Create_Games.py"
click node_dataset "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/dataset.sqlite"
click node_training "https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/src/Train-Models"
click node_flaskapp "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Flask/app.py"
click node_webclient "https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Flask/static/app.js"

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_main,node_tools,node_oddsprovider,node_features,node_user,node_webuser toneBlue
class node_dict,node_teamfetch,node_teamdb,node_oddsfetch,node_oddsdb,node_rest,node_gamebuilder,node_dataset,node_stats,node_sportsbooks toneAmber
class node_nnrunner,node_xgbrunner,node_nnmodels,node_xgbmodels,node_expected,node_kelly,node_training toneMint
class node_flaskapp,node_webclient toneRose
```

## Components

### Live Predictions

- [Prediction Orchestrator](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/main.py): `main.py`
- [NBA Data Utilities](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/tools.py): `src/Utils/tools.py`
- [Live Odds Provider](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/DataProviders/SbrOddsProvider.py): `src/DataProviders/SbrOddsProvider.py`
- [Matchup Features](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/main.py): `main.py`

### Data Preparation

- [Team Indexes](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Dictionaries.py): `src/Utils/Dictionaries.py`
- [Team Stats Ingest](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Get_Data.py): `src/Process-Data/Get_Data.py`
- [Team Stats Store](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/TeamData.sqlite): `Data/TeamData.sqlite`
- [Historical Odds Ingest](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Get_Odds_Data.py): `src/Process-Data/Get_Odds_Data.py`
- [Odds Store](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/OddsData.sqlite): `Data/OddsData.sqlite`
- [Rest-Day Processing](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Add_Days_Rest.py): `src/Process-Data/Add_Days_Rest.py`
- [Game Dataset Builder](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Process-Data/Create_Games.py): `src/Process-Data/Create_Games.py`
- [Training Dataset](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Data/dataset.sqlite): `Data/dataset.sqlite`

### Models and Betting

- [Neural Net Inference](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/NN_Runner.py): `src/Predict/NN_Runner.py`
- [XGBoost Inference](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Predict/XGBoost_Runner.py): `src/Predict/XGBoost_Runner.py`
- [Neural Net Models](https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/Models/NN_Models): `Models/NN_Models`
- [XGBoost Models](https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/Models/XGBoost_Models): `Models/XGBoost_Models`
- [Expected Value](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Expected_Value.py): `src/Utils/Expected_Value.py`
- [Kelly Sizing](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/src/Utils/Kelly_Criterion.py): `src/Utils/Kelly_Criterion.py`
- [Model Training](https://github.com/kyleskom/nba-machine-learning-sports-betting/tree/master/src/Train-Models): `src/Train-Models`

### Web Interface

- [Flask Application](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Flask/app.py): `Flask/app.py`
- [Web UI](https://github.com/kyleskom/nba-machine-learning-sports-betting/blob/master/Flask/static/app.js): `Flask/static/app.js`

### Other components

- **User**
- **NBA Stats API**
- **Sportsbook Odds**
- **Browser User**

## Connections

- User → Prediction Orchestrator: requests predictions (evidence: `README.md`)
- Prediction Orchestrator → Live Odds Provider: fetches odds (evidence: `main.py`)
- Live Odds Provider → Sportsbook Odds: reads odds (evidence: `src/DataProviders/SbrOddsProvider.py`)
- Prediction Orchestrator → NBA Stats API: fetches stats (evidence: `README.md`)
- Prediction Orchestrator → NBA Data Utilities: uses data helpers (evidence: `main.py`)
- Prediction Orchestrator → Matchup Features: builds matchups (evidence: `main.py`)
- NBA Data Utilities → Team Indexes: uses team indexes (evidence: `src/Utils/tools.py`)
- Prediction Orchestrator → Neural Net Inference: runs selected model (evidence: `README.md`)
- Prediction Orchestrator → XGBoost Inference: runs selected model (evidence: `README.md`)
- Neural Net Inference → Neural Net Models: loads models (evidence: `src/Predict/NN_Runner.py`)
- XGBoost Inference → XGBoost Models: loads models (evidence: `src/Predict/XGBoost_Runner.py`)
- Neural Net Inference → Expected Value: calculates value (evidence: `src/Predict/NN_Runner.py`)
- Neural Net Inference → Kelly Sizing: calculates stakes (evidence: `src/Predict/NN_Runner.py`)
- XGBoost Inference → Expected Value: calculates value (evidence: `src/Predict/XGBoost_Runner.py`)
- XGBoost Inference → Kelly Sizing: calculates stakes (evidence: `src/Predict/XGBoost_Runner.py`)
- Prediction Orchestrator → User: prints results (evidence: `README.md`)
- Team Stats Ingest → NBA Stats API: requests stats (evidence: `README.md`)
- Team Stats Ingest → NBA Data Utilities: parses responses (evidence: `src/Process-Data/Get_Data.py`)
- Team Stats Ingest → Team Stats Store: stores daily stats (evidence: `README.md`)
- Historical Odds Ingest → Sportsbook Odds: collects odds (evidence: `README.md`)
- Historical Odds Ingest → Odds Store: stores odds (evidence: `README.md`)
- Rest-Day Processing → Team Stats Store: adds rest data
- Game Dataset Builder → Team Stats Store: reads stats (evidence: `README.md`)
- Game Dataset Builder → Odds Store: reads odds (evidence: `README.md`)
- Game Dataset Builder → Training Dataset: writes games (evidence: `README.md`)
- Game Dataset Builder → Team Indexes: uses season indexes (evidence: `src/Process-Data/Create_Games.py`)
- Model Training → Training Dataset: trains from (evidence: `README.md`)
- Model Training → Neural Net Models: saves trained models (evidence: `README.md`)
- Model Training → XGBoost Models: saves trained models (evidence: `README.md`)
- Browser User → Web UI: browses outputs (evidence: `README.md`)
- Web UI → Flask Application: uses application
