# lblommesteyn/canada_basketball_fiba architecture

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

- Interactive diagram: https://gitdiagram.com/lblommesteyn/canada_basketball_fiba
- Repository: https://github.com/lblommesteyn/canada_basketball_fiba

## Overview

##### Project type and purpose
- This is a data-analysis pipeline (an open-source tool) that ingests FIBA play-by-play CSVs, runs a series of models (win-probability, Δ-WPA), a Monte Carlo analysis, and produces figures and CSV outputs.
- It’s invoked via a CLI (`timeout_pipeline.py`) and configured with `config.json` and the CSVs in `data/`.

##### File structure
- Top-level:
- `data/` – raw input CSV files
- `timeout_pipeline.py` (aka `timeout_analysis_pipeline.py`) – the orchestration entry point
- `requirements.txt` – Python dependencies
- `config.json` – pipeline parameters
- `old_analysis_and_testing/` – exploratory notebooks and scripts (archival)
- `README.md`, `Summary.md`, `technotes_and_hiccups.md` – documentation
- No “frontend” or “backend” per se—this is a batch pipeline with modular stages.

##### README for additional insights
- Describes 5 key steps:
1. ETL (load & clean)
2. Win-Probability logistic model
3. Δ-WPA Gradient-Boosting regressor
4. Monte Carlo “traffic lights”
5. Figures (heat-map, charts, cumulative gain)
- Outputs go to an `outputs/` directory at runtime.

##### Main components and interactions
a. Data Store
- Raw CSVs in `data/`
- Config in `config.json`
b. ETL Module
- Reads CSVs with pandas, cleans and normalizes events
- Produces a master DataFrame passed downstream
c. Win-Prob Model Module
- Fits or loads a logistic regression on `score_diff`, `time_remaining`, `period_num`
- Appends `wp` (win probability) column
d. Δ-WPA Regressor Module
- Uses gradient boosting (e.g., XGBoost or sklearn’s GBM) to predict changes in win probability given context features (runs, timeouts left)
e. Monte Carlo Module
- Bootstraps residuals of Δ-WPA model to assign green/yellow/red flags
f. Visualization / Reporting Module
- Generates heat-map, situational bar charts, cumulative gain plots (matplotlib/seaborn)
g. Outputs
- Final CSVs and figures land in `outputs/`

##### Architectural patterns and design principles
- Modular pipeline: each stage is its own Python function or class
- Single orchestration script (CLI) that wires modules together
- Configuration-driven (via `config.json`) rather than hard‐coded
- Clear separation of “analysis experiments” (`old_analysis_and_testing/`) vs. “production pipeline”

##### Important reminders
- Be very detailed: break the Δ-WPA stage into “feature engineering” vs. “model training vs. prediction” if desired
- Configuration inputs (CLI args, `config.json`)
- Do not overthink: maximize clarity by showing every discrete component and its connections

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    Orchestrator["timeout_analysis_pipeline.py"]:::code
    click Orchestrator "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"

    %% Data Inputs
    DataRaw[(data/)]:::data
    click DataRaw "https://github.com/lblommesteyn/canada_basketball_fiba/tree/master/data/"
    Config{{"config.json"}}:::config
    click Config "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/config.json"

    %% Modules
    subgraph "Pipeline Modules"
        direction TB
        ETL["ETL Module\n(load & clean)"]:::etl
        WinProb["Win-Probability Model"]:::modeling
        DeltaWPA["Δ-WPA Regressor"]:::modeling
        Monte["Monte Carlo Module"]:::monte
        Reporting["Visualization / Reporting"]:::reporting
    end
    click ETL "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"
    click WinProb "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"
    click DeltaWPA "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"
    click Monte "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"
    click Reporting "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/timeout_analysis_pipeline.py"

    %% Outputs
    Outputs[(outputs/)]:::outputs
    click Outputs "https://github.com/lblommesteyn/canada_basketball_fiba/tree/master/outputs/"

    %% Archived Research Sandbox
    Sandbox["old_analysis_and_testing/"]:::research
    click Sandbox "https://github.com/lblommesteyn/canada_basketball_fiba/tree/master/old_analysis_and_testing/"

    %% Documentation & Dependencies
    Req["requirements.txt"]:::docs
    click Req "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/requirements.txt"
    Docs1["README.md"]:::docs
    click Docs1 "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/README.md"
    Docs2["Summary.md"]:::docs
    click Docs2 "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/Summary.md"
    Docs3["technotes_and_hiccups.md"]:::docs
    click Docs3 "https://github.com/lblommesteyn/canada_basketball_fiba/blob/master/technotes_and_hiccups.md"

    %% Orchestration Flow
    Orchestrator -->|invokes| ETL
    Orchestrator -->|invokes| WinProb
    Orchestrator -->|invokes| DeltaWPA
    Orchestrator -->|invokes| Monte
    Orchestrator -->|invokes| Reporting

    %% Data Flow
    DataRaw -->|raw CSVs| ETL
    ETL -->|"cleaned DataFrame"| WinProb
    WinProb -->|"features + wp"| DeltaWPA
    DeltaWPA -->|"residuals"| Monte
    Monte -->|"flags"| Reporting
    Reporting -->|"plots + CSVs"| Outputs

    %% Config Injection
    Config -.->|parameters| ETL
    Config -.->|parameters| WinProb
    Config -.->|parameters| DeltaWPA
    Config -.->|parameters| Monte
    Config -.->|parameters| Reporting

    %% Side Components
    Sandbox -.->|exploratory only| Orchestrator
    Req -.->|defines deps| Orchestrator
    Docs1 -.->|reference| Orchestrator
    Docs2 -.->|reference| Orchestrator
    Docs3 -.->|reference| Orchestrator

    %% Styles
    classDef data fill:#b3e6ff,stroke:#333,stroke-width:1px;
    classDef config fill:#e6e6e6,stroke:#333,stroke-width:1px;
    classDef code fill:#f0f0f0,stroke:#333,stroke-width:1px;
    classDef etl fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef modeling fill:#ccffcc,stroke:#333,stroke-width:1px;
    classDef monte fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef reporting fill:#ffd8a8,stroke:#333,stroke-width:1px;
    classDef outputs fill:#ffddb3,stroke:#333,stroke-width:1px;
    classDef research fill:#f5f5f5,stroke:#333,stroke-width:1px;
    classDef docs fill:#d9d9d9,stroke:#333,stroke-width:1px;
```
