FootStats AI

A personal football performance tracker with an AI intelligence layer: match reports, a self-improving rating predictor, workload/fatigue scoring, a "form fingerprint" similarity search, a conversational data agent, and an autonomous weekly coach agent.

Originally a console/CLI application built for a Data Structures and Algorithms course, rebuilt as a full-stack Python/React application with an AI layer using Groq and Gemini, and a custom broadcast-style frontend rather than a generic admin-dashboard template.

Tech Stack

Backend

• FastAPI
• PostgreSQL + SQLAlchemy 2.0, with the pgvector extension for embeddings
• Alembic for migrations
• Celery + Redis for scheduled/background jobs
• JWT auth (python-jose) + bcrypt (passlib)
• Pydantic v2 schemas

AI / intelligence layer

• Groq API (Llama 3.3 70B) for fast conversational responses
• Gemini API (Gemini 1.5 Flash) for longer structured generation and as a fallback
• llm_router.py — tries Groq first, falls back to Gemini
• scikit-learn for the match-rating predictor
• LangGraph for the autonomous weekly coach agent
• pgvector for the form fingerprint embedding similarity search

Frontend

• React 19 + TypeScript + Vite
• Tailwind CSS with a custom design system
• Framer Motion for animation
• Recharts for data visualization

Features

Core

• Auth: register, login, forgot/reset password with expiring single-use tokens
• Match Manager: log matches with minute-by-minute events (goals, cards, assists, penalties, Man of the Match); totals are derived automatically from events
• Training Log: fitness/technical/tactical sessions with duration and intensity
• Fixture Scheduler: queue fixtures, mark one played to auto-create its match record
• Season Manager: season summaries, switching seasons without losing history
• Career Records: lifetime bests (highest rating, longest win streak, biggest victory, favorite opponent, etc.), computed automatically
• Season Comparison: compare any two seasons side by side with charts
• Achievements & Badges: milestone-based unlocks with progress tracking

AI

• AI match report generator
• Rating predictor with a self-correcting feedback loop (predicted vs. actual rating logged and retrained periodically) and an accuracy-over-time chart
• ACWR (acute:chronic workload ratio) fatigue/injury-risk score
• Form Fingerprint: embedding-based similarity search across historical form periods ("am I playing like my best month?")
• Conversational data agent with tool-calling and persistent multi-turn memory
• Autonomous weekly coach agent (LangGraph) producing a structured weekly review
• AI training planner based on recent form, workload, and upcoming fixtures
• AI end-of-season review (executive summary, weaknesses, recommendations, goals)

Screenshots

Screenshots are available in the screenshots/ directory at the root of this repository.

Project Structure

football-tracker/
├── backend/
│   ├── app/
│   │   ├── models/        SQLAlchemy models
│   │   ├── schemas/       Pydantic request/response schemas
│   │   ├── routers/       FastAPI route handlers
│   │   ├── services/      Business logic (matches, seasons, AI features)
│   │   ├── ml/            scikit-learn rating predictor
│   │   ├── agents/        Chat agent + LangGraph weekly coach agent
│   │   ├── tasks/         Celery app and scheduled tasks
│   │   └── core/          Security and shared dependencies
│   ├── alembic/           Database migrations
│   ├── tests/             Pytest suite
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── pages/         Route-level views
│   │   ├── components/    Shared UI components
│   │   ├── context/       Auth context
│   │   └── lib/           API client and TypeScript types
│   ├── package.json
│   └── .env.example
├── docker-compose.yml
├── .vscode/
├── screenshots/
└── README.md

Requirements

Python 3.11+, Node.js 20+, PostgreSQL 16 with the pgvector extension, Redis, and Docker Desktop (recommended — the pgvector/pgvector:pg16 image ships pgvector already built, and Redis has no native Windows build).

Setup

git clone <your-repo-url> footstats
cd footstats

# backend
cd backend
copy .env.example .env      # macOS/Linux: cp .env.example .env
python -m venv .venv
.venv\Scripts\activate      # macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt

# frontend
cd ../frontend
copy .env.example .env      # macOS/Linux: cp .env.example .env
npm install

Fill in backend/.env: generate SECRET_KEY with python -c "import secrets; print(secrets.token_hex(32))", and add GROQ_API_KEY / GEMINI_API_KEY (both free tier — console.groq.com, aistudio.google.com/app/apikey). Neither key is required to run the app — AI features fall back to a clear "unavailable" state if unset, and every non-AI feature works with zero keys.

Run migrations (alembic upgrade head), then start everything with:

docker compose up --build

or run each piece natively — API (uvicorn app.main:app --reload), Celery worker (celery -A app.tasks.celery_app worker --loglevel=info --pool=solo on Windows), Celery beat (celery -A app.tasks.celery_app beat --loglevel=info), and frontend (npm run dev).

• Frontend: http://localhost:5173
• API docs: http://localhost:8000/docs

Tests: cd backend && pytest -v (uses in-memory SQLite, no Postgres/Redis needed).

.vscode/launch.json and .vscode/tasks.json have pre-configured debug configs and one-click tasks for all of the above.

Feature Map

Feature	Backend	Frontend
Auth	app/routers/auth.py	pages/Login.tsx, Register.tsx, ForgotPassword.tsx, ResetPassword.tsx
Match Manager + Match Events	app/routers/matches.py, app/services/match_service.py	pages/Matches.tsx
Training Log	app/routers/training.py	pages/Training.tsx
Fixture Scheduler	app/routers/fixtures.py	pages/Fixtures.tsx
Season Manager + Comparison	app/routers/seasons.py, app/services/season_service.py	pages/SeasonSheet.tsx
Career Records	app/routers/career_records.py, app/services/career_record_service.py	pages/CareerRecords.tsx
Achievements & Badges	app/routers/achievements.py, app/services/achievement_service.py	pages/Achievements.tsx
AI Match Report	app/services/match_report_service.py	pages/Matches.tsx
Rating Predictor + self-correcting loop	app/ml/rating_predictor.py, app/tasks/tasks.py	pages/Profile.tsx
ACWR workload score	app/services/acwr_service.py	pages/MatchdayHome.tsx
Form Fingerprint	app/services/form_fingerprint_service.py	pages/Chat.tsx
Conversational Data Agent	app/agents/chat_agent.py, app/agents/tools.py	pages/Chat.tsx
Weekly Coach Agent (LangGraph)	app/agents/weekly_coach_agent.py, app/tasks/celery_app.py	pages/WeeklyReview.tsx
AI Training Planner	app/services/training_planner_service.py	pages/WeeklyReview.tsx
AI Season Review	app/services/season_review_service.py	pages/SeasonSheet.tsx

Design Direction

"Matchday Program" — a broadcast-graphics aesthetic: squad-sheet typography, lower-third stat blocks, a scrolling recent-form ticker, and a rating badge that flips in rather than fades. Type pairing is Oswald (display/headers) and Karla (body). Palette: pitch green (#1B4332), chalk white (#F5F3EC), crimson accent (#D62839), amber accent (#E0A72A), on a near-black (#101410) background.

License

MIT.