# marvin3742/ufc-prediction-modeling architecture

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

- Interactive diagram: https://gitdiagram.com/marvin3742/ufc-prediction-modeling
- Repository: https://github.com/marvin3742/ufc-prediction-modeling

## Overview

UFC Predictions is a terminal app whose main workflow is fighter matchup input, historical-stat feature construction, model inference, and a winner/confidence result recorded for later review or deletion. The repository also contains parallel UFC Stats scraping and data-preparation paths, plus prebuilt models and datasets. The app excerpt is partial, so links to model/data selection and inference rely on the README’s documented behavior; scraper output and its schema are visible, but downstream ingestion is not established by the excerpts.

Main entry points: [`app.py`](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py) (Prediction CLI), [`data/ufc_scraper/ufc_scraper/utils.py`](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/utils.py) (Scrape parsing), [`data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py`](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py) (Unified crawler), [`data/cleaned/cleaned_fights.csv`](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/cleaned/cleaned_fights.csv) (Cleaned tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prediction["Prediction app"]
  node_app["Prediction CLI<br/>[app.py]"]
  node_feature["Match features<br/>[app.py]"]
  node_history["Prediction history<br/>[app.py]"]
  node_training["Model training<br/>[baseline.ipynb]"]
end

subgraph group_data["Data preparation"]
  node_raw_scraper["HTML scraper<br/>[webscraper.py]"]
  node_clean_bs4["BS4 cleaning"]
  node_sort_raw["Raw sorting<br/>[sort_raw.py]"]
  node_sort_fighters["Fighter sorting<br/>[sort_fighters.py]"]
  node_csv_data["Prepared datasets<br/>[v1.csv]"]
  node_cleaned_csv["Cleaned tables<br/>[cleaned_fights.csv]"]
  node_database_loader["Database loader<br/>[write_to_db.py]"]
  node_sql_schema["Database schema<br/>[create_ufc_db.sql]"]
end

subgraph group_scraping["UFC Stats scraping"]
  node_scrape_main["Unified crawler<br/>[ufc_crawler.py]"]
  node_scrape_fighters["Fighter crawler<br/>[fighter_crawler.py]"]
  node_scrape_fights["Fight crawler<br/>[fight_crawler.py]"]
  node_scrape_rounds["Round crawler<br/>[round_crawler.py]"]
  node_scrape_utils["Scrape parsing<br/>[utils.py]"]
  node_item_schema["Scraped records<br/>[items.py]"]
end

subgraph group_artifacts["Prediction artifacts"]
  node_models["Model files<br/>[knn_v1.joblib]"]
  node_scaler["Feature scaler<br/>[scaler_v1.joblib]"]
  node_logreg["Logistic model<br/>[log_reg_v1.joblib]"]
end

node_user(("Terminal user"))
node_ufcstats{{"UFC Stats"}}
node_postgres[("PostgreSQL")]
node_prediction_file["Prediction log"]

node_user -->|"enters matchup"| node_app
node_app -->|"builds features"| node_feature
node_app -->|"selects model"| node_models
node_app -->|"supports models"| node_logreg
node_app -->|"selects dataset"| node_csv_data
node_feature -->|"feeds prediction"| node_app
node_app -->|"records result"| node_history
node_history -->|"writes JSON"| node_prediction_file
node_app -->|"shows confidence"| node_user
node_training -.->|"trains models"| node_models
node_scrape_main -->|"requests pages"| node_ufcstats
node_scrape_main -->|"yields records"| node_item_schema
node_scrape_main -->|"uses parsing"| node_scrape_utils
node_scrape_fighters -->|"requests pages"| node_ufcstats
node_scrape_fighters -->|"uses parsing"| node_scrape_utils
node_scrape_fights -->|"requests pages"| node_ufcstats
node_scrape_fights -->|"uses parsing"| node_scrape_utils
node_scrape_rounds -->|"requests pages"| node_ufcstats
node_scrape_rounds -->|"uses parsing"| node_scrape_utils
node_raw_scraper -->|"scrapes stats"| node_ufcstats
node_raw_scraper -.->|"provides raw data"| node_clean_bs4
node_clean_bs4 -.->|"prepares data"| node_csv_data
node_sort_raw -.->|"sorts records"| node_cleaned_csv
node_sort_fighters -.->|"sorts fighters"| node_cleaned_csv
node_database_loader -->|"reads CSVs"| node_cleaned_csv
node_database_loader -->|"inserts rows"| node_postgres
node_sql_schema -.->|"defines tables"| node_postgres
node_app -.->|"uses scaling"| node_scaler

click node_app "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py"
click node_feature "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py"
click node_history "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py"
click node_training "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/training/baseline.ipynb"
click node_scrape_main "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py"
click node_scrape_fighters "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/fighter_crawler.py"
click node_scrape_fights "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/fight_crawler.py"
click node_scrape_rounds "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/round_crawler.py"
click node_scrape_utils "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/utils.py"
click node_item_schema "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/items.py"
click node_raw_scraper "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/scripts/webscraper.py"
click node_clean_bs4 "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/scripts/clean_fighter_data.py"
click node_sort_raw "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/scripts/sort_raw.py"
click node_sort_fighters "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/scripts/sort_fighters.py"
click node_csv_data "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/datasets/v1.csv"
click node_cleaned_csv "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/cleaned/cleaned_fights.csv"
click node_database_loader "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/sql/write_to_db.py"
click node_sql_schema "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/sql/create_ufc_db.sql"
click node_models "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/models/knn_v1.joblib"
click node_scaler "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/scalers/scaler_v1.joblib"
click node_logreg "https://github.com/marvin3742/ufc-prediction-modeling/blob/main/models/log_reg_v1.joblib"

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_feature,node_history,node_training,node_user toneBlue
class node_raw_scraper,node_clean_bs4,node_sort_raw,node_sort_fighters,node_csv_data,node_cleaned_csv,node_database_loader,node_sql_schema,node_postgres toneAmber
class node_scrape_main,node_scrape_fighters,node_scrape_fights,node_scrape_rounds,node_scrape_utils,node_item_schema toneMint
class node_models,node_scaler,node_logreg toneRose
class node_ufcstats,node_prediction_file toneIndigo
```

## Components

### Prediction app

- [Prediction CLI](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py): `app.py`
- [Match features](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py): `app.py`
- [Prediction history](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/app.py): `app.py`
- [Model training](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/training/baseline.ipynb): `training/baseline.ipynb`

### Data preparation

- [HTML scraper](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/scripts/webscraper.py): `data_bs4/scripts/webscraper.py`
- [BS4 cleaning](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/scripts/clean_fighter_data.py): `data_bs4/scripts/clean_fighter_data.py`
- [Raw sorting](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/scripts/sort_raw.py): `data/scripts/sort_raw.py`
- [Fighter sorting](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/scripts/sort_fighters.py): `data/scripts/sort_fighters.py`
- [Prepared datasets](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data_bs4/datasets/v1.csv): `data_bs4/datasets/v1.csv`
- [Cleaned tables](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/cleaned/cleaned_fights.csv): `data/cleaned/cleaned_fights.csv`
- [Database loader](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/sql/write_to_db.py): `sql/write_to_db.py`
- [Database schema](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/sql/create_ufc_db.sql): `sql/create_ufc_db.sql`

### UFC Stats scraping

- [Unified crawler](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py): `data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py`
- [Fighter crawler](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/fighter_crawler.py): `data/ufc_scraper/ufc_scraper/spiders/fighter_crawler.py`
- [Fight crawler](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/fight_crawler.py): `data/ufc_scraper/ufc_scraper/spiders/fight_crawler.py`
- [Round crawler](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/spiders/round_crawler.py): `data/ufc_scraper/ufc_scraper/spiders/round_crawler.py`
- [Scrape parsing](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/utils.py): `data/ufc_scraper/ufc_scraper/utils.py`
- [Scraped records](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/data/ufc_scraper/ufc_scraper/items.py): `data/ufc_scraper/ufc_scraper/items.py`

### Prediction artifacts

- [Model files](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/models/knn_v1.joblib): `models/knn_v1.joblib`
- [Feature scaler](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/scalers/scaler_v1.joblib): `scalers/scaler_v1.joblib`
- [Logistic model](https://github.com/marvin3742/ufc-prediction-modeling/blob/main/models/log_reg_v1.joblib): `models/log_reg_v1.joblib`

### Other components

- **Terminal user**
- **UFC Stats**
- **PostgreSQL**
- **Prediction log**

## Connections

- Terminal user → Prediction CLI: enters matchup (evidence: `README.md`)
- Prediction CLI → Match features: builds features (evidence: `app.py`)
- Prediction CLI → Model files: selects model (evidence: `README.md`)
- Prediction CLI → Logistic model: supports models (evidence: `README.md`)
- Prediction CLI → Prepared datasets: selects dataset (evidence: `README.md`)
- Match features → Prediction CLI: feeds prediction (evidence: `README.md`)
- Prediction CLI → Prediction history: records result (evidence: `app.py`)
- Prediction history → Prediction log: writes JSON (evidence: `app.py`)
- Prediction CLI → Terminal user: shows confidence (evidence: `README.md`)
- Model training → Model files: trains models
- Unified crawler → UFC Stats: requests pages (evidence: `data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py`)
- Unified crawler → Scraped records: yields records (evidence: `data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py`)
- Unified crawler → Scrape parsing: uses parsing (evidence: `data/ufc_scraper/ufc_scraper/spiders/ufc_crawler.py`)
- Fighter crawler → UFC Stats: requests pages (evidence: `data/ufc_scraper/ufc_scraper/spiders/fighter_crawler.py`)
- Fighter crawler → Scrape parsing: uses parsing (evidence: `data/ufc_scraper/ufc_scraper/spiders/fighter_crawler.py`)
- Fight crawler → UFC Stats: requests pages (evidence: `data/ufc_scraper/ufc_scraper/spiders/fight_crawler.py`)
- Fight crawler → Scrape parsing: uses parsing (evidence: `data/ufc_scraper/ufc_scraper/spiders/fight_crawler.py`)
- Round crawler → UFC Stats: requests pages (evidence: `data/ufc_scraper/ufc_scraper/spiders/round_crawler.py`)
- Round crawler → Scrape parsing: uses parsing (evidence: `data/ufc_scraper/ufc_scraper/spiders/round_crawler.py`)
- HTML scraper → UFC Stats: scrapes stats (evidence: `README.md`)
- HTML scraper → BS4 cleaning: provides raw data
- BS4 cleaning → Prepared datasets: prepares data
- Raw sorting → Cleaned tables: sorts records
- Fighter sorting → Cleaned tables: sorts fighters
- Database loader → Cleaned tables: reads CSVs (evidence: `sql/write_to_db.py`)
- Database loader → PostgreSQL: inserts rows (evidence: `sql/write_to_db.py`)
- Database schema → PostgreSQL: defines tables
- Prediction CLI → Feature scaler: uses scaling
