# madman-10/international-football-prediction architecture

> Architecture diagram of the GitHub repository madman-10/international-football-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/madman-10/international-football-prediction
- Repository: https://github.com/madman-10/international-football-prediction

## Overview

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`](https://github.com/madman-10/international-football-prediction/blob/main/train_model.py) (Train model), [`src/main.js`](https://github.com/madman-10/international-football-prediction/blob/main/src/main.js) (Main UI), [`api/prediction.py`](https://github.com/madman-10/international-football-prediction/blob/main/api/prediction.py) (Prediction logic), [`api/index.py`](https://github.com/madman-10/international-football-prediction/blob/main/api/index.py) (API entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_data_training["Data & training"]
  node_node_datasets_results["Match results<br/>csv data<br/>[results.csv]"]
  node_node_datasets_shootouts["Shootouts<br/>csv data<br/>[shootouts.csv]"]
  node_node_datasets_goalscorers["Goalscorers<br/>csv data<br/>[goalscorers.csv]"]
  node_node_datasets_former_names["Former names<br/>reference data<br/>[former_names.csv]"]
  node_node_datasets_reduced["Reduced sets<br/>curated csvs"]
  node_node_train_model["Train model<br/>python training<br/>[train_model.py]"]
end

subgraph group_group_runtime["Model serving"]
  node_node_xgb_model[("XGB model<br/>pickle artifact")]
  node_node_label_encoder[("Label encoder<br/>pickle artifact")]
  node_node_prediction_logic["Prediction logic<br/>python inference<br/>[prediction.py]"]
  node_node_api_entry["API entry<br/>serverless python<br/>[index.py]"]
  node_node_vercel{{"Vercel deploy<br/>serverless host<br/>[.vercelignore]"}}
end

subgraph group_group_frontend["Frontend"]
  node_node_index_html["App shell<br/>html ui<br/>[index.html]"]
  node_node_main_js["Main UI<br/>javascript client<br/>[main.js]"]
  node_node_style_css["Styles<br/>css<br/>[style.css]"]
  node_node_counter_js["UI helper<br/>javascript helper<br/>[counter.js]"]
  node_node_assets["Assets"]
  node_node_teams["Teams list<br/>static reference<br/>[teams.txt]"]
end

node_node_datasets_results -->|"training input"| node_node_train_model
node_node_datasets_shootouts -->|"training input"| node_node_train_model
node_node_datasets_goalscorers -->|"training input"| node_node_train_model
node_node_datasets_former_names -->|"reference input"| node_node_train_model
node_node_datasets_reduced -->|"curated input"| node_node_train_model
node_node_train_model -->|"writes"| node_node_xgb_model
node_node_train_model -->|"writes"| node_node_label_encoder
node_node_xgb_model -->|"loaded by"| node_node_prediction_logic
node_node_label_encoder -->|"loaded by"| node_node_prediction_logic
node_node_prediction_logic -->|"exposed through"| node_node_api_entry
node_node_api_entry -->|"deployed on"| node_node_vercel
node_node_index_html -->|"bootstraps"| node_node_main_js
node_node_main_js -->|"uses"| node_node_style_css
node_node_main_js -->|"imports"| node_node_counter_js
node_node_main_js -->|"reads"| node_node_teams
node_node_main_js -->|"requests predictions"| node_node_api_entry
node_node_assets -.->|"supports UI"| node_node_main_js

click node_node_datasets_results "https://github.com/madman-10/international-football-prediction/blob/main/datasets/results.csv"
click node_node_datasets_shootouts "https://github.com/madman-10/international-football-prediction/blob/main/datasets/shootouts.csv"
click node_node_datasets_goalscorers "https://github.com/madman-10/international-football-prediction/blob/main/datasets/goalscorers.csv"
click node_node_datasets_former_names "https://github.com/madman-10/international-football-prediction/blob/main/datasets/former_names.csv"
click node_node_datasets_reduced "https://github.com/madman-10/international-football-prediction/blob/main/datasets/reduced_results.csv"
click node_node_train_model "https://github.com/madman-10/international-football-prediction/blob/main/train_model.py"
click node_node_xgb_model "https://github.com/madman-10/international-football-prediction/blob/main/api/world_cup_xgb_model.pkl"
click node_node_label_encoder "https://github.com/madman-10/international-football-prediction/blob/main/api/target_label_encoder.pkl"
click node_node_prediction_logic "https://github.com/madman-10/international-football-prediction/blob/main/api/prediction.py"
click node_node_api_entry "https://github.com/madman-10/international-football-prediction/blob/main/api/index.py"
click node_node_vercel "https://github.com/madman-10/international-football-prediction/blob/main/.vercelignore"
click node_node_index_html "https://github.com/madman-10/international-football-prediction/blob/main/index.html"
click node_node_main_js "https://github.com/madman-10/international-football-prediction/blob/main/src/main.js"
click node_node_style_css "https://github.com/madman-10/international-football-prediction/blob/main/src/style.css"
click node_node_counter_js "https://github.com/madman-10/international-football-prediction/blob/main/src/counter.js"
click node_node_assets "https://github.com/madman-10/international-football-prediction/tree/main/src/assets"
click node_node_teams "https://github.com/madman-10/international-football-prediction/blob/main/public/teams.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_datasets_results,node_node_datasets_shootouts,node_node_datasets_goalscorers,node_node_datasets_former_names,node_node_datasets_reduced,node_node_train_model toneBlue
class node_node_xgb_model,node_node_label_encoder,node_node_prediction_logic,node_node_api_entry,node_node_vercel toneAmber
class node_node_index_html,node_node_main_js,node_node_style_css,node_node_counter_js,node_node_assets,node_node_teams toneMint
```

## Components

### Data & training

Historical CSV inputs and offline model training pipeline.

- [Match results](https://github.com/madman-10/international-football-prediction/blob/main/datasets/results.csv): csv data · Primary historical match results used for model building. · `datasets/results.csv`
- [Shootouts](https://github.com/madman-10/international-football-prediction/blob/main/datasets/shootouts.csv): csv data · Penalty shootout outcomes for historical match records. · `datasets/shootouts.csv`
- [Goalscorers](https://github.com/madman-10/international-football-prediction/blob/main/datasets/goalscorers.csv): csv data · Scorer-level historical match data. · `datasets/goalscorers.csv`
- [Former names](https://github.com/madman-10/international-football-prediction/blob/main/datasets/former_names.csv): reference data · Team name reference data for normalization. · `datasets/former_names.csv`
- [Reduced sets](https://github.com/madman-10/international-football-prediction/blob/main/datasets/reduced_results.csv): curated csvs · Cleaned and reduced training datasets derived from the raw historical data. · `datasets/reduced_results.csv`
- [Train model](https://github.com/madman-10/international-football-prediction/blob/main/train_model.py): python training · Offline training entrypoint that prepares features and fits the classifier. · `train_model.py`

### Model serving

Packaged artifacts and stateless Python prediction API.

- [XGB model](https://github.com/madman-10/international-football-prediction/blob/main/api/world_cup_xgb_model.pkl): pickle artifact · Serialized XGBoost classifier used at runtime. · `api/world_cup_xgb_model.pkl`
- [Label encoder](https://github.com/madman-10/international-football-prediction/blob/main/api/target_label_encoder.pkl): pickle artifact · Serialized target label encoder for decoding predictions. · `api/target_label_encoder.pkl`
- [Prediction logic](https://github.com/madman-10/international-football-prediction/blob/main/api/prediction.py): python inference · Loads artifacts, transforms inputs, and produces prediction outputs. · `api/prediction.py`
- [API entry](https://github.com/madman-10/international-football-prediction/blob/main/api/index.py): serverless python · Runtime entrypoint for the deployed prediction service. · `api/index.py`
- [Vercel deploy](https://github.com/madman-10/international-football-prediction/blob/main/.vercelignore): serverless host · Deployment boundary implied by the Vercel configuration. · `.vercelignore`

### Frontend

Browser UI and static presentation assets.

- [App shell](https://github.com/madman-10/international-football-prediction/blob/main/index.html): html ui · Top-level browser entry point for the client app. · `index.html`
- [Main UI](https://github.com/madman-10/international-football-prediction/blob/main/src/main.js): javascript client · Client-side application logic that gathers inputs and calls the API. · `src/main.js`
- [Styles](https://github.com/madman-10/international-football-prediction/blob/main/src/style.css): css · Presentation layer for the browser UI. · `src/style.css`
- [UI helper](https://github.com/madman-10/international-football-prediction/blob/main/src/counter.js): javascript helper · Small client-side helper module. · `src/counter.js`
- [Assets](https://github.com/madman-10/international-football-prediction/tree/main/src/assets): static assets · Frontend asset bundle used by the UI. · `src/assets`
- [Teams list](https://github.com/madman-10/international-football-prediction/blob/main/public/teams.txt): static reference · Valid team names used by the frontend. · `public/teams.txt`

## Connections

- 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.