# mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction architecture

> Architecture diagram of the GitHub repository mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction
- Repository: https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction

## Overview

1. **Repository shape**
   This is a self-contained Python machine-learning project with two main execution surfaces: a **Jupyter notebook** for analysis/training (`world-cup.ipynb`) and a **Streamlit app** for interactive prediction (`app.py`). There is no separate backend service or database.

2. **Primary data source**
   The core input is a single preprocessed CSV: `data/teams_match_features.csv`. It contains historical international match records plus engineered features such as recent form, FIFA player ratings, and ELO values. This dataset is the foundation for both model training and tournament simulation.

3. **Offline analytics / model development boundary**
   `world-cup.ipynb` is the offline workbench where the ML pipeline is explored, benchmarked, and validated. Based on the README, it handles EDA, preprocessing, model comparison, and selection of the final classifier. This is where the project’s predictive logic is established before being used in the app.

4. **Modeling pipeline**
   All candidate models are wrapped in a consistent `scikit-learn` pipeline with `StandardScaler` before classification. The project benchmarks multiple classifiers, then selects **XGBoost** as the best-performing model using weighted F1-score. That model becomes the decision engine for match outcome prediction.

5. **Prediction logic**
   The system predicts **win / draw / loss** probabilities for a match using team-level features from the CSV. A notable architectural choice is **symmetric prediction**: the same match is evaluated twice with home/away swapped, and the probabilities are averaged to reduce positional bias.

6. **Tournament simulation engine**
   The app is not just a single-match predictor; it simulates the full **FIFA World Cup 2026** structure. That includes:
   - 12 groups of 4 teams
   - group standings and points calculation
   - qualification of top 2 plus best 8 third-placed teams
   - Round of 32 through Final
   - third-place play-off
   Knockout draws are resolved by higher predicted win probability rather than penalty-shootout modeling.

7. **Streamlit application boundary**
   `app.py` is the user-facing runtime. It presents a two-page Streamlit dashboard:
   - **Group Prediction**: interactive head-to-head match prediction for chosen teams
   - **Knockout Bracket**: full tournament progression, stage filters, and podium summary
   This is the presentation layer that consumes the trained prediction/simulation logic.

8. **Visualization layer**
   The app uses **Plotly** for interactive probability charts and stage-by-stage match displays. This visualization layer is part of the Streamlit UI, not a separate service. In the notebook, exploratory charts likely use `matplotlib` and `seaborn`, which are for offline analysis rather than the live app.

9. **Static assets and presentation config**
   `pictures/` stores images used in the UI header and branding. `.streamlit/config.toml` defines the app’s theme and Streamlit presentation settings. These files affect look-and-feel, not model behavior.

10. **Runtime and environment**
    The project is pure Python and depends on `pandas`, `numpy`, `scikit-learn`, `xgboost`, `lightgbm`, `plotly`, and `streamlit`. The `.devcontainer/` folder indicates the repo is set up for reproducible development in a containerized environment.

11. **End-to-end data flow**
    The conceptual flow is:
    historical match dataset → feature engineering / model training in notebook → selected XGBoost classifier → match probability inference → group-stage and knockout simulation → Streamlit charts and tables.
    The app is the final consumer of this pipeline and exposes the tournament results interactively.

12. **Key architectural takeaway**
    This repository is best understood as a **single-project ML pipeline with an interactive front end**, not a multi-service system. The important boundaries are between:
    - **data preparation and model selection** (`world-cup.ipynb`)
    - **live prediction and simulation** (`app.py`)
    - **static resources and UI configuration** (`data/`, `pictures/`, `.streamlit/`)

Main entry points: [`app.py`](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/app.py) (Streamlit app), [`world-cup.ipynb`](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/world-cup.ipynb) (Notebook), [`.devcontainer/devcontainer.json`](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/.devcontainer/devcontainer.json) (Dev container), [`requirements.txt`](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/requirements.txt) (Dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline_ml["Offline ML"]
  node_data_teams_match_features[("Match features<br/>dataset")]
  node_world_cup_notebook["Notebook<br/>analysis workspace<br/>[world-cup.ipynb]"]
  node_feature_engineering["Feature prep<br/>preprocessing"]
  node_model_benchmarking["Model bench<br/>evaluation"]
  node_xgboost_classifier{{"XGBoost<br/>classifier"}}
end

subgraph group_runtime_ui["Runtime UI"]
  node_symmetric_inference["Symmetric predict<br/>inference logic"]
  node_group_stage_engine["Group stage<br/>simulation engine"]
  node_knockout_engine["Knockout run<br/>simulation engine"]
  node_app_runtime["Streamlit app<br/>presentation app<br/>[app.py]"]
  node_group_prediction_page["Group prediction<br/>ui page"]
  node_knockout_bracket_page["Knockout bracket<br/>ui page"]
  node_plotly_viz(("Plotly charts<br/>visualization"))
end

subgraph group_support["Support"]
  node_ui_theme["Streamlit theme<br/>presentation config<br/>[config.toml]"]
  node_branding_assets["Brand images<br/>static assets"]
  node_dev_environment["Dev container<br/>environment<br/>[devcontainer.json]"]
  node_dependencies["Dependencies<br/>runtime deps<br/>[requirements.txt]"]
end

node_data_teams_match_features -->|"training data"| node_feature_engineering
node_feature_engineering -->|"explored in"| node_world_cup_notebook
node_world_cup_notebook -->|"benchmarks"| node_model_benchmarking
node_model_benchmarking -->|"selects"| node_xgboost_classifier
node_xgboost_classifier -->|"predicts with"| node_symmetric_inference
node_symmetric_inference -->|"scores matches"| node_group_stage_engine
node_symmetric_inference -->|"resolves ties"| node_knockout_engine
node_group_stage_engine -->|"feeds"| node_app_runtime
node_knockout_engine -->|"feeds"| node_app_runtime
node_app_runtime -->|"renders"| node_group_prediction_page
node_app_runtime -->|"renders"| node_knockout_bracket_page
node_group_prediction_page -->|"charts"| node_plotly_viz
node_knockout_bracket_page -->|"charts"| node_plotly_viz
node_ui_theme -->|"styles"| node_app_runtime
node_branding_assets -->|"decorates"| node_app_runtime
node_dependencies -.->|"supports"| node_world_cup_notebook
node_dependencies -.->|"supports"| node_app_runtime
node_dev_environment -.->|"supports"| node_world_cup_notebook
node_dev_environment -.->|"supports"| node_app_runtime

click node_data_teams_match_features "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/data/teams_match_features.csv"
click node_world_cup_notebook "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/world-cup.ipynb"
click node_app_runtime "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/app.py"
click node_ui_theme "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/.streamlit/config.toml"
click node_branding_assets "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/tree/main/pictures"
click node_dev_environment "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/.devcontainer/devcontainer.json"
click node_dependencies "https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/requirements.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_data_teams_match_features,node_world_cup_notebook,node_feature_engineering,node_model_benchmarking,node_xgboost_classifier toneBlue
class node_symmetric_inference,node_group_stage_engine,node_knockout_engine,node_app_runtime,node_group_prediction_page,node_knockout_bracket_page,node_plotly_viz toneAmber
class node_ui_theme,node_branding_assets,node_dev_environment,node_dependencies toneMint
```

## Components

### Offline ML

Notebook-driven exploration, preprocessing, benchmarking, and model selection.

- [Match features](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/data/teams_match_features.csv): dataset · Preprocessed historical match records with engineered team features used for training and simulation. · `data/teams_match_features.csv`
- [Notebook](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/world-cup.ipynb): analysis workspace · Offline workbench for EDA, preprocessing, model comparison, and validation. · `world-cup.ipynb`
- **Feature prep**: preprocessing · Transforms match history into model-ready team-level features and target labels.
- **Model bench**: evaluation · Compares candidate scikit-learn pipelines and selects the best classifier by weighted F1.
- **XGBoost**: classifier · Selected decision model for win/draw/loss probability prediction.

### Runtime UI

Streamlit application that performs prediction, tournament simulation, and visualization.

- **Symmetric predict**: inference logic · Runs the same match twice with swapped sides and averages probabilities to reduce positional bias.
- **Group stage**: simulation engine · Simulates group standings, points, and qualification for the tournament opening round.
- **Knockout run**: simulation engine · Advances the bracket from Round of 32 to the Final and third-place play-off using predicted win probability.
- [Streamlit app](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/app.py): presentation app · Interactive front end for match prediction and full tournament simulation. · `app.py`
- **Group prediction**: ui page · Interactive head-to-head predictor for selected teams with probability output.
- **Knockout bracket**: ui page · Tournament progression view with stage filters, bracket results, and podium summary.
- **Plotly charts**: visualization · Interactive probability charts and stage-by-stage match displays used in the app.

### Support

Static assets, environment, and presentation configuration.

- [Streamlit theme](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/.streamlit/config.toml): presentation config · Streamlit styling and app presentation settings. · `.streamlit/config.toml`
- [Brand images](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/tree/main/pictures): static assets · Images used for headers and visual branding in the UI. · `pictures`
- [Dev container](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/.devcontainer/devcontainer.json): environment · Containerized development setup for reproducible local execution. · `.devcontainer/devcontainer.json`
- [Dependencies](https://github.com/mohamederrahmouni/fifa-world-cup-2026-outcomes-prediction/blob/main/requirements.txt): runtime deps · Python package requirements for data processing, modeling, visualization, and Streamlit runtime. · `requirements.txt`

## Connections

- Match features → Feature prep: training data · Historical match features feed preprocessing and label construction.
- Feature prep → Notebook: explored in · Notebook drives offline preparation and analysis.
- Notebook → Model bench: benchmarks · Notebook compares candidate pipelines and metrics.
- Model bench → XGBoost: selects · Best weighted F1 classifier becomes the final decision engine.
- XGBoost → Symmetric predict: predicts with · Classifier powers win/draw/loss probability estimation.
- Symmetric predict → Group stage: scores matches · Symmetric probabilities are reused for group-stage head-to-heads.
- Symmetric predict → Knockout run: resolves ties · Predicted win probability determines knockout advancement.
- Group stage → Streamlit app: feeds · Group standings and qualifiers are surfaced in the app.
- Knockout run → Streamlit app: feeds · Bracket progression and podium results are surfaced in the app.
- Streamlit app → Group prediction: renders · Interactive single-match prediction surface.
- Streamlit app → Knockout bracket: renders · Full tournament simulation and bracket surface.
- Group prediction → Plotly charts: charts · Probability outputs are visualized interactively.
- Knockout bracket → Plotly charts: charts · Stage results and match displays are visualized interactively.
- Streamlit theme → Streamlit app: styles · Streamlit configuration controls appearance and layout.
- Brand images → Streamlit app: decorates · Images provide UI branding and header presentation.
- Dependencies → Notebook: supports · Notebook analysis depends on the project Python stack.
- Dependencies → Streamlit app: supports · Streamlit runtime and prediction stack rely on shared packages.
- Dev container → Notebook: supports · Container setup enables reproducible offline development.
- Dev container → Streamlit app: supports · Container setup enables reproducible app execution.