# omnimahui/epl-betting architecture

> Architecture diagram of the GitHub repository omnimahui/epl-betting, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omnimahui/epl-betting
- Repository: https://github.com/omnimahui/epl-betting
- Video tour (about a minute): https://gitdiagram.com/omnimahui/epl-betting/video

## Overview

EPL Match Predictor turns historical match results, bookmaker odds and Understat xG into engineered match features, then trains and evaluates prediction models and offers a CLI for match probabilities. The README also describes a walk-forward betting strategy, but no implementation path for that strategy is present in the tree, so it is not mapped as a runtime component. Several referenced model and data-acquisition modules are also absent; links are limited to documented or excerpt-supported behavior.

Main entry points: [`predict.py`](https://github.com/omnimahui/epl-betting/blob/main/predict.py) (Prediction CLI), [`src/pipeline/merge.py`](https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/merge.py) (Normalize and merge), [`src/pipeline/features_v2.py`](https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/features_v2.py) (Feature engineering), [`train_supervised.py`](https://github.com/omnimahui/epl-betting/blob/main/train_supervised.py) (Supervised training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_team_map["Team name map<br/>[team_name_map.json]"]
  node_merge["Normalize and merge<br/>[merge.py]"]
  node_matches["Unified matches"]
  node_features["Feature engineering<br/>[features_v2.py]"]
  node_feature_data["Match features"]
end

subgraph group_prediction["Prediction"]
  node_training["Supervised training"]
  node_trained_model["Trained LSTM"]
  node_rl_environment["RL environment"]
end

subgraph group_analysis["Evaluation and analysis"]
  node_metrics["Model metrics<br/>[metrics.py]"]
  node_ablation["Feature ablation<br/>[ablation.py]"]
  node_importance["Feature importance"]
end

subgraph group_interaction["User interface"]
  node_predict_cli["Prediction CLI<br/>[predict.py]"]
  node_probabilities["Outcome probabilities"]
end

node_football_data(("Match data source"))
node_understat(("Understat xG"))
node_match_user(("Match requester"))

node_football_data -->|"provides results"| node_merge
node_understat -->|"provides xG"| node_merge
node_team_map -->|"normalizes names"| node_merge
node_merge -->|"writes matches"| node_matches
node_matches -.->|"builds from"| node_features
node_features -->|"produces features"| node_feature_data
node_features -->|"builds features"| node_training
node_feature_data -->|"loads features"| node_training
node_training -->|"saves model"| node_trained_model
node_match_user -->|"requests prediction"| node_predict_cli
node_predict_cli -->|"reads features"| node_feature_data
node_predict_cli -.->|"uses model"| node_trained_model
node_predict_cli -->|"prints probabilities"| node_probabilities
node_feature_data -.->|"evaluates predictions"| node_metrics
node_feature_data -->|"compares feature groups"| node_ablation
node_feature_data -->|"ranks features"| node_importance
node_feature_data -.->|"provides observations"| node_rl_environment

click node_team_map "https://github.com/omnimahui/epl-betting/blob/main/config/team_name_map.json"
click node_merge "https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/merge.py"
click node_features "https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/features_v2.py"
click node_training "https://github.com/omnimahui/epl-betting/blob/main/train_supervised.py"
click node_rl_environment "https://github.com/omnimahui/epl-betting/blob/main/src/env/match_prediction_env.py"
click node_predict_cli "https://github.com/omnimahui/epl-betting/blob/main/predict.py"
click node_metrics "https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/metrics.py"
click node_ablation "https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/ablation.py"
click node_importance "https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/feature_importance.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_team_map,node_merge,node_matches,node_features,node_feature_data toneBlue
class node_training,node_trained_model,node_rl_environment toneAmber
class node_metrics,node_ablation,node_importance,node_match_user toneMint
class node_predict_cli,node_probabilities toneRose
class node_football_data,node_understat toneIndigo
```

## Components

### Data preparation

- [Team name map](https://github.com/omnimahui/epl-betting/blob/main/config/team_name_map.json): `config/team_name_map.json`
- [Normalize and merge](https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/merge.py): `src/pipeline/merge.py`
- **Unified matches**
- [Feature engineering](https://github.com/omnimahui/epl-betting/blob/main/src/pipeline/features_v2.py): `src/pipeline/features_v2.py`
- **Match features**

### Prediction

- [Supervised training](https://github.com/omnimahui/epl-betting/blob/main/train_supervised.py): `train_supervised.py`
- **Trained LSTM**
- [RL environment](https://github.com/omnimahui/epl-betting/blob/main/src/env/match_prediction_env.py): `src/env/match_prediction_env.py`

### Evaluation and analysis

- [Model metrics](https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Feature ablation](https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/ablation.py): `src/evaluation/ablation.py`
- [Feature importance](https://github.com/omnimahui/epl-betting/blob/main/src/evaluation/feature_importance.py): `src/evaluation/feature_importance.py`

### User interface

- [Prediction CLI](https://github.com/omnimahui/epl-betting/blob/main/predict.py): `predict.py`
- **Outcome probabilities**

### Other components

- **Match data source**
- **Understat xG**
- **Match requester**

## Connections

- Match data source → Normalize and merge: provides results
- Understat xG → Normalize and merge: provides xG
- Team name map → Normalize and merge: normalizes names
- Normalize and merge → Unified matches: writes matches
- Unified matches → Feature engineering: builds from
- Feature engineering → Match features: produces features
- Feature engineering → Supervised training: builds features
- Match features → Supervised training: loads features
- Supervised training → Trained LSTM: saves model
- Match requester → Prediction CLI: requests prediction
- Prediction CLI → Match features: reads features
- Prediction CLI → Trained LSTM: uses model
- Prediction CLI → Outcome probabilities: prints probabilities
- Match features → Model metrics: evaluates predictions
- Match features → Feature ablation: compares feature groups
- Match features → Feature importance: ranks features
- Match features → RL environment: provides observations