# kaiser-inc/resenhark architecture

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

- Interactive diagram: https://gitdiagram.com/kaiser-inc/resenhark
- Repository: https://github.com/kaiser-inc/resenhark

## Overview

ResenhARK is a code-based social game room: people join without accounts, chat in real time, and play server-authoritative games. The main flow runs from the web room/lobby through HTTP and Socket.IO into room state and game engines, with Redis persistence and projected updates. Hitline supports built-in or Spotify-imported playlists and audio previews; Huehint’s backend is ready while its interface is still being built. Edges reflect the README and shown import/call references; unsampled UI and integrations are connected only where documented or directly evidenced.

Main entry points: [`apps/api/src/app/realtime/socket-gateway.ts`](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/realtime/socket-gateway.ts) (Socket event gateway), [`apps/api/src/app/core/server.ts`](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/core/server.ts) (API server), [`apps/web/src/components/room/room-shell.tsx`](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/room/room-shell.tsx) (Room interface), [`apps/api/src/app/http/routes/rooms.routes.ts`](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/http/routes/rooms.routes.ts) (Room HTTP routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_home["Home and join<br/>[home-actions.tsx]"]
  node_roomui["Room interface<br/>[room-shell.tsx]"]
  node_hitlineui["Hitline interface<br/>[hitline-board.tsx]"]
  node_huehintui["Huehint interface<br/>[huehint-board.tsx]"]
  node_lobbyui["Lobby setup<br/>[lobby-panel.tsx]"]
end

subgraph group_api["API and realtime"]
  node_roomroutes["Room HTTP routes<br/>[rooms.routes.ts]"]
  node_socket["Socket event gateway<br/>[socket-gateway.ts]"]
  node_hub["Room hub<br/>[room-hub.ts]"]
  node_server["API server<br/>[server.ts]"]
  node_roomdomain["Room and membership<br/>[room.ts]"]
  node_chat["Chat validation<br/>[chat.ts]"]
  node_audioroutes["Audio delivery<br/>[audio.routes.ts]"]
end

subgraph group_games["Game domain"]
  node_hitline["Hitline engine<br/>[engine.ts]"]
  node_huehint["Huehint engine<br/>[engine.ts]"]
  node_registry["Game registry<br/>[registry.ts]"]
end

subgraph group_integrations["Media integrations"]
  node_spotify["Spotify playlist import"]
  node_spotifyauth["Spotify authorization<br/>[spotify-auth.ts]"]
  node_audio["Audio preview providers<br/>[chained-preview.ts]"]
end

subgraph group_state["State and contracts"]
  node_store[("Room persistence")]
  node_contracts["Shared event contracts<br/>[realtime.ts]"]
end

node_player(("Player"))
node_redis[("Redis")]

node_player -->|"creates or joins"| node_home
node_home -->|"creates or joins"| node_roomroutes
node_player -->|"uses room"| node_roomui
node_roomui -->|"sends room events"| node_socket
node_roomui -->|"joins by HTTP"| node_roomroutes
node_lobbyui -->|"configures game"| node_socket
node_roomui -->|"shows game"| node_hitlineui
node_roomui -->|"shows game"| node_huehintui
node_server -->|"registers"| node_roomroutes
node_server -->|"creates"| node_hub
node_server -->|"registers"| node_socket
node_roomroutes -->|"creates membership"| node_roomdomain
node_roomroutes -->|"mutates room"| node_hub
node_socket -->|"mutates room"| node_hub
node_socket -->|"validates messages"| node_chat
node_socket -->|"dispatches game actions"| node_registry
node_hub -->|"ticks game"| node_registry
node_registry -->|"dispatches Hitline"| node_hitline
node_registry -.->|"dispatches Huehint"| node_huehint
node_hub -->|"loads and saves"| node_store
node_store -->|"persists state"| node_redis
node_socket -->|"uses event schemas"| node_contracts
node_roomui -->|"shares event protocol"| node_contracts
node_lobbyui -->|"imports playlist"| node_spotify
node_server -->|"configures source"| node_spotify
node_server -->|"configures authorization"| node_spotifyauth
node_server -->|"registers"| node_audioroutes
node_audioroutes -->|"resolves preview"| node_audio
node_hitline -.->|"serves current draw audio"| node_audioroutes

click node_home "https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/home-actions.tsx"
click node_roomui "https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/room/room-shell.tsx"
click node_hitlineui "https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/hitline/hitline-board.tsx"
click node_huehintui "https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/huehint/huehint-board.tsx"
click node_lobbyui "https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/lobby/lobby-panel.tsx"
click node_roomroutes "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/http/routes/rooms.routes.ts"
click node_socket "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/realtime/socket-gateway.ts"
click node_hub "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/realtime/room-hub.ts"
click node_server "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/core/server.ts"
click node_roomdomain "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/domain/room/room.ts"
click node_chat "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/domain/room/chat.ts"
click node_hitline "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/hitline/engine.ts"
click node_huehint "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/huehint/engine.ts"
click node_registry "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/registry.ts"
click node_spotify "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/spotify/spotify-playlist-source.ts"
click node_spotifyauth "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/spotify/spotify-auth.ts"
click node_audio "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/audio/chained-preview.ts"
click node_audioroutes "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/http/routes/audio.routes.ts"
click node_store "https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/repositories/redis-room-store.ts"
click node_contracts "https://github.com/kaiser-inc/resenhark/blob/main/packages/shared/src/realtime.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_home,node_roomui,node_hitlineui,node_huehintui,node_lobbyui toneBlue
class node_roomroutes,node_socket,node_hub,node_server,node_roomdomain,node_chat,node_audioroutes,node_redis toneAmber
class node_hitline,node_huehint,node_registry toneMint
class node_spotify,node_spotifyauth,node_audio toneRose
class node_store,node_contracts,node_player toneIndigo
```

## Components

### Web experience

- [Home and join](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/home-actions.tsx): `apps/web/src/components/home-actions.tsx`
- [Room interface](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/room/room-shell.tsx): `apps/web/src/components/room/room-shell.tsx`
- [Hitline interface](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/hitline/hitline-board.tsx): `apps/web/src/components/hitline/hitline-board.tsx`
- [Huehint interface](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/huehint/huehint-board.tsx): `apps/web/src/components/huehint/huehint-board.tsx`
- [Lobby setup](https://github.com/kaiser-inc/resenhark/blob/main/apps/web/src/components/lobby/lobby-panel.tsx): `apps/web/src/components/lobby/lobby-panel.tsx`

### API and realtime

- [Room HTTP routes](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/http/routes/rooms.routes.ts): `apps/api/src/app/http/routes/rooms.routes.ts`
- [Socket event gateway](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/realtime/socket-gateway.ts): `apps/api/src/app/realtime/socket-gateway.ts`
- [Room hub](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/realtime/room-hub.ts): `apps/api/src/app/realtime/room-hub.ts`
- [API server](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/core/server.ts): `apps/api/src/app/core/server.ts`
- [Room and membership](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/domain/room/room.ts): `apps/api/src/app/domain/room/room.ts`
- [Chat validation](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/domain/room/chat.ts): `apps/api/src/app/domain/room/chat.ts`
- [Audio delivery](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/http/routes/audio.routes.ts): `apps/api/src/app/http/routes/audio.routes.ts`

### Game domain

- [Hitline engine](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/hitline/engine.ts): `apps/api/src/app/games/hitline/engine.ts`
- [Huehint engine](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/huehint/engine.ts): `apps/api/src/app/games/huehint/engine.ts`
- [Game registry](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/games/registry.ts): `apps/api/src/app/games/registry.ts`

### Media integrations

- [Spotify playlist import](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/spotify/spotify-playlist-source.ts): `apps/api/src/app/gateways/spotify/spotify-playlist-source.ts`
- [Spotify authorization](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/spotify/spotify-auth.ts): `apps/api/src/app/gateways/spotify/spotify-auth.ts`
- [Audio preview providers](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/gateways/audio/chained-preview.ts): `apps/api/src/app/gateways/audio/chained-preview.ts`

### State and contracts

- [Room persistence](https://github.com/kaiser-inc/resenhark/blob/main/apps/api/src/app/repositories/redis-room-store.ts): `apps/api/src/app/repositories/redis-room-store.ts`
- [Shared event contracts](https://github.com/kaiser-inc/resenhark/blob/main/packages/shared/src/realtime.ts): `packages/shared/src/realtime.ts`

### Other components

- **Player**
- **Redis**

## Connections

- Player → Home and join: creates or joins (evidence: `README.md`)
- Home and join → Room HTTP routes: creates or joins (evidence: `README.md`)
- Player → Room interface: uses room (evidence: `README.md`)
- Room interface → Socket event gateway: sends room events (evidence: `README.md`)
- Room interface → Room HTTP routes: joins by HTTP (evidence: `README.md`)
- Lobby setup → Socket event gateway: configures game (evidence: `README.md`)
- Room interface → Hitline interface: shows game (evidence: `README.md`)
- Room interface → Huehint interface: shows game (evidence: `README.md`)
- API server → Room HTTP routes: registers (evidence: `apps/api/src/app/core/server.ts`)
- API server → Room hub: creates (evidence: `apps/api/src/app/core/server.ts`)
- API server → Socket event gateway: registers (evidence: `apps/api/src/app/core/server.ts`)
- Room HTTP routes → Room and membership: creates membership (evidence: `apps/api/src/app/http/routes/rooms.routes.ts`)
- Room HTTP routes → Room hub: mutates room (evidence: `apps/api/src/app/http/routes/rooms.routes.ts`)
- Socket event gateway → Room hub: mutates room (evidence: `apps/api/src/app/realtime/socket-gateway.ts`)
- Socket event gateway → Chat validation: validates messages (evidence: `apps/api/src/app/realtime/socket-gateway.ts`)
- Socket event gateway → Game registry: dispatches game actions (evidence: `apps/api/src/app/realtime/socket-gateway.ts`)
- Room hub → Game registry: ticks game (evidence: `apps/api/src/app/realtime/room-hub.ts`)
- Game registry → Hitline engine: dispatches Hitline (evidence: `apps/api/src/app/realtime/room-hub.ts`)
- Game registry → Huehint engine: dispatches Huehint
- Room hub → Room persistence: loads and saves (evidence: `apps/api/src/app/realtime/room-hub.ts`)
- Room persistence → Redis: persists state
- Socket event gateway → Shared event contracts: uses event schemas (evidence: `apps/api/src/app/realtime/socket-gateway.ts`)
- Room interface → Shared event contracts: shares event protocol (evidence: `README.md`)
- Lobby setup → Spotify playlist import: imports playlist (evidence: `README.md`)
- API server → Spotify playlist import: configures source (evidence: `apps/api/src/main.ts`)
- API server → Spotify authorization: configures authorization (evidence: `apps/api/src/main.ts`)
- API server → Audio delivery: registers (evidence: `apps/api/src/app/core/server.ts`)
- Audio delivery → Audio preview providers: resolves preview (evidence: `apps/api/src/app/http/routes/audio.routes.ts`)
- Hitline engine → Audio delivery: serves current draw audio
