# jodhbirs/valai architecture

> Architecture diagram of the GitHub repository jodhbirs/valai, 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/valai
- Repository: https://github.com/jodhbirs/valai

## Overview

ValAI is a Valorant composition optimizer: a user selects a map and locks agents, requests role-valid completions, and receives ranked teams with predicted win rate and uncertainty. The runtime path is React UI → API client → FastAPI solve route → combinatorial solver → batched scorer → permutation-invariant Transformer; metadata initializes the UI. Separate model-preparation capabilities include tournament-data scraping, Bayesian-adjusted datasets, pairwise pretraining, and full-composition training. The README documents these capabilities, though source excerpts for scraping and pair-data loading were not provided, so uncertain implementation links are omitted.

Main entry points: [`api/app.py`](https://github.com/jodhbirs/valai/blob/main/api/app.py) (API routes), [`scorer.py`](https://github.com/jodhbirs/valai/blob/main/scorer.py) (Team scorer), [`dataset.py`](https://github.com/jodhbirs/valai/blob/main/dataset.py) (Composition dataset), [`train.py`](https://github.com/jodhbirs/valai/blob/main/train.py) (Two-phase trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app["App bootstrap<br/>[App.tsx]"]
  node_optimizer["Composition UI<br/>[OptimizerView.tsx]"]
  node_client["API client<br/>[client.ts]"]
  node_types["API types<br/>[index.ts]"]
end

subgraph group_api["Inference API"]
  node_api_routes["API routes<br/>[app.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
end

subgraph group_prediction["Prediction engine"]
  node_solver["Completion solver<br/>[solver.py]"]
  node_scorer["Team scorer<br/>[scorer.py]"]
  node_model["Synergy Transformer<br/>[model.py]"]
  node_constants["Agent and map catalog<br/>[constants.py]"]
  node_baseline_data[("Agent win-rate data")]
  node_checkpoint["Trained checkpoint<br/>[valai_model.pt]"]
end

subgraph group_training["Model preparation"]
  node_comp_data[("Composition win-rate data<br/>[comp_win_rates.csv]")]
  node_comp_dataset["Composition dataset<br/>[dataset.py]"]
  node_pair_dataset["Pairwise dataset<br/>[pair_dataset.py]"]
  node_trainer["Two-phase trainer<br/>[train.py]"]
  node_scrape_agents["Agent data scraper<br/>[scrape_data.py]"]
  node_scrape_comps["Composition scraper<br/>[scrape_comps.py]"]
end

node_user(("Optimizer user"))
node_data_source(("rib.gg tournament data"))

node_user -->|"selects picks"| node_optimizer
node_app -->|"checks metadata"| node_client
node_app -->|"renders"| node_optimizer
node_optimizer -->|"requests solve"| node_client
node_client -->|"calls endpoints"| node_api_routes
node_optimizer -->|"uses response types"| node_types
node_client -->|"uses API types"| node_types
node_api_routes -->|"validates requests"| node_schemas
node_api_routes -->|"dispatches solve"| node_solver
node_api_routes -->|"builds metadata"| node_constants
node_api_routes -->|"loads checkpoint scorer"| node_scorer
node_solver -->|"scores batches"| node_scorer
node_solver -->|"checks roles"| node_constants
node_scorer -->|"predicts win rate"| node_model
node_scorer -->|"loads adjusted baselines"| node_comp_dataset
node_scorer -.->|"reads baselines"| node_baseline_data
node_model -->|"uses role mappings"| node_constants
node_comp_dataset -->|"reads compositions"| node_comp_data
node_comp_dataset -->|"reads agent rates"| node_baseline_data
node_comp_dataset -->|"maps identities"| node_constants
node_trainer -->|"pretrains embeddings"| node_pair_dataset
node_trainer -->|"trains compositions"| node_comp_dataset
node_trainer -->|"fine-tunes"| node_model
node_trainer -->|"saves model"| node_checkpoint
node_pair_dataset -.->|"reads composition data"| node_comp_data
node_scrape_agents -.->|"collects data"| node_data_source
node_scrape_comps -.->|"collects data"| node_data_source
node_scrape_agents -.->|"produces rates"| node_baseline_data
node_scrape_comps -.->|"produces compositions"| node_comp_data

click node_app "https://github.com/jodhbirs/valai/blob/main/frontend/src/App.tsx"
click node_optimizer "https://github.com/jodhbirs/valai/blob/main/frontend/src/components/OptimizerView.tsx"
click node_client "https://github.com/jodhbirs/valai/blob/main/frontend/src/api/client.ts"
click node_types "https://github.com/jodhbirs/valai/blob/main/frontend/src/types/index.ts"
click node_api_routes "https://github.com/jodhbirs/valai/blob/main/api/app.py"
click node_schemas "https://github.com/jodhbirs/valai/blob/main/api/schemas.py"
click node_solver "https://github.com/jodhbirs/valai/blob/main/solver.py"
click node_scorer "https://github.com/jodhbirs/valai/blob/main/scorer.py"
click node_model "https://github.com/jodhbirs/valai/blob/main/model.py"
click node_constants "https://github.com/jodhbirs/valai/blob/main/constants.py"
click node_baseline_data "https://github.com/jodhbirs/valai/blob/main/agent_win_rates.csv"
click node_comp_data "https://github.com/jodhbirs/valai/blob/main/comp_win_rates.csv"
click node_comp_dataset "https://github.com/jodhbirs/valai/blob/main/dataset.py"
click node_pair_dataset "https://github.com/jodhbirs/valai/blob/main/pair_dataset.py"
click node_trainer "https://github.com/jodhbirs/valai/blob/main/train.py"
click node_checkpoint "https://github.com/jodhbirs/valai/blob/main/valai_model.pt"
click node_scrape_agents "https://github.com/jodhbirs/valai/blob/main/scrape_data.py"
click node_scrape_comps "https://github.com/jodhbirs/valai/blob/main/scrape_comps.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_optimizer,node_client,node_types,node_user toneBlue
class node_api_routes,node_schemas toneAmber
class node_solver,node_scorer,node_model,node_constants,node_baseline_data,node_checkpoint toneMint
class node_comp_data,node_comp_dataset,node_pair_dataset,node_trainer,node_scrape_agents,node_scrape_comps toneRose
class node_data_source toneIndigo
```

## Components

### Web interface

- [App bootstrap](https://github.com/jodhbirs/valai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Composition UI](https://github.com/jodhbirs/valai/blob/main/frontend/src/components/OptimizerView.tsx): `frontend/src/components/OptimizerView.tsx`
- [API client](https://github.com/jodhbirs/valai/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [API types](https://github.com/jodhbirs/valai/blob/main/frontend/src/types/index.ts): `frontend/src/types/index.ts`

### Inference API

- [API routes](https://github.com/jodhbirs/valai/blob/main/api/app.py): `api/app.py`
- [Request schemas](https://github.com/jodhbirs/valai/blob/main/api/schemas.py): `api/schemas.py`

### Prediction engine

- [Completion solver](https://github.com/jodhbirs/valai/blob/main/solver.py): `solver.py`
- [Team scorer](https://github.com/jodhbirs/valai/blob/main/scorer.py): `scorer.py`
- [Synergy Transformer](https://github.com/jodhbirs/valai/blob/main/model.py): `model.py`
- [Agent and map catalog](https://github.com/jodhbirs/valai/blob/main/constants.py): `constants.py`
- [Agent win-rate data](https://github.com/jodhbirs/valai/blob/main/agent_win_rates.csv): `agent_win_rates.csv`
- [Trained checkpoint](https://github.com/jodhbirs/valai/blob/main/valai_model.pt): `valai_model.pt`

### Model preparation

- [Composition win-rate data](https://github.com/jodhbirs/valai/blob/main/comp_win_rates.csv): `comp_win_rates.csv`
- [Composition dataset](https://github.com/jodhbirs/valai/blob/main/dataset.py): `dataset.py`
- [Pairwise dataset](https://github.com/jodhbirs/valai/blob/main/pair_dataset.py): `pair_dataset.py`
- [Two-phase trainer](https://github.com/jodhbirs/valai/blob/main/train.py): `train.py`
- [Agent data scraper](https://github.com/jodhbirs/valai/blob/main/scrape_data.py): `scrape_data.py`
- [Composition scraper](https://github.com/jodhbirs/valai/blob/main/scrape_comps.py): `scrape_comps.py`

### Other components

- **Optimizer user**
- **rib.gg tournament data**

## Connections

- Optimizer user → Composition UI: selects picks (evidence: `frontend/src/components/OptimizerView.tsx`)
- App bootstrap → API client: checks metadata (evidence: `frontend/src/App.tsx`)
- App bootstrap → Composition UI: renders (evidence: `frontend/src/App.tsx`)
- Composition UI → API client: requests solve (evidence: `frontend/src/components/OptimizerView.tsx`)
- API client → API routes: calls endpoints (evidence: `frontend/src/api/client.ts`)
- Composition UI → API types: uses response types (evidence: `frontend/src/components/OptimizerView.tsx`)
- API client → API types: uses API types (evidence: `frontend/src/api/client.ts`)
- API routes → Request schemas: validates requests (evidence: `api/app.py`)
- API routes → Completion solver: dispatches solve (evidence: `api/app.py`)
- API routes → Agent and map catalog: builds metadata (evidence: `api/app.py`)
- API routes → Team scorer: loads checkpoint scorer (evidence: `api/app.py`)
- Completion solver → Team scorer: scores batches (evidence: `solver.py`)
- Completion solver → Agent and map catalog: checks roles (evidence: `solver.py`)
- Team scorer → Synergy Transformer: predicts win rate (evidence: `scorer.py`)
- Team scorer → Composition dataset: loads adjusted baselines (evidence: `scorer.py`)
- Team scorer → Agent win-rate data: reads baselines
- Synergy Transformer → Agent and map catalog: uses role mappings (evidence: `model.py`)
- Composition dataset → Composition win-rate data: reads compositions (evidence: `dataset.py`)
- Composition dataset → Agent win-rate data: reads agent rates (evidence: `dataset.py`)
- Composition dataset → Agent and map catalog: maps identities (evidence: `dataset.py`)
- Two-phase trainer → Pairwise dataset: pretrains embeddings (evidence: `train.py`)
- Two-phase trainer → Composition dataset: trains compositions (evidence: `train.py`)
- Two-phase trainer → Synergy Transformer: fine-tunes (evidence: `train.py`)
- Two-phase trainer → Trained checkpoint: saves model (evidence: `train.py`)
- Pairwise dataset → Composition win-rate data: reads composition data
- Agent data scraper → rib.gg tournament data: collects data
- Composition scraper → rib.gg tournament data: collects data
- Agent data scraper → Agent win-rate data: produces rates
- Composition scraper → Composition win-rate data: produces compositions