RiftCoach

Personalised, on-demand champion-pool coaching for League of Legends players. RiftCoach ingests your recent matches, compares your stats to curated Challenger/Grandmaster datasets, and returns actionable steps in seconds.

Highlights

• Async FastAPI backend with Celery workers keeps the API responsive while heavy analyses run in the background.
• Champion taxonomy + embedding engine produce meaningful pool cohesion scores and role-aware swap suggestions.
• Daily pro index refresh keeps comparisons grounded in up-to-date high-Elo data.
• Next.js 14 frontend provides a polished entry point for players to submit Riot IDs and track job status.

Architecture at a Glance

• Backend – apps/backend, FastAPI (app/main.py) with /coach/analyze + /coach/analyze/{job_id}. Celery (app/celery_app.py) executes analysis (tasks/analyze.py) and scheduled pro index refreshes (tasks/pro_index.py). Riot API access is handled by a shared RiotClient (app/utils/riot.py).
• Frontend – apps/frontend, Next.js 14 + Tailwind + shadcn/ui. The UI submits jobs to the backend and explains how RiftCoach works.
• Data – Cached Riot payloads live under data/raw/<puuid>/; Challenger/Grandmaster projections sit in data/pros/<region>/index.jsonl. These directories are git-ignored so large caches stay local.
• Infra – AWS CDK scaffolding (infra/) prepared for future deployment automation. Production Dockerfiles target EC2 hosts (backend + worker) and static hosting for the frontend.

Quick Start (Docker Compose)

Prerequisites: Docker Desktop (or Docker Engine), a Riot API key, and make (optional convenience).

1. Duplicate .env.local and fill in the blanks:

   copy .env.local .env.local.dev
   # edit .env.local.dev and replace RIOT_API_KEY with your key

   Docker Compose reads .env.local by default, so either edit the file in place or point env_file to your copy.
2. Start the stack:

   make up
   # or without make:
   docker compose up --build

3. Visit http://localhost:3000 to access the frontend. The backend listens on http://localhost:8000 and exposes a /docs Swagger UI.
4. When finished, shut everything down with make down or docker compose down.

Windows Helpers

• PowerShell: .\scripts\riftrewind.ps1 up | down | logs | build-prod
• Command Prompt: scripts\riftrewind.cmd up | down | logs | build-prod

Manual Development Workflows

Backend (FastAPI + Celery)

cd apps/backend
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload
celery -A app.celery_app.celery_app worker --loglevel=info

Set the same environment variables as in .env.local (at minimum RIOT_API_KEY, CELERY_BROKER_URL, CELERY_RESULT_BACKEND).

Frontend (Next.js)

cd apps/frontend
npm install
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
npm run dev    # http://localhost:3000

API Cheatsheet

• POST /coach/analyze

  curl -s http://localhost:8000/coach/analyze \
    -H "Content-Type: application/json" \
    -d '{"game_name":"Sneaky","tag_line":"NA1","region":"americas","queue":420,"limit":50}'

  Response:

  { "job_id": "e3c3a6f1-...", "status": "ok" }

• GET /coach/analyze/{job_id}

  curl -s http://localhost:8000/coach/analyze/e3c3a6f1-...

  Returns "running" until complete, then a full AnalyzeResponse containing:
  • top 5 champions with stats, winrate, and taxonomy metadata,
  • a recommended swap (drop/add champion ids + similarity),
  • the closest Challenger/Grandmaster “pro twin”,
  • the biggest statistical delta to focus on,
  • session-by-session winrate progression.

If Riot’s API throttles or the job fails, the status endpoint surfaces a friendly error message.

Data & Background Jobs

• Match caches are stored on disk at data/raw/<puuid>/. Each directory contains per-match JSON files, a manifest.json index, and a compatibility matches.json.
• The pro index is refreshed daily by Celery Beat. To run it manually:

  python -m apps.backend.app.services.pro_index_builder update-region \
    --region europe --platform EUW1 --queue 420 --limit 50

  This command requires a Riot API key and writes to data/pros/europe/index.jsonl.
• Sample payloads under sample_data/ unblock development without live API access.

Testing

python -m pytest

• tests/test_ingest_local.py covers caching, Riot ID resolution, and year-based ingestion.

Environment Variables

Variable	Description	Default
RIOT_API_KEY	Required to call Riot’s Match-V5 and account APIs.	none
CELERY_BROKER_URL	Celery broker (Redis by default in Docker Compose).	redis://redis:6379/0
CELERY_RESULT_BACKEND	Celery result backend.	Same as broker
DEFAULT_REGION	Fallback Riot regional shard.	europe
DEFAULT_QUEUE	Ranked queue id.	420
USER_RECENT_MATCHES	Default number of matches to analyse.	50
API_ALLOWED_ORIGINS	Comma-separated CORS allowlist for the API.	*
NEXT_PUBLIC_API_URL	Frontend environment variable pointing to the API base URL.	http://localhost:8000

See apps/backend/app/core/config.py for additional toggles (ROLE_HARD_FILTER, embedding weights, cache TTL).

Repository Layout

├── apps
│   ├── backend        # FastAPI app, Celery tasks, services, data helpers
│   └── frontend       # Next.js UI
├── data               # Local caches (git-ignored)
├── docs               # Architecture, run-books, onboarding material
├── infra              # CDK placeholders
├── scripts            # Cross-platform tooling and utilities
├── tests              # Pytest suite
└── docker-compose.yml # Local stack orchestration

License

MIT – see LICENSE.

---

Questions or ideas? Open an issue or reach out via the project discussions. Contributions are welcome!