# qingtian1927/rune-race architecture

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

- Interactive diagram: https://gitdiagram.com/qingtian1927/rune-race
- Repository: https://github.com/qingtian1927/rune-race

## Overview

Rune Race is a 3D online horse-racing game with secret Rune tactics, multiplayer rooms, bots, accounts, profiles, and a shop. Players enter through the web client, join a lobby, and play through realtime server coordination and shared game rules; the client renders the match on a 3D board. The graph also includes the operator console and analytics. Some server routes and client pages are unsampled, so those connections are included only where the README or source index supports them.

Main entry points: [`apps/server/src/socket/handlers.ts`](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/socket/handlers.ts) (Realtime handlers), [`apps/web/src/App.tsx`](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/App.tsx) (Web routes), [`apps/server/src/bot/bot-manager.ts`](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/bot/bot-manager.ts) (Bot manager), [`apps/web/src/pages/OnlineGamePage.tsx`](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/OnlineGamePage.tsx) (Match experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Web routes<br/>[App.tsx]"]
  node_auth["Player identity<br/>[useAuth.tsx]"]
  node_lobbyui["Lobby experience<br/>[LobbyPage.tsx]"]
  node_gameui["Match experience<br/>[OnlineGamePage.tsx]"]
  node_board["3D board<br/>[BoardScene.tsx]"]
  node_profile["Profiles<br/>[ProfileEdit.tsx]"]
  node_shop["Cosmetics shop<br/>[ShopPage.tsx]"]
end

subgraph group_server["Realtime server"]
  node_lobby["Lobby state<br/>[lobby-store.ts]"]
  node_socket["Realtime handlers<br/>[handlers.ts]"]
  node_game_store["Game sessions<br/>[game-store.ts]"]
  node_chat["Room chat<br/>[chat-store.ts]"]
  node_bots["Bot manager<br/>[bot-manager.ts]"]
end

subgraph group_game["Game domain"]
  node_engine["Game engine<br/>[engine.ts]"]
  node_runes["Rune state<br/>[state.ts]"]
  node_placement["Rune placement<br/>[placement.ts]"]
end

subgraph group_shared["Shared rules"]
  node_protocol["Shared protocol<br/>[events.ts]"]
  node_botai["Bot decisions<br/>[decide.ts]"]
end

subgraph group_ops["Operations"]
  node_admin["Admin console<br/>[App.tsx]"]
  node_analytics["Analytics service<br/>[service.ts]"]
end

node_player(("Player"))
node_store[("Supabase")]

node_player -->|"uses"| node_webapp
node_webapp -->|"provides identity"| node_auth
node_webapp -->|"routes to"| node_lobbyui
node_webapp -->|"routes to"| node_gameui
node_webapp -->|"routes to"| node_profile
node_webapp -->|"routes to"| node_shop
node_gameui -.->|"renders"| node_board
node_lobbyui -.->|"sends commands"| node_socket
node_gameui -.->|"sends commands"| node_socket
node_socket -->|"dispatches lobby actions"| node_lobby
node_socket -->|"dispatches game actions"| node_game_store
node_socket -->|"dispatches chat"| node_chat
node_socket -->|"coordinates bots"| node_bots
node_bots -->|"seats bots"| node_lobby
node_bots -->|"executes actions"| node_game_store
node_bots -.->|"generates chat"| node_chat
node_bots -->|"requests decisions"| node_botai
node_game_store -->|"applies game rules"| node_engine
node_engine -->|"initializes Rune state"| node_runes
node_engine -->|"opens placement phase"| node_placement
node_socket -->|"validates commands"| node_protocol
node_admin -.->|"requests reports"| node_analytics
node_analytics -->|"reads and writes"| node_store
node_profile -.->|"uses account data"| node_store
node_shop -.->|"uses account data"| node_store

click node_webapp "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/App.tsx"
click node_auth "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/hooks/useAuth.tsx"
click node_lobbyui "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/LobbyPage.tsx"
click node_gameui "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/OnlineGamePage.tsx"
click node_board "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/scenes/BoardScene.tsx"
click node_profile "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/ProfileEdit.tsx"
click node_shop "https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/ShopPage.tsx"
click node_lobby "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/lobby/lobby-store.ts"
click node_socket "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/socket/handlers.ts"
click node_game_store "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/game/game-store.ts"
click node_chat "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/chat/chat-store.ts"
click node_bots "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/bot/bot-manager.ts"
click node_engine "https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/engine.ts"
click node_runes "https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/rune/state.ts"
click node_placement "https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/rune/placement.ts"
click node_protocol "https://github.com/qingtian1927/rune-race/blob/master/packages/shared/src/protocol/events.ts"
click node_botai "https://github.com/qingtian1927/rune-race/blob/master/packages/bot-ai/src/decide.ts"
click node_admin "https://github.com/qingtian1927/rune-race/blob/master/apps/admin/src/App.tsx"
click node_analytics "https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/analytics/service.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_webapp,node_auth,node_lobbyui,node_gameui,node_board,node_profile,node_shop toneBlue
class node_lobby,node_socket,node_game_store,node_chat,node_bots,node_store toneAmber
class node_engine,node_runes,node_placement toneMint
class node_protocol,node_botai toneRose
class node_admin,node_analytics,node_player toneIndigo
```

## Components

### Web client

- [Web routes](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Player identity](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/hooks/useAuth.tsx): `apps/web/src/hooks/useAuth.tsx`
- [Lobby experience](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/LobbyPage.tsx): `apps/web/src/pages/LobbyPage.tsx`
- [Match experience](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/OnlineGamePage.tsx): `apps/web/src/pages/OnlineGamePage.tsx`
- [3D board](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/scenes/BoardScene.tsx): `apps/web/src/scenes/BoardScene.tsx`
- [Profiles](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/ProfileEdit.tsx): `apps/web/src/pages/ProfileEdit.tsx`
- [Cosmetics shop](https://github.com/qingtian1927/rune-race/blob/master/apps/web/src/pages/ShopPage.tsx): `apps/web/src/pages/ShopPage.tsx`

### Realtime server

- [Lobby state](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/lobby/lobby-store.ts): `apps/server/src/lobby/lobby-store.ts`
- [Realtime handlers](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/socket/handlers.ts): `apps/server/src/socket/handlers.ts`
- [Game sessions](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/game/game-store.ts): `apps/server/src/game/game-store.ts`
- [Room chat](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/chat/chat-store.ts): `apps/server/src/chat/chat-store.ts`
- [Bot manager](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/bot/bot-manager.ts): `apps/server/src/bot/bot-manager.ts`

### Game domain

- [Game engine](https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/engine.ts): `packages/game-engine/src/engine.ts`
- [Rune state](https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/rune/state.ts): `packages/game-engine/src/rune/state.ts`
- [Rune placement](https://github.com/qingtian1927/rune-race/blob/master/packages/game-engine/src/rune/placement.ts): `packages/game-engine/src/rune/placement.ts`

### Shared rules

- [Shared protocol](https://github.com/qingtian1927/rune-race/blob/master/packages/shared/src/protocol/events.ts): `packages/shared/src/protocol/events.ts`
- [Bot decisions](https://github.com/qingtian1927/rune-race/blob/master/packages/bot-ai/src/decide.ts): `packages/bot-ai/src/decide.ts`

### Operations

- [Admin console](https://github.com/qingtian1927/rune-race/blob/master/apps/admin/src/App.tsx): `apps/admin/src/App.tsx`
- [Analytics service](https://github.com/qingtian1927/rune-race/blob/master/apps/server/src/analytics/service.ts): `apps/server/src/analytics/service.ts`

### Other components

- **Player**
- **Supabase**

## Connections

- Player → Web routes: uses (evidence: `README.md`)
- Web routes → Player identity: provides identity (evidence: `apps/web/src/App.tsx`)
- Web routes → Lobby experience: routes to (evidence: `apps/web/src/App.tsx`)
- Web routes → Match experience: routes to (evidence: `apps/web/src/App.tsx`)
- Web routes → Profiles: routes to (evidence: `apps/web/src/App.tsx`)
- Web routes → Cosmetics shop: routes to (evidence: `apps/web/src/App.tsx`)
- Match experience → 3D board: renders
- Lobby experience → Realtime handlers: sends commands
- Match experience → Realtime handlers: sends commands
- Realtime handlers → Lobby state: dispatches lobby actions (evidence: `apps/server/src/socket/handlers.ts`)
- Realtime handlers → Game sessions: dispatches game actions (evidence: `apps/server/src/socket/handlers.ts`)
- Realtime handlers → Room chat: dispatches chat (evidence: `apps/server/src/socket/handlers.ts`)
- Realtime handlers → Bot manager: coordinates bots (evidence: `apps/server/src/socket/handlers.ts`)
- Bot manager → Lobby state: seats bots (evidence: `apps/server/src/bot/bot-manager.ts`)
- Bot manager → Game sessions: executes actions (evidence: `apps/server/src/bot/bot-manager.ts`)
- Bot manager → Room chat: generates chat (evidence: `apps/server/src/bot/bot-manager.ts`)
- Bot manager → Bot decisions: requests decisions (evidence: `apps/server/src/bot/bot-manager.ts`)
- Game sessions → Game engine: applies game rules (evidence: `apps/server/src/game/game-store.ts`)
- Game engine → Rune state: initializes Rune state (evidence: `packages/game-engine/src/engine.ts`)
- Game engine → Rune placement: opens placement phase (evidence: `packages/game-engine/src/engine.ts`)
- Realtime handlers → Shared protocol: validates commands (evidence: `apps/server/src/socket/handlers.ts`)
- Admin console → Analytics service: requests reports
- Analytics service → Supabase: reads and writes (evidence: `apps/server/src/analytics/service.ts`)
- Profiles → Supabase: uses account data
- Cosmetics shop → Supabase: uses account data
