# abishek2429/codexcape architecture

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

- Interactive diagram: https://gitdiagram.com/abishek2429/codexcape
- Repository: https://github.com/abishek2429/codexcape

## Overview

CodeXcape is a centrally authoritative, two-player technical escape-room game: players log in separately, cooperate through six puzzle levels, and earn clue fragments toward a server-verified final passkey. The browser provides player and organizer interfaces; the Express backend owns sessions, progression, scoring, hints, security, and live updates, persisting state in PostgreSQL. Organizers manage events and teams and monitor results. The README documents the major capabilities; some detailed service-to-route wiring is unsampled, so those links are omitted or marked unverified.

Main entry points: [`backend/routes/playerRoutes.js`](https://github.com/abishek2429/codexcape/blob/main/backend/routes/playerRoutes.js) (HTTP API routes), [`backend/repositories`](https://github.com/abishek2429/codexcape/tree/main/backend/repositories) (Repositories), [`frontend/src/pages/player/PlayerGamePage.tsx`](https://github.com/abishek2429/codexcape/blob/main/frontend/src/pages/player/PlayerGamePage.tsx) (Player game UI), [`backend/services/questionAnswerService.js`](https://github.com/abishek2429/codexcape/blob/main/backend/services/questionAnswerService.js) (Game progression)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_player["Player experience"]
  node_playerui["Player game UI<br/>[PlayerGamePage.tsx]"]
  node_playerauth["Player login"]
  node_clientservices["Game API clients"]
  node_liveclient["Live sync client"]
end

subgraph group_engine["Game engine"]
  node_session["Player sessions"]
  node_progression["Game progression"]
  node_gamestate["Game state"]
  node_scoring["Scoring<br/>[scoringService.js]"]
  node_hints["Hints and riddles<br/>[hintService.js]"]
  node_story["Story sequences"]
  node_passkey["Final passkey"]
  node_anticheat["Anti-cheat"]
end

subgraph group_admin["Organizer operations"]
  node_adminui["Organizer console"]
  node_adminapi["Admin routes<br/>[adminRoutes.js]"]
  node_adminops["Event and team controls"]
  node_leaderboard["Rankings and results"]
end

subgraph group_platform["Backend platform"]
  node_api["HTTP API routes<br/>[playerRoutes.js]"]
  node_broadcast["WebSocket updates"]
  node_dbconfig["Database pool<br/>[db.js]"]
end

subgraph group_data["Persistent data"]
  node_repositories["Repositories"]
  node_postgres[("PostgreSQL")]
end

node_players(("Two players"))
node_organizers(("Organizers"))

node_players -->|"play through"| node_playerui
node_playerui -->|"authenticates with"| node_playerauth
node_playerui -.->|"requests game data"| node_clientservices
node_clientservices -.->|"calls"| node_api
node_api -->|"routes sessions to"| node_session
node_session -->|"reads and updates"| node_repositories
node_api -->|"routes answers to"| node_progression
node_progression -->|"uses scoring"| node_scoring
node_progression -->|"uses game state"| node_gamestate
node_progression -->|"reads and updates"| node_repositories
node_api -->|"routes hint requests"| node_hints
node_api -->|"routes story requests"| node_story
node_api -->|"routes passkey requests"| node_passkey
node_api -->|"routes security events"| node_anticheat
node_playerui -.->|"subscribes to updates"| node_liveclient
node_liveclient -->|"syncs over WebSocket"| node_broadcast
node_session -->|"notifies event start"| node_broadcast
node_organizers -->|"manage events"| node_adminui
node_adminui -.->|"uses admin API"| node_adminapi
node_adminapi -->|"routes event controls"| node_adminops
node_adminops -->|"reads and updates"| node_repositories
node_adminops -->|"publishes live status"| node_broadcast
node_adminapi -.->|"routes results"| node_leaderboard
node_leaderboard -->|"reads ranking data"| node_repositories
node_leaderboard -->|"notifies rank changes"| node_broadcast
node_repositories -->|"queries through"| node_dbconfig
node_dbconfig -->|"reads and writes"| node_postgres

click node_playerui "https://github.com/abishek2429/codexcape/blob/main/frontend/src/pages/player/PlayerGamePage.tsx"
click node_playerauth "https://github.com/abishek2429/codexcape/blob/main/frontend/src/services/playerAuthService.ts"
click node_clientservices "https://github.com/abishek2429/codexcape/tree/main/frontend/src/services"
click node_liveclient "https://github.com/abishek2429/codexcape/blob/main/frontend/src/hooks/useGameWebSocket.ts"
click node_api "https://github.com/abishek2429/codexcape/blob/main/backend/routes/playerRoutes.js"
click node_session "https://github.com/abishek2429/codexcape/blob/main/backend/services/playerSessionService.js"
click node_progression "https://github.com/abishek2429/codexcape/blob/main/backend/services/questionAnswerService.js"
click node_gamestate "https://github.com/abishek2429/codexcape/blob/main/backend/services/gameStateService.js"
click node_scoring "https://github.com/abishek2429/codexcape/blob/main/backend/services/scoringService.js"
click node_hints "https://github.com/abishek2429/codexcape/blob/main/backend/services/hintService.js"
click node_story "https://github.com/abishek2429/codexcape/blob/main/backend/services/cinematicStoryService.js"
click node_passkey "https://github.com/abishek2429/codexcape/blob/main/backend/services/finalPasskeyService.js"
click node_anticheat "https://github.com/abishek2429/codexcape/blob/main/backend/services/antiCheatService.js"
click node_adminui "https://github.com/abishek2429/codexcape/blob/main/frontend/src/pages/admin/AdminDashboardPage.tsx"
click node_adminapi "https://github.com/abishek2429/codexcape/blob/main/backend/routes/adminRoutes.js"
click node_adminops "https://github.com/abishek2429/codexcape/blob/main/backend/services/admin/adminDashboardService.js"
click node_leaderboard "https://github.com/abishek2429/codexcape/blob/main/backend/services/admin/leaderboardService.js"
click node_broadcast "https://github.com/abishek2429/codexcape/blob/main/backend/services/webSocketService.js"
click node_repositories "https://github.com/abishek2429/codexcape/tree/main/backend/repositories"
click node_dbconfig "https://github.com/abishek2429/codexcape/blob/main/backend/config/db.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_playerui,node_playerauth,node_clientservices,node_liveclient toneBlue
class node_session,node_progression,node_gamestate,node_scoring,node_hints,node_story,node_passkey,node_anticheat toneAmber
class node_adminui,node_adminapi,node_adminops,node_leaderboard toneMint
class node_api,node_broadcast,node_dbconfig toneRose
class node_repositories,node_postgres,node_players,node_organizers toneIndigo
```

## Components

### Player experience

- [Player game UI](https://github.com/abishek2429/codexcape/blob/main/frontend/src/pages/player/PlayerGamePage.tsx): `frontend/src/pages/player/PlayerGamePage.tsx`
- [Player login](https://github.com/abishek2429/codexcape/blob/main/frontend/src/services/playerAuthService.ts): `frontend/src/services/playerAuthService.ts`
- [Game API clients](https://github.com/abishek2429/codexcape/tree/main/frontend/src/services): `frontend/src/services`
- [Live sync client](https://github.com/abishek2429/codexcape/blob/main/frontend/src/hooks/useGameWebSocket.ts): `frontend/src/hooks/useGameWebSocket.ts`

### Game engine

- [Player sessions](https://github.com/abishek2429/codexcape/blob/main/backend/services/playerSessionService.js): `backend/services/playerSessionService.js`
- [Game progression](https://github.com/abishek2429/codexcape/blob/main/backend/services/questionAnswerService.js): `backend/services/questionAnswerService.js`
- [Game state](https://github.com/abishek2429/codexcape/blob/main/backend/services/gameStateService.js): `backend/services/gameStateService.js`
- [Scoring](https://github.com/abishek2429/codexcape/blob/main/backend/services/scoringService.js): `backend/services/scoringService.js`
- [Hints and riddles](https://github.com/abishek2429/codexcape/blob/main/backend/services/hintService.js): `backend/services/hintService.js`
- [Story sequences](https://github.com/abishek2429/codexcape/blob/main/backend/services/cinematicStoryService.js): `backend/services/cinematicStoryService.js`
- [Final passkey](https://github.com/abishek2429/codexcape/blob/main/backend/services/finalPasskeyService.js): `backend/services/finalPasskeyService.js`
- [Anti-cheat](https://github.com/abishek2429/codexcape/blob/main/backend/services/antiCheatService.js): `backend/services/antiCheatService.js`

### Organizer operations

- [Organizer console](https://github.com/abishek2429/codexcape/blob/main/frontend/src/pages/admin/AdminDashboardPage.tsx): `frontend/src/pages/admin/AdminDashboardPage.tsx`
- [Admin routes](https://github.com/abishek2429/codexcape/blob/main/backend/routes/adminRoutes.js): `backend/routes/adminRoutes.js`
- [Event and team controls](https://github.com/abishek2429/codexcape/blob/main/backend/services/admin/adminDashboardService.js): `backend/services/admin/adminDashboardService.js`
- [Rankings and results](https://github.com/abishek2429/codexcape/blob/main/backend/services/admin/leaderboardService.js): `backend/services/admin/leaderboardService.js`

### Backend platform

- [HTTP API routes](https://github.com/abishek2429/codexcape/blob/main/backend/routes/playerRoutes.js): `backend/routes/playerRoutes.js`
- [WebSocket updates](https://github.com/abishek2429/codexcape/blob/main/backend/services/webSocketService.js): `backend/services/webSocketService.js`
- [Database pool](https://github.com/abishek2429/codexcape/blob/main/backend/config/db.js): `backend/config/db.js`

### Persistent data

- [Repositories](https://github.com/abishek2429/codexcape/tree/main/backend/repositories): `backend/repositories`
- **PostgreSQL**

### Other components

- **Two players**
- **Organizers**

## Connections

- Two players → Player game UI: play through (evidence: `README.md`)
- Player game UI → Player login: authenticates with
- Player game UI → Game API clients: requests game data
- Game API clients → HTTP API routes: calls
- HTTP API routes → Player sessions: routes sessions to (evidence: `backend/routes/playerRoutes.js`)
- Player sessions → Repositories: reads and updates (evidence: `backend/services/playerSessionService.js`)
- HTTP API routes → Game progression: routes answers to (evidence: `backend/routes/playerRoutes.js`)
- Game progression → Scoring: uses scoring (evidence: `backend/services/questionAnswerService.js`)
- Game progression → Game state: uses game state (evidence: `backend/services/questionAnswerService.js`)
- Game progression → Repositories: reads and updates (evidence: `backend/services/questionAnswerService.js`)
- HTTP API routes → Hints and riddles: routes hint requests (evidence: `backend/routes/playerRoutes.js`)
- HTTP API routes → Story sequences: routes story requests (evidence: `backend/routes/playerRoutes.js`)
- HTTP API routes → Final passkey: routes passkey requests (evidence: `backend/routes/playerRoutes.js`)
- HTTP API routes → Anti-cheat: routes security events (evidence: `backend/routes/playerRoutes.js`)
- Player game UI → Live sync client: subscribes to updates
- Live sync client → WebSocket updates: syncs over WebSocket (evidence: `frontend/src/hooks/useGameWebSocket.ts`)
- Player sessions → WebSocket updates: notifies event start (evidence: `backend/services/playerSessionService.js`)
- Organizers → Organizer console: manage events (evidence: `README.md`)
- Organizer console → Admin routes: uses admin API
- Admin routes → Event and team controls: routes event controls (evidence: `backend/routes/adminRoutes.js`)
- Event and team controls → Repositories: reads and updates (evidence: `backend/services/admin/adminDashboardService.js`)
- Event and team controls → WebSocket updates: publishes live status (evidence: `backend/services/admin/adminDashboardService.js`)
- Admin routes → Rankings and results: routes results
- Rankings and results → Repositories: reads ranking data (evidence: `backend/services/admin/leaderboardService.js`)
- Rankings and results → WebSocket updates: notifies rank changes (evidence: `backend/services/admin/leaderboardService.js`)
- Repositories → Database pool: queries through (evidence: `backend/repositories/teamRepository.js`)
- Database pool → PostgreSQL: reads and writes (evidence: `backend/config/db.js`)
