# hibaazmatkhan/axiom_project_ai architecture

> Architecture diagram of the GitHub repository hibaazmatkhan/axiom_project_ai, 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/hibaazmatkhan/axiom_project_ai
- Repository: https://github.com/hibaazmatkhan/axiom_project_ai

## Overview

AXIOM: THE LAST ROOM is a browser-based, four-player 3D escape-room game. Players join a room, authenticate or play as guests, then send actions over WebSockets to a server-authoritative match loop. The loop runs the shifting arena, role-specific information, puzzles, and Dealer adaptation; the client renders the arena and team state. Distinct supporting capabilities include accounts and profiles, avatar selection/uploads, and persistent match history. Several backend modules and UI routes are indexed but unsampled, so their documented roles are shown without asserting unverified call details.

Main entry points: [`backend/app/game.py`](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/game.py) (Authoritative match), [`backend/app/main.py`](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/main.py) (Web and WS server), [`frontend/components/GameClient.tsx`](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/GameClient.tsx) (Game client), [`frontend/app/lobby/page.tsx`](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/lobby/page.tsx) (Room lobby)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Player entry"]
  node_lobby["Room lobby<br/>[page.tsx]"]
  node_gamepage["Game page<br/>[page.tsx]"]
end

subgraph group_client["Game client"]
  node_gameclient["Game client<br/>[GameClient.tsx]"]
  node_socket["Game socket<br/>[useGameSocket.ts]"]
  node_canvas["3D arena view<br/>[GameCanvas.tsx]"]
  node_wristband["Wristband map<br/>[WristbandMap.tsx]"]
end

subgraph group_runtime["Match runtime"]
  node_backend["Web and WS server<br/>[main.py]"]
  node_rooms["Room registry<br/>[room_registry.py]"]
  node_match["Authoritative match<br/>[game.py]"]
end

subgraph group_intelligence["Game systems"]
  node_arena["Shifting arena<br/>[arena.py]"]
  node_patterns["Pattern engine<br/>[patterns.py]"]
  node_stages["Match stages<br/>[stages.py]"]
  node_roles["Asymmetric roles<br/>[roles.py]"]
  node_puzzles["Co-op puzzles<br/>[puzzles.py]"]
  node_dealer["Dealer director<br/>[nexus.py]"]
end

subgraph group_identity["Accounts and persistence"]
  node_auth["Firebase auth<br/>[auth.py]"]
  node_accounts["Account UI<br/>[page.tsx]"]
  node_profile["Player profile<br/>[page.tsx]"]
  node_avatar["Avatar service<br/>[avatar_store.py]"]
  node_matchstore[("Match persistence<br/>[db.py]")]
  node_supabase[("Supabase profiles<br/>[supabase_store.py]")]
end

node_player(("Player"))

node_player -->|"joins room"| node_lobby
node_lobby -->|"opens match"| node_gamepage
node_gamepage -->|"loads"| node_gameclient
node_gameclient -->|"uses"| node_socket
node_gameclient -->|"renders"| node_canvas
node_gameclient -->|"renders"| node_wristband
node_socket -->|"sends actions"| node_backend
node_backend -.->|"reserves rooms"| node_rooms
node_backend -->|"routes match play"| node_match
node_match -.->|"uses arena"| node_arena
node_match -.->|"uses rules"| node_patterns
node_match -.->|"advances stages"| node_stages
node_match -.->|"filters information"| node_roles
node_match -->|"generates puzzles"| node_puzzles
node_match -.->|"adapts difficulty"| node_dealer
node_player -->|"signs in"| node_accounts
node_accounts -.->|"authenticates"| node_auth
node_player -->|"manages profile"| node_profile
node_profile -.->|"selects avatar"| node_avatar
node_backend -->|"verifies identity"| node_auth
node_backend -.->|"persists matches"| node_matchstore
node_backend -->|"reads profiles"| node_supabase

click node_lobby "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/lobby/page.tsx"
click node_gamepage "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/game/page.tsx"
click node_gameclient "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/GameClient.tsx"
click node_socket "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/lib/useGameSocket.ts"
click node_canvas "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/GameCanvas.tsx"
click node_wristband "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/WristbandMap.tsx"
click node_backend "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/main.py"
click node_rooms "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/room_registry.py"
click node_match "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/game.py"
click node_arena "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/arena.py"
click node_patterns "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/patterns.py"
click node_stages "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/stages.py"
click node_roles "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/roles.py"
click node_puzzles "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/puzzles.py"
click node_dealer "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/nexus.py"
click node_auth "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/auth.py"
click node_accounts "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/login/page.tsx"
click node_profile "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/profile/page.tsx"
click node_avatar "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/avatar_store.py"
click node_matchstore "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/db.py"
click node_supabase "https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/supabase_store.py"

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_lobby,node_gamepage toneBlue
class node_gameclient,node_socket,node_canvas,node_wristband toneAmber
class node_backend,node_rooms,node_match toneMint
class node_arena,node_patterns,node_stages,node_roles,node_puzzles,node_dealer toneRose
class node_auth,node_accounts,node_profile,node_avatar,node_matchstore,node_supabase,node_player toneIndigo
```

## Components

### Player entry

- [Room lobby](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/lobby/page.tsx): `frontend/app/lobby/page.tsx`
- [Game page](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/game/page.tsx): `frontend/app/game/page.tsx`

### Game client

- [Game client](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/GameClient.tsx): `frontend/components/GameClient.tsx`
- [Game socket](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/lib/useGameSocket.ts): `frontend/lib/useGameSocket.ts`
- [3D arena view](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/GameCanvas.tsx): `frontend/components/GameCanvas.tsx`
- [Wristband map](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/components/WristbandMap.tsx): `frontend/components/WristbandMap.tsx`

### Match runtime

- [Web and WS server](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Room registry](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/room_registry.py): `backend/app/room_registry.py`
- [Authoritative match](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/game.py): `backend/app/game.py`

### Game systems

- [Shifting arena](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/arena.py): `backend/app/arena.py`
- [Pattern engine](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/patterns.py): `backend/app/patterns.py`
- [Match stages](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/stages.py): `backend/app/stages.py`
- [Asymmetric roles](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/roles.py): `backend/app/roles.py`
- [Co-op puzzles](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/puzzles.py): `backend/app/puzzles.py`
- [Dealer director](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/nexus.py): `backend/app/nexus.py`

### Accounts and persistence

- [Firebase auth](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Account UI](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/login/page.tsx): `frontend/app/login/page.tsx`
- [Player profile](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/frontend/app/profile/page.tsx): `frontend/app/profile/page.tsx`
- [Avatar service](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/avatar_store.py): `backend/app/avatar_store.py`
- [Match persistence](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/db.py): `backend/app/db.py`
- [Supabase profiles](https://github.com/hibaazmatkhan/axiom_project_ai/blob/main/backend/app/supabase_store.py): `backend/app/supabase_store.py`

### Other components

- **Player**

## Connections

- Player → Room lobby: joins room
- Room lobby → Game page: opens match
- Game page → Game client: loads (evidence: `frontend/app/game/page.tsx`)
- Game client → Game socket: uses (evidence: `frontend/components/GameClient.tsx`)
- Game client → 3D arena view: renders (evidence: `frontend/components/GameClient.tsx`)
- Game client → Wristband map: renders (evidence: `frontend/components/GameClient.tsx`)
- Game socket → Web and WS server: sends actions
- Web and WS server → Room registry: reserves rooms (evidence: `backend/app/main.py`)
- Web and WS server → Authoritative match: routes match play (evidence: `backend/app/main.py`)
- Authoritative match → Shifting arena: uses arena (evidence: `backend/app/game.py`)
- Authoritative match → Pattern engine: uses rules (evidence: `backend/app/game.py`)
- Authoritative match → Match stages: advances stages (evidence: `backend/app/game.py`)
- Authoritative match → Asymmetric roles: filters information (evidence: `backend/app/game.py`)
- Authoritative match → Co-op puzzles: generates puzzles (evidence: `backend/app/game.py`)
- Authoritative match → Dealer director: adapts difficulty (evidence: `backend/app/game.py`)
- Player → Account UI: signs in
- Account UI → Firebase auth: authenticates
- Player → Player profile: manages profile
- Player profile → Avatar service: selects avatar
- Web and WS server → Firebase auth: verifies identity (evidence: `backend/app/main.py`)
- Web and WS server → Match persistence: persists matches (evidence: `backend/app/main.py`)
- Web and WS server → Supabase profiles: reads profiles (evidence: `backend/app/main.py`)
