# timbee706/kaspabattle2 architecture

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

- Interactive diagram: https://gitdiagram.com/timbee706/kaspabattle2
- Repository: https://github.com/timbee706/kaspabattle2

## Overview

KaspaBattle is a P2P esports wagering product: players browse or create challenges, join matches, authenticate through FACEIT, fund wagers, and receive verified-result payouts. The React app calls the Rust API and also connects to Kaspa wallet/RPC functionality; the backend coordinates match state, FACEIT verification, escrow, and settlement. Tournaments add a separate registration, deposit, and payout capability. The kdapp Episode path is documented as work in progress. Some backend wiring is inferred only where README explicitly describes it; unsampled links are omitted.

Main entry points: [`battle-frontend/src/api/client.ts`](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/api/client.ts) (API client), [`battle-frontend/src/App.tsx`](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/App.tsx) (React app), [`battle-frontend/src/hooks/useWallet.ts`](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/hooks/useWallet.ts) (Wallet actions), [`kaspabattle/battle-api/src/main.rs`](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/main.rs) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Player application"]
  node_app["React app<br/>[App.tsx]"]
  node_match_ui["Match pages<br/>[MatchPage.tsx]"]
  node_lobby_ui["Lobby pages<br/>[LobbyPage.tsx]"]
  node_tournament_ui["Tournament pages"]
  node_wallet_hook["Wallet actions<br/>[useWallet.ts]"]
  node_auth_store["Auth state<br/>[useAuthStore.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_backend["API and match domain"]
  node_api_server["API server<br/>[main.rs]"]
  node_match_handlers["Match handlers<br/>[matches.rs]"]
  node_auth_handlers["Auth handlers<br/>[auth.rs]"]
  node_match_domain["Match state<br/>[match_state.rs]"]
  node_faceit_client["FACEIT data<br/>[faceit_client.rs]"]
  node_faceit_watcher["FACEIT watcher<br/>[faceit_watcher.rs]"]
  node_match_payout["Payout worker<br/>[payout_worker.rs]"]
end

subgraph group_settlement["Kaspa settlement"]
  node_escrow_service["Multisig escrow<br/>[service.rs]"]
  node_kaspa_wallet["Wallet integration<br/>[wallet.ts]"]
end

subgraph group_tournaments["Tournament and Episodes"]
  node_tournament_api["Tournament API<br/>[tournament.rs]"]
  node_tournament_worker["Tournament payouts"]
  node_kdapp_engine["Episode engine<br/>[kdapp_engine.rs]"]
  node_kdapp_handler["Episode handler<br/>[handler.rs]"]
end

node_player(("Player"))
node_postgres[("PostgreSQL")]
node_faceit["FACEIT"]
node_kaspa_node["Kaspa node"]
node_winner(("Wager payout"))

node_player -->|"uses"| node_app
node_app -->|"routes to"| node_lobby_ui
node_app -->|"routes to"| node_match_ui
node_app -->|"routes to"| node_tournament_ui
node_lobby_ui -->|"requests lobby"| node_api_client
node_match_ui -->|"requests match"| node_api_client
node_tournament_ui -->|"requests tournaments"| node_api_client
node_wallet_hook -->|"uses"| node_kaspa_wallet
node_wallet_hook -->|"submits deposits"| node_api_client
node_wallet_hook -->|"updates identity"| node_auth_store
node_auth_store -->|"requests auth"| node_api_client
node_api_client -->|"REST requests"| node_api_server
node_api_server -->|"dispatches"| node_match_handlers
node_api_server -->|"dispatches"| node_auth_handlers
node_match_handlers -->|"applies transitions"| node_match_domain
node_match_handlers -->|"reads and writes"| node_postgres
node_auth_handlers -->|"reads and writes"| node_postgres
node_faceit_watcher -->|"polls results"| node_faceit_client
node_faceit_client -->|"fetches match data"| node_faceit
node_match_payout -->|"reads and updates"| node_postgres
node_match_payout -->|"requests settlement"| node_escrow_service
node_escrow_service -->|"checks and broadcasts"| node_kaspa_node
node_escrow_service -->|"sends payout"| node_winner
node_tournament_api -->|"reads and writes"| node_postgres
node_tournament_worker -->|"tracks deposits and payouts"| node_postgres
node_tournament_worker -->|"watches deposits"| node_kaspa_node
node_kdapp_engine -.->|"dispatches events"| node_kdapp_handler
node_kdapp_handler -.->|"updates match records"| node_postgres

click node_app "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/App.tsx"
click node_match_ui "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/MatchPage.tsx"
click node_lobby_ui "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/LobbyPage.tsx"
click node_tournament_ui "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/TournamentListPage.tsx"
click node_wallet_hook "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/hooks/useWallet.ts"
click node_auth_store "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/stores/useAuthStore.ts"
click node_api_client "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/api/client.ts"
click node_api_server "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/main.rs"
click node_match_handlers "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/handlers/matches.rs"
click node_auth_handlers "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/handlers/auth.rs"
click node_match_domain "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/match_state.rs"
click node_faceit_client "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/faceit_client.rs"
click node_faceit_watcher "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/workers/faceit_watcher.rs"
click node_match_payout "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/payout_worker.rs"
click node_tournament_api "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/tournament.rs"
click node_tournament_worker "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/tournament_payout_worker.rs"
click node_kdapp_engine "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kdapp/src/kdapp_engine.rs"
click node_kdapp_handler "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kdapp/src/handler.rs"
click node_escrow_service "https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kaspa/src/multisig/service.rs"
click node_kaspa_wallet "https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/kaspa/wallet.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_app,node_match_ui,node_lobby_ui,node_tournament_ui,node_wallet_hook,node_auth_store,node_api_client toneBlue
class node_api_server,node_match_handlers,node_auth_handlers,node_match_domain,node_faceit_client,node_faceit_watcher,node_match_payout,node_postgres toneAmber
class node_escrow_service,node_kaspa_wallet toneMint
class node_tournament_api,node_tournament_worker,node_kdapp_engine,node_kdapp_handler toneRose
class node_player,node_faceit,node_kaspa_node,node_winner toneIndigo
```

## Components

### Player application

- [React app](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/App.tsx): `battle-frontend/src/App.tsx`
- [Match pages](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/MatchPage.tsx): `battle-frontend/src/pages/MatchPage.tsx`
- [Lobby pages](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/LobbyPage.tsx): `battle-frontend/src/pages/LobbyPage.tsx`
- [Tournament pages](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/pages/TournamentListPage.tsx): `battle-frontend/src/pages/TournamentListPage.tsx`
- [Wallet actions](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/hooks/useWallet.ts): `battle-frontend/src/hooks/useWallet.ts`
- [Auth state](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/stores/useAuthStore.ts): `battle-frontend/src/stores/useAuthStore.ts`
- [API client](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/api/client.ts): `battle-frontend/src/api/client.ts`

### API and match domain

- [API server](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/main.rs): `kaspabattle/battle-api/src/main.rs`
- [Match handlers](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/handlers/matches.rs): `kaspabattle/battle-api/src/api/handlers/matches.rs`
- [Auth handlers](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/handlers/auth.rs): `kaspabattle/battle-api/src/api/handlers/auth.rs`
- [Match state](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/match_state.rs): `kaspabattle/battle-core/src/match_state.rs`
- [FACEIT data](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/faceit_client.rs): `kaspabattle/battle-core/src/faceit_client.rs`
- [FACEIT watcher](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-core/src/workers/faceit_watcher.rs): `kaspabattle/battle-core/src/workers/faceit_watcher.rs`
- [Payout worker](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/payout_worker.rs): `kaspabattle/battle-api/src/payout_worker.rs`

### Kaspa settlement

- [Multisig escrow](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kaspa/src/multisig/service.rs): `kaspabattle/battle-kaspa/src/multisig/service.rs`
- [Wallet integration](https://github.com/timbee706/kaspabattle2/blob/main/battle-frontend/src/kaspa/wallet.ts): `battle-frontend/src/kaspa/wallet.ts`

### Tournament and Episodes

- [Tournament API](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/api/tournament.rs): `kaspabattle/battle-api/src/api/tournament.rs`
- [Tournament payouts](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-api/src/tournament_payout_worker.rs): `kaspabattle/battle-api/src/tournament_payout_worker.rs`
- [Episode engine](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kdapp/src/kdapp_engine.rs): `kaspabattle/battle-kdapp/src/kdapp_engine.rs`
- [Episode handler](https://github.com/timbee706/kaspabattle2/blob/main/kaspabattle/battle-kdapp/src/handler.rs): `kaspabattle/battle-kdapp/src/handler.rs`

### Other components

- **Player**
- **PostgreSQL**
- **FACEIT**
- **Kaspa node**
- **Wager payout**

## Connections

- Player → React app: uses
- React app → Lobby pages: routes to
- React app → Match pages: routes to
- React app → Tournament pages: routes to
- Lobby pages → API client: requests lobby
- Match pages → API client: requests match
- Tournament pages → API client: requests tournaments
- Wallet actions → Wallet integration: uses
- Wallet actions → API client: submits deposits
- Wallet actions → Auth state: updates identity
- Auth state → API client: requests auth
- API client → API server: REST requests
- API server → Match handlers: dispatches
- API server → Auth handlers: dispatches
- Match handlers → Match state: applies transitions
- Match handlers → PostgreSQL: reads and writes
- Auth handlers → PostgreSQL: reads and writes
- FACEIT watcher → FACEIT data: polls results
- FACEIT data → FACEIT: fetches match data
- Payout worker → PostgreSQL: reads and updates
- Payout worker → Multisig escrow: requests settlement
- Multisig escrow → Kaspa node: checks and broadcasts
- Multisig escrow → Wager payout: sends payout
- Tournament API → PostgreSQL: reads and writes
- Tournament payouts → PostgreSQL: tracks deposits and payouts
- Tournament payouts → Kaspa node: watches deposits
- Episode engine → Episode handler: dispatches events
- Episode handler → PostgreSQL: updates match records