# starryx727/valcoach architecture

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

- Interactive diagram: https://gitdiagram.com/starryx727/valcoach
- Repository: https://github.com/starryx727/valcoach

## Overview

ValCoach is a local VALORANT replay-review application. A player signs in, uploads a supported `.vrf`, follows or cancels parsing, then inspects match statistics, roster selections, round maps, profile trends, and asks a configurable LLM for evidence-backed coaching. The principal runtime boundary is the Rust API: it coordinates replay ingestion and persistence, while the web client presents results. The README documents Global and China parser support and coaching/provider capabilities; sampled excerpts do not expose every internal call, so uncertain wiring is omitted.

Main entry points: [`crates/db/src/lib.rs`](https://github.com/starryx727/valcoach/blob/main/crates/db/src/lib.rs) (SQLite store), [`apps/server/src/main.rs`](https://github.com/starryx727/valcoach/blob/main/apps/server/src/main.rs) (API router), [`apps/server/src/jobs.rs`](https://github.com/starryx727/valcoach/blob/main/apps/server/src/jobs.rs) (Replay jobs), [`crates/replay_adapter/src/lib.rs`](https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/lib.rs) (Replay adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web UI<br/>[main.tsx]"]
end

subgraph group_api["API and coaching"]
  node_server["API router<br/>[main.rs]"]
  node_auth["Authentication<br/>[auth.rs]"]
  node_jobs["Replay jobs<br/>[jobs.rs]"]
  node_matches["Match views<br/>[matches.rs]"]
  node_profile["Profiles and trends<br/>[profile.rs]"]
  node_agent["Coach agent<br/>[agent.rs]"]
end

subgraph group_replay["Replay processing"]
  node_adapter["Replay adapter<br/>[lib.rs]"]
  node_china["China transform<br/>[china.rs]"]
  node_bundle["Bundle reader<br/>[bundle.rs]"]
  node_probe["VRF probe<br/>[lib.rs]"]
end

subgraph group_data["Domain and storage"]
  node_domain["Domain contracts<br/>[lib.rs]"]
  node_maps["Map resolution<br/>[lib.rs]"]
  node_metrics["Replay metrics<br/>[lib.rs]"]
  node_db[("SQLite store<br/>[lib.rs]")]
  node_semantic["Semantic analysis<br/>[semantic.rs]"]
  node_gamecontent["Offline game content<br/>[catalog.json]"]
end

node_player(("Player"))
node_llm{{"LLM provider"}}
node_parser["Parser process"]

node_player -->|"uses"| node_web
node_web -->|"API requests"| node_server
node_server -->|"routes auth"| node_auth
node_server -->|"routes uploads"| node_jobs
node_server -->|"routes matches"| node_matches
node_server -->|"routes profiles"| node_profile
node_server -->|"routes coaching"| node_agent
node_auth -->|"reads and writes"| node_db
node_jobs -->|"ingests replay"| node_adapter
node_adapter -->|"runs export"| node_parser
node_adapter -->|"reads bundle"| node_bundle
node_adapter -->|"transforms China"| node_china
node_jobs -->|"probes container"| node_probe
node_jobs -->|"persists match"| node_db
node_matches -->|"reads and updates"| node_db
node_profile -->|"reads and writes"| node_db
node_agent -->|"loads context and history"| node_db
node_agent -.->|"requests coaching"| node_llm
node_db -->|"builds evidence"| node_semantic
node_semantic -->|"resolves areas"| node_maps
node_db -->|"stores domain records"| node_domain
node_metrics -->|"summarizes records"| node_domain
node_domain -->|"resolves names"| node_gamecontent

click node_web "https://github.com/starryx727/valcoach/blob/main/web/src/main.tsx"
click node_server "https://github.com/starryx727/valcoach/blob/main/apps/server/src/main.rs"
click node_auth "https://github.com/starryx727/valcoach/blob/main/apps/server/src/auth.rs"
click node_jobs "https://github.com/starryx727/valcoach/blob/main/apps/server/src/jobs.rs"
click node_matches "https://github.com/starryx727/valcoach/blob/main/apps/server/src/matches.rs"
click node_profile "https://github.com/starryx727/valcoach/blob/main/apps/server/src/profile.rs"
click node_agent "https://github.com/starryx727/valcoach/blob/main/apps/server/src/agent.rs"
click node_adapter "https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/lib.rs"
click node_china "https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/china.rs"
click node_bundle "https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/bundle.rs"
click node_probe "https://github.com/starryx727/valcoach/blob/main/crates/vrf_probe/src/lib.rs"
click node_domain "https://github.com/starryx727/valcoach/blob/main/crates/domain/src/lib.rs"
click node_maps "https://github.com/starryx727/valcoach/blob/main/crates/maps/src/lib.rs"
click node_metrics "https://github.com/starryx727/valcoach/blob/main/crates/metrics/src/lib.rs"
click node_db "https://github.com/starryx727/valcoach/blob/main/crates/db/src/lib.rs"
click node_semantic "https://github.com/starryx727/valcoach/blob/main/crates/db/src/semantic.rs"
click node_gamecontent "https://github.com/starryx727/valcoach/blob/main/web/public/game-content/catalog.json"

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_web toneBlue
class node_server,node_auth,node_jobs,node_matches,node_profile,node_agent toneAmber
class node_adapter,node_china,node_bundle,node_probe toneMint
class node_domain,node_maps,node_metrics,node_db,node_semantic,node_gamecontent toneRose
class node_player,node_llm,node_parser toneIndigo
```

## Components

### Web client

- [Web UI](https://github.com/starryx727/valcoach/blob/main/web/src/main.tsx): `web/src/main.tsx`

### API and coaching

- [API router](https://github.com/starryx727/valcoach/blob/main/apps/server/src/main.rs): `apps/server/src/main.rs`
- [Authentication](https://github.com/starryx727/valcoach/blob/main/apps/server/src/auth.rs): `apps/server/src/auth.rs`
- [Replay jobs](https://github.com/starryx727/valcoach/blob/main/apps/server/src/jobs.rs): `apps/server/src/jobs.rs`
- [Match views](https://github.com/starryx727/valcoach/blob/main/apps/server/src/matches.rs): `apps/server/src/matches.rs`
- [Profiles and trends](https://github.com/starryx727/valcoach/blob/main/apps/server/src/profile.rs): `apps/server/src/profile.rs`
- [Coach agent](https://github.com/starryx727/valcoach/blob/main/apps/server/src/agent.rs): `apps/server/src/agent.rs`

### Replay processing

- [Replay adapter](https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/lib.rs): `crates/replay_adapter/src/lib.rs`
- [China transform](https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/china.rs): `crates/replay_adapter/src/china.rs`
- [Bundle reader](https://github.com/starryx727/valcoach/blob/main/crates/replay_adapter/src/bundle.rs): `crates/replay_adapter/src/bundle.rs`
- [VRF probe](https://github.com/starryx727/valcoach/blob/main/crates/vrf_probe/src/lib.rs): `crates/vrf_probe/src/lib.rs`

### Domain and storage

- [Domain contracts](https://github.com/starryx727/valcoach/blob/main/crates/domain/src/lib.rs): `crates/domain/src/lib.rs`
- [Map resolution](https://github.com/starryx727/valcoach/blob/main/crates/maps/src/lib.rs): `crates/maps/src/lib.rs`
- [Replay metrics](https://github.com/starryx727/valcoach/blob/main/crates/metrics/src/lib.rs): `crates/metrics/src/lib.rs`
- [SQLite store](https://github.com/starryx727/valcoach/blob/main/crates/db/src/lib.rs): `crates/db/src/lib.rs`
- [Semantic analysis](https://github.com/starryx727/valcoach/blob/main/crates/db/src/semantic.rs): `crates/db/src/semantic.rs`
- [Offline game content](https://github.com/starryx727/valcoach/blob/main/web/public/game-content/catalog.json): `web/public/game-content/catalog.json`

### Other components

- **Player**
- **LLM provider**
- **Parser process**

## Connections

- Player → Web UI: uses
- Web UI → API router: API requests
- API router → Authentication: routes auth
- API router → Replay jobs: routes uploads
- API router → Match views: routes matches
- API router → Profiles and trends: routes profiles
- API router → Coach agent: routes coaching
- Authentication → SQLite store: reads and writes
- Replay jobs → Replay adapter: ingests replay
- Replay adapter → Parser process: runs export
- Replay adapter → Bundle reader: reads bundle
- Replay adapter → China transform: transforms China
- Replay jobs → VRF probe: probes container
- Replay jobs → SQLite store: persists match
- Match views → SQLite store: reads and updates
- Profiles and trends → SQLite store: reads and writes
- Coach agent → SQLite store: loads context and history
- Coach agent → LLM provider: requests coaching
- SQLite store → Semantic analysis: builds evidence
- Semantic analysis → Map resolution: resolves areas
- SQLite store → Domain contracts: stores domain records
- Replay metrics → Domain contracts: summarizes records
- Domain contracts → Offline game content: resolves names