FPL Copilot
Fantasy Premier League decision support: who to start, who to captain, which
transfers are worth a hit, and when to play chips, with every recommendation
explained by the numbers behind it. An iOS and Android app with a web
dashboard, on a FastAPI backend.
The advice comes from a transparent projection model and exact optimisers,
not a language model: every number traces back to FPL data, and the solvers
say when an answer is proven optimal.
What is in this repository
| Folder | What | Stack |
|---|
backend/ | API, projection model, optimisers, scheduled refresh, accounts and billing | Python 3.12, FastAPI, SQLAlchemy (async), Alembic, OR-Tools |
mobile/ | The iOS and Android app | Expo SDK 57, React Native, Expo Router, TanStack Query |
frontend/ | Web dashboard for signed-in users | Next.js 16, React 19, Tailwind |
docs/ | Developer documentation | |
Hosted on free tiers: Render (API), Vercel (web), Supabase (Postgres and
Auth), Upstash (Redis and QStash), RevenueCat (billing), Sentry and
Healthchecks.io (monitoring).
Quick start
You need Python 3.12 (3.14 is too new: asyncpg and pydantic-core have no
wheels for it), Node.js 22, and either Docker or free Supabase and Upstash
accounts.
1. Database and Redis
Locally, with Docker:
docker compose up -d postgres redis
That matches the backend's default DATABASE_URL and REDIS_URL, so delete
those two lines from backend/.env after copying it in the next step.
Without Docker, create a free Supabase project (Settings → Database → URI,
with the scheme changed to postgresql+asyncpg://) and a free Upstash Redis
database, and put their URLs in backend/.env.
2. Backend
Windows:
cd backend
copy .env.example .env
.\setup.bat
macOS and Linux:
cd backend
cp .env.example .env
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
Then, with the virtual environment active, create the tables and start the
API:
alembic upgrade head
uvicorn app.main:app --reload --port 8000
(.\start.bat does the second line on Windows.) Check
http://localhost:8000/api/v1/health returns "status": "ok"; the interactive
API docs are at http://localhost:8000/api/docs.
3. Load FPL data (the worker)
There is no separate worker process. All background work is one refresh job,
triggered over HTTP. Locally, with JOB_TOKEN empty, it needs no token:
curl -X POST "http://localhost:8000/api/v1/jobs/refresh"
It pulls players and fixtures from the live FPL API, builds projections and
raises alerts; the first run takes a minute or two. To keep data fresh while
you work, set SCHEDULER_ENABLED=true in backend/.env and restart the API;
it then refreshes every REFRESH_INTERVAL_MINUTES.
With AUTH_REQUIRED=false (the local default) you can call team endpoints
from the API docs without signing in, e.g. GET /api/v1/decisions/{your FPL team id}.
4. Web dashboard
cd frontend
npm install
cp .env.example .env.local
npm run dev
Open http://localhost:3000. The dashboard requires sign-in, so it needs a
Supabase project with Apple or Google configured
(docs/AUTHENTICATION.md) and its URL
and publishable key in .env.local. If you run on another port, add that
origin to CORS_ORIGINS in backend/.env and to Supabase's redirect URLs.
5. Mobile app
The app needs a development build (Expo Go lacks its native modules):
cd mobile
npm install
cp .env.example .env
npx expo run:android
Point EXPO_PUBLIC_API_URL at your computer's LAN IP, or 10.0.2.2 from the
Android emulator. Full instructions: docs/MOBILE_APP.md.
6. Tests
Install the backend test dependencies once inside the virtual environment
(setup.bat installs only the runtime ones):
pip install -r requirements-dev.txt
Then:
cd backend && .\test.bat
cd mobile && npm test
On macOS and Linux run the backend tests with
DATABASE_URL="sqlite+aiosqlite:///:memory:" ENVIRONMENT=test pytest -m "not network".
Everything else, including Maestro end-to-end tests: docs/TESTING.md.
Documentation
| Document | Covers |
|---|
| ARCHITECTURE.md | Components, request flow, the refresh pipeline, data model, design decisions |
| AUTHENTICATION.md | Sign-in, token verification, authorisation, FPL team ownership, account deletion |
| PAYMENTS.md | Store billing via RevenueCat, the trial, entitlements, the webhook |
| MOBILE_APP.md | The Expo app: features, structure, running, builds |
| API.md | Conventions, errors, rate limits, and every route with its access level |
| TESTING.md | Suites, how to run them, CI, manual release checks |
| DEPLOYMENT.md | First deploy, routine deploys, migrations, rollback, app releases |
| STORE_LISTING.md | Store text, App Review notes, the review team, privacy and data safety answers |
| ENVIRONMENT_VARIABLES.md | Every setting, where it is read and where it is set |
| OBSERVABILITY.md | Logging, error and crash tracking, job and webhook monitoring, runbook |
Status
The backend, web dashboard and mobile app are feature complete for a first
release and covered by automated tests. Not yet done before launch: running
the pending migrations and production configuration, real-device testing of
sign-in, purchases and push, and submitting the store listings
(STORE_LISTING.md). See
DEPLOYMENT.md and the release checklist in
SECURITY.md.
