# genarossi19/character-us-front architecture

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

- Interactive diagram: https://gitdiagram.com/genarossi19/character-us-front
- Repository: https://github.com/genarossi19/character-us-front

## Overview

CharacterUs is a React frontend for a social impostor game. The principal flow is: a player authenticates or joins by room code, configures or enters a room, waits for the lobby to start, then participates in server-authoritative word, debate, voting, and results stages. Socket hooks and Zustand stores form the key internal layer for commands and synchronized room/game state; HTTP handles authentication and category data. The README documents additional recovery, invitations, inactivity, and in-person play. Some page and event-handler implementations were not sampled, so links for those capabilities are shown only where the README documents them.

Main entry points: [`src/App.tsx`](https://github.com/genarossi19/character-us-front/blob/main/src/App.tsx) (Route shell), [`src/pages/GameScreenV2.tsx`](https://github.com/genarossi19/character-us-front/blob/main/src/pages/GameScreenV2.tsx) (Game screen), [`src/hooks/useSocketRoom.ts`](https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketRoom.ts) (Room commands), [`src/hooks/useSocketGame.ts`](https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketGame.ts) (Game commands and events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and identity"]
  node_app["Route shell<br/>[App.tsx]"]
  node_authui["Login and signup"]
  node_identity[("Identity state<br/>[useUserStore.ts]")]
  node_authapi["Auth API<br/>[auth.ts]"]
  node_menu["Home and menu"]
end

subgraph group_rooms["Room lifecycle"]
  node_create["Room creation"]
  node_categories["Category API<br/>[category.ts]"]
  node_join["Join by code"]
  node_lobby["Waiting room<br/>[WaitingRoomV2.tsx]"]
  node_roomhook["Room commands<br/>[useSocketRoom.ts]"]
  node_recovery["Room recovery<br/>[roomRecovery.ts]"]
end

subgraph group_play["Game experience"]
  node_gamescreen["Game screen<br/>[GameScreenV2.tsx]"]
  node_word["Word turns<br/>[WordSubmission.tsx]"]
  node_debate["Debate and chat<br/>[DebateChat.tsx]"]
  node_voting["Voting<br/>[VotingPhase.tsx]"]
  node_results["Round and game results<br/>[RoundResults.tsx]"]
  node_gamehook["Game commands and events<br/>[useSocketGame.ts]"]
end

subgraph group_runtime["Client runtime"]
  node_http["HTTP client<br/>[client.ts]"]
  node_roomstate[("Room state<br/>[useRoomStore.ts]")]
  node_sessionstate[("Recovery session")]
  node_gamestate[("Game state<br/>[useGameStore.ts]")]
  node_socketfacade["Socket facade<br/>[index.ts]"]
  node_socket["Socket connection<br/>[socket.ts]"]
end

node_player(("Player"))
node_backend{{"CharacterUs backend"}}

node_player -->|"opens"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_menu
node_app -->|"routes to"| node_create
node_app -->|"routes to"| node_join
node_app -->|"routes to"| node_lobby
node_app -->|"routes to"| node_gamescreen
node_authui -->|"updates"| node_identity
node_identity -->|"requests"| node_authapi
node_authapi -->|"uses"| node_http
node_http -->|"HTTP requests"| node_backend
node_create -->|"loads categories"| node_categories
node_create -->|"creates room"| node_roomhook
node_join -->|"joins room"| node_roomhook
node_lobby -->|"manages room"| node_roomhook
node_roomhook -->|"emits commands"| node_socketfacade
node_socketfacade -->|"uses connection"| node_socket
node_socket -->|"Socket.IO"| node_backend
node_roomhook -->|"updates"| node_roomstate
node_lobby -->|"server lobby contract"| node_backend
node_gamescreen -->|"uses"| node_gamehook
node_gamehook -->|"emits and listens"| node_socketfacade
node_gamehook -->|"updates"| node_gamestate
node_gamehook -->|"reads room"| node_roomstate
node_gamescreen -->|"presents"| node_word
node_gamescreen -->|"presents"| node_debate
node_gamescreen -->|"presents"| node_voting
node_gamescreen -->|"presents"| node_results
node_player -->|"submits clue"| node_word
node_player -->|"debates"| node_debate
node_player -->|"votes"| node_voting
node_recovery -->|"reads credential"| node_sessionstate
node_player -->|"restores room"| node_recovery
node_backend -->|"room updates"| node_roomstate
node_backend -->|"game events"| node_gamestate

click node_app "https://github.com/genarossi19/character-us-front/blob/main/src/App.tsx"
click node_authui "https://github.com/genarossi19/character-us-front/tree/main/src/pages"
click node_identity "https://github.com/genarossi19/character-us-front/blob/main/src/store/useUserStore.ts"
click node_authapi "https://github.com/genarossi19/character-us-front/blob/main/src/services/api/auth.ts"
click node_http "https://github.com/genarossi19/character-us-front/blob/main/src/services/api/client.ts"
click node_menu "https://github.com/genarossi19/character-us-front/tree/main/src/pages"
click node_create "https://github.com/genarossi19/character-us-front/blob/main/src/pages/CreateRoomPageV2.tsx"
click node_categories "https://github.com/genarossi19/character-us-front/blob/main/src/services/api/category.ts"
click node_join "https://github.com/genarossi19/character-us-front/blob/main/src/pages/QuickJoinScreenV2.tsx"
click node_lobby "https://github.com/genarossi19/character-us-front/blob/main/src/pages/WaitingRoomV2.tsx"
click node_roomhook "https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketRoom.ts"
click node_roomstate "https://github.com/genarossi19/character-us-front/blob/main/src/store/useRoomStore.ts"
click node_recovery "https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/roomRecovery.ts"
click node_sessionstate "https://github.com/genarossi19/character-us-front/blob/main/src/store/useRoomSessionStore.ts"
click node_gamescreen "https://github.com/genarossi19/character-us-front/blob/main/src/pages/GameScreenV2.tsx"
click node_word "https://github.com/genarossi19/character-us-front/blob/main/src/components/game/WordSubmission.tsx"
click node_debate "https://github.com/genarossi19/character-us-front/blob/main/src/components/game/DebateChat.tsx"
click node_voting "https://github.com/genarossi19/character-us-front/blob/main/src/components/game/VotingPhase.tsx"
click node_results "https://github.com/genarossi19/character-us-front/blob/main/src/components/game/RoundResults.tsx"
click node_gamehook "https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketGame.ts"
click node_gamestate "https://github.com/genarossi19/character-us-front/blob/main/src/store/useGameStore.ts"
click node_socketfacade "https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/index.ts"
click node_socket "https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/socket.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_authui,node_identity,node_authapi,node_menu toneBlue
class node_create,node_categories,node_join,node_lobby,node_roomhook,node_recovery toneAmber
class node_gamescreen,node_word,node_debate,node_voting,node_results,node_gamehook toneMint
class node_http,node_roomstate,node_sessionstate,node_gamestate,node_socketfacade,node_socket toneRose
class node_player,node_backend toneIndigo
```

## Components

### Entry and identity

- [Route shell](https://github.com/genarossi19/character-us-front/blob/main/src/App.tsx): `src/App.tsx`
- [Login and signup](https://github.com/genarossi19/character-us-front/tree/main/src/pages): `src/pages`
- [Identity state](https://github.com/genarossi19/character-us-front/blob/main/src/store/useUserStore.ts): `src/store/useUserStore.ts`
- [Auth API](https://github.com/genarossi19/character-us-front/blob/main/src/services/api/auth.ts): `src/services/api/auth.ts`
- [Home and menu](https://github.com/genarossi19/character-us-front/tree/main/src/pages): `src/pages`

### Room lifecycle

- [Room creation](https://github.com/genarossi19/character-us-front/blob/main/src/pages/CreateRoomPageV2.tsx): `src/pages/CreateRoomPageV2.tsx`
- [Category API](https://github.com/genarossi19/character-us-front/blob/main/src/services/api/category.ts): `src/services/api/category.ts`
- [Join by code](https://github.com/genarossi19/character-us-front/blob/main/src/pages/QuickJoinScreenV2.tsx): `src/pages/QuickJoinScreenV2.tsx`
- [Waiting room](https://github.com/genarossi19/character-us-front/blob/main/src/pages/WaitingRoomV2.tsx): `src/pages/WaitingRoomV2.tsx`
- [Room commands](https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketRoom.ts): `src/hooks/useSocketRoom.ts`
- [Room recovery](https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/roomRecovery.ts): `src/services/socket/roomRecovery.ts`

### Game experience

- [Game screen](https://github.com/genarossi19/character-us-front/blob/main/src/pages/GameScreenV2.tsx): `src/pages/GameScreenV2.tsx`
- [Word turns](https://github.com/genarossi19/character-us-front/blob/main/src/components/game/WordSubmission.tsx): `src/components/game/WordSubmission.tsx`
- [Debate and chat](https://github.com/genarossi19/character-us-front/blob/main/src/components/game/DebateChat.tsx): `src/components/game/DebateChat.tsx`
- [Voting](https://github.com/genarossi19/character-us-front/blob/main/src/components/game/VotingPhase.tsx): `src/components/game/VotingPhase.tsx`
- [Round and game results](https://github.com/genarossi19/character-us-front/blob/main/src/components/game/RoundResults.tsx): `src/components/game/RoundResults.tsx`
- [Game commands and events](https://github.com/genarossi19/character-us-front/blob/main/src/hooks/useSocketGame.ts): `src/hooks/useSocketGame.ts`

### Client runtime

- [HTTP client](https://github.com/genarossi19/character-us-front/blob/main/src/services/api/client.ts): `src/services/api/client.ts`
- [Room state](https://github.com/genarossi19/character-us-front/blob/main/src/store/useRoomStore.ts): `src/store/useRoomStore.ts`
- [Recovery session](https://github.com/genarossi19/character-us-front/blob/main/src/store/useRoomSessionStore.ts): `src/store/useRoomSessionStore.ts`
- [Game state](https://github.com/genarossi19/character-us-front/blob/main/src/store/useGameStore.ts): `src/store/useGameStore.ts`
- [Socket facade](https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/index.ts): `src/services/socket/index.ts`
- [Socket connection](https://github.com/genarossi19/character-us-front/blob/main/src/services/socket/socket.ts): `src/services/socket/socket.ts`

### Other components

- **Player**
- **CharacterUs backend**

## Connections

- Player → Route shell: opens (evidence: `src/App.tsx`)
- Route shell → Login and signup: routes to (evidence: `src/App.tsx`)
- Route shell → Home and menu: routes to (evidence: `src/App.tsx`)
- Route shell → Room creation: routes to (evidence: `src/App.tsx`)
- Route shell → Join by code: routes to (evidence: `src/App.tsx`)
- Route shell → Waiting room: routes to (evidence: `src/App.tsx`)
- Route shell → Game screen: routes to (evidence: `src/App.tsx`)
- Login and signup → Identity state: updates (evidence: `src/pages/SignupScreenV2.tsx`)
- Identity state → Auth API: requests (evidence: `src/store/useUserStore.ts`)
- Auth API → HTTP client: uses (evidence: `src/services/api/auth.ts`)
- HTTP client → CharacterUs backend: HTTP requests (evidence: `README.md`)
- Room creation → Category API: loads categories (evidence: `src/pages/CreateRoomPageV2.tsx`)
- Room creation → Room commands: creates room (evidence: `src/pages/CreateRoomPageV2.tsx`)
- Join by code → Room commands: joins room (evidence: `src/pages/QuickJoinScreenV2.tsx`)
- Waiting room → Room commands: manages room (evidence: `src/pages/WaitingRoomV2.tsx`)
- Room commands → Socket facade: emits commands (evidence: `src/hooks/useSocketRoom.ts`)
- Socket facade → Socket connection: uses connection (evidence: `src/services/socket/index.ts`)
- Socket connection → CharacterUs backend: Socket.IO (evidence: `README.md`)
- Room commands → Room state: updates (evidence: `src/hooks/useSocketRoom.ts`)
- Waiting room → CharacterUs backend: server lobby contract (evidence: `README.md`)
- Game screen → Game commands and events: uses (evidence: `README.md`)
- Game commands and events → Socket facade: emits and listens (evidence: `src/hooks/useSocketGame.ts`)
- Game commands and events → Game state: updates (evidence: `src/hooks/useSocketGame.ts`)
- Game commands and events → Room state: reads room (evidence: `src/hooks/useSocketGame.ts`)
- Game screen → Word turns: presents (evidence: `README.md`)
- Game screen → Debate and chat: presents (evidence: `README.md`)
- Game screen → Voting: presents (evidence: `README.md`)
- Game screen → Round and game results: presents (evidence: `README.md`)
- Player → Word turns: submits clue (evidence: `README.md`)
- Player → Debate and chat: debates (evidence: `README.md`)
- Player → Voting: votes (evidence: `README.md`)
- Room recovery → Recovery session: reads credential (evidence: `src/services/socket/roomRecovery.ts`)
- Player → Room recovery: restores room (evidence: `README.md`)
- CharacterUs backend → Room state: room updates (evidence: `README.md`)
- CharacterUs backend → Game state: game events (evidence: `README.md`)
