🏆 FPL Optimizer

A Fantasy Premier League squad optimization tool that helps users make informed decisions about transfers, captain choices, and team selections.

---

🚀 Quick Start

Development (Localhost)

docker compose up -d
./scripts/check-bootstrap.sh

Services Available:

• 🌐 Frontend: http://localhost:3000
• 🔧 Backend API: http://localhost:8000
• 📖 API Docs: http://localhost:8000/docs

Production (Your Domain)

# 1. Configure environment
nano .env backend/.env frontend/.env.local

# 2. Run setup
./scripts/setup-production.sh

# 3. Done!

---

📊 Features

Core Functionality

• Squad Analysis: Import and analyze your FPL team via official API
• Captain Recommendations: AI-powered suggestions based on form, fixtures, and ownership
• Transfer Suggestions: Optimized recommendations within budget constraints
• Player Explorer: Browse and filter top-performing players
• Automatic Gameweek Handling: Auto-syncs data when gameweeks transition

Technical Features

• Auto-Initialization: Bootstrap data syncs automatically on startup
• Background Scheduler: 4 scheduled jobs for data synchronization
  • Hourly bootstrap sync
  • Daily gameweek transition checks
  • Match-day fixture updates
  • Pre-deadline reminders
• Real-time Data: Direct integration with official FPL API
• Intelligent Caching: Redis-powered caching for optimal performance
• Rate Limiting: Respects FPL API limits with intelligent throttling

---

🛠️ Helper Scripts

All scripts located in scripts/ directory:

Check Bootstrap Status

./scripts/check-bootstrap.sh

Shows: Events, Players, Teams count + Current Gameweek

Initialize Bootstrap Manually

./scripts/init-bootstrap.sh

Use this if automatic initialization fails.

View Logs

./scripts/logs.sh backend           # All backend logs
./scripts/logs.sh backend bootstrap # Filter for bootstrap
./scripts/logs.sh frontend          # Frontend logs

Full Diagnostics

./scripts/debug-startup.sh

Runs comprehensive checks on Docker, containers, DB, Redis, FPL API, environment variables, bootstrap data, and scheduler.

Production Setup

./scripts/setup-production.sh

One-command production deployment with diagnostics.

See scripts/README.md for detailed documentation.

---

🏗️ Architecture

fpl/
├── backend/              # FastAPI backend with SQLAlchemy & Redis
│   ├── app/
│   │   ├── api/          # API endpoints
│   │   ├── services/     # Business logic (scheduler, data sync)
│   │   ├── models/       # Database models
│   │   ├── startup.py    # Auto-initialization logic
│   │   └── main.py       # FastAPI app
│   └── requirements.txt
├── frontend/             # Next.js frontend with TypeScript
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── pages/        # Next.js pages
│   │   └── lib/          # Utilities
│   └── package.json
├── scripts/              # Helper scripts for deployment
│   ├── check-bootstrap.sh
│   ├── init-bootstrap.sh
│   ├── debug-startup.sh
│   ├── logs.sh
│   └── setup-production.sh
├── docker compose.yml    # Unified Docker Compose (dev + prod)
├── .env                  # Docker environment (mode switching)
└── DEPLOYMENT.md         # Comprehensive deployment guide

---

📦 Configuration

Root .env - Docker Compose Mode Switching

# Development (default)
ENVIRONMENT=development
DEBUG=true
NEXT_PUBLIC_API_URL=http://localhost:8000

# Production (uncomment to use)
# ENVIRONMENT=production
# DEBUG=false
# NEXT_PUBLIC_API_URL=https://api.fpl.tonyalapatt.in

backend/.env - Backend Application Settings

DATABASE_URL=postgresql://fpl_user:password@db:5432/fpl_db
REDIS_URL=redis://redis:6379/0
DEBUG=false
SECRET_KEY=generate-secure-key
JWT_SECRET_KEY=generate-jwt-key
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-secret
FRONTEND_URL=https://fpl.tonyalapatt.in
CORS_ORIGINS=https://fpl.tonyalapatt.in
FPL_API_BASE_URL=https://fantasy.premierleague.com/api

frontend/.env.local - Frontend Settings

NEXT_PUBLIC_API_URL=https://api.fpl.tonyalapatt.in
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id

See DEPLOYMENT.md for comprehensive configuration guide.

---

🔧 API Documentation

Health Endpoints

• GET /api/health/ - Basic health check
• GET /api/health/ready - Readiness check (DB, Redis, Bootstrap, Scheduler)
• GET /api/health/scheduler - Scheduler status with job details

Key Endpoints

• POST /api/squad/fetch - Fetch user squad from FPL API
• GET /api/squad/{team_id} - Get squad details and statistics
• GET /api/recommendations/captain/{team_id} - Captain recommendations
• GET /api/recommendations/transfers/{team_id} - Transfer suggestions
• GET /api/recommendations/players/top - Top players for transfers
• POST /api/sync/bootstrap - Manual bootstrap sync

Interactive Docs

Visit http://localhost:8000/docs for full Swagger UI documentation.

---

🐳 Docker Commands

# Start services
docker compose up -d

# Stop services
docker compose down

# Rebuild
docker compose up -d --build

# View logs
docker compose logs backend
docker compose logs frontend

# Shell into container
docker compose exec backend bash

# Database shell
docker compose exec db psql -U fpl_user -d fpl_db

---

🏗️ Tech Stack

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy - Database ORM
• APScheduler - Background task scheduling
• Redis - Caching and session storage
• PostgreSQL - Primary database
• Pydantic - Data validation

Frontend

• Next.js 14 - React framework
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS
• Axios - HTTP client

Infrastructure

• Docker - Containerization
• Gunicorn + Uvicorn - Production server

---

🐛 Troubleshooting

Bootstrap Not Initializing?

# 1. Run diagnostics
./scripts/debug-startup.sh

# 2. Check logs
./scripts/logs.sh backend bootstrap

# 3. Manual trigger
./scripts/init-bootstrap.sh

Squad Not Loading?

# Check if bootstrap initialized
./scripts/check-bootstrap.sh

# Verify backend health
curl http://localhost:8000/api/health/ready

Scheduler Not Running?

# Check scheduler status
curl http://localhost:8000/api/health/scheduler

# Restart backend
docker compose restart backend

See DEPLOYMENT.md for comprehensive troubleshooting guide.

---

🎯 Success Indicators

After deployment, verify:

• ✅ ./scripts/check-bootstrap.sh shows data initialized
• ✅ /api/health/ready returns 200 OK
• ✅ /api/health/scheduler shows "running": true
• ✅ Frontend loads and Google Sign-In works
• ✅ Squad data loads successfully

---

📚 Documentation

• DEPLOYMENT.md - Comprehensive deployment guide
• scripts/README.md - Helper scripts documentation
• CLAUDE.md - Application plan and architecture
• API Docs - http://localhost:8000/docs (when running)

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

---

📝 License

This project is licensed under the MIT License.

---

⚡ Performance Notes

• Caching Strategy: Bootstrap data cached 1 hour, user squads 10 minutes
• Rate Limiting: Respects FPL API limits (200 requests/hour)
• Auto-Sync: Background scheduler keeps data fresh automatically
• Database: Optimized queries with proper indexing

---

Last Updated: 2025-10-07 Maintainer: Tony Alapatt