# darragh7/scoreline architecture

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

- Interactive diagram: https://gitdiagram.com/darragh7/scoreline
- Repository: https://github.com/darragh7/scoreline

## Overview

Scoreline combines a Django website, a separate FastAPI backend, and football prediction/modeling code. The user-facing flow is website signup/login through FastAPI to the database; match browsing calls the external football data service, while prediction requests enter a separate service. The AI tree contains both a staged training pipeline and a separate baseline/evaluation suite. The README documents the service split and Supabase connection; arrows for unsampled model internals are omitted where source evidence does not establish their calls.

Main entry points: [`ai/training/predict.py`](https://github.com/darragh7/scoreline/blob/main/ai/training/predict.py) (Prediction inference), [`backend/app/controllers/user_controller.py`](https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/user_controller.py) (Signup and login), [`ai/training/season_eval.py`](https://github.com/darragh7/scoreline/blob/main/ai/training/season_eval.py) (Season evaluation), [`ai/training/pipeline.py`](https://github.com/darragh7/scoreline/blob/main/ai/training/pipeline.py) (Training orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Django Website"]
  node_django_site["Website routes<br/>[urls.py]"]
  node_django_views["Web views and sessions<br/>[views.py]"]
end

subgraph group_api["FastAPI Backend"]
  node_api_entry["API app and routes<br/>[main.py]"]
  node_user_routes["Signup and login<br/>[user_controller.py]"]
  node_auth_service["Password hashing"]
  node_user_schema["User validation<br/>[user_schema.py]"]
  node_user_model["User records<br/>[user.py]"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_match_routes["Match lookup"]
  node_football_api["Football data client<br/>[football_api.py]"]
  node_prediction_routes["Prediction endpoint"]
  node_prediction_service["Prediction service"]
end

subgraph group_ai_training["Training Pipeline"]
  node_training_pipeline["Training orchestrator<br/>[pipeline.py]"]
  node_data_pull["Historical match pull<br/>[data_pull.py]"]
  node_preprocessing["Match preparation<br/>[preprocessing.py]"]
  node_team_names["Team normalization<br/>[teams.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_training_models["Model selection<br/>[train.py]"]
  node_prediction_inference["Prediction inference<br/>[predict.py]"]
  node_season_eval["Season evaluation<br/>[season_eval.py]"]
end

subgraph group_ml["ML Baselines"]
  node_ml_common["Shared ML data and metrics<br/>[common.py]"]
  node_elo_model["Elo baseline<br/>[elo_baseline.py]"]
  node_poisson_model["Poisson baseline"]
  node_ml_training["Baseline model training<br/>[train_models.py]"]
  node_ml_evaluation["Baseline evaluation<br/>[evaluate.py]"]
end

node_visitor(("Website visitor"))
node_football_provider{{"Football data service"}}

node_visitor -->|"opens website"| node_django_site
node_django_site -->|"routes requests"| node_django_views
node_django_views -->|"POSTs auth requests"| node_api_entry
node_api_entry -->|"registers router"| node_user_routes
node_api_entry -->|"registers router"| node_match_routes
node_api_entry -->|"registers router"| node_prediction_routes
node_user_routes -->|"queries and writes"| node_database
node_user_routes -->|"hashes and verifies"| node_auth_service
node_user_routes -->|"uses records"| node_user_model
node_user_routes -->|"validates payloads"| node_user_schema
node_match_routes -->|"requests matches"| node_football_api
node_football_api -.->|"fetches data"| node_football_provider
node_prediction_routes -->|"requests prediction"| node_prediction_service
node_training_pipeline -->|"prepares matches"| node_preprocessing
node_training_pipeline -->|"builds features"| node_features
node_training_pipeline -->|"selects and evaluates"| node_training_models
node_training_pipeline -->|"loads historical data"| node_data_pull
node_preprocessing -->|"normalizes teams"| node_team_names
node_prediction_inference -->|"uses features"| node_features
node_prediction_inference -->|"uses preparation"| node_preprocessing
node_prediction_inference -->|"uses trained models"| node_training_models
node_prediction_inference -->|"uses team mappings"| node_team_names
node_prediction_inference -->|"uses season evaluation"| node_season_eval
node_season_eval -->|"uses features"| node_features
node_season_eval -->|"uses preparation"| node_preprocessing
node_season_eval -->|"uses training"| node_training_models
node_season_eval -->|"uses evaluation"| node_ml_evaluation
node_elo_model -->|"uses shared helpers"| node_ml_common
node_poisson_model -->|"uses shared helpers"| node_ml_common
node_training_models -->|"uses shared helpers"| node_ml_common
node_ml_evaluation -->|"uses shared helpers"| node_ml_common

click node_django_site "https://github.com/darragh7/scoreline/blob/main/Django/webplay/urls.py"
click node_django_views "https://github.com/darragh7/scoreline/blob/main/Django/webplay/views.py"
click node_api_entry "https://github.com/darragh7/scoreline/blob/main/backend/app/main.py"
click node_user_routes "https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/user_controller.py"
click node_auth_service "https://github.com/darragh7/scoreline/blob/main/backend/app/services/authentication_service.py"
click node_user_schema "https://github.com/darragh7/scoreline/blob/main/backend/app/schemas/user_schema.py"
click node_user_model "https://github.com/darragh7/scoreline/blob/main/backend/app/models/user.py"
click node_database "https://github.com/darragh7/scoreline/blob/main/backend/app/database/database.py"
click node_match_routes "https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/match_controller.py"
click node_football_api "https://github.com/darragh7/scoreline/blob/main/backend/app/services/football_api.py"
click node_prediction_routes "https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/prediction_controller.py"
click node_prediction_service "https://github.com/darragh7/scoreline/blob/main/backend/app/services/prediction_service.py"
click node_training_pipeline "https://github.com/darragh7/scoreline/blob/main/ai/training/pipeline.py"
click node_data_pull "https://github.com/darragh7/scoreline/blob/main/ai/training/data_pull.py"
click node_preprocessing "https://github.com/darragh7/scoreline/blob/main/ai/training/preprocessing.py"
click node_team_names "https://github.com/darragh7/scoreline/blob/main/ai/training/teams.py"
click node_features "https://github.com/darragh7/scoreline/blob/main/ai/training/features.py"
click node_training_models "https://github.com/darragh7/scoreline/blob/main/ai/training/train.py"
click node_prediction_inference "https://github.com/darragh7/scoreline/blob/main/ai/training/predict.py"
click node_season_eval "https://github.com/darragh7/scoreline/blob/main/ai/training/season_eval.py"
click node_ml_common "https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/common.py"
click node_elo_model "https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/elo_baseline.py"
click node_poisson_model "https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/poisson_baseline.py"
click node_ml_training "https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/train_models.py"
click node_ml_evaluation "https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/evaluate.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_django_site,node_django_views toneBlue
class node_api_entry,node_user_routes,node_auth_service,node_user_schema,node_user_model,node_database,node_match_routes,node_football_api,node_prediction_routes,node_prediction_service toneAmber
class node_training_pipeline,node_data_pull,node_preprocessing,node_team_names,node_features,node_training_models,node_prediction_inference,node_season_eval toneMint
class node_ml_common,node_elo_model,node_poisson_model,node_ml_training,node_ml_evaluation toneRose
class node_visitor,node_football_provider toneIndigo
```

## Components

### Django Website

- [Website routes](https://github.com/darragh7/scoreline/blob/main/Django/webplay/urls.py): `Django/webplay/urls.py`
- [Web views and sessions](https://github.com/darragh7/scoreline/blob/main/Django/webplay/views.py): `Django/webplay/views.py`

### FastAPI Backend

- [API app and routes](https://github.com/darragh7/scoreline/blob/main/backend/app/main.py): `backend/app/main.py`
- [Signup and login](https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/user_controller.py): `backend/app/controllers/user_controller.py`
- [Password hashing](https://github.com/darragh7/scoreline/blob/main/backend/app/services/authentication_service.py): `backend/app/services/authentication_service.py`
- [User validation](https://github.com/darragh7/scoreline/blob/main/backend/app/schemas/user_schema.py): `backend/app/schemas/user_schema.py`
- [User records](https://github.com/darragh7/scoreline/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [PostgreSQL](https://github.com/darragh7/scoreline/blob/main/backend/app/database/database.py): `backend/app/database/database.py`
- [Match lookup](https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/match_controller.py): `backend/app/controllers/match_controller.py`
- [Football data client](https://github.com/darragh7/scoreline/blob/main/backend/app/services/football_api.py): `backend/app/services/football_api.py`
- [Prediction endpoint](https://github.com/darragh7/scoreline/blob/main/backend/app/controllers/prediction_controller.py): `backend/app/controllers/prediction_controller.py`
- [Prediction service](https://github.com/darragh7/scoreline/blob/main/backend/app/services/prediction_service.py): `backend/app/services/prediction_service.py`

### Training Pipeline

- [Training orchestrator](https://github.com/darragh7/scoreline/blob/main/ai/training/pipeline.py): `ai/training/pipeline.py`
- [Historical match pull](https://github.com/darragh7/scoreline/blob/main/ai/training/data_pull.py): `ai/training/data_pull.py`
- [Match preparation](https://github.com/darragh7/scoreline/blob/main/ai/training/preprocessing.py): `ai/training/preprocessing.py`
- [Team normalization](https://github.com/darragh7/scoreline/blob/main/ai/training/teams.py): `ai/training/teams.py`
- [Feature engineering](https://github.com/darragh7/scoreline/blob/main/ai/training/features.py): `ai/training/features.py`
- [Model selection](https://github.com/darragh7/scoreline/blob/main/ai/training/train.py): `ai/training/train.py`
- [Prediction inference](https://github.com/darragh7/scoreline/blob/main/ai/training/predict.py): `ai/training/predict.py`
- [Season evaluation](https://github.com/darragh7/scoreline/blob/main/ai/training/season_eval.py): `ai/training/season_eval.py`

### ML Baselines

- [Shared ML data and metrics](https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/common.py): `ai/ml_pipeline/common.py`
- [Elo baseline](https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/elo_baseline.py): `ai/ml_pipeline/elo_baseline.py`
- [Poisson baseline](https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/poisson_baseline.py): `ai/ml_pipeline/poisson_baseline.py`
- [Baseline model training](https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/train_models.py): `ai/ml_pipeline/train_models.py`
- [Baseline evaluation](https://github.com/darragh7/scoreline/blob/main/ai/ml_pipeline/evaluate.py): `ai/ml_pipeline/evaluate.py`

### Other components

- **Website visitor**
- **Football data service**

## Connections

- Website visitor → Website routes: opens website
- Website routes → Web views and sessions: routes requests (evidence: `Django/webplay/urls.py`)
- Web views and sessions → API app and routes: POSTs auth requests (evidence: `Django/webplay/views.py`)
- API app and routes → Signup and login: registers router (evidence: `backend/app/main.py`)
- API app and routes → Match lookup: registers router (evidence: `backend/app/main.py`)
- API app and routes → Prediction endpoint: registers router (evidence: `backend/app/main.py`)
- Signup and login → PostgreSQL: queries and writes (evidence: `backend/app/controllers/user_controller.py`)
- Signup and login → Password hashing: hashes and verifies (evidence: `backend/app/controllers/user_controller.py`)
- Signup and login → User records: uses records (evidence: `backend/app/controllers/user_controller.py`)
- Signup and login → User validation: validates payloads (evidence: `backend/app/controllers/user_controller.py`)
- Match lookup → Football data client: requests matches (evidence: `backend/app/controllers/match_controller.py`)
- Football data client → Football data service: fetches data
- Prediction endpoint → Prediction service: requests prediction (evidence: `backend/app/controllers/prediction_controller.py`)
- Training orchestrator → Match preparation: prepares matches (evidence: `ai/training/pipeline.py`)
- Training orchestrator → Feature engineering: builds features (evidence: `ai/training/pipeline.py`)
- Training orchestrator → Model selection: selects and evaluates (evidence: `ai/training/pipeline.py`)
- Training orchestrator → Historical match pull: loads historical data (evidence: `ai/training/pipeline.py`)
- Match preparation → Team normalization: normalizes teams (evidence: `ai/training/preprocessing.py`)
- Prediction inference → Feature engineering: uses features (evidence: `ai/training/predict.py`)
- Prediction inference → Match preparation: uses preparation (evidence: `ai/training/predict.py`)
- Prediction inference → Model selection: uses trained models (evidence: `ai/training/predict.py`)
- Prediction inference → Team normalization: uses team mappings (evidence: `ai/training/predict.py`)
- Prediction inference → Season evaluation: uses season evaluation (evidence: `ai/training/predict.py`)
- Season evaluation → Feature engineering: uses features (evidence: `ai/training/season_eval.py`)
- Season evaluation → Match preparation: uses preparation (evidence: `ai/training/season_eval.py`)
- Season evaluation → Model selection: uses training (evidence: `ai/training/season_eval.py`)
- Season evaluation → Baseline evaluation: uses evaluation (evidence: `ai/training/season_eval.py`)
- Elo baseline → Shared ML data and metrics: uses shared helpers (evidence: `ai/ml_pipeline/elo_baseline.py`)
- Poisson baseline → Shared ML data and metrics: uses shared helpers (evidence: `ai/ml_pipeline/poisson_baseline.py`)
- Model selection → Shared ML data and metrics: uses shared helpers
- Baseline evaluation → Shared ML data and metrics: uses shared helpers (evidence: `ai/ml_pipeline/evaluate.py`)
