# taetep01/cpfreezetag architecture

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

- Interactive diagram: https://gitdiagram.com/taetep01/cpfreezetag
- Repository: https://github.com/taetep01/cpfreezetag

## Overview

CP Freezetag is a browser-based multiplayer freeze-tag game. Players enter through the menu, host a room or join by code, wait in a lobby, then play a real-time round with chaser/runner roles, freezing, items, and win conditions. The Phaser client communicates with a Colyseus server; the server owns room state and game rules. The excerpts show key message handlers and client state listeners, but not every rule or scene interaction, so unverified protocol links are dashed.

Main entry points: [`server/src/rooms/GameRoom.ts`](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts) (Game room), [`client/src/scenes/HostJoinScene.ts`](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/HostJoinScene.ts) (Host or join), [`client/src/scenes/LobbyScene.ts`](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/LobbyScene.ts) (Room lobby), [`client/src/main.ts`](https://github.com/taetep01/cpfreezetag/blob/main/client/src/main.ts) (Phaser entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client_flow["Client flow"]
  node_main_menu["Main menu<br/>[MainMenuScene.ts]"]
  node_host_join["Host or join<br/>[HostJoinScene.ts]"]
  node_lobby["Room lobby<br/>[LobbyScene.ts]"]
  node_game_scene["Game scene<br/>[GameScene.ts]"]
end

subgraph group_client_runtime["Client runtime"]
  node_client_entry["Phaser entry<br/>[main.ts]"]
  node_game_client["Room client<br/>[GameClient.ts]"]
  node_version["Game version<br/>[version.ts]"]
end

subgraph group_server_runtime["Server runtime"]
  node_server["Colyseus server<br/>[index.ts]"]
  node_room["Game room<br/>[GameRoom.ts]"]
end

subgraph group_game_rules["Game rules"]
  node_room_state["Player and item state<br/>[GameRoom.ts]"]
  node_round_setup["Round setup<br/>[GameRoom.ts]"]
  node_movement_tags["Movement and tagging<br/>[GameRoom.ts]"]
  node_item_rules["Item effects<br/>[GameRoom.ts]"]
  node_round_clock["Round timer<br/>[GameRoom.ts]"]
  node_round_result["Win and end rules<br/>[GameRoom.ts]"]
end

node_player(("Player"))

node_player -->|"opens"| node_main_menu
node_main_menu -->|"opens"| node_host_join
node_client_entry -->|"registers"| node_main_menu
node_client_entry -->|"registers"| node_host_join
node_client_entry -->|"registers"| node_lobby
node_client_entry -->|"registers"| node_game_scene
node_host_join -->|"creates or joins"| node_game_client
node_host_join -->|"opens after connection"| node_lobby
node_lobby -->|"requests start"| node_game_client
node_lobby -->|"opens on start"| node_game_scene
node_game_scene -->|"sends gameplay actions"| node_game_client
node_host_join -->|"displays"| node_version
node_lobby -->|"displays"| node_version
node_main_menu -->|"displays"| node_version
node_game_client -.->|"connects to"| node_server
node_server -->|"registers room"| node_room
node_room -->|"initializes"| node_room_state
node_room -->|"handles start"| node_round_setup
node_room -->|"handles movement"| node_movement_tags
node_room -->|"handles item actions"| node_item_rules
node_round_setup -->|"assigns roles"| node_room_state
node_movement_tags -->|"updates players"| node_room_state
node_movement_tags -.->|"can end round"| node_round_result
node_item_rules -->|"updates items and players"| node_room_state
node_room -->|"starts timer"| node_round_clock
node_round_clock -->|"ends on timeout"| node_round_result
node_room -->|"handles departures"| node_round_result
node_room_state -.->|"syncs state"| node_game_scene

click node_main_menu "https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/MainMenuScene.ts"
click node_host_join "https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/HostJoinScene.ts"
click node_lobby "https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/LobbyScene.ts"
click node_game_scene "https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/GameScene.ts"
click node_client_entry "https://github.com/taetep01/cpfreezetag/blob/main/client/src/main.ts"
click node_game_client "https://github.com/taetep01/cpfreezetag/blob/main/client/src/network/GameClient.ts"
click node_version "https://github.com/taetep01/cpfreezetag/blob/main/client/src/version.ts"
click node_server "https://github.com/taetep01/cpfreezetag/blob/main/server/src/index.ts"
click node_room "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_room_state "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_round_setup "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_movement_tags "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_item_rules "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_round_clock "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts"
click node_round_result "https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.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_main_menu,node_host_join,node_lobby,node_game_scene toneBlue
class node_client_entry,node_game_client,node_version toneAmber
class node_server,node_room toneMint
class node_room_state,node_round_setup,node_movement_tags,node_item_rules,node_round_clock,node_round_result toneRose
class node_player toneIndigo
```

## Components

### Client flow

- [Main menu](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/MainMenuScene.ts): `client/src/scenes/MainMenuScene.ts`
- [Host or join](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/HostJoinScene.ts): `client/src/scenes/HostJoinScene.ts`
- [Room lobby](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/LobbyScene.ts): `client/src/scenes/LobbyScene.ts`
- [Game scene](https://github.com/taetep01/cpfreezetag/blob/main/client/src/scenes/GameScene.ts): `client/src/scenes/GameScene.ts`

### Client runtime

- [Phaser entry](https://github.com/taetep01/cpfreezetag/blob/main/client/src/main.ts): `client/src/main.ts`
- [Room client](https://github.com/taetep01/cpfreezetag/blob/main/client/src/network/GameClient.ts): `client/src/network/GameClient.ts`
- [Game version](https://github.com/taetep01/cpfreezetag/blob/main/client/src/version.ts): `client/src/version.ts`

### Server runtime

- [Colyseus server](https://github.com/taetep01/cpfreezetag/blob/main/server/src/index.ts): `server/src/index.ts`
- [Game room](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`

### Game rules

- [Player and item state](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`
- [Round setup](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`
- [Movement and tagging](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`
- [Item effects](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`
- [Round timer](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`
- [Win and end rules](https://github.com/taetep01/cpfreezetag/blob/main/server/src/rooms/GameRoom.ts): `server/src/rooms/GameRoom.ts`

### Other components

- **Player**

## Connections

- Player → Main menu: opens (evidence: `client/src/scenes/MainMenuScene.ts`)
- Main menu → Host or join: opens (evidence: `client/src/scenes/MainMenuScene.ts`)
- Phaser entry → Main menu: registers (evidence: `client/src/main.ts`)
- Phaser entry → Host or join: registers (evidence: `client/src/main.ts`)
- Phaser entry → Room lobby: registers (evidence: `client/src/main.ts`)
- Phaser entry → Game scene: registers (evidence: `client/src/main.ts`)
- Host or join → Room client: creates or joins (evidence: `client/src/scenes/HostJoinScene.ts`)
- Host or join → Room lobby: opens after connection (evidence: `client/src/scenes/HostJoinScene.ts`)
- Room lobby → Room client: requests start (evidence: `client/src/scenes/LobbyScene.ts`)
- Room lobby → Game scene: opens on start (evidence: `client/src/scenes/LobbyScene.ts`)
- Game scene → Room client: sends gameplay actions (evidence: `client/src/scenes/GameScene.ts`)
- Host or join → Game version: displays (evidence: `client/src/scenes/HostJoinScene.ts`)
- Room lobby → Game version: displays (evidence: `client/src/scenes/LobbyScene.ts`)
- Main menu → Game version: displays (evidence: `client/src/scenes/MainMenuScene.ts`)
- Room client → Colyseus server: connects to
- Colyseus server → Game room: registers room (evidence: `server/src/index.ts`)
- Game room → Player and item state: initializes (evidence: `server/src/rooms/GameRoom.ts`)
- Game room → Round setup: handles start (evidence: `server/src/rooms/GameRoom.ts`)
- Game room → Movement and tagging: handles movement (evidence: `server/src/rooms/GameRoom.ts`)
- Game room → Item effects: handles item actions (evidence: `server/src/rooms/GameRoom.ts`)
- Round setup → Player and item state: assigns roles (evidence: `server/src/rooms/GameRoom.ts`)
- Movement and tagging → Player and item state: updates players (evidence: `server/src/rooms/GameRoom.ts`)
- Movement and tagging → Win and end rules: can end round (evidence: `server/src/rooms/GameRoom.ts`)
- Item effects → Player and item state: updates items and players (evidence: `server/src/rooms/GameRoom.ts`)
- Game room → Round timer: starts timer (evidence: `server/src/rooms/GameRoom.ts`)
- Round timer → Win and end rules: ends on timeout (evidence: `server/src/rooms/GameRoom.ts`)
- Game room → Win and end rules: handles departures (evidence: `server/src/rooms/GameRoom.ts`)
- Player and item state → Game scene: syncs state
