# pepper-candy/firechicks architecture

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

- Interactive diagram: https://gitdiagram.com/pepper-candy/firechicks
- Repository: https://github.com/pepper-candy/firechicks

## Overview

Fire Chicks is an asymmetric multiplayer game: a host runs the shared game on a large screen while phone players join as cooperative Chicks or the Eagle. The workflow moves from room setup and role-based play through tip collection, hunting, disruptive mini-games, a final exam, and transcript-style results. The graph includes the game-state, room-connection, map, scoring, asset-loading, and exam/event layers. Several page and API implementations were not sampled; those links are included only where the README or source index supports them.

Main entry points: [`src/hooks/useGameLogic.ts`](https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameLogic.ts) (Game-state logic), [`src/hooks/useGameRoom.ts`](https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameRoom.ts) (Room connections), [`src/App.tsx`](https://github.com/pepper-candy/firechicks/blob/main/src/App.tsx) (Route application), [`src/pages/Host.tsx`](https://github.com/pepper-candy/firechicks/blob/main/src/pages/Host.tsx) (Host console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Game entry"]
  node_app["Route application<br/>[App.tsx]"]
  node_gameindex["Game entry page<br/>[GameIndex.tsx]"]
  node_hostpage["Host console<br/>[Host.tsx]"]
  node_clientpage["Player client<br/>[Client.tsx]"]
end

subgraph group_sessions["Rooms and sync"]
  node_roomhook["Room connections<br/>[useGameRoom.ts]"]
  node_roomapi["Room and tip APIs"]
  node_supabase[("Realtime backend<br/>[client.ts]")]
end

subgraph group_gameplay["Game rules and world"]
  node_gamelogic["Game-state logic<br/>[useGameLogic.ts]"]
  node_types["Game state types<br/>[gameTypes.ts]"]
  node_mapdata["Map and collision rules<br/>[gameplayMapData.ts]"]
  node_botai["Bot behavior<br/>[botAI.ts]"]
  node_grading["Grades and scoring<br/>[gradeSystem.ts]"]
  node_stages["Stage definitions<br/>[stageInfo.ts]"]
  node_character["Character viewer"]
end

subgraph group_events["Exams and events"]
  node_crossy["Crossy Road event"]
  node_mockexam["Mock exam client<br/>[MockExamClient.tsx]"]
  node_finalexam["Final exam client"]
  node_tips["Exam tips page<br/>[ExamTips.tsx]"]
end

subgraph group_support["Assets and services"]
  node_assets["Asset loading"]
  node_assetcache["Asset cache<br/>[assetCache.ts]"]
  node_assetcatalog["Asset catalog<br/>[assets.ts]"]
  node_sw["Asset cache worker<br/>[asset-cache-sw.js]"]
end

node_host(("Host"))
node_players(("Phone players"))

node_host -->|"runs game"| node_hostpage
node_players -->|"join by code"| node_clientpage
node_app -->|"routes to"| node_gameindex
node_app -->|"routes to"| node_hostpage
node_app -->|"routes to"| node_clientpage
node_hostpage -.->|"uses room"| node_roomhook
node_clientpage -->|"uses room"| node_roomhook
node_roomhook -->|"creates rooms"| node_roomapi
node_roomhook -->|"syncs state"| node_supabase
node_roomhook -.->|"exchanges game messages"| node_gamelogic
node_gamelogic -->|"serializes state"| node_types
node_gamelogic -->|"resolves movement"| node_mapdata
node_gamelogic -->|"updates grades"| node_grading
node_gamelogic -->|"uses bot decisions"| node_botai
node_gamelogic -->|"uses stage data"| node_stages
node_gamelogic -->|"uses character view"| node_character
node_gamelogic -.->|"runs mini-games"| node_crossy
node_gamelogic -.->|"runs mock exam"| node_mockexam
node_gamelogic -.->|"runs final exam"| node_finalexam
node_players -->|"read exam tips"| node_tips
node_assets -->|"reads and writes"| node_assetcache
node_character -->|"loads assets"| node_assetcatalog
node_assets -.->|"registers worker"| node_sw

click node_app "https://github.com/pepper-candy/firechicks/blob/main/src/App.tsx"
click node_gameindex "https://github.com/pepper-candy/firechicks/blob/main/src/pages/GameIndex.tsx"
click node_hostpage "https://github.com/pepper-candy/firechicks/blob/main/src/pages/Host.tsx"
click node_clientpage "https://github.com/pepper-candy/firechicks/blob/main/src/pages/Client.tsx"
click node_roomhook "https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameRoom.ts"
click node_roomapi "https://github.com/pepper-candy/firechicks/tree/main/api"
click node_supabase "https://github.com/pepper-candy/firechicks/blob/main/src/integrations/supabase/client.ts"
click node_gamelogic "https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameLogic.ts"
click node_types "https://github.com/pepper-candy/firechicks/blob/main/src/lib/gameTypes.ts"
click node_mapdata "https://github.com/pepper-candy/firechicks/blob/main/src/lib/gameplayMapData.ts"
click node_botai "https://github.com/pepper-candy/firechicks/blob/main/src/lib/botAI.ts"
click node_grading "https://github.com/pepper-candy/firechicks/blob/main/src/lib/gradeSystem.ts"
click node_stages "https://github.com/pepper-candy/firechicks/blob/main/src/lib/stageInfo.ts"
click node_character "https://github.com/pepper-candy/firechicks/blob/main/src/components/CharacterViewer.tsx"
click node_crossy "https://github.com/pepper-candy/firechicks/blob/main/src/components/events/CrossyRoadClient.tsx"
click node_mockexam "https://github.com/pepper-candy/firechicks/blob/main/src/components/events/MockExamClient.tsx"
click node_finalexam "https://github.com/pepper-candy/firechicks/blob/main/src/components/exam/FinalExamClient.tsx"
click node_tips "https://github.com/pepper-candy/firechicks/blob/main/src/pages/ExamTips.tsx"
click node_assets "https://github.com/pepper-candy/firechicks/blob/main/src/context/AssetLoadingContext.tsx"
click node_assetcache "https://github.com/pepper-candy/firechicks/blob/main/src/lib/assetCache.ts"
click node_assetcatalog "https://github.com/pepper-candy/firechicks/blob/main/src/lib/assets.ts"
click node_sw "https://github.com/pepper-candy/firechicks/blob/main/public/asset-cache-sw.js"

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_gameindex,node_hostpage,node_clientpage toneBlue
class node_roomhook,node_roomapi,node_supabase toneAmber
class node_gamelogic,node_types,node_mapdata,node_botai,node_grading,node_stages,node_character toneMint
class node_crossy,node_mockexam,node_finalexam,node_tips toneRose
class node_assets,node_assetcache,node_assetcatalog,node_sw,node_host,node_players toneIndigo
```

## Components

### Game entry

- [Route application](https://github.com/pepper-candy/firechicks/blob/main/src/App.tsx): `src/App.tsx`
- [Game entry page](https://github.com/pepper-candy/firechicks/blob/main/src/pages/GameIndex.tsx): `src/pages/GameIndex.tsx`
- [Host console](https://github.com/pepper-candy/firechicks/blob/main/src/pages/Host.tsx): `src/pages/Host.tsx`
- [Player client](https://github.com/pepper-candy/firechicks/blob/main/src/pages/Client.tsx): `src/pages/Client.tsx`

### Rooms and sync

- [Room connections](https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameRoom.ts): `src/hooks/useGameRoom.ts`
- [Room and tip APIs](https://github.com/pepper-candy/firechicks/tree/main/api): `api`
- [Realtime backend](https://github.com/pepper-candy/firechicks/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`

### Game rules and world

- [Game-state logic](https://github.com/pepper-candy/firechicks/blob/main/src/hooks/useGameLogic.ts): `src/hooks/useGameLogic.ts`
- [Game state types](https://github.com/pepper-candy/firechicks/blob/main/src/lib/gameTypes.ts): `src/lib/gameTypes.ts`
- [Map and collision rules](https://github.com/pepper-candy/firechicks/blob/main/src/lib/gameplayMapData.ts): `src/lib/gameplayMapData.ts`
- [Bot behavior](https://github.com/pepper-candy/firechicks/blob/main/src/lib/botAI.ts): `src/lib/botAI.ts`
- [Grades and scoring](https://github.com/pepper-candy/firechicks/blob/main/src/lib/gradeSystem.ts): `src/lib/gradeSystem.ts`
- [Stage definitions](https://github.com/pepper-candy/firechicks/blob/main/src/lib/stageInfo.ts): `src/lib/stageInfo.ts`
- [Character viewer](https://github.com/pepper-candy/firechicks/blob/main/src/components/CharacterViewer.tsx): `src/components/CharacterViewer.tsx`

### Exams and events

- [Crossy Road event](https://github.com/pepper-candy/firechicks/blob/main/src/components/events/CrossyRoadClient.tsx): `src/components/events/CrossyRoadClient.tsx`
- [Mock exam client](https://github.com/pepper-candy/firechicks/blob/main/src/components/events/MockExamClient.tsx): `src/components/events/MockExamClient.tsx`
- [Final exam client](https://github.com/pepper-candy/firechicks/blob/main/src/components/exam/FinalExamClient.tsx): `src/components/exam/FinalExamClient.tsx`
- [Exam tips page](https://github.com/pepper-candy/firechicks/blob/main/src/pages/ExamTips.tsx): `src/pages/ExamTips.tsx`

### Assets and services

- [Asset loading](https://github.com/pepper-candy/firechicks/blob/main/src/context/AssetLoadingContext.tsx): `src/context/AssetLoadingContext.tsx`
- [Asset cache](https://github.com/pepper-candy/firechicks/blob/main/src/lib/assetCache.ts): `src/lib/assetCache.ts`
- [Asset catalog](https://github.com/pepper-candy/firechicks/blob/main/src/lib/assets.ts): `src/lib/assets.ts`
- [Asset cache worker](https://github.com/pepper-candy/firechicks/blob/main/public/asset-cache-sw.js): `public/asset-cache-sw.js`

### Other components

- **Host**
- **Phone players**

## Connections

- Host → Host console: runs game (evidence: `README.md`)
- Phone players → Player client: join by code (evidence: `README.md`)
- Route application → Game entry page: routes to (evidence: `src/App.tsx`)
- Route application → Host console: routes to (evidence: `src/App.tsx`)
- Route application → Player client: routes to (evidence: `src/App.tsx`)
- Host console → Room connections: uses room
- Player client → Room connections: uses room (evidence: `src/pages/Client.tsx`)
- Room connections → Room and tip APIs: creates rooms (evidence: `src/hooks/useGameRoom.ts`)
- Room connections → Realtime backend: syncs state (evidence: `src/hooks/useGameRoom.ts`)
- Room connections → Game-state logic: exchanges game messages (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Game state types: serializes state (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Map and collision rules: resolves movement (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Grades and scoring: updates grades (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Bot behavior: uses bot decisions (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Stage definitions: uses stage data (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Character viewer: uses character view (evidence: `src/hooks/useGameLogic.ts`)
- Game-state logic → Crossy Road event: runs mini-games
- Game-state logic → Mock exam client: runs mock exam
- Game-state logic → Final exam client: runs final exam
- Phone players → Exam tips page: read exam tips (evidence: `README.md`)
- Asset loading → Asset cache: reads and writes (evidence: `src/context/AssetLoadingContext.tsx`)
- Character viewer → Asset catalog: loads assets (evidence: `src/components/CharacterViewer.tsx`)
- Asset loading → Asset cache worker: registers worker
