uvicorn

• 🔍 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

Prerequisites

• Docker Engine with Compose v2
• Riot API Key from [Riot Developer Portal](https://developer.riotgames.com/)

1. Setup

```bash

git clone

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

```bash

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!

Player Analysis Algorithm

Analyzes players using 9 weighted factors:

| Factor | Weight | What It Checks |

| ----------------------- | ------ | ---------------------------- |

| Rank Discrepancy | 20% | Performance vs rank mismatch |

| Win Rate Analysis | 18% | High win rates over time |

| Performance Trends | 15% | KDA consistency patterns |

| Win Rate Trends | 10% | Improvement patterns |

| Role Performance | 9% | Multi-role versatility |

| Rank Progression | 9% | Fast climbing detection |

| Account Level | 8% | Low account level |

| Performance Consistency | 8% | Variance analysis |

| KDA Analysis | 3% | Kill/death ratios |

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

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)

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

```bash

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)
• Dockerf