# ooks-io/wowsim-stats architecture

> Architecture diagram of the GitHub repository ooks-io/wowsim-stats, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ooks-io/wowsim-stats
- Repository: https://github.com/ooks-io/wowsim-stats

## Overview

wowsimstats combines a WoW statistics-data pipeline, a web frontend for browsing player and simulation data, and Discord interactions. The README describes a separate simulation workflow—generating inputs, running wowsimcli, and aggregating results—but its implementation is not present in this tree, so the graph focuses on components that are represented here. Go pipeline connections are kept unasserted because the sampled Go files do not show their callers; web and Discord links are limited to relationships visible in excerpts or explicit README statements.

Main entry points: [`nix/pkgs/ookstats/src/cmd`](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/cmd) (ookstats CLI), [`web/api/discord.ts`](https://github.com/ooks-io/wowsim-stats/blob/master/web/api/discord.ts) (Discord interaction endpoint), [`web/src/client/simulation-comparison.ts`](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/simulation-comparison.ts) (Simulation comparison), [`nix/pkgs/ookstats/src/internal/pipeline`](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/pipeline) (Fetch and process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Statistics data pipeline"]
  node_ookstats["ookstats CLI"]
  node_blizzard["Blizzard API client"]
  node_database[("Statistics database")]
  node_loader["Data loaders"]
  node_pipeline["Fetch and process"]
  node_identity["Player identity"]
  node_rankings["Ranking calculations<br/>[player_rankings.go]"]
  node_generator["Site data generation"]
  node_writer["JSON writer<br/>[json.go]"]
end

subgraph group_web["Web experience"]
  node_staticdata["Generated JSON data"]
  node_playersearch["Player search<br/>[PlayerSearch.ts]"]
  node_api["Data API helpers<br/>[api.ts]"]
  node_comparison["Simulation comparison"]
  node_chart["Comparison chart<br/>[charts.ts]"]
  node_metadata["Comparison metadata<br/>[meta.ts]"]
  node_chartui["Comparison UI<br/>[ui.ts]"]
  node_loadout["Loadout rendering<br/>[loadout.ts]"]
end

subgraph group_discord["Discord bot"]
  node_discordendpoint["Discord interaction endpoint<br/>[discord.ts]"]
  node_cache["Autocomplete indexes<br/>[cache.ts]"]
  node_leaderboardcmd["Leaderboard command<br/>[leaderboard.ts]"]
  node_playercmd["Player command<br/>[player.ts]"]
  node_embeds["Leaderboard embeds<br/>[leaderboard.ts]"]
  node_verify["Request verification<br/>[verify.ts]"]
end

subgraph group_shared["Shared domain logic"]
  node_domain["WoW domain constants<br/>[wow-constants.ts]"]
  node_clientutils["Client formatting<br/>[client-utils.ts]"]
  node_equipment["Equipment utilities<br/>[equipment-utils.ts]"]
end

node_operator(("Data operator"))
node_visitor(("Website visitor"))
node_discorduser(("Discord user"))

node_discorduser -->|"sends interaction"| node_discordendpoint
node_discordendpoint -->|"verifies signature"| node_verify
node_discordendpoint -->|"initializes caches"| node_cache
node_discordendpoint -->|"dispatches commands"| node_leaderboardcmd
node_discordendpoint -->|"dispatches commands"| node_playercmd
node_leaderboardcmd -->|"fetches leaderboard"| node_api
node_leaderboardcmd -->|"reads dungeon index"| node_cache
node_leaderboardcmd -->|"builds embed"| node_embeds
node_cache -->|"fetches index files"| node_staticdata
node_visitor -.->|"searches players"| node_playersearch
node_playersearch -.->|"loads player index"| node_staticdata
node_comparison -->|"renders chart"| node_chart
node_comparison -->|"renders metadata"| node_metadata
node_comparison -->|"updates interface"| node_chartui
node_comparison -.->|"loads comparison data"| node_staticdata
node_loadout -->|"renders equipment"| node_equipment
node_clientutils -->|"uses class and spec data"| node_domain
node_operator -.->|"runs data commands"| node_ookstats
node_ookstats -.->|"requests game data"| node_blizzard
node_ookstats -.->|"manages stored data"| node_database
node_ookstats -.->|"runs processing"| node_pipeline
node_pipeline -.->|"loads records"| node_loader
node_pipeline -.->|"resolves players"| node_identity
node_pipeline -.->|"calculates rankings"| node_rankings
node_ookstats -.->|"builds site datasets"| node_generator
node_generator -.->|"writes JSON"| node_writer
node_writer -.->|"produces data files"| node_staticdata

click node_ookstats "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/cmd"
click node_blizzard "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/blizzard"
click node_database "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/database"
click node_loader "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/loader"
click node_pipeline "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/pipeline"
click node_identity "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/playerid"
click node_rankings "https://github.com/ooks-io/wowsim-stats/blob/master/nix/pkgs/ookstats/src/internal/pipeline/player_rankings.go"
click node_generator "https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/generator"
click node_writer "https://github.com/ooks-io/wowsim-stats/blob/master/nix/pkgs/ookstats/src/internal/writer/json.go"
click node_playersearch "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/components/PlayerSearch/PlayerSearch.ts"
click node_api "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/api.ts"
click node_comparison "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/simulation-comparison.ts"
click node_chart "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/render/charts.ts"
click node_metadata "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/render/meta.ts"
click node_chartui "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/ui.ts"
click node_loadout "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/loadout.ts"
click node_discordendpoint "https://github.com/ooks-io/wowsim-stats/blob/master/web/api/discord.ts"
click node_cache "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/indexes/cache.ts"
click node_leaderboardcmd "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/commands/leaderboard.ts"
click node_playercmd "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/commands/player.ts"
click node_embeds "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/embeds/leaderboard.ts"
click node_verify "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/verify.ts"
click node_domain "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/wow-constants.ts"
click node_clientutils "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/client-utils.ts"
click node_equipment "https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/equipment-utils.ts"

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_ookstats,node_blizzard,node_database,node_loader,node_pipeline,node_identity,node_rankings,node_generator,node_writer,node_discorduser toneBlue
class node_staticdata,node_playersearch,node_api,node_comparison,node_chart,node_metadata,node_chartui,node_loadout toneAmber
class node_discordendpoint,node_cache,node_leaderboardcmd,node_playercmd,node_embeds,node_verify toneMint
class node_domain,node_clientutils,node_equipment toneRose
class node_operator,node_visitor toneIndigo
```

## Components

### Statistics data pipeline

- [ookstats CLI](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/cmd): `nix/pkgs/ookstats/src/cmd`
- [Blizzard API client](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/blizzard): `nix/pkgs/ookstats/src/internal/blizzard`
- [Statistics database](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/database): `nix/pkgs/ookstats/src/internal/database`
- [Data loaders](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/loader): `nix/pkgs/ookstats/src/internal/loader`
- [Fetch and process](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/pipeline): `nix/pkgs/ookstats/src/internal/pipeline`
- [Player identity](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/playerid): `nix/pkgs/ookstats/src/internal/playerid`
- [Ranking calculations](https://github.com/ooks-io/wowsim-stats/blob/master/nix/pkgs/ookstats/src/internal/pipeline/player_rankings.go): `nix/pkgs/ookstats/src/internal/pipeline/player_rankings.go`
- [Site data generation](https://github.com/ooks-io/wowsim-stats/tree/master/nix/pkgs/ookstats/src/internal/generator): `nix/pkgs/ookstats/src/internal/generator`
- [JSON writer](https://github.com/ooks-io/wowsim-stats/blob/master/nix/pkgs/ookstats/src/internal/writer/json.go): `nix/pkgs/ookstats/src/internal/writer/json.go`

### Web experience

- **Generated JSON data**
- [Player search](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/components/PlayerSearch/PlayerSearch.ts): `web/src/components/PlayerSearch/PlayerSearch.ts`
- [Data API helpers](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Simulation comparison](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/simulation-comparison.ts): `web/src/client/simulation-comparison.ts`
- [Comparison chart](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/render/charts.ts): `web/src/client/sim-chart/render/charts.ts`
- [Comparison metadata](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/render/meta.ts): `web/src/client/sim-chart/render/meta.ts`
- [Comparison UI](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/ui.ts): `web/src/client/sim-chart/ui.ts`
- [Loadout rendering](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/client/sim-chart/loadout.ts): `web/src/client/sim-chart/loadout.ts`

### Discord bot

- [Discord interaction endpoint](https://github.com/ooks-io/wowsim-stats/blob/master/web/api/discord.ts): `web/api/discord.ts`
- [Autocomplete indexes](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/indexes/cache.ts): `web/src/discord/indexes/cache.ts`
- [Leaderboard command](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/commands/leaderboard.ts): `web/src/discord/commands/leaderboard.ts`
- [Player command](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/commands/player.ts): `web/src/discord/commands/player.ts`
- [Leaderboard embeds](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/embeds/leaderboard.ts): `web/src/discord/embeds/leaderboard.ts`
- [Request verification](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/discord/verify.ts): `web/src/discord/verify.ts`

### Shared domain logic

- [WoW domain constants](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/wow-constants.ts): `web/src/lib/wow-constants.ts`
- [Client formatting](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/client-utils.ts): `web/src/lib/client-utils.ts`
- [Equipment utilities](https://github.com/ooks-io/wowsim-stats/blob/master/web/src/lib/equipment-utils.ts): `web/src/lib/equipment-utils.ts`

### Other components

- **Data operator**
- **Website visitor**
- **Discord user**

## Connections

- Discord user → Discord interaction endpoint: sends interaction (evidence: `web/api/discord.ts`)
- Discord interaction endpoint → Request verification: verifies signature (evidence: `web/api/discord.ts`)
- Discord interaction endpoint → Autocomplete indexes: initializes caches (evidence: `web/api/discord.ts`)
- Discord interaction endpoint → Leaderboard command: dispatches commands (evidence: `web/api/discord.ts`)
- Discord interaction endpoint → Player command: dispatches commands (evidence: `web/api/discord.ts`)
- Leaderboard command → Data API helpers: fetches leaderboard (evidence: `web/src/discord/commands/leaderboard.ts`)
- Leaderboard command → Autocomplete indexes: reads dungeon index (evidence: `web/src/discord/commands/leaderboard.ts`)
- Leaderboard command → Leaderboard embeds: builds embed (evidence: `web/src/discord/commands/leaderboard.ts`)
- Autocomplete indexes → Generated JSON data: fetches index files (evidence: `web/src/discord/indexes/cache.ts`)
- Website visitor → Player search: searches players
- Player search → Generated JSON data: loads player index
- Simulation comparison → Comparison chart: renders chart (evidence: `web/src/client/simulation-comparison.ts`)
- Simulation comparison → Comparison metadata: renders metadata (evidence: `web/src/client/simulation-comparison.ts`)
- Simulation comparison → Comparison UI: updates interface (evidence: `web/src/client/simulation-comparison.ts`)
- Simulation comparison → Generated JSON data: loads comparison data
- Loadout rendering → Equipment utilities: renders equipment (evidence: `web/src/client/sim-chart/loadout.ts`)
- Client formatting → WoW domain constants: uses class and spec data (evidence: `web/src/lib/client-utils.ts`)
- Data operator → ookstats CLI: runs data commands
- ookstats CLI → Blizzard API client: requests game data
- ookstats CLI → Statistics database: manages stored data
- ookstats CLI → Fetch and process: runs processing
- Fetch and process → Data loaders: loads records
- Fetch and process → Player identity: resolves players
- Fetch and process → Ranking calculations: calculates rankings
- ookstats CLI → Site data generation: builds site datasets
- Site data generation → JSON writer: writes JSON
- JSON writer → Generated JSON data: produces data files
