# 333ian/football-ai-platform architecture

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

- Interactive diagram: https://gitdiagram.com/333ian/football-ai-platform
- Repository: https://github.com/333ian/football-ai-platform

## Overview

Football AI Prediction Platform serves match-outcome probabilities through a React dashboard and FastAPI, backed by PostgreSQL and trained XGBoost/Elo artifacts. The principal flow is team selection, prediction request, database team validation and model inference, then probability display. Separate ingestion scripts populate match/team records; model training reads historical results and writes artifacts. The README also describes a daily updater and batch forecasting. Some subsystem connections are documented rather than visible in sampled source, so those links are marked accordingly.

Main entry points: [`api.py`](https://github.com/333ian/football-ai-platform/blob/main/api.py) (REST API), [`database_setup.py`](https://github.com/333ian/football-ai-platform/blob/main/database_setup.py) (PostgreSQL schema), [`train_model.py`](https://github.com/333ian/football-ai-platform/blob/main/train_model.py) (Training pipeline), [`frontend/src/App.jsx`](https://github.com/333ian/football-ai-platform/blob/main/frontend/src/App.jsx) (Match dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Match dashboard"]
  node_dashboard["Match dashboard<br/>[App.jsx]"]
end

subgraph group_inference["Prediction service"]
  node_api["REST API<br/>[api.py]"]
  node_batch["Batch forecasts<br/>[batch_predict.py]"]
end

subgraph group_data["Match data"]
  node_database[("PostgreSQL schema<br/>[database_setup.py]")]
  node_bulk_ingest["Tournament ingestion<br/>[mass_ingestion.py]"]
  node_historical_ingest["Historical ingestion"]
  node_fixture_ingest["Fixture ingestion<br/>[data-ingestion.py]"]
end

subgraph group_ml["Model lifecycle"]
  node_training["Training pipeline<br/>[train_model.py]"]
  node_elo["Elo and features<br/>[train_model.py]"]
  node_artifacts["Model artifacts"]
  node_updater["Daily updater<br/>[auto_updater.py]"]
end

node_user(("Football user"))
node_sports_api["Sports data API"]

node_user -->|"selects matchup"| node_dashboard
node_dashboard -->|"requests teams"| node_api
node_dashboard -->|"submits prediction"| node_api
node_api -->|"queries teams"| node_database
node_api -->|"loads model and Elo"| node_artifacts
node_api -->|"returns probabilities"| node_dashboard
node_bulk_ingest -->|"fetches tournaments"| node_sports_api
node_historical_ingest -->|"fetches results"| node_sports_api
node_fixture_ingest -->|"fetches fixtures"| node_sports_api
node_bulk_ingest -->|"writes teams and matches"| node_database
node_historical_ingest -->|"writes teams and matches"| node_database
node_fixture_ingest -->|"writes teams and matches"| node_database
node_training -->|"reads finished matches"| node_database
node_training -->|"calculates ratings and features"| node_elo
node_training -->|"saves model and ratings"| node_artifacts
node_updater -.->|"re-trains model"| node_training
node_updater -.->|"fetches daily results"| node_sports_api
node_batch -->|"posts forecasts"| node_api
node_batch -->|"queries scheduled fixtures"| node_database

click node_dashboard "https://github.com/333ian/football-ai-platform/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/333ian/football-ai-platform/blob/main/api.py"
click node_database "https://github.com/333ian/football-ai-platform/blob/main/database_setup.py"
click node_bulk_ingest "https://github.com/333ian/football-ai-platform/blob/main/mass_ingestion.py"
click node_historical_ingest "https://github.com/333ian/football-ai-platform/blob/main/historical_ingestion.py"
click node_fixture_ingest "https://github.com/333ian/football-ai-platform/blob/main/data-ingestion.py"
click node_training "https://github.com/333ian/football-ai-platform/blob/main/train_model.py"
click node_elo "https://github.com/333ian/football-ai-platform/blob/main/train_model.py"
click node_artifacts "https://github.com/333ian/football-ai-platform/tree/main/ml_models/saved_models"
click node_updater "https://github.com/333ian/football-ai-platform/blob/main/auto_updater.py"
click node_batch "https://github.com/333ian/football-ai-platform/blob/main/batch_predict.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_dashboard,node_user toneBlue
class node_api,node_batch toneAmber
class node_database,node_bulk_ingest,node_historical_ingest,node_fixture_ingest,node_sports_api toneMint
class node_training,node_elo,node_artifacts,node_updater toneRose
```

## Components

### Match dashboard

- [Match dashboard](https://github.com/333ian/football-ai-platform/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Prediction service

- [REST API](https://github.com/333ian/football-ai-platform/blob/main/api.py): `api.py`
- [Batch forecasts](https://github.com/333ian/football-ai-platform/blob/main/batch_predict.py): `batch_predict.py`

### Match data

- [PostgreSQL schema](https://github.com/333ian/football-ai-platform/blob/main/database_setup.py): `database_setup.py`
- [Tournament ingestion](https://github.com/333ian/football-ai-platform/blob/main/mass_ingestion.py): `mass_ingestion.py`
- [Historical ingestion](https://github.com/333ian/football-ai-platform/blob/main/historical_ingestion.py): `historical_ingestion.py`
- [Fixture ingestion](https://github.com/333ian/football-ai-platform/blob/main/data-ingestion.py): `data-ingestion.py`

### Model lifecycle

- [Training pipeline](https://github.com/333ian/football-ai-platform/blob/main/train_model.py): `train_model.py`
- [Elo and features](https://github.com/333ian/football-ai-platform/blob/main/train_model.py): `train_model.py`
- [Model artifacts](https://github.com/333ian/football-ai-platform/tree/main/ml_models/saved_models): `ml_models/saved_models`
- [Daily updater](https://github.com/333ian/football-ai-platform/blob/main/auto_updater.py): `auto_updater.py`

### Other components

- **Football user**
- **Sports data API**

## Connections

- Football user → Match dashboard: selects matchup (evidence: `README.md`)
- Match dashboard → REST API: requests teams (evidence: `frontend/src/App.jsx`)
- Match dashboard → REST API: submits prediction (evidence: `frontend/src/App.jsx`)
- REST API → PostgreSQL schema: queries teams (evidence: `api.py`)
- REST API → Model artifacts: loads model and Elo (evidence: `api.py`)
- REST API → Match dashboard: returns probabilities (evidence: `frontend/src/App.jsx`)
- Tournament ingestion → Sports data API: fetches tournaments (evidence: `mass_ingestion.py`)
- Historical ingestion → Sports data API: fetches results (evidence: `historical_ingestion.py`)
- Fixture ingestion → Sports data API: fetches fixtures (evidence: `data-ingestion.py`)
- Tournament ingestion → PostgreSQL schema: writes teams and matches (evidence: `mass_ingestion.py`)
- Historical ingestion → PostgreSQL schema: writes teams and matches (evidence: `historical_ingestion.py`)
- Fixture ingestion → PostgreSQL schema: writes teams and matches (evidence: `data-ingestion.py`)
- Training pipeline → PostgreSQL schema: reads finished matches (evidence: `train_model.py`)
- Training pipeline → Elo and features: calculates ratings and features (evidence: `train_model.py`)
- Training pipeline → Model artifacts: saves model and ratings (evidence: `train_model.py`)
- Daily updater → Training pipeline: re-trains model (evidence: `README.md`)
- Daily updater → Sports data API: fetches daily results (evidence: `README.md`)
- Batch forecasts → REST API: posts forecasts (evidence: `batch_predict.py`)
- Batch forecasts → PostgreSQL schema: queries scheduled fixtures (evidence: `batch_predict.py`)
