# jaynik-s/nba_insights architecture

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

- Interactive diagram: https://gitdiagram.com/jaynik-s/nba_insights
- Repository: https://github.com/jaynik-s/nba_insights

## Overview

##### Main Components
- Frontend Interface:
- This is represented by the HTML templates (located in the templates folder such as cluster.html, compare.html, etc.) and static assets (from the static folder with style.css). These files form the web pages presented to users.
- Backend Logic:
- Flask Application: The central component is app.py, which handles routing, user input, and overall orchestration.
- Supporting Scripts:
▪ career_stats.py likely provides functions related to retrieving or processing player statistics.
▪ centroid_clustering.py contains the implementation and parameters for the K-Means clustering algorithm used in defining archetypes.
- Data Management:
- Data Files: The data folder holds essential files – archetype_centroids.json for clustering centroids and scaler/pca.pkl for the preprocessing model artifacts (scaler and PCA).
- External Services:
- nba_api: Acts as the external data provider for NBA player statistics.
- Visualization:
- Matplotlib is used (as mentioned in the README) to generate plots showing player coordinates relative to archetype centroids.

##### Mapping Relationships and Interactions
- User Interaction: A user initiates an action (like searching for a player or comparing players) via the frontend. Their input is sent to the Flask application.
- Request Handling: app.py receives the request and invokes helper modules like career_stats.py to fetch data from the nba_api.
- Data Processing Pipeline:
▪ After data is fetched, the information is transformed using preprocessing tools (loaded scaler.pkl and pca.pkl) following the steps outlined in the README.
▪ Clustering: centroid_clustering.py is used to compare the processed data with precomputed archetype centroids from archetype_centroids.json to determine the player's archetypes.
- Visualization: Based on the computed results, Matplotlib generates a visualization (graph) that is rendered on the webpage.
- Caching Mechanism: There is a caching system (involving player_stats_cache.json in the data folder) to reduce the number of API calls.

##### Architectural Patterns and Technologies
- Pattern: There is a clear separation of concerns (data retrieval, processing, and presentation). The use of Flask’s routing helps encapsulate different functionalities (such as player search and comparison).
- Technologies: Python libraries for data processing and visualization, Flask for web routing, nba_api for external data, and JSON/Pickle files for model and clustering parameters.
- Design Principle: Modularity is strongly favored, so each component (data retrieval, clustering, visualization) is handled by specific scripts/modules, making the system easier to maintain and extend.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Define subgraphs
    subgraph "Frontend"
        FE1("HTML Templates"):::frontend
        FE2("Static Assets"):::frontend
    end

    subgraph "Backend"
        BE1("Flask Application (app.py)"):::backend
        BE2("Data Retrieval (career_stats.py)"):::backend
        BE3("Clustering Module (centroid_clustering.py)"):::backend
        BE4("Visualization (Matplotlib)"):::backend
    end

    subgraph "Data Management"
        DM1("Clustering Centroids (archetype_centroids.json)"):::data
        DM2a("Scaler (scaler.pkl)"):::data
        DM2b("PCA (pca.pkl)"):::data
        DM3("Player Stats Cache (player_stats_cache.json)"):::data
    end

    EX("nba_api"):::external
    USER("User"):::external

    %% Define Relationships
    USER -->|"access"| FE1
    FE1 -->|"submits_request"| BE1
    FE1 -->|"loads"| FE2

    BE1 -->|"invokes_stats"| BE2
    BE2 -->|"calls"| EX
    EX -->|"returns_data"| BE2
    BE2 -->|"checks_cache"| DM3

    BE1 -->|"triggers_clustering"| BE3
    BE3 -->|"loads_centroids"| DM1
    BE3 -->|"loads_scaler"| DM2a
    BE3 -->|"loads_PCA"| DM2b

    BE1 -->|"generates_visual"| BE4
    BE4 -->|"renders_output"| FE1

    %% Class Definitions for Colors
    classDef frontend fill:#cce5ff,stroke:#0d6efd,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#198754,stroke-width:2px;
    classDef data fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#dc3545,stroke-width:2px;

    %% Click Events
    click FE1 "https://github.com/jaynik-s/nba_insights/tree/main//templates"
    click FE2 "https://github.com/jaynik-s/nba_insights/tree/main//static"
    click BE1 "https://github.com/jaynik-s/nba_insights/blob/main//app.py"
    click BE2 "https://github.com/jaynik-s/nba_insights/blob/main//career_stats.py"
    click BE3 "https://github.com/jaynik-s/nba_insights/blob/main//centroid_clustering.py"
    click DM1 "https://github.com/jaynik-s/nba_insights/blob/main//data/archetype_centroids.json"
    click DM2a "https://github.com/jaynik-s/nba_insights/blob/main//data/scaler.pkl"
    click DM2b "https://github.com/jaynik-s/nba_insights/blob/main//data/pca.pkl"
    click DM3 "https://github.com/jaynik-s/nba_insights/blob/main//data/player_stats_cache.json"
```
