# jakekandell/nba-predict architecture

> Architecture diagram of the GitHub repository jakekandell/nba-predict, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jakekandell/nba-predict
- Repository: https://github.com/jakekandell/nba-predict

## Overview

##### Main components and layers
- Data Layer – This includes raw input files (CSV files in the Data folder) as well as the source of NBA game data scraped from stats.nba.com.
- Scraping & Data Acquisition Module – Scripts such as getStats.py, availableStats.py, getDailyMatchups.py, and customHeaders.py are responsible for interfacing with external data sources, scraping relevant statistics, and setting up proper HTTP requests (possibly with custom headers). They feed the raw data into the processing pipeline.
- Data Preprocessing Layer – This comprises scripts that prepare the data for prediction. For example, standardizeStats.py and any custom processing done in configureCWD.py or teamIds.py are likely involved in cleaning, standardizing, and formatting data.
- Model Training & Persistence Layer – The createModel.py script is used for constructing and possibly training the logistic regression model, and the resulting model is saved in the SavedModels directory (finalized_model.pkl).
- Prediction & Execution Module – The nbaPredict.py and makePastPredictions.py scripts use the saved model along with fresh or historical game data to compute prediction outputs (win chances) for NBA games. These scripts also handle the generation and output of CSV files in the case of past predictions.
- Utility & Configuration – Files like requirements.txt ensure that the necessary libraries and dependencies are installed for everything to work smoothly.

##### Relationships and interactions among these components
- The Data Acquisition Module interacts with external data sources and outputs raw stats.
- Raw data is either directly used by the prediction modules or first passed through the preprocessing layer to standardize and format the data appropriately.
- Preprocessed data is then used both for training (when createModel.py is used) and for performing live or historical predictions.
- The final logistic regression model is stored persistently and later loaded by the prediction modules.
- The nbaPredict.py script is designed for daily/real-time prediction, while makePastPredictions.py is tailored for evaluating historical data over a set period.
- Utility scripts (e.g., configureCWD.py, teamIds.py) support both data acquisition and prediction logic by handling environment configuration and identification mappings.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different scripts are designed to handle distinct tasks such as data scraping, preprocessing, model creation, and prediction, ensuring modularity.
- Pipeline Architecture: The data flows sequentially from acquisition → preprocessing → model training → prediction, which should be clearly represented.
- Reusability and Persistence: The saved logistic regression model (finalized_model.pkl) emphasizes reusability, making it possible to separate the training process from daily predictions.

##### Key Technologies and Libraries
- Python is the primary programming environment.
- The project likely uses libraries for data scraping and HTTP requests (possibly requests or BeautifulSoup), data manipulation (like pandas), and machine learning (likely scikit-learn for logistic regression).
- The requirements.txt file would list these dependencies, which help in understanding the technology stack.

##### Specific Elements to be Included
- Clear labels for each component:
– “Data Preprocessing” (standardizeStats.py, customHeaders.py, configureCWD.py, teamIds.py)
– “Model Training & Persistence” (createModel.py and SavedModels/finalized_model.pkl)
– “Prediction Engine” (nbaPredict.py, makePastPredictions.py)
– External NBA statistics → Data Acquisition → Preprocessing → Model Training/Loading → Prediction

## Diagram (Mermaid)

```mermaid
flowchart TD
    ext["stats.nba.com"]:::external

    subgraph "Scraping & Data Acquisition"
        GA1["getStats.py"]:::acquisition
        GA2["availableStats.py"]:::acquisition
        GA3["getDailyMatchups.py"]:::acquisition
        GA4["customHeaders.py"]:::acquisition
    end

    subgraph "Data Preprocessing"
        DP1["standardizeStats.py"]:::preprocessing
        DP2["configureCWD.py"]:::preprocessing
        DP3["teamIds.py"]:::preprocessing
    end

    subgraph "Model Training & Persistence"
        MT1["createModel.py"]:::model
        MT2["finalized_model.pkl"]:::model
    end

    subgraph "Prediction Engine"
        PE1["nbaPredict.py"]:::prediction
        PE2["makePastPredictions.py"]:::prediction
    end

    DL["Data (CSV files)"]:::storage
    UT["requirements.txt"]:::utility

    %% Data flow connections
    ext -->|"fetches"| GA1
    ext -->|"fetches"| GA2
    ext -->|"fetches"| GA3
    ext -->|"fetches"| GA4

    GA1 -->|"processes"| DP1

    DP1 -->|"prepares"| MT1
    DP1 -->|"prepares"| PE1

    MT1 -->|"savesModel"| MT2
    MT2 -->|"loadedBy"| PE1

    PE1 -->|"writesCSV"| DL
    GA1 -->|"writesRawCSV"| DL
    GA2 -->|"writesRawCSV"| DL
    GA3 -->|"writesRawCSV"| DL
    GA4 -->|"writesRawCSV"| DL

    UT -.-> GA1
    UT -.-> GA2
    UT -.-> GA3
    UT -.-> GA4
    UT -.-> DP1
    UT -.-> DP2
    UT -.-> DP3
    UT -.-> MT1
    UT -.-> PE1
    UT -.-> PE2

    %% Click Events
    click DL "https://github.com/jakekandell/nba-predict/tree/master/Data"
    click GA1 "https://github.com/jakekandell/nba-predict/blob/master/getStats.py"
    click GA2 "https://github.com/jakekandell/nba-predict/blob/master/availableStats.py"
    click GA3 "https://github.com/jakekandell/nba-predict/blob/master/getDailyMatchups.py"
    click GA4 "https://github.com/jakekandell/nba-predict/blob/master/customHeaders.py"
    click DP1 "https://github.com/jakekandell/nba-predict/blob/master/standardizeStats.py"
    click DP2 "https://github.com/jakekandell/nba-predict/blob/master/configureCWD.py"
    click DP3 "https://github.com/jakekandell/nba-predict/blob/master/teamIds.py"
    click MT1 "https://github.com/jakekandell/nba-predict/blob/master/createModel.py"
    click MT2 "https://github.com/jakekandell/nba-predict/blob/master/SavedModels/finalized_model.pkl"
    click PE1 "https://github.com/jakekandell/nba-predict/blob/master/nbaPredict.py"
    click PE2 "https://github.com/jakekandell/nba-predict/blob/master/makePastPredictions.py"
    click UT "https://github.com/jakekandell/nba-predict/blob/master/requirements.txt"

    %% Class Definitions for Colors and Styles
    classDef external fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef acquisition fill:#98fb98,stroke:#333,stroke-width:2px;
    classDef preprocessing fill:#ffebcd,stroke:#333,stroke-width:2px;
    classDef model fill:#ffa07a,stroke:#333,stroke-width:2px;
    classDef prediction fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef storage fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef utility fill:#87cefa,stroke:#333,stroke-width:2px;
```
