TACTIQ.gg — AI Assistant Coach for Esports

A demo production-feeling project: Next.js frontend + FastAPI backend + GPT-5 analysis.

Features:

• FastAPI backend with endpoints: /match/{id}, /analysis/{id}, /recommendations/{id}
• Rule-based mistake detection and pattern analysis
• GPT-5 (OpenAI Responses API) integration for coach recommendations
• Next.js 14 (App Router) frontend with dark esports UI, Tailwind, Framer Motion, Recharts

Quick start (Windows PowerShell):

1. Backend

• cd backend
• python -m venv .venv
• ..venv\Scripts\Activate.ps1
• pip install -r requirements.txt
• copy .env.example .env and set OPENAI_API_KEY
• uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

2. Frontend

• cd web
• npm install
• npm run dev (opens at http://localhost:3000)

Docker (one-command)

• Ensure Docker is installed and running
• From the project root run: docker compose up --build

This will build and run both backend (http://localhost:8000) and frontend (http://localhost:3000). The frontend will talk to the backend via the service name backend in docker-compose.

Optional helper (Windows PowerShell): run .\\docker-start.ps1 to build, start, wait for backend health, and open the dashboard automatically.

Screenshot-ready routes:

• Dashboard: http://localhost:3000/dashboard
• Player detail: http://localhost:3000/player/<player_id>
• Recommendations / coach: http://localhost:3000/recommendations

API Notes:

• /analysis/{match_id} now includes timeline (array of points with t, label, win in 0..1) and event_deltas (array of events with timestamp, delta, type, winProbBefore, winProbAfter).
• /coach/{match_id} returns structured JSON when AI can produce it, with retries and schema validation; if AI fails a human-friendly fallback message is returned in the coach field.

CI: E2E Docker smoke tests

• A GitHub Actions workflow .github/workflows/e2e-docker.yml will spin up the prod compose (docker-compose.yml + docker-compose.prod.yml), wait for backend health, and run the E2E smoke tests in tests/e2e/test_docker_smoke.py which validate /health, /analysis/match_sample_1, and /coach/match_sample_1.
• The E2E test uses Python requests; the backend requirements.txt includes requests so CI can run the smoke test easily.

Run E2E smoke tests locally (PowerShell):

1. Start production-style services and run tests with the helper script (the helper will wait for the backend and run pytest): .\scripts\run-e2e.ps1

2. Or manually: docker compose -f docker-compose.yml -f docker-compose.prod.yml up --build -d python -m pip install -r backend/requirements.txt pytest -q tests/e2e/test_docker_smoke.py docker compose -f docker-compose.yml -f docker-compose.prod.yml down -v

Notes:

• To run in detached mode: docker compose up -d --build
• To stop and remove containers: docker compose down
• Ensure you pass OPENAI_API_KEY or OPENROUTER_API_KEY as environment variables when running Docker if you want AI recommendations. Example (PowerShell): $env:OPENAI_API_KEY="sk-..."; docker compose up --build

Notes:

• The recommendations endpoint requires a valid OpenAI API key with access to GPT-5. Set OPENAI_API_KEY in backend .env.
• Optional: you can also configure OpenRouter as a fallback by setting OPENROUTER_API_KEY, OPENAI_BASE_URL (e.g., https://openrouter.ai/api/v1), and DEFAULT_LLM (e.g., openai/gpt-4o-mini) in .env — the backend will use OpenAI when OPENAI_API_KEY is set and OpenRouter when OPENAI_API_KEY is not configured but OPENROUTER_API_KEY is present.
• All sample match data is in backend/app/sample_data/ (e.g., match_sample_1.json, lol_match_sample.json, valorant_match_sample.json).
• Run backend tests with python -m pytest -q (see backend/run_tests.ps1).

Development

• The project is modular and designed for hackathon/demo use. For production harden auth and secrets, add database migrations, rate-limiting, tests, and CI.

Files of interest

• backend/app/main.py — API routes
• backend/app/services/mistakes.py — rule-based mistake detection
• backend/app/services/gpt_service.py — GPT-5 prompt + wrapper
• web/app — Next.js App Router pages and components

Enjoy! 🚀