# suvajit324/who-is-the-imposter architecture

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

- Interactive diagram: https://gitdiagram.com/suvajit324/who-is-the-imposter
- Repository: https://github.com/suvajit324/who-is-the-imposter

## Overview

Who's the Imposter? is a browser-based, real-time social deduction game. Players create or join private rooms, configure and ready a lobby, then play server-authoritative rounds through private role reveal, clues, discussion, voting/runoffs, results, scoring, and rematches. The React client sends Socket.IO actions to the server’s room manager; shared contracts define the event and data shapes. Room state is in memory, while MongoDB optionally supplies word pairs and stores completed games. Edges reflect README statements and shown source references; unsampled capability wiring is not inferred.

Main entry points: [`apps/server/src/domain/roomManager.ts`](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/domain/roomManager.ts) (Room engine), [`apps/web/src/App.tsx`](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/App.tsx) (Game UI), [`apps/server/src/socket/registerHandlers.ts`](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/socket/registerHandlers.ts) (Event handlers), [`apps/web/src/state/socket.ts`](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/state/socket.ts) (Socket client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["Game UI<br/>[App.tsx]"]
  node_socket_client["Socket client<br/>[socket.ts]"]
  node_chat_hook["Chat sync<br/>[useRoomChat.ts]"]
  node_chat_service["Chat service<br/>[chatService.ts]"]
  node_chat_ui["Chat UI<br/>[ChatBox.tsx]"]
end

subgraph group_server["Game server"]
  node_server_entry["Server entry<br/>[index.ts]"]
  node_socket_handlers["Event handlers"]
  node_rooms["Room engine<br/>[roomManager.ts]"]
  node_round_rules["Round rules"]
  node_server_chat["Room chat<br/>[chat.ts]"]
  node_moderation["Chat moderation"]
end

subgraph group_content["Game content"]
  node_word_bank["Word bank<br/>[wordBank.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_shared_contracts["Contracts<br/>[index.ts]"]
end

subgraph group_storage["Persistence"]
  node_persistence["Persistence<br/>[index.ts]"]
  node_models[("Stored records<br/>[models.ts]")]
end

node_players(("Players"))
node_mongo[("MongoDB")]

node_players -->|"use game"| node_app
node_app -->|"sends actions"| node_socket_client
node_socket_client -.->|"Socket.IO events"| node_socket_handlers
node_server_entry -->|"registers"| node_socket_handlers
node_socket_handlers -->|"dispatches actions"| node_rooms
node_rooms -->|"uses rules"| node_round_rules
node_rooms -->|"selects words"| node_word_bank
node_rooms -->|"creates engine"| node_moderation
node_rooms -->|"manages chat"| node_server_chat
node_chat_hook -->|"syncs history"| node_chat_service
node_chat_ui -->|"renders chat"| node_chat_hook
node_app -.->|"shows chat"| node_chat_ui
node_chat_service -->|"sends chat"| node_socket_client
node_socket_handlers -->|"validates events"| node_shared_contracts
node_app -->|"uses game types"| node_shared_contracts
node_server_entry -->|"initializes"| node_persistence
node_persistence -->|"uses models"| node_models
node_models -.->|"stores records"| node_mongo
node_players -.->|"optional storage"| node_mongo

click node_app "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/App.tsx"
click node_socket_client "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/state/socket.ts"
click node_chat_hook "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/chat/useRoomChat.ts"
click node_chat_service "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/chat/chatService.ts"
click node_chat_ui "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/components/chat/ChatBox.tsx"
click node_server_entry "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/index.ts"
click node_socket_handlers "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/socket/registerHandlers.ts"
click node_rooms "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/domain/roomManager.ts"
click node_round_rules "https://github.com/suvajit324/who-is-the-imposter/tree/main/apps/server/src/domain"
click node_server_chat "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/domain/chat.ts"
click node_moderation "https://github.com/suvajit324/who-is-the-imposter/tree/main/apps/server/src/moderation"
click node_word_bank "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/data/wordBank.ts"
click node_shared_contracts "https://github.com/suvajit324/who-is-the-imposter/blob/main/packages/shared/src/index.ts"
click node_persistence "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/persistence/index.ts"
click node_models "https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/persistence/models.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_client,node_chat_hook,node_chat_service,node_chat_ui toneBlue
class node_server_entry,node_socket_handlers,node_rooms,node_round_rules,node_server_chat,node_moderation,node_mongo toneAmber
class node_word_bank toneMint
class node_shared_contracts toneRose
class node_persistence,node_models,node_players toneIndigo
```

## Components

### Web client

- [Game UI](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Socket client](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/state/socket.ts): `apps/web/src/state/socket.ts`
- [Chat sync](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/chat/useRoomChat.ts): `apps/web/src/chat/useRoomChat.ts`
- [Chat service](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/chat/chatService.ts): `apps/web/src/chat/chatService.ts`
- [Chat UI](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/web/src/components/chat/ChatBox.tsx): `apps/web/src/components/chat/ChatBox.tsx`

### Game server

- [Server entry](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/index.ts): `apps/server/src/index.ts`
- [Event handlers](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/socket/registerHandlers.ts): `apps/server/src/socket/registerHandlers.ts`
- [Room engine](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/domain/roomManager.ts): `apps/server/src/domain/roomManager.ts`
- [Round rules](https://github.com/suvajit324/who-is-the-imposter/tree/main/apps/server/src/domain): `apps/server/src/domain`
- [Room chat](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/domain/chat.ts): `apps/server/src/domain/chat.ts`
- [Chat moderation](https://github.com/suvajit324/who-is-the-imposter/tree/main/apps/server/src/moderation): `apps/server/src/moderation`

### Game content

- [Word bank](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/data/wordBank.ts): `apps/server/src/data/wordBank.ts`

### Shared contracts

- [Contracts](https://github.com/suvajit324/who-is-the-imposter/blob/main/packages/shared/src/index.ts): `packages/shared/src/index.ts`

### Persistence

- [Persistence](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/persistence/index.ts): `apps/server/src/persistence/index.ts`
- [Stored records](https://github.com/suvajit324/who-is-the-imposter/blob/main/apps/server/src/persistence/models.ts): `apps/server/src/persistence/models.ts`

### Other components

- **Players**
- **MongoDB**

## Connections

- Players → Game UI: use game (evidence: `README.md`)
- Game UI → Socket client: sends actions (evidence: `apps/web/src/App.tsx`)
- Socket client → Event handlers: Socket.IO events (evidence: `README.md`)
- Server entry → Event handlers: registers (evidence: `apps/server/src/index.ts`)
- Event handlers → Room engine: dispatches actions (evidence: `apps/server/src/socket/registerHandlers.ts`)
- Room engine → Round rules: uses rules (evidence: `apps/server/src/domain/roomManager.ts`)
- Room engine → Word bank: selects words (evidence: `apps/server/src/domain/roomManager.ts`)
- Room engine → Chat moderation: creates engine (evidence: `apps/server/src/domain/roomManager.ts`)
- Room engine → Room chat: manages chat (evidence: `apps/server/src/domain/roomManager.ts`)
- Chat sync → Chat service: syncs history (evidence: `apps/web/src/chat/useRoomChat.ts`)
- Chat UI → Chat sync: renders chat (evidence: `apps/web/src/components/chat/ChatBox.tsx`)
- Game UI → Chat UI: shows chat (evidence: `README.md`)
- Chat service → Socket client: sends chat (evidence: `apps/web/src/chat/chatService.ts`)
- Event handlers → Contracts: validates events (evidence: `apps/server/src/socket/registerHandlers.ts`)
- Game UI → Contracts: uses game types (evidence: `apps/web/src/App.tsx`)
- Server entry → Persistence: initializes (evidence: `apps/server/src/index.ts`)
- Persistence → Stored records: uses models (evidence: `apps/server/src/persistence/index.ts`)
- Stored records → MongoDB: stores records (evidence: `README.md`)
- Players → MongoDB: optional storage (evidence: `README.md`)