# mpope9/nba-sql architecture

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

- Interactive diagram: https://gitdiagram.com/mpope9/nba-sql
- Repository: https://github.com/mpope9/nba-sql
- Video tour (about a minute): https://gitdiagram.com/mpope9/nba-sql/video

## Overview

nba-sql loads NBA statistics into a queryable SQLite, PostgreSQL, or MySQL/MariaDB database, either for selected historical seasons or to refresh the current season. The CLI driver coordinates domain-specific fetchers and builders; fetched data is mapped into relational tables and batch-inserted. The README also documents play-by-play, shot-chart, season, team, and player-stat capabilities. Edges reflect the sampled driver, requester, and model references; unsampled subsystem details are limited to documented capabilities and indexed dependencies.

Main entry points: [`stats/nba_sql.py`](https://github.com/mpope9/nba-sql/blob/main/stats/nba_sql.py) (CLI driver), [`stats/models`](https://github.com/mpope9/nba-sql/tree/main/stats/models) (Relational models), [`stats/general_requester.py`](https://github.com/mpope9/nba-sql/blob/main/stats/general_requester.py) (HTTP requester), [`stats/player.py`](https://github.com/mpope9/nba-sql/blob/main/stats/player.py) (Player data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Load orchestration"]
  node_cli["CLI driver<br/>[nba_sql.py]"]
end

subgraph group_fetch["NBA data fetch"]
  node_player_fetch["Player data<br/>[player.py]"]
  node_team_fetch["Team data<br/>[team.py]"]
  node_game_fetch["Game data<br/>[game.py]"]
  node_season_fetch["Season data<br/>[season.py]"]
  node_event_fetch["Event types"]
  node_player_season["Player seasons<br/>[player_season.py]"]
  node_player_log["Player game logs<br/>[player_game_log.py]"]
  node_player_totals["Player totals"]
  node_play_by_play["Play by play<br/>[play_by_play.py]"]
  node_play_by_play_v3["Play by play v3<br/>[play_by_playv3.py]"]
  node_shot_charts["Shot charts"]
  node_requester["HTTP requester"]
end

subgraph group_schema["Domain tables"]
  node_models["Relational models"]
end

subgraph group_persist["Storage layer"]
  node_db_utils["Batch inserts<br/>[db_utils.py]"]
end

node_operator(("Operator"))
node_nba_api{{"NBA stats API"}}
node_database[("SQL database")]

node_operator -->|"runs"| node_cli
node_cli -->|"dispatches"| node_player_fetch
node_cli -->|"dispatches"| node_team_fetch
node_cli -->|"dispatches"| node_game_fetch
node_cli -->|"dispatches"| node_season_fetch
node_cli -->|"dispatches"| node_event_fetch
node_cli -->|"dispatches"| node_player_season
node_cli -->|"dispatches"| node_player_log
node_cli -->|"dispatches"| node_player_totals
node_cli -->|"dispatches"| node_play_by_play
node_cli -->|"dispatches"| node_play_by_play_v3
node_cli -->|"dispatches"| node_shot_charts
node_player_fetch -->|"uses"| node_requester
node_team_fetch -->|"uses"| node_requester
node_player_season -->|"uses"| node_requester
node_player_log -->|"uses"| node_requester
node_player_totals -->|"uses"| node_requester
node_shot_charts -->|"uses"| node_requester
node_requester -->|"requests data"| node_nba_api
node_player_fetch -->|"maps to"| node_models
node_team_fetch -->|"maps to"| node_models
node_game_fetch -->|"builds"| node_models
node_season_fetch -->|"maps to"| node_models
node_event_fetch -->|"maps to"| node_models
node_player_season -->|"maps to"| node_models
node_player_log -->|"maps to"| node_models
node_player_totals -->|"maps to"| node_models
node_play_by_play -->|"maps to"| node_models
node_play_by_play_v3 -->|"maps to"| node_models
node_shot_charts -->|"maps to"| node_models
node_requester -->|"batch inserts"| node_db_utils
node_db_utils -->|"writes rows"| node_database
node_cli -.->|"configures connection"| node_database

click node_cli "https://github.com/mpope9/nba-sql/blob/main/stats/nba_sql.py"
click node_player_fetch "https://github.com/mpope9/nba-sql/blob/main/stats/player.py"
click node_team_fetch "https://github.com/mpope9/nba-sql/blob/main/stats/team.py"
click node_game_fetch "https://github.com/mpope9/nba-sql/blob/main/stats/game.py"
click node_season_fetch "https://github.com/mpope9/nba-sql/blob/main/stats/season.py"
click node_event_fetch "https://github.com/mpope9/nba-sql/blob/main/stats/event_message_type.py"
click node_player_season "https://github.com/mpope9/nba-sql/blob/main/stats/player_season.py"
click node_player_log "https://github.com/mpope9/nba-sql/blob/main/stats/player_game_log.py"
click node_player_totals "https://github.com/mpope9/nba-sql/blob/main/stats/player_general_traditional_total.py"
click node_play_by_play "https://github.com/mpope9/nba-sql/blob/main/stats/play_by_play.py"
click node_play_by_play_v3 "https://github.com/mpope9/nba-sql/blob/main/stats/play_by_playv3.py"
click node_shot_charts "https://github.com/mpope9/nba-sql/blob/main/stats/shot_chart_detail.py"
click node_requester "https://github.com/mpope9/nba-sql/blob/main/stats/general_requester.py"
click node_models "https://github.com/mpope9/nba-sql/tree/main/stats/models"
click node_db_utils "https://github.com/mpope9/nba-sql/blob/main/stats/db_utils.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_cli toneBlue
class node_player_fetch,node_team_fetch,node_game_fetch,node_season_fetch,node_event_fetch,node_player_season,node_player_log,node_player_totals,node_play_by_play,node_play_by_play_v3,node_shot_charts,node_requester,node_database toneAmber
class node_models,node_nba_api toneMint
class node_db_utils toneRose
class node_operator toneIndigo
```

## Components

### Load orchestration

- [CLI driver](https://github.com/mpope9/nba-sql/blob/main/stats/nba_sql.py): `stats/nba_sql.py`

### NBA data fetch

- [Player data](https://github.com/mpope9/nba-sql/blob/main/stats/player.py): `stats/player.py`
- [Team data](https://github.com/mpope9/nba-sql/blob/main/stats/team.py): `stats/team.py`
- [Game data](https://github.com/mpope9/nba-sql/blob/main/stats/game.py): `stats/game.py`
- [Season data](https://github.com/mpope9/nba-sql/blob/main/stats/season.py): `stats/season.py`
- [Event types](https://github.com/mpope9/nba-sql/blob/main/stats/event_message_type.py): `stats/event_message_type.py`
- [Player seasons](https://github.com/mpope9/nba-sql/blob/main/stats/player_season.py): `stats/player_season.py`
- [Player game logs](https://github.com/mpope9/nba-sql/blob/main/stats/player_game_log.py): `stats/player_game_log.py`
- [Player totals](https://github.com/mpope9/nba-sql/blob/main/stats/player_general_traditional_total.py): `stats/player_general_traditional_total.py`
- [Play by play](https://github.com/mpope9/nba-sql/blob/main/stats/play_by_play.py): `stats/play_by_play.py`
- [Play by play v3](https://github.com/mpope9/nba-sql/blob/main/stats/play_by_playv3.py): `stats/play_by_playv3.py`
- [Shot charts](https://github.com/mpope9/nba-sql/blob/main/stats/shot_chart_detail.py): `stats/shot_chart_detail.py`
- [HTTP requester](https://github.com/mpope9/nba-sql/blob/main/stats/general_requester.py): `stats/general_requester.py`

### Domain tables

- [Relational models](https://github.com/mpope9/nba-sql/tree/main/stats/models): `stats/models`

### Storage layer

- [Batch inserts](https://github.com/mpope9/nba-sql/blob/main/stats/db_utils.py): `stats/db_utils.py`

### Other components

- **Operator**
- **NBA stats API**
- **SQL database**

## Connections

- Operator → CLI driver: runs (evidence: `README.md`)
- CLI driver → Player data: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Team data: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Game data: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Season data: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Event types: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Player seasons: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Player game logs: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Player totals: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Play by play: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Play by play v3: dispatches (evidence: `stats/nba_sql.py`)
- CLI driver → Shot charts: dispatches (evidence: `stats/nba_sql.py`)
- Player data → HTTP requester: uses (evidence: `stats/player.py`)
- Team data → HTTP requester: uses (evidence: `stats/team.py`)
- Player seasons → HTTP requester: uses (evidence: `stats/player_season.py`)
- Player game logs → HTTP requester: uses (evidence: `stats/player_game_log.py`)
- Player totals → HTTP requester: uses (evidence: `stats/player_general_traditional_total.py`)
- Shot charts → HTTP requester: uses (evidence: `stats/shot_chart_detail.py`)
- HTTP requester → NBA stats API: requests data (evidence: `stats/general_requester.py`)
- Player data → Relational models: maps to (evidence: `stats/player.py`)
- Team data → Relational models: maps to (evidence: `stats/team.py`)
- Game data → Relational models: builds (evidence: `stats/game.py`)
- Season data → Relational models: maps to (evidence: `stats/season.py`)
- Event types → Relational models: maps to (evidence: `stats/event_message_type.py`)
- Player seasons → Relational models: maps to (evidence: `stats/player_season.py`)
- Player game logs → Relational models: maps to (evidence: `stats/player_game_log.py`)
- Player totals → Relational models: maps to (evidence: `stats/player_general_traditional_total.py`)
- Play by play → Relational models: maps to (evidence: `stats/play_by_play.py`)
- Play by play v3 → Relational models: maps to (evidence: `stats/play_by_playv3.py`)
- Shot charts → Relational models: maps to (evidence: `stats/shot_chart_detail.py`)
- HTTP requester → Batch inserts: batch inserts (evidence: `stats/general_requester.py`)
- Batch inserts → SQL database: writes rows (evidence: `stats/db_utils.py`)
- CLI driver → SQL database: configures connection (evidence: `README.md`)
