# nathanblatter/impostor architecture

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

- Interactive diagram: https://gitdiagram.com/nathanblatter/impostor
- Repository: https://github.com/nathanblatter/impostor

## Overview

This is a browser-based multiplayer party-game platform: players create or join rooms, configure a game, play one of several social-deduction and party-game modes, then vote or reveal results. The WebSocket server manages room membership and routes game actions through a room-level orchestrator to mode-specific engines; the client presents room and play interfaces and receives game state. Source excerpts show these core connections, but not all UI routing or every server message handler, so those relationships are omitted where unverified.

Main entry points: [`server/GameRoom.ts`](https://github.com/nathanblatter/impostor/blob/main/server/GameRoom.ts) (Room orchestrator), [`server/main.ts`](https://github.com/nathanblatter/impostor/blob/main/server/main.ts) (HTTP and WebSocket server), [`shared/messages.ts`](https://github.com/nathanblatter/impostor/blob/main/shared/messages.ts) (Message protocol), [`client/components/Playing.tsx`](https://github.com/nathanblatter/impostor/blob/main/client/components/Playing.tsx) (Core game screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_app["Application shell<br/>[App.tsx]"]
  node_socket["Socket session<br/>[useSocket.ts]"]
  node_audio["Narration playback<br/>[useAudio.ts]"]
  node_playing["Core game screens<br/>[Playing.tsx]"]
  node_lobby["Room lobby<br/>[Lobby.tsx]"]
  node_results["Results view<br/>[Results.tsx]"]
  node_mode_screens["Mode screens"]
  node_timer["Game timer<br/>[useTimer.ts]"]
  node_sound["Sound effects<br/>[useSound.ts]"]
end

subgraph group_server["Realtime server"]
  node_server["HTTP and WebSocket server<br/>[main.ts]"]
  node_rooms["Room registry<br/>[RoomManager.ts]"]
  node_room["Room orchestrator<br/>[GameRoom.ts]"]
  node_player_model["Player connection<br/>[Player.ts]"]
end

subgraph group_games["Game engines"]
  node_mode_engines["Mode engines"]
  node_word_pool["Word pool<br/>[WordPool.ts]"]
end

subgraph group_shared["Shared protocol"]
  node_protocol["Message protocol<br/>[messages.ts]"]
  node_game_types["Game state types<br/>[types.ts]"]
end

subgraph group_integrations["Data and AI"]
  node_ai["AI content generation<br/>[AiPlayer.ts]"]
  node_database[("Persistent assets and sessions<br/>[db.ts]")]
end

node_player(("Player"))
node_claude["Anthropic API"]

node_player -->|"uses"| node_app
node_app -->|"opens session"| node_socket
node_socket -->|"queues narration"| node_audio
node_playing -->|"uses timer"| node_timer
node_playing -->|"plays effects"| node_sound
node_mode_screens -->|"uses timer"| node_timer
node_mode_screens -->|"plays effects"| node_sound
node_server -->|"manages rooms"| node_rooms
node_rooms -->|"creates rooms"| node_room
node_rooms -->|"tracks players"| node_player_model
node_server -->|"constructs players"| node_player_model
node_server -->|"routes game actions"| node_room
node_room -->|"delegates mode play"| node_mode_engines
node_room -.->|"broadcasts state"| node_player_model
node_room -.->|"loads word data"| node_word_pool
node_room -->|"requests generated content"| node_ai
node_ai -->|"reads and saves assets"| node_database
node_ai -->|"generates content"| node_claude
node_server -->|"initializes and records sessions"| node_database
node_app -->|"uses message types"| node_protocol
node_socket -->|"sends and receives"| node_protocol
node_playing -->|"uses message types"| node_protocol
node_server -->|"dispatches messages"| node_protocol
node_room -->|"builds game state"| node_game_types
node_lobby -->|"uses settings and state"| node_game_types
node_results -->|"renders results"| node_game_types

click node_app "https://github.com/nathanblatter/impostor/blob/main/client/components/App.tsx"
click node_socket "https://github.com/nathanblatter/impostor/blob/main/client/useSocket.ts"
click node_audio "https://github.com/nathanblatter/impostor/blob/main/client/useAudio.ts"
click node_playing "https://github.com/nathanblatter/impostor/blob/main/client/components/Playing.tsx"
click node_lobby "https://github.com/nathanblatter/impostor/blob/main/client/components/Lobby.tsx"
click node_results "https://github.com/nathanblatter/impostor/blob/main/client/components/Results.tsx"
click node_mode_screens "https://github.com/nathanblatter/impostor/tree/main/client/components"
click node_timer "https://github.com/nathanblatter/impostor/blob/main/client/useTimer.ts"
click node_sound "https://github.com/nathanblatter/impostor/blob/main/client/useSound.ts"
click node_protocol "https://github.com/nathanblatter/impostor/blob/main/shared/messages.ts"
click node_game_types "https://github.com/nathanblatter/impostor/blob/main/shared/types.ts"
click node_server "https://github.com/nathanblatter/impostor/blob/main/server/main.ts"
click node_rooms "https://github.com/nathanblatter/impostor/blob/main/server/RoomManager.ts"
click node_room "https://github.com/nathanblatter/impostor/blob/main/server/GameRoom.ts"
click node_player_model "https://github.com/nathanblatter/impostor/blob/main/server/Player.ts"
click node_mode_engines "https://github.com/nathanblatter/impostor/tree/main/server"
click node_word_pool "https://github.com/nathanblatter/impostor/blob/main/server/WordPool.ts"
click node_ai "https://github.com/nathanblatter/impostor/blob/main/server/AiPlayer.ts"
click node_database "https://github.com/nathanblatter/impostor/blob/main/server/db.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_socket,node_audio,node_playing,node_lobby,node_results,node_mode_screens,node_timer,node_sound toneBlue
class node_server,node_rooms,node_room,node_player_model toneAmber
class node_mode_engines,node_word_pool,node_claude toneMint
class node_protocol,node_game_types toneRose
class node_ai,node_database,node_player toneIndigo
```

## Components

### Browser client

- [Application shell](https://github.com/nathanblatter/impostor/blob/main/client/components/App.tsx): `client/components/App.tsx`
- [Socket session](https://github.com/nathanblatter/impostor/blob/main/client/useSocket.ts): `client/useSocket.ts`
- [Narration playback](https://github.com/nathanblatter/impostor/blob/main/client/useAudio.ts): `client/useAudio.ts`
- [Core game screens](https://github.com/nathanblatter/impostor/blob/main/client/components/Playing.tsx): `client/components/Playing.tsx`
- [Room lobby](https://github.com/nathanblatter/impostor/blob/main/client/components/Lobby.tsx): `client/components/Lobby.tsx`
- [Results view](https://github.com/nathanblatter/impostor/blob/main/client/components/Results.tsx): `client/components/Results.tsx`
- [Mode screens](https://github.com/nathanblatter/impostor/tree/main/client/components): `client/components`
- [Game timer](https://github.com/nathanblatter/impostor/blob/main/client/useTimer.ts): `client/useTimer.ts`
- [Sound effects](https://github.com/nathanblatter/impostor/blob/main/client/useSound.ts): `client/useSound.ts`

### Realtime server

- [HTTP and WebSocket server](https://github.com/nathanblatter/impostor/blob/main/server/main.ts): `server/main.ts`
- [Room registry](https://github.com/nathanblatter/impostor/blob/main/server/RoomManager.ts): `server/RoomManager.ts`
- [Room orchestrator](https://github.com/nathanblatter/impostor/blob/main/server/GameRoom.ts): `server/GameRoom.ts`
- [Player connection](https://github.com/nathanblatter/impostor/blob/main/server/Player.ts): `server/Player.ts`

### Game engines

- [Mode engines](https://github.com/nathanblatter/impostor/tree/main/server): `server`
- [Word pool](https://github.com/nathanblatter/impostor/blob/main/server/WordPool.ts): `server/WordPool.ts`

### Shared protocol

- [Message protocol](https://github.com/nathanblatter/impostor/blob/main/shared/messages.ts): `shared/messages.ts`
- [Game state types](https://github.com/nathanblatter/impostor/blob/main/shared/types.ts): `shared/types.ts`

### Data and AI

- [AI content generation](https://github.com/nathanblatter/impostor/blob/main/server/AiPlayer.ts): `server/AiPlayer.ts`
- [Persistent assets and sessions](https://github.com/nathanblatter/impostor/blob/main/server/db.ts): `server/db.ts`

### Other components

- **Player**
- **Anthropic API**

## Connections

- Player → Application shell: uses
- Application shell → Socket session: opens session (evidence: `client/components/App.tsx`)
- Socket session → Narration playback: queues narration (evidence: `client/useSocket.ts`)
- Core game screens → Game timer: uses timer (evidence: `client/components/Playing.tsx`)
- Core game screens → Sound effects: plays effects (evidence: `client/components/Playing.tsx`)
- Mode screens → Game timer: uses timer (evidence: `client/components/BonusPlaying.tsx`)
- Mode screens → Sound effects: plays effects (evidence: `client/components/Voting.tsx`)
- HTTP and WebSocket server → Room registry: manages rooms (evidence: `server/main.ts`)
- Room registry → Room orchestrator: creates rooms (evidence: `server/RoomManager.ts`)
- Room registry → Player connection: tracks players (evidence: `server/RoomManager.ts`)
- HTTP and WebSocket server → Player connection: constructs players (evidence: `server/main.ts`)
- HTTP and WebSocket server → Room orchestrator: routes game actions (evidence: `server/main.ts`)
- Room orchestrator → Mode engines: delegates mode play (evidence: `server/GameRoom.ts`)
- Room orchestrator → Player connection: broadcasts state (evidence: `server/GameRoom.ts`)
- Room orchestrator → Word pool: loads word data (evidence: `server/GameRoom.ts`)
- Room orchestrator → AI content generation: requests generated content (evidence: `server/GameRoom.ts`)
- AI content generation → Persistent assets and sessions: reads and saves assets (evidence: `server/AiPlayer.ts`)
- AI content generation → Anthropic API: generates content (evidence: `server/AiPlayer.ts`)
- HTTP and WebSocket server → Persistent assets and sessions: initializes and records sessions (evidence: `server/main.ts`)
- Application shell → Message protocol: uses message types (evidence: `client/components/App.tsx`)
- Socket session → Message protocol: sends and receives (evidence: `client/useSocket.ts`)
- Core game screens → Message protocol: uses message types (evidence: `client/components/Playing.tsx`)
- HTTP and WebSocket server → Message protocol: dispatches messages (evidence: `server/main.ts`)
- Room orchestrator → Game state types: builds game state (evidence: `server/GameRoom.ts`)
- Room lobby → Game state types: uses settings and state (evidence: `client/components/Lobby.tsx`)
- Results view → Game state types: renders results (evidence: `client/components/Results.tsx`)
