League Analysis - Analyze Player, Detect Smurfs & More

A League of Legends player analysis platform that identifies potential smurf accounts using advanced algorithms and Riot API data.

🎯 What It Does

• 🔍 Player Analysis: Analyzes 9 factors to detect likely smurf accounts
• ⚖️ Matchmaking Analysis: Analyzes average win rates of teammates vs opponents
• 📊 Player Analytics: Match history, performance stats, and rank tracking
• ⚡ Real-time Monitoring: Automated background jobs for continuous updates
• 🌍 Multi-Region Support: Works on all major Riot API regions

🚀 Quick Start

Prerequisites

• Docker Engine with Compose v2
• Riot API Key from Riot Developer Portal

1. Setup

git clone <repository-url>
cd riot-api-project
cp .env.example .env
# Edit .env with database credentials and JWT secret
# Riot API key will be set via web UI after startup

2. Start Development

docker compose up -d                    # Start services with hot reload

3. Access the App

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Hot reload is automatic: Changes to Python files auto-restart the backend via uvicorn --reload. Changes to TypeScript/JSX files hot reload the frontend via next dev. No manual restart needed!

🎯 Key Features

Player Analysis Algorithm

Analyzes players using 9 weighted factors:

Confidence Levels:

• 🔴 High (80%+): Very likely smurf
• 🟡 Medium (60-79%): Probable smurf
• 🟢 Low (40-59%): Possible smurf

Web Interface

• Player Analysis: Search players and run analysis
• Matchmaking Analysis: Analyze matchmaking fairness for tracked players
• Tracked Players: Monitor players automatically
• Background Jobs: View system status and job history

🏗️ Tech Stack

Backend

• Python 3.13 + FastAPI + PostgreSQL
• SQLAlchemy + Pydantic for type safety
• APScheduler for background jobs

Frontend

• Next.js 15 + React 19 + TypeScript
• shadcn/ui + Tailwind CSS
• TanStack Query for data fetching

Infrastructure

• Docker + Docker Compose + Docker Bake
• Modern multi-stage builds with BuildKit
• Multi-environment support (dev/prod)

🛠️ Development

Both frontend and backend support automatic hot reload via volume mounts—just save files, no restart needed:

docker compose up -d                                # Start services
docker compose logs -f                              # View all logs
docker compose logs -f backend                      # View backend logs only
docker compose exec backend uv run alembic current  # Check migration status
docker compose down                                 # Stop services

How hot reload works:

• Backend: uvicorn --reload watches Python files and auto-restarts on changes
• Frontend: next dev watches TypeScript/JSX files and hot reloads on changes
• Two-way sync: Volume mounts (./backend:/app, ./frontend:/app) sync code changes to containers and generated files (like Alembic migrations) back to host

When to rebuild containers:

• Dependency changes (pyproject.toml, package.json)
• Dockerfile modifications
• System package changes

For detailed build info and production deployment, see docker/AGENTS.md and scripts/AGENTS.md.

📊 Background Jobs

The system runs two automated jobs:

1. Tracked Player Updater (every 2 minutes)

   • Fetches new matches for monitored players
   • Updates ranks and statistics

2. Player Analyzer (continuous)

   • Runs player analysis on players with 20+ matches
   • Stores analysis results with confidence scores

Monitor jobs at: http://localhost:3000/jobs

🔧 API Endpoints

Players

• GET /api/v1/players/search - Search by Riot ID or summoner name
• POST /api/v1/players/{puuid}/track - Add player to tracking
• DELETE /api/v1/players/{puuid}/track - Remove from tracking

Matches & Analysis

• GET /api/v1/matches/player/{puuid} - Get match history
• POST /api/v1/player-analysis/analyze - Run player analysis
• GET /api/v1/player-analysis/player/{puuid}/latest - Get latest analysis
• `POST /api/v1/

...