How madman-10/international-football-prediction works
1. Repository shape
This is a hybrid machine-learning app with two clear halves: an offline training pipeline in Python and an online prediction app consisting of a Python API plus a small JavaScript frontend.
2. Data layer
The datasets/ directory contains the historical football data used to build the model. The files suggest multiple stages of curation:
- raw or near-raw match results (results.csv, shootouts.csv, goalscorers.csv)
- cleaned/reduced training sets (reduced_results.csv, reduced_results_check.csv, reduced_results_winners.csv)
- supporting reference data (former_names.csv)
This is the source of truth for model training, not a live database.
3. Training pipeline
train_model.py is the offline training entrypoint. It likely reads the CSV datasets, performs preprocessing/feature engineering, trains an XGBoost classifier, and serializes the resulting artifacts. The README confirms the model is used to predict international match outcomes such as win/loss/draw.
4. Model artifacts
The trained assets live in api/:
- world_cup_xgb_model.pkl — the trained XGBoost model
- target_label_encoder.pkl — label encoding for the output classes
These files are the bridge between the training pipeline and runtime inference.
5. Inference service
api/prediction.py appears to contain the core prediction logic. It likely loads the pickle artifacts, transforms request inputs into the model’s expected feature space, and returns a predicted label or probability distribution.
6. API boundary
api/index.py is the runtime entrypoint for the prediction service. The presence of .vercelignore strongly suggests this is deployed as a serverless Python API on Vercel. This API should be treated as stateless: it reads packaged model artifacts and returns predictions without persisting user data.
7. Frontend/UI layer
The web UI lives in index.html, src/main.js, src/style.css, and supporting JS files under src/. This is a lightweight client-side application, likely built with a modern JS toolchain. Its role is to collect match inputs from a user and call the Python API for predictions.
8. Static assets and reference data
public/teams.txt is likely a static list of valid national teams used by the UI for selection/autocomplete or validation. src/assets/ holds frontend assets. These files are part of the presentation layer, not the model itself.
9. Execution flow
The main data flow is:
historical CSVs → preprocessing/training in train_model.py → serialized model/encoder in api/ → API inference via api/index.py and api/prediction.py → browser UI in src/ / index.html.
10. Technology boundaries
The Python side uses the ML stack implied by the README and filenames: pandas/numpy/scikit-learn/XGBoost. The frontend side is JavaScript-based, with package.json / package-lock.json managing the client build dependencies. The two sides are separated by an HTTP-style API contract.
11. Operational model
There is no sign of a database, message queue, or background worker. The architecture is intentionally simple: one offline batch training step, one deployed inference service, and one static client. That makes it suitable for architecture diagrams as a three-tier flow with a packaged model artifact at the center.
12. What to highlight in a diagram
Show three main blocks:
- Data & training: CSV datasets and train_model.py
- Model serving: Python API loading the .pkl artifacts
- User interface: browser frontend invoking the API
The important boundary is between offline model creation and online prediction, with the pickled model files as the handoff point.
Main entry points: train_model.py Train model · main.js Main UI · prediction.py Prediction logic · index.py API entry
Components 17
Data & training
Historical CSV inputs and offline model training pipeline.
- Match results · Primary historical match results used for model building.
datasets/results.csv - Shootouts · Penalty shootout outcomes for historical match records.
datasets/shootouts.csv - Goalscorers · Scorer-level historical match data.
datasets/goalscorers.csv - Former names · Team name reference data for normalization.
datasets/former_names.csv - Reduced sets · Cleaned and reduced training datasets derived from the raw historical data.
datasets/reduced_results.csv - Train model · Offline training entrypoint that prepares features and fits the classifier.
train_model.py
Model serving
Packaged artifacts and stateless Python prediction API.
- XGB model · Serialized XGBoost classifier used at runtime.
api/world_cup_xgb_model.pkl - Label encoder · Serialized target label encoder for decoding predictions.
api/target_label_encoder.pkl - Prediction logic · Loads artifacts, transforms inputs, and produces prediction outputs.
api/prediction.py - API entry · Runtime entrypoint for the deployed prediction service.
api/index.py - Vercel deploy · Deployment boundary implied by the Vercel configuration.
.vercelignore
Frontend
Browser UI and static presentation assets.
- App shell · Top-level browser entry point for the client app.
index.html - Main UI · Client-side application logic that gathers inputs and calls the API.
src/main.js - Styles · Presentation layer for the browser UI.
src/style.css - UI helper · Small client-side helper module.
src/counter.js - Assets · Frontend asset bundle used by the UI.
src/assets - Teams list · Valid team names used by the frontend.
public/teams.txt
Connections 17
- Match results → Train model: training input · Historical match data feeds offline model training.
- Shootouts → Train model: training input · Additional match outcome data used during preparation.
- Goalscorers → Train model: training input · Supplementary historical data for feature creation.
- Former names → Train model: reference input · Supports team-name normalization during preprocessing.
- Reduced sets → Train model: curated input · Cleaned training sets derived from the raw CSV sources.
- Train model → XGB model: writes · Training serializes the fitted classifier artifact.
- Train model → Label encoder: writes · Training serializes the target encoding artifact.
- XGB model → Prediction logic: loaded by · Inference uses the saved model weights at runtime.
- Label encoder → Prediction logic: loaded by · Inference decodes predicted classes using the saved encoder.
- Prediction logic → API entry: exposed through · API entrypoint calls the core prediction module.
- API entry → Vercel deploy: deployed on · Serverless runtime boundary for the prediction service.
- App shell → Main UI: bootstraps · HTML shell loads the client application.
- Main UI → Styles: uses · Client UI consumes the stylesheet for presentation.
- Main UI → UI helper: imports · Client application includes a small helper module.
- Main UI → Teams list: reads · Frontend uses the team list for selection or validation.
- Main UI → API entry: requests predictions · Browser app sends match inputs to the Python API.
- Assets → Main UI: supports UI · Static assets are part of the presentation layer.