# nahianibnat-2000/esports-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/nahianibnat-2000/esports-intelligence
- Repository: https://github.com/nahianibnat-2000/esports-intelligence

## Overview

Esports Intelligence ingests Oracle’s Elixir professional League of Legends data, builds Elo and machine-learning comparisons, computes statistical analyses, and serves the results through a web app and API. The primary user flow is browser views or prediction requests → FastAPI domain services → stored match/model/analysis data; defaults can instead render from precomputed snapshots. Offline, the documented pipeline acquires, cleans, validates, transforms, and loads data before training and analytics. The graph preserves the major documented product areas; some subsystem links rely on README descriptions because their implementation was not sampled.

Main entry points: [`machine_learning/training/train.py`](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/training/train.py) (Model training), [`backend/app/models/core.py`](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/models/core.py) (Platform database), [`pipelines/oracle_elixir/run.py`](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/run.py) (Ingest workflow), [`machine_learning/experiments/walk_forward.py`](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/experiments/walk_forward.py) (Walk-forward studies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Web views"]
  node_api_client["API client<br/>[api.ts]"]
  node_snapshots["Page snapshots<br/>[snapshot.ts]"]
end

subgraph group_api["API and domain"]
  node_http_api["REST routes<br/>[v1.py]"]
  node_services["Domain services"]
  node_research["Research reports<br/>[research.py]"]
  node_providers["Provider adapters"]
  node_db_session["DB sessions<br/>[session.py]"]
  node_database[("Platform database<br/>[core.py]")]
end

subgraph group_data["Data ingestion"]
  node_oracle_source["Oracle Elixir files"]
  node_download["Source acquisition<br/>[download.py]"]
  node_pipeline["Ingest workflow<br/>[run.py]"]
  node_cleaning["Clean and validate<br/>[clean.py]"]
  node_transform["Table transforms<br/>[transform.py]"]
  node_loader["Database loading<br/>[load.py]"]
end

subgraph group_models["Ratings and research"]
  node_splits["Temporal splits<br/>[splits.py]"]
  node_elo["Elo ratings<br/>[elo.py]"]
  node_features["Prematch features<br/>[features.py]"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[metrics.py]"]
  node_walk_forward["Walk-forward studies<br/>[walk_forward.py]"]
end

subgraph group_analysis["Statistical analysis"]
  node_analytics["Analytics batch<br/>[run_all.py]"]
  node_concentration["Balance measures<br/>[concentration.py]"]
end

node_browser(("Platform user"))

node_browser -->|"browses"| node_frontend
node_frontend -->|"requests data"| node_api_client
node_frontend -->|"loads defaults"| node_snapshots
node_api_client -->|"calls API"| node_http_api
node_http_api -->|"dispatches requests"| node_services
node_http_api -->|"serves reports"| node_research
node_services -.->|"uses sessions"| node_db_session
node_db_session -->|"connects"| node_database
node_http_api -->|"uses adapters"| node_providers
node_oracle_source -->|"provides files"| node_download
node_pipeline -->|"acquires data"| node_download
node_pipeline -->|"runs cleaning"| node_cleaning
node_pipeline -->|"runs transforms"| node_transform
node_pipeline -->|"loads tables"| node_loader
node_loader -->|"writes records"| node_database
node_database -.->|"supplies match data"| node_training
node_splits -->|"assigns periods"| node_training
node_training -->|"replays ratings"| node_elo
node_training -->|"builds features"| node_features
node_training -->|"scores models"| node_evaluation
node_walk_forward -->|"uses splits"| node_splits
node_walk_forward -->|"compares ratings"| node_elo
node_walk_forward -->|"builds features"| node_features
node_walk_forward -.->|"evaluates results"| node_evaluation
node_training -.->|"persists models"| node_database
node_analytics -->|"reads and stores outputs"| node_database
node_analytics -->|"computes measures"| node_concentration
node_research -->|"uses computed outputs"| node_analytics

click node_frontend "https://github.com/nahianibnat-2000/esports-intelligence/tree/master/frontend/app"
click node_api_client "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/frontend/lib/api.ts"
click node_snapshots "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/frontend/lib/snapshot.ts"
click node_http_api "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/api/routes/v1.py"
click node_services "https://github.com/nahianibnat-2000/esports-intelligence/tree/master/backend/app/services"
click node_research "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/services/research.py"
click node_providers "https://github.com/nahianibnat-2000/esports-intelligence/tree/master/backend/app/providers"
click node_db_session "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/database/session.py"
click node_database "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/models/core.py"
click node_download "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/download.py"
click node_pipeline "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/run.py"
click node_cleaning "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/clean.py"
click node_transform "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/transform.py"
click node_loader "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/load.py"
click node_splits "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/data_preparation/splits.py"
click node_elo "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/elo/elo.py"
click node_features "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/feature_engineering/features.py"
click node_training "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/training/train.py"
click node_evaluation "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/evaluation/metrics.py"
click node_walk_forward "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/experiments/walk_forward.py"
click node_analytics "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/analytics/run_all.py"
click node_concentration "https://github.com/nahianibnat-2000/esports-intelligence/blob/master/analytics/economics/concentration.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_frontend,node_api_client,node_snapshots,node_browser toneBlue
class node_http_api,node_services,node_research,node_providers,node_db_session,node_database toneAmber
class node_oracle_source,node_download,node_pipeline,node_cleaning,node_transform,node_loader toneMint
class node_splits,node_elo,node_features,node_training,node_evaluation,node_walk_forward toneRose
class node_analytics,node_concentration toneIndigo
```

## Components

### Web experience

- [Web views](https://github.com/nahianibnat-2000/esports-intelligence/tree/master/frontend/app): `frontend/app`
- [API client](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Page snapshots](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/frontend/lib/snapshot.ts): `frontend/lib/snapshot.ts`

### API and domain

- [REST routes](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/api/routes/v1.py): `backend/app/api/routes/v1.py`
- [Domain services](https://github.com/nahianibnat-2000/esports-intelligence/tree/master/backend/app/services): `backend/app/services`
- [Research reports](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/services/research.py): `backend/app/services/research.py`
- [Provider adapters](https://github.com/nahianibnat-2000/esports-intelligence/tree/master/backend/app/providers): `backend/app/providers`
- [DB sessions](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/database/session.py): `backend/app/database/session.py`
- [Platform database](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/backend/app/models/core.py): `backend/app/models/core.py`

### Data ingestion

- **Oracle Elixir files**
- [Source acquisition](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/download.py): `pipelines/oracle_elixir/download.py`
- [Ingest workflow](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/run.py): `pipelines/oracle_elixir/run.py`
- [Clean and validate](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/clean.py): `pipelines/oracle_elixir/clean.py`
- [Table transforms](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/transform.py): `pipelines/oracle_elixir/transform.py`
- [Database loading](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/pipelines/oracle_elixir/load.py): `pipelines/oracle_elixir/load.py`

### Ratings and research

- [Temporal splits](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/data_preparation/splits.py): `machine_learning/data_preparation/splits.py`
- [Elo ratings](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/elo/elo.py): `machine_learning/elo/elo.py`
- [Prematch features](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/feature_engineering/features.py): `machine_learning/feature_engineering/features.py`
- [Model training](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/training/train.py): `machine_learning/training/train.py`
- [Model evaluation](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/evaluation/metrics.py): `machine_learning/evaluation/metrics.py`
- [Walk-forward studies](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/machine_learning/experiments/walk_forward.py): `machine_learning/experiments/walk_forward.py`

### Statistical analysis

- [Analytics batch](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/analytics/run_all.py): `analytics/run_all.py`
- [Balance measures](https://github.com/nahianibnat-2000/esports-intelligence/blob/master/analytics/economics/concentration.py): `analytics/economics/concentration.py`

### Other components

- **Platform user**

## Connections

- Platform user → Web views: browses
- Web views → API client: requests data
- Web views → Page snapshots: loads defaults
- API client → REST routes: calls API
- REST routes → Domain services: dispatches requests (evidence: `backend/app/api/routes/v1.py`)
- REST routes → Research reports: serves reports (evidence: `backend/app/api/routes/v1.py`)
- Domain services → DB sessions: uses sessions
- DB sessions → Platform database: connects (evidence: `backend/app/database/session.py`)
- REST routes → Provider adapters: uses adapters (evidence: `backend/app/api/routes/v1.py`)
- Oracle Elixir files → Source acquisition: provides files
- Ingest workflow → Source acquisition: acquires data (evidence: `pipelines/oracle_elixir/run.py`)
- Ingest workflow → Clean and validate: runs cleaning (evidence: `pipelines/oracle_elixir/run.py`)
- Ingest workflow → Table transforms: runs transforms (evidence: `pipelines/oracle_elixir/run.py`)
- Ingest workflow → Database loading: loads tables (evidence: `pipelines/oracle_elixir/run.py`)
- Database loading → Platform database: writes records (evidence: `pipelines/oracle_elixir/load.py`)
- Platform database → Model training: supplies match data
- Temporal splits → Model training: assigns periods (evidence: `machine_learning/training/train.py`)
- Model training → Elo ratings: replays ratings (evidence: `machine_learning/training/train.py`)
- Model training → Prematch features: builds features (evidence: `machine_learning/training/train.py`)
- Model training → Model evaluation: scores models (evidence: `machine_learning/training/train.py`)
- Walk-forward studies → Temporal splits: uses splits (evidence: `machine_learning/experiments/walk_forward.py`)
- Walk-forward studies → Elo ratings: compares ratings (evidence: `machine_learning/experiments/walk_forward.py`)
- Walk-forward studies → Prematch features: builds features (evidence: `machine_learning/experiments/walk_forward.py`)
- Walk-forward studies → Model evaluation: evaluates results (evidence: `machine_learning/experiments/walk_forward.py`)
- Model training → Platform database: persists models
- Analytics batch → Platform database: reads and stores outputs (evidence: `analytics/run_all.py`)
- Analytics batch → Balance measures: computes measures (evidence: `analytics/run_all.py`)
- Research reports → Analytics batch: uses computed outputs (evidence: `backend/app/services/research.py`)
