# mahender-reddy85/escape-room architecture

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

- Interactive diagram: https://gitdiagram.com/mahender-reddy85/escape-room
- Repository: https://github.com/mahender-reddy85/escape-room

## Overview

##### What this project is (type + purpose)

**C-ESCAPE** is a **frontend-only** web application: a **3D escape-room game** built with **React + TypeScript**, rendered via **Three.js / React Three Fiber**, bundled with **Vite**, and deployed to **Vercel or GitHub Pages**.

- A **browser client** containing all gameplay + rendering logic
- Static hosting (Vercel/GH Pages) delivering the app bundle

“anti-cheat protection” is implemented at the **client layer** (the README explicitly references `index.html`).

##### How to read the file structure (what maps to components)

Top-level files imply a typical Vite React app:

- `index.html`

- `index.tsx`
React bootstrap (mount `<App />`).

- `App.tsx`
Main React composition / routing between screens (likely StartScreen -> GameScene) and global state wiring.

- `components/`
- `StartScreen.tsx`: initial UI / start flow
- `GameScene.tsx`: the **core 3D scene** (React Three Fiber canvas, lights, physics-ish, level loading)
- `Room.tsx`: room geometry / level layout
- `InteractiveObject.tsx`: interaction wrapper (click/hover/proximity triggers)
- `UIOverlay.tsx`: HUD/lives/questions/instructions overlay atop 3D canvas

- `constants.ts`
Level definitions/config: the “5 progressive levels” and tuning knobs should be modeled as “Level Config Data”.

- `types.ts`
Shared domain types (Level, Question, Object interactions). Useful to infer domain boundaries: “Game State”, “Level State”, “Question Model”.

- `metadata.json`
Likely asset/config metadata. Treat it as “Static game data”.

- `vite.config.ts`, `tsconfig.json`, `package.json`

Use names that align with the project’s actual structure:

##### React App Shell
- `index.tsx`, `App.tsx`

##### Start / Navigation
- `StartScreen.tsx` (Start → Begin Level 1)

##### 3D Rendering + Scene Graph
- `GameScene.tsx` (Canvas, camera, lighting)
- `Room.tsx` (room meshes/layout)

##### Interaction System
- `InteractiveObject.tsx`
- Inputs: mouse/keyboard/pointer lock (if used)
- Outputs: triggers to game state (open drawer, collect cube, attempt terminal)

##### Game State / Rules
- Lives (3), restart logic
- Level progression (1..5)
- Inventory: cube/key/tools
- Gate conditions: “cube powers terminal”, “key unlocks exit”, etc.

##### Question/Challenge Subsystem
- Gemini API call to generate/validate questions (based on README)
- Model: “Question”, “Answer”, “Attempts”, “Lives decrement”

##### UI Overlay / HUD
- `UIOverlay.tsx`
- Displays: lives, prompts, question modal, hints, success/fail

##### Anti-cheat Controls
- `index.html` scripts/event listeners
- Tab visibility change, right-click/copy prevention, refresh on suspicious activity

##### Google Gemini API
- Authentication via `GEMINI_API_KEY` (environment variable at build/deploy time)
- It as “External SaaS”

##### Hosting
- Vercel or GitHub Pages (Static site)

##### Player → Browser App
- “Pointer/keyboard input”

##### React App Shell ↔ Game State
- “State updates: lives, inventory, level”

##### GameScene → InteractiveObject
- “Registers objects / hit testing / onClick handlers”

##### InteractiveObject → Game State
- “Emit interaction event: open drawer / pick up cube / use terminal”

##### Game State → UIOverlay
- “Render HUD; show question; show lives”

##### Terminal Interaction → Gemini Client → Gemini API
- “HTTPS request: generate C question (topic=level)”
- “Response: question text + options/expected answer”

##### Answer Submission → Game State
- “Validate answer; decrement lives; progress gating”

##### Anti-cheat Guard → App Runtime
- “On blur/visibility change/copy: block or refresh”
- It as a cross-cutting concern attached to the browser container

##### Hosting/CDN → Browser
- “Serves index.html + JS bundle + assets”

##### Architectural patterns/design principles evident here

- **Client-heavy SPA**: Nearly all logic runs in the browser.
- **Component composition** (React): UI and 3D scene are built from modular components.
- **Scene/Entity interaction abstraction**: `InteractiveObject.tsx` suggests a reusable wrapper for click/inspect/use behavior (like a lightweight entity-component pattern).
- **Configuration-driven levels**: `constants.ts` + `metadata.json` implies levels and objects are driven by data rather than hardcoded logic.
- **Cross-cutting security/anti-cheat**: implemented at the document level (`index.html`) and affects all UI/scene flows.
- **External dependency for content**: Gemini API is a runtime dependency for generating challenges.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% View A: C4 L1 System Context
    %% =========================
    subgraph "C4 L1 — System Context"
        direction TB

        Player["Player"]:::external

        Hosting["Static Hosting/CDN\n(Vercel or GitHub Pages)"]:::hosting
        Browser["Browser Runtime"]:::browser

        AppSPA["C-ESCAPE Web App (SPA)\nReact + TypeScript + Vite"]:::app

        Gemini["Google Gemini API\n(External AI Service)"]:::externalService

        Player -->|"pointer/keyboard input"| Browser
        Hosting -->|"serve static bundle\n(index.html + JS/CSS + assets)"| Browser
        Browser -->|"runs"| AppSPA
        AppSPA -->|"HTTPS: generate question\n(topic=level)"| Gemini
        Gemini -->|"question payload"| AppSPA
    end

    %% =========================
    %% View B: C4 L2 Container (runtime pieces in-browser)
    %% =========================
    subgraph "C4 L2 — Container Diagram (Runtime in Browser)"
        direction TB

        subgraph "Browser Client (Single Page App)"
            direction TB

            AppShell["React App Shell\n(index.tsx + App.tsx)"]:::module
            StartScreen["Start / Navigation\n(StartScreen)"]:::module

            subgraph "3D Engine Layer"
                direction TB
                GameScene["GameScene\n(React Three Fiber Canvas)"]:::module
                Room["Room\n(Geometry / Layout)"]:::module
                InteractiveObject["InteractiveObject\n(Click/Hover/Use wrapper)"]:::module
                R3F["React Three Fiber / Three.js"]:::framework
            end

            UIOverlay["UI Overlay / HUD\n(lives, prompts, question modal)"]:::module

            GameState["Game Logic & State\n(levels 1..5, lives=3,\ninventory, gating rules)"]:::state

            QuestionClient["Gemini Question Client\n(generate/validate challenges)"]:::module

            StaticData[("Static Data\n(constants + metadata)")]:::data

            AntiCheat["Anti-cheat / Event Guard\n(tab-switch, copy/right-click prevention)"]:::anticheat
        end

        %% External / runtime adjacencies
        Hosting2["Static Hosting/CDN\n(Vercel or GitHub Pages)"]:::hosting
        Gemini2["Google Gemini API"]:::externalService
    end

    %% Runtime connections (Container)
    Hosting2 -->|"serve index.html + bundle + assets"| AppShell

    AppShell -->|"route/compose screens"| StartScreen
    AppShell -->|"enter gameplay"| GameScene

    GameScene -->|"compose meshes/layout"| Room
    GameScene -->|"register objects / hit testing"| InteractiveObject
    GameScene -->|"render via"| R3F

    InteractiveObject -->|"interaction event\n(open/pickup/use)"| GameState
    GameState -->|"state updates\n(level/lives/inventory)"| GameScene
    GameState -->|"render HUD / prompts"| UIOverlay

    GameState -->|"needs question\n(terminal/board)"| QuestionClient
    QuestionClient -->|"HTTPS request\nGenerate question"| Gemini2
    Gemini2 -->|"question response"| QuestionClient
    QuestionClient -->|"question model\n(answer rules)"| GameState

    StaticData -->|"level definitions\n& metadata load"| GameState
    StaticData -->|"scene init data"| GameScene

    AntiCheat -.->|"document-level hooks\nblock/refresh on suspicious activity"| AppShell
    AntiCheat -.->|"affects all flows"| GameScene
    AntiCheat -.->|"affects UI actions"| UIOverlay

    %% =========================
    %% View C: Component/Module (code mapping)
    %% =========================
    subgraph "C4 L3 — Component / Module Diagram (Repo-level mapping)"
        direction TB

        IndexHTML["index.html\n(Entry HTML + Anti-cheat hooks)"]:::module
        IndexTSX["index.tsx\n(React bootstrap)"]:::module
        AppTSX["App.tsx\n(Root composition)"]:::module

        subgraph "components/"
            direction TB
            StartScreenTSX["StartScreen.tsx"]:::module
            GameSceneTSX["GameScene.tsx"]:::module
            RoomTSX["Room.tsx"]:::module
            InteractiveObjectTSX["InteractiveObject.tsx"]:::module
            UIOverlayTSX["UIOverlay.tsx"]:::module
        end

        Constants["constants.ts\n(Level config definitions)"]:::data
        Types["types.ts\n(Shared domain types)"]:::data
        Metadata["metadata.json\n(Static game metadata)"]:::data

        Tooling["Build & Tooling\n(Vite + TS + npm)"]:::tooling

        Gemini3["Google Gemini API"]:::externalService
    end

    %% Module wiring (code mapping)
    IndexHTML -->|"loads bundle"| IndexTSX
    IndexTSX -->|"mount <App />"| AppTSX

    AppTSX -->|"show start flow"| StartScreenTSX
    AppTSX -->|"start gameplay"| GameSceneTSX

    GameSceneTSX -->|"compose"| RoomTSX
    GameSceneTSX -->|"wrap interactables"| InteractiveObjectTSX
    GameSceneTSX -->|"overlay HUD"| UIOverlayTSX

    Constants -->|"configure levels"| GameSceneTSX
    Constants -->|"drive gating rules"| AppTSX
    Metadata -->|"static data"| GameSceneTSX
    Types -->|"Level/Question/Interaction models"| AppTSX
    Types -->|"typed props/state"| GameSceneTSX

    GameSceneTSX -->|"terminal interaction\ntriggers question generation"| Gemini3

    Tooling -->|"builds & bundles"| IndexHTML

    %% =========================
    %% Click events (from component_mapping)
    %% =========================
    click IndexTSX "https://github.com/mahender-reddy85/escape-room/blob/main/index.tsx"
    click AppTSX "https://github.com/mahender-reddy85/escape-room/blob/main/App.tsx"
    click StartScreenTSX "https://github.com/mahender-reddy85/escape-room/blob/main/components/StartScreen.tsx"
    click GameSceneTSX "https://github.com/mahender-reddy85/escape-room/blob/main/components/GameScene.tsx"
    click RoomTSX "https://github.com/mahender-reddy85/escape-room/blob/main/components/Room.tsx"
    click InteractiveObjectTSX "https://github.com/mahender-reddy85/escape-room/blob/main/components/InteractiveObject.tsx"
    click UIOverlayTSX "https://github.com/mahender-reddy85/escape-room/blob/main/components/UIOverlay.tsx"
    click Constants "https://github.com/mahender-reddy85/escape-room/blob/main/constants.ts"
    click Types "https://github.com/mahender-reddy85/escape-room/blob/main/types.ts"
    click Metadata "https://github.com/mahender-reddy85/escape-room/blob/main/metadata.json"
    click IndexHTML "https://github.com/mahender-reddy85/escape-room/blob/main/index.html"
    click Tooling "https://github.com/mahender-reddy85/escape-room/blob/main/vite.config.ts"
    click Tooling "https://github.com/mahender-reddy85/escape-room/blob/main/tsconfig.json"
    click Tooling "https://github.com/mahender-reddy85/escape-room/blob/main/package.json"
    click Tooling "https://github.com/mahender-reddy85/escape-room/blob/main/package-lock.json"

    %% =========================
    %% Styles
    %% =========================
    classDef browser fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
    classDef app fill:#BBDEFB,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
    classDef module fill:#CFE8FF,stroke:#1E5AA8,stroke-width:1.2px,color:#0B2E5C
    classDef state fill:#B3E5FC,stroke:#0277BD,stroke-width:1.2px,color:#003B57
    classDef framework fill:#D1C4E9,stroke:#5E35B1,stroke-width:1.2px,color:#311B92
    classDef data fill:#ECEFF1,stroke:#546E7A,stroke-width:1.2px,color:#263238
    classDef hosting fill:#E0E0E0,stroke:#616161,stroke-width:1.2px,color:#212121
    classDef external fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
    classDef externalService fill:#FFE0B2,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
    classDef anticheat fill:#FFEBEE,stroke:#C62828,stroke-width:1.8px,color:#7F0000,stroke-dasharray: 6 4
    classDef tooling fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.2px,color:#1B5E20
```
