# carlmedinav/nba-ml architecture

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

- Interactive diagram: https://gitdiagram.com/carlmedinav/nba-ml
- Repository: https://github.com/carlmedinav/nba-ml

## Overview

NBA Totals ML is a basketball forecasting product with a reproducible data-to-model pipeline and user-facing dashboards. Its main workflow builds pre-game features from game data, trains models, and serves total, margin and player-prop projections; the web app also offers injury context and a Bet Builder. The graph includes documented capabilities whose implementation was not sampled. Some links are supported only by README descriptions, so uncertain internal wiring is omitted.

Main entry points: [`app.py`](https://github.com/carlmedinav/nba-ml/blob/main/app.py) (FastAPI application), [`src/nba_ml/cli.py`](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/cli.py) (Command-line interface), [`public/app.js`](https://github.com/carlmedinav/nba-ml/blob/main/public/app.js) (Web interface), [`src/nba_ml/data/build_dataset.py`](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/build_dataset.py) (Game feature dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data and Features"]
  node_config["Project configuration<br/>[config.py]"]
  node_download["Game data download<br/>[download.py]"]
  node_schedule["Schedule data<br/>[schedule.py]"]
  node_espn_data["ESPN data adapters<br/>[espn.py]"]
  node_player_data["Player data<br/>[players.py]"]
  node_player_logs["Player game logs<br/>[player_logs.py]"]
  node_dataset["Game feature dataset<br/>[build_dataset.py]"]
  node_eda["Exploratory analysis<br/>[eda.py]"]
end

subgraph group_models["Modeling"]
  node_train["Game model training<br/>[train.py]"]
  node_results["Model results<br/>[results.py]"]
  node_predict["Game predictions<br/>[predict.py]"]
  node_props["Player props model<br/>[player_props.py]"]
  node_artifacts["Model and data artifacts"]
end

subgraph group_serve["Prediction and API"]
  node_cli["Command-line interface<br/>[cli.py]"]
  node_api["FastAPI application<br/>[app.py]"]
  node_streamlit["Streamlit dashboards<br/>[dashboard.py]"]
  node_pro_dashboard["Pro dashboard<br/>[dashboard_pro.py]"]
  node_betting_probability["Betting probabilities<br/>[probability.py]"]
end

subgraph group_web["Web Experience"]
  node_web_app["Web interface<br/>[app.js]"]
  node_injuries_ui["Injuries view<br/>[injuries.js]"]
  node_bet_builder_ui["Bet Builder<br/>[bet-builder.js]"]
  node_analytics_ui["Advanced analytics"]
end

node_user(("NBA user"))
node_nba_stats["NBA stats API"]
node_espn_service["ESPN data"]
node_browser(("Web visitor"))

node_nba_stats -->|"provides game logs"| node_download
node_nba_stats -->|"provides schedules"| node_schedule
node_espn_service -->|"provides updates"| node_espn_data
node_config -->|"configures paths"| node_download
node_config -->|"configures paths"| node_dataset
node_download -->|"supplies raw data"| node_dataset
node_dataset -->|"analyzes features"| node_eda
node_dataset -->|"trains from"| node_train
node_train -->|"writes models"| node_artifacts
node_train -->|"evaluates models"| node_results
node_player_logs -->|"builds player features"| node_props
node_props -->|"stores projections"| node_artifacts
node_artifacts -->|"loads model state"| node_predict
node_cli -->|"runs download"| node_download
node_cli -->|"builds dataset"| node_dataset
node_cli -->|"runs training"| node_train
node_cli -->|"requests prediction"| node_predict
node_cli -->|"opens dashboard"| node_streamlit
node_cli -->|"opens dashboard"| node_pro_dashboard
node_streamlit -->|"generates forecasts"| node_predict
node_pro_dashboard -->|"generates forecasts"| node_predict
node_api -->|"serves predictions"| node_predict
node_api -->|"serves player props"| node_props
node_api -->|"uses model results"| node_results
node_api -->|"uses betting calculations"| node_betting_probability
node_browser -->|"uses interface"| node_web_app
node_web_app -->|"requests app data"| node_api
node_web_app -->|"shows injuries"| node_injuries_ui
node_web_app -->|"offers Bet Builder"| node_bet_builder_ui
node_web_app -.->|"offers analytics"| node_analytics_ui
node_bet_builder_ui -->|"analyzes selections"| node_api
node_injuries_ui -->|"loads injury data"| node_api

click node_config "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/config.py"
click node_download "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/download.py"
click node_schedule "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/schedule.py"
click node_espn_data "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/espn.py"
click node_player_data "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/players.py"
click node_player_logs "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/player_logs.py"
click node_dataset "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/build_dataset.py"
click node_eda "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/eda.py"
click node_train "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/train.py"
click node_results "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/results.py"
click node_predict "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/predict.py"
click node_props "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/player_props.py"
click node_artifacts "https://github.com/carlmedinav/nba-ml/tree/main/artifacts"
click node_cli "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/cli.py"
click node_api "https://github.com/carlmedinav/nba-ml/blob/main/app.py"
click node_streamlit "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/dashboard.py"
click node_pro_dashboard "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/dashboard_pro.py"
click node_web_app "https://github.com/carlmedinav/nba-ml/blob/main/public/app.js"
click node_injuries_ui "https://github.com/carlmedinav/nba-ml/blob/main/public/injuries.js"
click node_bet_builder_ui "https://github.com/carlmedinav/nba-ml/blob/main/public/bet-builder.js"
click node_analytics_ui "https://github.com/carlmedinav/nba-ml/blob/main/public/advanced-analytics.js"
click node_betting_probability "https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/betting/probability.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_config,node_download,node_schedule,node_espn_data,node_player_data,node_player_logs,node_dataset,node_eda,node_user toneBlue
class node_train,node_results,node_predict,node_props,node_artifacts toneAmber
class node_cli,node_api,node_streamlit,node_pro_dashboard,node_betting_probability,node_nba_stats toneMint
class node_web_app,node_injuries_ui,node_bet_builder_ui,node_analytics_ui toneRose
class node_espn_service,node_browser toneIndigo
```

## Components

### Data and Features

- [Project configuration](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/config.py): `src/nba_ml/config.py`
- [Game data download](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/download.py): `src/nba_ml/data/download.py`
- [Schedule data](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/schedule.py): `src/nba_ml/data/schedule.py`
- [ESPN data adapters](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/espn.py): `src/nba_ml/data/espn.py`
- [Player data](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/players.py): `src/nba_ml/data/players.py`
- [Player game logs](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/player_logs.py): `src/nba_ml/data/player_logs.py`
- [Game feature dataset](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/data/build_dataset.py): `src/nba_ml/data/build_dataset.py`
- [Exploratory analysis](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/eda.py): `src/nba_ml/eda.py`

### Modeling

- [Game model training](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/train.py): `src/nba_ml/models/train.py`
- [Model results](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/results.py): `src/nba_ml/models/results.py`
- [Game predictions](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/predict.py): `src/nba_ml/models/predict.py`
- [Player props model](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/models/player_props.py): `src/nba_ml/models/player_props.py`
- [Model and data artifacts](https://github.com/carlmedinav/nba-ml/tree/main/artifacts): `artifacts`

### Prediction and API

- [Command-line interface](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/cli.py): `src/nba_ml/cli.py`
- [FastAPI application](https://github.com/carlmedinav/nba-ml/blob/main/app.py): `app.py`
- [Streamlit dashboards](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/dashboard.py): `src/nba_ml/dashboard.py`
- [Pro dashboard](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/dashboard_pro.py): `src/nba_ml/dashboard_pro.py`
- [Betting probabilities](https://github.com/carlmedinav/nba-ml/blob/main/src/nba_ml/betting/probability.py): `src/nba_ml/betting/probability.py`

### Web Experience

- [Web interface](https://github.com/carlmedinav/nba-ml/blob/main/public/app.js): `public/app.js`
- [Injuries view](https://github.com/carlmedinav/nba-ml/blob/main/public/injuries.js): `public/injuries.js`
- [Bet Builder](https://github.com/carlmedinav/nba-ml/blob/main/public/bet-builder.js): `public/bet-builder.js`
- [Advanced analytics](https://github.com/carlmedinav/nba-ml/blob/main/public/advanced-analytics.js): `public/advanced-analytics.js`

### Other components

- **NBA user**
- **NBA stats API**
- **ESPN data**
- **Web visitor**

## Connections

- NBA stats API → Game data download: provides game logs (evidence: `README.md`)
- NBA stats API → Schedule data: provides schedules (evidence: `src/nba_ml/data/schedule.py`)
- ESPN data → ESPN data adapters: provides updates (evidence: `src/nba_ml/data/espn.py`)
- Project configuration → Game data download: configures paths (evidence: `src/nba_ml/data/download.py`)
- Project configuration → Game feature dataset: configures paths (evidence: `src/nba_ml/data/build_dataset.py`)
- Game data download → Game feature dataset: supplies raw data (evidence: `src/nba_ml/data/build_dataset.py`)
- Game feature dataset → Exploratory analysis: analyzes features (evidence: `src/nba_ml/eda.py`)
- Game feature dataset → Game model training: trains from (evidence: `src/nba_ml/models/train.py`)
- Game model training → Model and data artifacts: writes models (evidence: `README.md`)
- Game model training → Model results: evaluates models (evidence: `README.md`)
- Player game logs → Player props model: builds player features (evidence: `README.md`)
- Player props model → Model and data artifacts: stores projections (evidence: `src/nba_ml/models/player_props.py`)
- Model and data artifacts → Game predictions: loads model state (evidence: `src/nba_ml/models/predict.py`)
- Command-line interface → Game data download: runs download (evidence: `src/nba_ml/cli.py`)
- Command-line interface → Game feature dataset: builds dataset (evidence: `src/nba_ml/cli.py`)
- Command-line interface → Game model training: runs training (evidence: `src/nba_ml/cli.py`)
- Command-line interface → Game predictions: requests prediction (evidence: `src/nba_ml/cli.py`)
- Command-line interface → Streamlit dashboards: opens dashboard (evidence: `src/nba_ml/cli.py`)
- Command-line interface → Pro dashboard: opens dashboard (evidence: `src/nba_ml/cli.py`)
- Streamlit dashboards → Game predictions: generates forecasts (evidence: `src/nba_ml/dashboard.py`)
- Pro dashboard → Game predictions: generates forecasts (evidence: `src/nba_ml/dashboard_pro.py`)
- FastAPI application → Game predictions: serves predictions (evidence: `app.py`)
- FastAPI application → Player props model: serves player props (evidence: `app.py`)
- FastAPI application → Model results: uses model results (evidence: `app.py`)
- FastAPI application → Betting probabilities: uses betting calculations
- Web visitor → Web interface: uses interface (evidence: `README.md`)
- Web interface → FastAPI application: requests app data (evidence: `README.md`)
- Web interface → Injuries view: shows injuries (evidence: `README.md`)
- Web interface → Bet Builder: offers Bet Builder (evidence: `README.md`)
- Web interface → Advanced analytics: offers analytics
- Bet Builder → FastAPI application: analyzes selections (evidence: `README.md`)
- Injuries view → FastAPI application: loads injury data (evidence: `README.md`)
