# samuarg/nba-mvp-predictor architecture

> Architecture diagram of the GitHub repository samuarg/nba-mvp-predictor, 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/samuarg/nba-mvp-predictor
- Repository: https://github.com/samuarg/nba-mvp-predictor

## Overview

##### Project Type & Purpose
- This project is a machine learning application designed to predict the NBA’s Most Valuable Player using historical and current performance metrics.
- It is a full-stack project with a Python-based backend for data processing, model training/inference, and API services; and a Vue.js–based frontend that displays predictions and analytics.
- Additionally, it features CI/CD pipelines via GitHub Actions, and integrates with an external MongoDB database (configured via the MONGOURI in the backend’s .env file).

##### Main Components & Their File Groupings
A. Frontend (located in the “frontend” directory)
- UI Framework & Build Tool: Vue with Vite (see files like App.vue, main.ts, vite.config.mts)
- Components: Numerous subcomponents such as NavBar, ChartPrediction, HistoricList, MvpChart, PlayerList, PredictionsList, and SideBar (all under frontend/src/components).
- Pages & Layouts: Specific pages (index.vue, historic.vue, about.vue) and layouts (Base.vue in frontend/src/layouts).
- Configuration & Build Files: package.json, package-lock.json, tsconfig files, netlify.toml (indicating deployment to Netlify).
- API Communication: API calls defined in frontend/src/api/mvps.ts connecting with the backend.
- Utilities & Styles: Dedicated folders for assets (NBA logos) and styling (settings.scss).

B. Backend (located in the “backend” directory)
- API & Server: The API is defined in backend/api (e.g., app.py for API endpoints and test_app.py for tests) and the server entry point is in wsgi.py.
- Data Management:
- Raw data and processed data folders are found under backend/data (raw CSV files with NBA stats and processed files like mvps.csv and scaled.csv).
- Models & Predictions:
- The “models” directory contains scripts and artifacts such as Mvp_mlp.py, best_model.pt, model.joblib; these represent the machine learning model code and saved models.
- Notebooks:
- Under backend/notebooks, there are exploratory and analysis notebooks (e.g., plot_importance.py, pre_analyze.py, predict2025.py) that cover data visualization and prediction experimentation.
- Utility Scripts:
- The “scripts” directory has modules such as Predict.py, Processed.py, Scrap.py, dailyPredictions.py, and datasets.py. These are likely scheduled or used to periodically update predictions or process new data.
- Configuration & Dependencies:
- requirements.txt for Python dependencies and instructions in the README for setting up the environment (including the MongoDB URI).
- CI/CD and Workflows:
- The .github directory contains GitHub workflows (daily_predictions.yml, test_backend.yml) that automate testing and deployment processes.

##### Relationships & Data Flows
- The Frontend communicates with the Backend API – requests initiated by the user’s browsing experience (via Axios/fetch calls contained in mvps.ts) reach endpoints defined in backend/api/app.py.
- Within the Backend:
- The API serves as an interface to trigger model predictions (using models in backend/models) and interact with the database.
- Data pipelines (from raw CSV files in data/raw and processed files in data/processed) feed into the machine learning models.
- Utility scripts are likely used to automate data collection, processing, and daily prediction tasks.
- There is an external dependency on a MongoDB instance (configured via a MONGOURI in the .env file), which may be used for data storage, logging, or caching predictions.
- The CI/CD pipelines (.github/workflows) ensure that both the frontend and backend get tested and deployed, integrating with version control and deployment environments (Netlify for the frontend).

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project is clearly divided between the frontend for display and interaction, and the backend for data processing, prediction, and API exposure.
- Modular Architecture: Within both the frontend and backend, functionality is partitioned into focused modules (e.g., individual Vue components; dedicated scripts for prediction and data scraping).
- Pipeline Approach for Machine Learning: Data collection, preprocessing, feature engineering, and model training/inference stages are clearly indicated via the structured data directories and notebooks.
- CI/CD Integration: Automated workflows help maintain code quality and deployment stability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend (Vue.js Application)"
        FE_UI["UI Components"]:::frontend
        FE_Pages["Pages & Layouts"]:::frontend
        FE_API["API Integration"]:::frontend
        FE_Config["Build & Config"]:::frontend
    end

    %% Backend Subgraph
    subgraph "Backend (Python API & ML Pipeline)"
        BE_API["API Service"]:::backend
        BE_Data["Data Management"]:::backend
        BE_Models["ML Models & Artifacts"]:::backend
        BE_Notebooks["Exploratory Notebooks"]:::backend
        BE_Scripts["Utility & Scheduled Scripts"]:::backend
        BE_Config["Configuration & Dependencies"]:::backend
    end

    %% External Components
    MongoDB["MongoDB"]:::external
    CICD["CI/CD (GitHub Actions)"]:::cicd

    %% Relationships between Frontend and Backend
    FE_API -->|"RESTfulCalls"| BE_API

    %% Internal Backend Data Flow
    BE_Data -->|"DataProcessing"| BE_Models
    BE_Models -->|"ModelInference"| BE_API

    %% Database Connection
    BE_API -->|"DBReadWrite"| MongoDB

    %% CI/CD Integration
    CICD -->|"Deploy_Frontend"| FE_Config
    CICD -->|"Deploy_Backend"| BE_Config

    %% Click Events for Frontend Components
    click FE_UI "https://github.com/samuarg/nba-mvp-predictor/tree/main/frontend/src/components"
    click FE_Pages "https://github.com/samuarg/nba-mvp-predictor/tree/main/frontend/src/pages"
    click FE_API "https://github.com/samuarg/nba-mvp-predictor/blob/main/frontend/src/api/mvps.ts"
    click FE_Config "https://github.com/samuarg/nba-mvp-predictor/blob/main/frontend/package.json"

    %% Click Events for Backend Components
    click BE_API "https://github.com/samuarg/nba-mvp-predictor/tree/main/backend/api"
    click BE_Data "https://github.com/samuarg/nba-mvp-predictor/tree/main/backend/data"
    click BE_Models "https://github.com/samuarg/nba-mvp-predictor/tree/main/backend/models"
    click BE_Notebooks "https://github.com/samuarg/nba-mvp-predictor/tree/main/backend/notebooks"
    click BE_Scripts "https://github.com/samuarg/nba-mvp-predictor/tree/main/backend/scripts"
    click BE_Config "https://github.com/samuarg/nba-mvp-predictor/blob/main/backend/requirements.txt"

    %% Click Event for CI/CD Workflows
    click CICD "https://github.com/samuarg/nba-mvp-predictor/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef external fill:#ffffcc,stroke:#000,stroke-width:1px,stroke-dasharray: 5, 5;
    classDef cicd fill:#d3d3d3,stroke:#000,stroke-width:1px,stroke-dasharray: 2, 2;
```
