# jpmouracodex/football-mle architecture

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

- Interactive diagram: https://gitdiagram.com/jpmouracodex/football-mle
- Repository: https://github.com/jpmouracodex/football-mle

## Overview

football_mle is a football-score MLE library with a Streamlit interface for club leagues and World Cup scenarios. The main workflow loads match data, canonicalizes it and applies time weights, fits Maher or Dixon–Coles parameters, then predicts scores and 1X2 outcomes or evaluates forecasts. A separate tournament branch reconstructs groups and simulates the knockout competition. README capabilities are retained; edges reflect only README or indexed-source relationships, since several implementation details were not excerpted.

Main entry points: [`app/streamlit_app.py`](https://github.com/jpmouracodex/football-mle/blob/main/app/streamlit_app.py) (Streamlit interface), [`football_mle/fitting.py`](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/fitting.py) (MLE and uncertainty), [`football_mle/simulation.py`](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/simulation.py) (Tournament simulation), [`football_mle/sources/leagues.py`](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/leagues.py) (League loaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit app"]
  node_app["Streamlit interface<br/>[streamlit_app.py]"]
  node_flags["Team flags<br/>[flags.py]"]
  node_translations["Translations<br/>[i18n.py]"]
  node_team_names["Team names<br/>[team_names.py]"]
end

subgraph group_ingest["Match data"]
  node_league_source["League loaders<br/>[leagues.py]"]
  node_international_source["International loaders<br/>[international.py]"]
  node_http["HTTP helpers<br/>[_http.py]"]
  node_data["Canonical data and weights<br/>[data.py]"]
end

subgraph group_model["Model fitting"]
  node_likelihood["Likelihood and rates<br/>[likelihood.py]"]
  node_fitting["MLE and uncertainty<br/>[fitting.py]"]
  node_maher["Maher model<br/>[maher.py]"]
  node_dc["Dixon–Coles model<br/>[dixon_coles.py]"]
end

subgraph group_outputs["Predictions and evaluation"]
  node_prediction["Score prediction<br/>[prediction.py]"]
  node_validation["Forecast validation<br/>[validation.py]"]
end

subgraph group_tournament["Tournament simulation"]
  node_sampler["Fixture sampler<br/>[simulation.py]"]
  node_tournament_engine["Tournament simulation<br/>[simulation.py]"]
end

node_user(("User"))
node_league_data[("League results")]
node_international_data[("International results and fixtures")]

node_user -->|"uses"| node_app
node_app -->|"uses"| node_flags
node_app -->|"uses"| node_translations
node_app -->|"uses"| node_team_names
node_app -->|"loads leagues"| node_league_source
node_app -->|"loads internationals"| node_international_source
node_league_source -->|"fetches via"| node_http
node_international_source -->|"fetches via"| node_http
node_league_source -->|"standardizes"| node_data
node_league_data -->|"provides results"| node_league_source
node_international_data -->|"provides results"| node_international_source
node_app -->|"prepares matches"| node_data
node_data -->|"provides match data"| node_maher
node_data -->|"provides match data"| node_dc
node_maher -->|"delegates fitting"| node_fitting
node_dc -->|"delegates fitting"| node_fitting
node_fitting -->|"optimizes objective"| node_likelihood
node_app -->|"predicts fixtures"| node_prediction
node_fitting -->|"supplies fitted model"| node_prediction
node_app -.->|"evaluates forecasts"| node_validation
node_validation -->|"scores predictions"| node_prediction
node_app -->|"runs tournament"| node_tournament_engine
node_tournament_engine -->|"samples fixtures"| node_sampler
node_sampler -->|"builds score distributions"| node_prediction
node_tournament_engine -->|"uses World Cup fixtures"| node_international_source
node_tournament_engine -->|"uses team ratings"| node_fitting

click node_app "https://github.com/jpmouracodex/football-mle/blob/main/app/streamlit_app.py"
click node_flags "https://github.com/jpmouracodex/football-mle/blob/main/app/flags.py"
click node_translations "https://github.com/jpmouracodex/football-mle/blob/main/app/i18n.py"
click node_team_names "https://github.com/jpmouracodex/football-mle/blob/main/app/team_names.py"
click node_league_source "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/leagues.py"
click node_international_source "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/international.py"
click node_http "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/_http.py"
click node_data "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/data.py"
click node_likelihood "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/likelihood.py"
click node_fitting "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/fitting.py"
click node_maher "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/maher.py"
click node_dc "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/dixon_coles.py"
click node_prediction "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/prediction.py"
click node_validation "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/validation.py"
click node_sampler "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/simulation.py"
click node_tournament_engine "https://github.com/jpmouracodex/football-mle/blob/main/football_mle/simulation.py"

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_app,node_flags,node_translations,node_team_names,node_user toneBlue
class node_league_source,node_international_source,node_http,node_data,node_league_data,node_international_data toneAmber
class node_likelihood,node_fitting,node_maher,node_dc toneMint
class node_prediction,node_validation toneRose
class node_sampler,node_tournament_engine toneIndigo
```

## Components

### Streamlit app

- [Streamlit interface](https://github.com/jpmouracodex/football-mle/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Team flags](https://github.com/jpmouracodex/football-mle/blob/main/app/flags.py): `app/flags.py`
- [Translations](https://github.com/jpmouracodex/football-mle/blob/main/app/i18n.py): `app/i18n.py`
- [Team names](https://github.com/jpmouracodex/football-mle/blob/main/app/team_names.py): `app/team_names.py`

### Match data

- [League loaders](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/leagues.py): `football_mle/sources/leagues.py`
- [International loaders](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/international.py): `football_mle/sources/international.py`
- [HTTP helpers](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/sources/_http.py): `football_mle/sources/_http.py`
- [Canonical data and weights](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/data.py): `football_mle/data.py`

### Model fitting

- [Likelihood and rates](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/likelihood.py): `football_mle/likelihood.py`
- [MLE and uncertainty](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/fitting.py): `football_mle/fitting.py`
- [Maher model](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/maher.py): `football_mle/maher.py`
- [Dixon–Coles model](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/dixon_coles.py): `football_mle/dixon_coles.py`

### Predictions and evaluation

- [Score prediction](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/prediction.py): `football_mle/prediction.py`
- [Forecast validation](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/validation.py): `football_mle/validation.py`

### Tournament simulation

- [Fixture sampler](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/simulation.py): `football_mle/simulation.py`
- [Tournament simulation](https://github.com/jpmouracodex/football-mle/blob/main/football_mle/simulation.py): `football_mle/simulation.py`

### Other components

- **User**
- **League results**
- **International results and fixtures**

## Connections

- User → Streamlit interface: uses (evidence: `README.md`)
- Streamlit interface → Team flags: uses (evidence: `app/streamlit_app.py`)
- Streamlit interface → Translations: uses (evidence: `app/streamlit_app.py`)
- Streamlit interface → Team names: uses (evidence: `app/streamlit_app.py`)
- Streamlit interface → League loaders: loads leagues (evidence: `app/streamlit_app.py`)
- Streamlit interface → International loaders: loads internationals (evidence: `app/streamlit_app.py`)
- League loaders → HTTP helpers: fetches via (evidence: `football_mle/sources/leagues.py`)
- International loaders → HTTP helpers: fetches via (evidence: `football_mle/sources/international.py`)
- League loaders → Canonical data and weights: standardizes (evidence: `football_mle/sources/leagues.py`)
- League results → League loaders: provides results (evidence: `README.md`)
- International results and fixtures → International loaders: provides results (evidence: `README.md`)
- Streamlit interface → Canonical data and weights: prepares matches (evidence: `app/streamlit_app.py`)
- Canonical data and weights → Maher model: provides match data (evidence: `football_mle/maher.py`)
- Canonical data and weights → Dixon–Coles model: provides match data (evidence: `football_mle/dixon_coles.py`)
- Maher model → MLE and uncertainty: delegates fitting (evidence: `football_mle/maher.py`)
- Dixon–Coles model → MLE and uncertainty: delegates fitting (evidence: `football_mle/dixon_coles.py`)
- MLE and uncertainty → Likelihood and rates: optimizes objective (evidence: `football_mle/fitting.py`)
- Streamlit interface → Score prediction: predicts fixtures (evidence: `README.md`)
- MLE and uncertainty → Score prediction: supplies fitted model (evidence: `football_mle/prediction.py`)
- Streamlit interface → Forecast validation: evaluates forecasts
- Forecast validation → Score prediction: scores predictions (evidence: `football_mle/validation.py`)
- Streamlit interface → Tournament simulation: runs tournament (evidence: `app/streamlit_app.py`)
- Tournament simulation → Fixture sampler: samples fixtures (evidence: `football_mle/simulation.py`)
- Fixture sampler → Score prediction: builds score distributions (evidence: `football_mle/simulation.py`)
- Tournament simulation → International loaders: uses World Cup fixtures (evidence: `README.md`)
- Tournament simulation → MLE and uncertainty: uses team ratings (evidence: `football_mle/simulation.py`)
