# tonao1/ufcstyles architecture

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

- Interactive diagram: https://gitdiagram.com/tonao1/ufcstyles
- Repository: https://github.com/tonao1/ufcstyles

## Overview

The UFC Style Embedding Engine turns historical fight statistics into leak-free fighter snapshots, trains and evaluates embeddings for style-versus-quality separation, then serves fighter similarity and matchup estimates. Its domain stages are data collection and scope analysis, feature construction and labeling, model training and evaluation, and deployment/inference. `src/models/common.py` is a shared internal training/export layer; the serving handler dispatches API requests to NumPy inference and DynamoDB-backed fighter records. Some subsystem links follow the README workflow because their source was not sampled.

Main entry points: [`src/eval/harness.py`](https://github.com/tonao1/ufcstyles/blob/main/src/eval/harness.py) (Evaluation harness), [`src/serve/handler.py`](https://github.com/tonao1/ufcstyles/blob/main/src/serve/handler.py) (API handler), [`src/scrape/fetch_ufcstats.py`](https://github.com/tonao1/ufcstyles/blob/main/src/scrape/fetch_ufcstats.py) (UFCStats scraper), [`src/models/contrastive.py`](https://github.com/tonao1/ufcstyles/blob/main/src/models/contrastive.py) (Contrastive model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_scraper["UFCStats scraper<br/>[fetch_ufcstats.py]"]
  node_scope["Scope analysis<br/>[scope_count.py]"]
  node_config["Pipeline config<br/>[v1.yaml]"]
end

subgraph group_features["Features and labels"]
  node_snapshots["Snapshot builder<br/>[snapshots.py]"]
  node_labels["Background labels"]
  node_labelsdata["Probe labels"]
end

subgraph group_learning["Training and evaluation"]
  node_harness["Evaluation harness<br/>[harness.py]"]
  node_autoencoder["Autoencoder<br/>[autoencoder.py]"]
  node_contrastive["Contrastive model<br/>[contrastive.py]"]
  node_common["Shared training<br/>[common.py]"]
  node_evaldata["Evaluation data"]
end

subgraph group_serving["Serving"]
  node_export["Serving export<br/>[export.py]"]
  node_loader["Record loader<br/>[load_dynamodb.py]"]
  node_handler["API handler<br/>[handler.py]"]
  node_inference["NumPy inference<br/>[inference.py]"]
  node_similarity["Similarity results"]
  node_matchup["Matchup estimate"]
end

node_analyst(("Pipeline operator"))
node_ufcstats(("UFCStats"))
node_wikipedia(("Wikipedia"))
node_gateway(("API Gateway"))
node_dynamo[("DynamoDB")]

node_analyst -->|"runs"| node_scraper
node_scraper -->|"fetches statistics"| node_ufcstats
node_scraper -->|"raw tables"| node_scope
node_analyst -->|"runs"| node_scope
node_scope -->|"informs decisions"| node_config
node_analyst -->|"runs"| node_snapshots
node_config -->|"configures"| node_snapshots
node_scraper -->|"raw tables"| node_snapshots
node_snapshots -->|"builds snapshots"| node_evaldata
node_analyst -->|"runs"| node_labels
node_labels -.->|"fetches text"| node_wikipedia
node_labels -->|"writes labels"| node_labelsdata
node_analyst -->|"runs baselines"| node_harness
node_evaldata -->|"evaluates"| node_harness
node_labelsdata -->|"probe labels"| node_harness
node_analyst -->|"trains"| node_autoencoder
node_analyst -->|"trains"| node_contrastive
node_autoencoder -->|"uses training"| node_common
node_contrastive -->|"uses training"| node_common
node_autoencoder -->|"evaluates embeddings"| node_harness
node_contrastive -->|"evaluates embeddings"| node_harness
node_harness -->|"writes scores"| node_evaldata
node_analyst -->|"exports model"| node_export
node_contrastive -->|"provides model"| node_export
node_export -->|"produces records"| node_loader
node_analyst -->|"loads records"| node_loader
node_loader -->|"writes records"| node_dynamo
node_gateway -->|"dispatches requests"| node_handler
node_handler -->|"reads fighter records"| node_dynamo
node_handler -->|"calls inference"| node_inference
node_inference -->|"computes neighbors"| node_similarity
node_inference -->|"computes probability"| node_matchup
node_handler -->|"returns response"| node_similarity
node_handler -->|"returns response"| node_matchup

click node_scraper "https://github.com/tonao1/ufcstyles/blob/main/src/scrape/fetch_ufcstats.py"
click node_scope "https://github.com/tonao1/ufcstyles/blob/main/src/analysis/scope_count.py"
click node_config "https://github.com/tonao1/ufcstyles/blob/main/configs/v1.yaml"
click node_snapshots "https://github.com/tonao1/ufcstyles/blob/main/src/features/snapshots.py"
click node_labels "https://github.com/tonao1/ufcstyles/blob/main/src/labeling/fetch_wiki_background.py"
click node_harness "https://github.com/tonao1/ufcstyles/blob/main/src/eval/harness.py"
click node_autoencoder "https://github.com/tonao1/ufcstyles/blob/main/src/models/autoencoder.py"
click node_contrastive "https://github.com/tonao1/ufcstyles/blob/main/src/models/contrastive.py"
click node_common "https://github.com/tonao1/ufcstyles/blob/main/src/models/common.py"
click node_evaldata "https://github.com/tonao1/ufcstyles/tree/main/data/eval"
click node_labelsdata "https://github.com/tonao1/ufcstyles/tree/main/data/labels"
click node_export "https://github.com/tonao1/ufcstyles/blob/main/src/serve/export.py"
click node_loader "https://github.com/tonao1/ufcstyles/blob/main/src/serve/load_dynamodb.py"
click node_handler "https://github.com/tonao1/ufcstyles/blob/main/src/serve/handler.py"
click node_inference "https://github.com/tonao1/ufcstyles/blob/main/src/serve/inference.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_scraper,node_scope,node_config toneBlue
class node_snapshots,node_labels,node_labelsdata,node_dynamo toneAmber
class node_harness,node_autoencoder,node_contrastive,node_common,node_evaldata,node_gateway toneMint
class node_export,node_loader,node_handler,node_inference,node_similarity,node_matchup toneRose
class node_analyst,node_ufcstats,node_wikipedia toneIndigo
```

## Components

### Data ingestion

- [UFCStats scraper](https://github.com/tonao1/ufcstyles/blob/main/src/scrape/fetch_ufcstats.py): `src/scrape/fetch_ufcstats.py`
- [Scope analysis](https://github.com/tonao1/ufcstyles/blob/main/src/analysis/scope_count.py): `src/analysis/scope_count.py`
- [Pipeline config](https://github.com/tonao1/ufcstyles/blob/main/configs/v1.yaml): `configs/v1.yaml`

### Features and labels

- [Snapshot builder](https://github.com/tonao1/ufcstyles/blob/main/src/features/snapshots.py): `src/features/snapshots.py`
- [Background labels](https://github.com/tonao1/ufcstyles/blob/main/src/labeling/fetch_wiki_background.py): `src/labeling/fetch_wiki_background.py`
- [Probe labels](https://github.com/tonao1/ufcstyles/tree/main/data/labels): `data/labels`

### Training and evaluation

- [Evaluation harness](https://github.com/tonao1/ufcstyles/blob/main/src/eval/harness.py): `src/eval/harness.py`
- [Autoencoder](https://github.com/tonao1/ufcstyles/blob/main/src/models/autoencoder.py): `src/models/autoencoder.py`
- [Contrastive model](https://github.com/tonao1/ufcstyles/blob/main/src/models/contrastive.py): `src/models/contrastive.py`
- [Shared training](https://github.com/tonao1/ufcstyles/blob/main/src/models/common.py): `src/models/common.py`
- [Evaluation data](https://github.com/tonao1/ufcstyles/tree/main/data/eval): `data/eval`

### Serving

- [Serving export](https://github.com/tonao1/ufcstyles/blob/main/src/serve/export.py): `src/serve/export.py`
- [Record loader](https://github.com/tonao1/ufcstyles/blob/main/src/serve/load_dynamodb.py): `src/serve/load_dynamodb.py`
- [API handler](https://github.com/tonao1/ufcstyles/blob/main/src/serve/handler.py): `src/serve/handler.py`
- [NumPy inference](https://github.com/tonao1/ufcstyles/blob/main/src/serve/inference.py): `src/serve/inference.py`
- **Similarity results**
- **Matchup estimate**

### Other components

- **Pipeline operator**
- **UFCStats**
- **Wikipedia**
- **API Gateway**
- **DynamoDB**

## Connections

- Pipeline operator → UFCStats scraper: runs
- UFCStats scraper → UFCStats: fetches statistics
- UFCStats scraper → Scope analysis: raw tables
- Pipeline operator → Scope analysis: runs
- Scope analysis → Pipeline config: informs decisions
- Pipeline operator → Snapshot builder: runs
- Pipeline config → Snapshot builder: configures
- UFCStats scraper → Snapshot builder: raw tables
- Snapshot builder → Evaluation data: builds snapshots
- Pipeline operator → Background labels: runs
- Background labels → Wikipedia: fetches text
- Background labels → Probe labels: writes labels
- Pipeline operator → Evaluation harness: runs baselines
- Evaluation data → Evaluation harness: evaluates
- Probe labels → Evaluation harness: probe labels
- Pipeline operator → Autoencoder: trains
- Pipeline operator → Contrastive model: trains
- Autoencoder → Shared training: uses training
- Contrastive model → Shared training: uses training
- Autoencoder → Evaluation harness: evaluates embeddings
- Contrastive model → Evaluation harness: evaluates embeddings
- Evaluation harness → Evaluation data: writes scores
- Pipeline operator → Serving export: exports model
- Contrastive model → Serving export: provides model
- Serving export → Record loader: produces records
- Pipeline operator → Record loader: loads records
- Record loader → DynamoDB: writes records
- API Gateway → API handler: dispatches requests
- API handler → DynamoDB: reads fighter records
- API handler → NumPy inference: calls inference
- NumPy inference → Similarity results: computes neighbors
- NumPy inference → Matchup estimate: computes probability
- API handler → Similarity results: returns response
- API handler → Matchup estimate: returns response