How samuarg/nba-mvp-predictor works
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.