A football prediction and market analysis platform that combines machine learning, Monte Carlo tournament simulation, live football data, and prediction market odds to identify potentially mispriced World Cup betting and prediction markets.
The system uses XGBoost, Logistic Regression, Elo ratings, squad valuations, injuries, lineups, and tournament simulations to estimate fair probabilities and compare them against market prices.
Because the entire application (Database, FastAPI Backend, Next.js Frontend) is heavily containerized, you only need Docker and Git to run this project. You do not need Python, Node.js, or PostgreSQL installed on your local machine.
Verify your installation:
docker --version
docker compose version
git --versionClone the repository to your local machine:
git clone <repository-url>
cd <repository-name>Copy the example environment files for both the root project and the backend:
# Setup root environment variables (ports and URLs)
cp .env.example .env
# Setup backend environment variables (secrets and API keys)
cd backend
cp .env.example .envOpen both .env files and populate all required values.
API-Football Setup: To obtain your API-Football credentials, follow the guide: docs/Football_API_Setup.md.
From the project root:
docker compose up -d --buildAfter startup:
- Frontend Dashboard: http://localhost:5173
- Backend API (FastAPI): http://localhost:8080
- Interactive API Docs: http://localhost:8080/docs
The project includes extensive documentation detailing the architecture, database schema, and machine learning models. Please review these before making major changes:
- Project Overview: High-level overview of the ingestion, evaluation, and operational loops.
- Database Schema: Detailed mapping of the PostgreSQL schemas (
raw,core,features,market,ml,opportunities). - Data Sources: Links and references to all datasets used to train the models and populate historical data.
- ML Models Overview: Detailed feature selection, hyperparameter tuning, and cross-validation methodology for the XGBoost and Logistic Regression models.
- REST API: Documentation of the endpoints exposed by the backend for fetching stats, matchups, and running simulations.
- API Setup Guide: Step-by-step instructions for configuring live external APIs.
This initiative began as a passion project inspired by the growing interest in football analytics leading up to the FIFA 2026 World Cup. Released as an open-source tool, it is freely available for personal, educational, and commercial use in accordance with its license.
While the system is fully functional, it remains in active development. Some components—particularly the frontend UI—were rapidly prototyped and generated using AI-assisted tools to accelerate the initial build. As such, there is always room for optimization and architectural improvements. Whether you choose to fork the project for your own use, build upon it, or contribute back to the repository, all forms of engagement are highly appreciated.
If you are interested in contributing, please refer to the Contributing section below.
This platform would not be possible without the extensive availability of public football data. I am deeply grateful to the community and the various platforms (including Kaggle and independent football APIs) that provide these vital resources. A comprehensive list of datasets and providers can be found in the Data Sources documentation.
We welcome contributions! Please read our Contributing Guide for details on our code of conduct, development setup, and the process for submitting Pull Requests.
This project is licensed under the Apache 2.0 License.