# vikhayatrana0110-crypto/footyforecast architecture

> Architecture diagram of the GitHub repository vikhayatrana0110-crypto/footyforecast, 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/vikhayatrana0110-crypto/footyforecast
- Repository: https://github.com/vikhayatrana0110-crypto/footyforecast

## Overview

FootyForecast turns historical international match results into Elo and rolling team/match features, trains outcome and goals models, then serves predictions with probabilities, expected goals, and SHAP explanations in Streamlit. The pipeline entry point owns the offline stages; the app owns interactive inference and presentation. README capabilities fill in the UI and schema layers where source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`run_pipeline.py`](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/run_pipeline.py) (Pipeline runner), [`src/database/db_manager.py`](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/database/db_manager.py) (Database manager), [`src/app/streamlit_app.py`](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/app/streamlit_app.py) (Streamlit interface), [`src/ingestion/download_data.py`](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/ingestion/download_data.py) (Results ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Data pipeline"]
  node_pipeline_entry["Pipeline runner<br/>[run_pipeline.py]"]
  node_ingestion["Results ingestion<br/>[download_data.py]"]
  node_raw_csv["Results CSV"]
  node_statsbomb_loader["StatsBomb enrichment"]
  node_db_manager["Database manager<br/>[db_manager.py]"]
  node_db_models["Database schema models<br/>[models.py]"]
  node_sql_schema["Layered schema<br/>[schema.sql]"]
end

subgraph group_features["Feature engineering"]
  node_elo["Elo ratings<br/>[elo_calculator.py]"]
  node_team_features["Team rolling features<br/>[team_features.py]"]
  node_match_features["Match features<br/>[match_features.py]"]
end

subgraph group_models["Modeling"]
  node_trainer["Model training<br/>[trainer.py]"]
  node_model_artifacts["Trained models"]
end

subgraph group_app["Prediction app"]
  node_streamlit["Streamlit interface<br/>[streamlit_app.py]"]
  node_predictor["Match predictor<br/>[predictor.py]"]
  node_explainer["SHAP explanations<br/>[explainer.py]"]
  node_app_data["Deployment results<br/>[results.csv]"]
end

node_operator(("Pipeline operator"))
node_user(("App user"))
node_results_source(("Historical results source"))
node_statsbomb(("StatsBomb"))
node_database[("PostgreSQL database")]

node_operator -->|"runs"| node_pipeline_entry
node_pipeline_entry -->|"calls"| node_ingestion
node_ingestion -->|"downloads"| node_results_source
node_ingestion -->|"writes"| node_raw_csv
node_ingestion -->|"loads matches"| node_db_manager
node_pipeline_entry -->|"reads and saves"| node_db_manager
node_db_manager -->|"queries and writes"| node_database
node_db_manager -->|"uses mappings"| node_db_models
node_sql_schema -->|"defines layers"| node_database
node_pipeline_entry -->|"computes ratings"| node_elo
node_pipeline_entry -->|"computes rolling stats"| node_team_features
node_pipeline_entry -->|"builds feature vectors"| node_match_features
node_team_features -->|"provides team stats"| node_match_features
node_pipeline_entry -->|"trains models"| node_trainer
node_trainer -->|"saves artifacts"| node_model_artifacts
node_user -->|"uses"| node_streamlit
node_streamlit -->|"reads and saves"| node_db_manager
node_streamlit -->|"requests prediction"| node_predictor
node_predictor -->|"builds prediction features"| node_match_features
node_predictor -->|"loads models"| node_model_artifacts
node_streamlit -->|"requests explanations"| node_explainer
node_explainer -->|"saves SHAP records"| node_db_manager
node_streamlit -->|"loads deployment data"| node_app_data
node_statsbomb_loader -.->|"fetches statistics"| node_statsbomb
node_statsbomb_loader -.->|"enriches database"| node_db_manager

click node_pipeline_entry "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/run_pipeline.py"
click node_ingestion "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/ingestion/download_data.py"
click node_statsbomb_loader "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/ingestion/statsbomb_loader.py"
click node_db_manager "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/database/db_manager.py"
click node_db_models "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/database/models.py"
click node_sql_schema "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/sql/schema.sql"
click node_elo "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/elo_calculator.py"
click node_team_features "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/team_features.py"
click node_match_features "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/match_features.py"
click node_trainer "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/trainer.py"
click node_model_artifacts "https://github.com/vikhayatrana0110-crypto/footyforecast/tree/main/src/app/models"
click node_streamlit "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/app/streamlit_app.py"
click node_predictor "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/predictor.py"
click node_explainer "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/explainer.py"
click node_app_data "https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/app/data/raw/results.csv"

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_pipeline_entry,node_ingestion,node_raw_csv,node_statsbomb_loader,node_db_manager,node_db_models,node_sql_schema,node_user toneBlue
class node_elo,node_team_features,node_match_features,node_database toneAmber
class node_trainer,node_model_artifacts toneMint
class node_streamlit,node_predictor,node_explainer,node_app_data toneRose
class node_operator,node_results_source,node_statsbomb toneIndigo
```

## Components

### Data pipeline

- [Pipeline runner](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/run_pipeline.py): `run_pipeline.py`
- [Results ingestion](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/ingestion/download_data.py): `src/ingestion/download_data.py`
- **Results CSV**
- [StatsBomb enrichment](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/ingestion/statsbomb_loader.py): `src/ingestion/statsbomb_loader.py`
- [Database manager](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/database/db_manager.py): `src/database/db_manager.py`
- [Database schema models](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/database/models.py): `src/database/models.py`
- [Layered schema](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/sql/schema.sql): `sql/schema.sql`

### Feature engineering

- [Elo ratings](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/elo_calculator.py): `src/features/elo_calculator.py`
- [Team rolling features](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/team_features.py): `src/features/team_features.py`
- [Match features](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/features/match_features.py): `src/features/match_features.py`

### Modeling

- [Model training](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/trainer.py): `src/models/trainer.py`
- [Trained models](https://github.com/vikhayatrana0110-crypto/footyforecast/tree/main/src/app/models): `src/app/models`

### Prediction app

- [Streamlit interface](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/app/streamlit_app.py): `src/app/streamlit_app.py`
- [Match predictor](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/predictor.py): `src/models/predictor.py`
- [SHAP explanations](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/models/explainer.py): `src/models/explainer.py`
- [Deployment results](https://github.com/vikhayatrana0110-crypto/footyforecast/blob/main/src/app/data/raw/results.csv): `src/app/data/raw/results.csv`

### Other components

- **Pipeline operator**
- **App user**
- **Historical results source**
- **StatsBomb**
- **PostgreSQL database**

## Connections

- Pipeline operator → Pipeline runner: runs
- Pipeline runner → Results ingestion: calls
- Results ingestion → Historical results source: downloads
- Results ingestion → Results CSV: writes
- Results ingestion → Database manager: loads matches
- Pipeline runner → Database manager: reads and saves
- Database manager → PostgreSQL database: queries and writes
- Database manager → Database schema models: uses mappings
- Layered schema → PostgreSQL database: defines layers
- Pipeline runner → Elo ratings: computes ratings
- Pipeline runner → Team rolling features: computes rolling stats
- Pipeline runner → Match features: builds feature vectors
- Team rolling features → Match features: provides team stats
- Pipeline runner → Model training: trains models
- Model training → Trained models: saves artifacts
- App user → Streamlit interface: uses
- Streamlit interface → Database manager: reads and saves
- Streamlit interface → Match predictor: requests prediction
- Match predictor → Match features: builds prediction features
- Match predictor → Trained models: loads models
- Streamlit interface → SHAP explanations: requests explanations
- SHAP explanations → Database manager: saves SHAP records
- Streamlit interface → Deployment results: loads deployment data
- StatsBomb enrichment → StatsBomb: fetches statistics
- StatsBomb enrichment → Database manager: enriches database