# jodhbirs/fightev architecture

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

- Interactive diagram: https://gitdiagram.com/jodhbirs/fightev
- Repository: https://github.com/jodhbirs/fightev

## Overview

FightEV serves UFC card predictions and fighter profiles: users browse odds, Elo probabilities, expected value and quarter-Kelly sizing, then explore a searchable fighter directory and Elo/fight histories. The frontend pages call a FastAPI API; it computes card metrics and reads fighter data backed by SQLite. Separate ingestion/update scripts maintain historical ratings and the upcoming card. Their detailed external data flows are documented at a high level but not excerpted here, so those links are shown as unverified. API and page implementations were sampled; unsampled ingestion details are not inferred.

Main entry points: [`frontend/src/App.tsx`](https://github.com/jodhbirs/fightev/blob/main/frontend/src/App.tsx) (Web app routes), [`backend/main.py`](https://github.com/jodhbirs/fightev/blob/main/backend/main.py) (FastAPI endpoints), [`backend/database.py`](https://github.com/jodhbirs/fightev/blob/main/backend/database.py) (DB sessions), [`frontend/src/api.ts`](https://github.com/jodhbirs/fightev/blob/main/frontend/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Web app routes<br/>[App.tsx]"]
  node_nav["Navigation<br/>[Navbar.tsx]"]
  node_card["Fight card<br/>[CardPage.tsx]"]
  node_directory["Fighter directory<br/>[FightersPage.tsx]"]
  node_profile["Fighter profile"]
  node_client["API client<br/>[api.ts]"]
end

subgraph group_api["Prediction API"]
  node_fastapi["FastAPI endpoints<br/>[main.py]"]
  node_metrics["Elo and EV metrics<br/>[elo_engine.py]"]
end

subgraph group_data["Ratings data"]
  node_dbsession["DB sessions<br/>[database.py]"]
  node_schema["Fight and rating schema<br/>[models.py]"]
  node_sqlite[("SQLite database<br/>[fightev.db]")]
  node_config["Database configuration<br/>[config.py]"]
end

subgraph group_refresh["Data refresh"]
  node_carddata["Upcoming card data<br/>[card.json]"]
  node_cardrefresh["Card refresh<br/>[update_card.py]"]
  node_scraper["Fight history scraper"]
end

node_user(("FightEV user"))
node_odds["The Odds API"]
node_ufc["UFC fight data"]

node_user -->|"browses"| node_app
node_app -->|"renders"| node_nav
node_app -->|"routes to"| node_card
node_app -->|"routes to"| node_directory
node_app -->|"routes to"| node_profile
node_card -->|"requests fights/history"| node_client
node_directory -->|"requests fighters"| node_client
node_profile -->|"requests profile"| node_client
node_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"computes card metrics"| node_metrics
node_fastapi -->|"queries via"| node_dbsession
node_dbsession -->|"uses URL"| node_config
node_dbsession -.->|"connects to"| node_sqlite
node_fastapi -->|"queries models"| node_schema
node_schema -->|"declares on"| node_dbsession
node_cardrefresh -.->|"writes card"| node_carddata
node_cardrefresh -.->|"fetches odds"| node_odds
node_scraper -.->|"collects results"| node_ufc
node_scraper -->|"updates history/ratings"| node_schema
node_scraper -->|"uses Elo engine"| node_metrics
node_cardrefresh -->|"uses fight models"| node_schema

click node_app "https://github.com/jodhbirs/fightev/blob/main/frontend/src/App.tsx"
click node_nav "https://github.com/jodhbirs/fightev/blob/main/frontend/src/components/Navbar.tsx"
click node_card "https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/CardPage.tsx"
click node_directory "https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/FightersPage.tsx"
click node_profile "https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/FighterDetailPage.tsx"
click node_client "https://github.com/jodhbirs/fightev/blob/main/frontend/src/api.ts"
click node_fastapi "https://github.com/jodhbirs/fightev/blob/main/backend/main.py"
click node_metrics "https://github.com/jodhbirs/fightev/blob/main/backend/elo_engine.py"
click node_dbsession "https://github.com/jodhbirs/fightev/blob/main/backend/database.py"
click node_schema "https://github.com/jodhbirs/fightev/blob/main/backend/models.py"
click node_sqlite "https://github.com/jodhbirs/fightev/blob/main/backend/data/fightev.db"
click node_config "https://github.com/jodhbirs/fightev/blob/main/backend/config.py"
click node_carddata "https://github.com/jodhbirs/fightev/blob/main/backend/data/card.json"
click node_cardrefresh "https://github.com/jodhbirs/fightev/blob/main/backend/update_card.py"
click node_scraper "https://github.com/jodhbirs/fightev/blob/main/backend/scrape_new_fights.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_app,node_nav,node_card,node_directory,node_profile,node_client,node_user toneBlue
class node_fastapi,node_metrics toneAmber
class node_dbsession,node_schema,node_sqlite,node_config,node_odds toneMint
class node_carddata,node_cardrefresh,node_scraper toneRose
class node_ufc toneIndigo
```

## Components

### Web experience

- [Web app routes](https://github.com/jodhbirs/fightev/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Navigation](https://github.com/jodhbirs/fightev/blob/main/frontend/src/components/Navbar.tsx): `frontend/src/components/Navbar.tsx`
- [Fight card](https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/CardPage.tsx): `frontend/src/pages/CardPage.tsx`
- [Fighter directory](https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/FightersPage.tsx): `frontend/src/pages/FightersPage.tsx`
- [Fighter profile](https://github.com/jodhbirs/fightev/blob/main/frontend/src/pages/FighterDetailPage.tsx): `frontend/src/pages/FighterDetailPage.tsx`
- [API client](https://github.com/jodhbirs/fightev/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Prediction API

- [FastAPI endpoints](https://github.com/jodhbirs/fightev/blob/main/backend/main.py): `backend/main.py`
- [Elo and EV metrics](https://github.com/jodhbirs/fightev/blob/main/backend/elo_engine.py): `backend/elo_engine.py`

### Ratings data

- [DB sessions](https://github.com/jodhbirs/fightev/blob/main/backend/database.py): `backend/database.py`
- [Fight and rating schema](https://github.com/jodhbirs/fightev/blob/main/backend/models.py): `backend/models.py`
- [SQLite database](https://github.com/jodhbirs/fightev/blob/main/backend/data/fightev.db): `backend/data/fightev.db`
- [Database configuration](https://github.com/jodhbirs/fightev/blob/main/backend/config.py): `backend/config.py`

### Data refresh

- [Upcoming card data](https://github.com/jodhbirs/fightev/blob/main/backend/data/card.json): `backend/data/card.json`
- [Card refresh](https://github.com/jodhbirs/fightev/blob/main/backend/update_card.py): `backend/update_card.py`
- [Fight history scraper](https://github.com/jodhbirs/fightev/blob/main/backend/scrape_new_fights.py): `backend/scrape_new_fights.py`

### Other components

- **FightEV user**
- **The Odds API**
- **UFC fight data**

## Connections

- FightEV user → Web app routes: browses
- Web app routes → Navigation: renders (evidence: `frontend/src/App.tsx`)
- Web app routes → Fight card: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Fighter directory: routes to (evidence: `frontend/src/App.tsx`)
- Web app routes → Fighter profile: routes to (evidence: `frontend/src/App.tsx`)
- Fight card → API client: requests fights/history (evidence: `frontend/src/pages/CardPage.tsx`)
- Fighter directory → API client: requests fighters (evidence: `frontend/src/pages/FightersPage.tsx`)
- Fighter profile → API client: requests profile (evidence: `frontend/src/pages/FighterDetailPage.tsx`)
- API client → FastAPI endpoints: HTTP requests (evidence: `frontend/src/api.ts`)
- FastAPI endpoints → Elo and EV metrics: computes card metrics (evidence: `backend/main.py`)
- FastAPI endpoints → DB sessions: queries via (evidence: `backend/main.py`)
- DB sessions → Database configuration: uses URL (evidence: `backend/database.py`)
- DB sessions → SQLite database: connects to
- FastAPI endpoints → Fight and rating schema: queries models (evidence: `backend/main.py`)
- Fight and rating schema → DB sessions: declares on (evidence: `backend/models.py`)
- Card refresh → Upcoming card data: writes card
- Card refresh → The Odds API: fetches odds
- Fight history scraper → UFC fight data: collects results
- Fight history scraper → Fight and rating schema: updates history/ratings (evidence: `backend/scrape_new_fights.py`)
- Fight history scraper → Elo and EV metrics: uses Elo engine (evidence: `backend/scrape_new_fights.py`)
- Card refresh → Fight and rating schema: uses fight models (evidence: `backend/update_card.py`)