🚧 THIS PROJECT IS STILL UNDER CONSTRUCTION! 🚧

NBA Elo Simulator 🏀

Inspired by Mr V's Garage F1 ELO Engine, this project aims to simulate an Elo engine on NBA game data.

Note: Data used in this project was web scraped from basketball-reference.com and wikipedia.org.

Getting Started

The following instructions will guide you through setting up a copy of the project on your local machine for development and testing purposes.

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 22 — use nvm: nvm install (reads .nvmrc)
• pnpm 10 — corepack enable && corepack prepare pnpm@10 --activate
• Python 3.11+ with uv — pip install uv
• PostgreSQL — running locally with a database named nba_elo

Installation

1. Clone the repository

   git clone https://github.com/m1nce/nba-rating.git
   cd nba-rating

2. Set up environment variables

   cp .env.example .env

   Edit .env and update DATABASE_URL if your PostgreSQL credentials differ from the defaults:

   DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost/nba_elo
   

3. Install Python dependencies

   uv sync

4. Install frontend dependencies

   cd frontend && pnpm install && cd ..

Data Setup

5. Scrape game data (outputs data/1975-2024.csv — takes several minutes due to rate limiting)

   uv run python -m backend.NBAScraper --beginning 1975 --end 2024

6. Migrate data and seed Elo ratings into PostgreSQL

   uv run python -m backend.migrate

Running the App

7. Start the backend (API available at http://127.0.0.1:8000)

   uv run uvicorn backend.app.main:app --reload

8. Start the frontend (in a separate terminal, available at http://localhost:5173)

   cd frontend && pnpm run dev

Built With

Major frameworks/libraries/languages used in this project:

• 
• 
• 
• 

License

Distributed under the MIT License. See LICENSE for more information.