# adishshah29-eng/codeverse_merge architecture

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

- Interactive diagram: https://gitdiagram.com/adishshah29-eng/codeverse_merge
- Repository: https://github.com/adishshah29-eng/codeverse_merge

## Overview

CODEVERSE 2.0 is a two-phase, server-authoritative competition platform. Teams sign in through the shared hub, choose an available phase, submit game attempts, and receive server-computed progress, scores, hints, and penalties. Phase 1 runs five Royal Mint Heist challenges; Phase 2 covers Money Trail, Control Server, Police, Extraction, and the Black Market. Organizers manage accounts and game configuration. The README documents the shared SQLite deployment and API boundaries; some router-to-engine details are unsampled, so those links are omitted or marked unverified.

Main entry points: [`backend/app/routers`](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/routers) (Phase 2 endpoints), [`backend/app/main.py`](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/main.py) (FastAPI app), [`backend/app/phase1/routers`](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/phase1/routers) (Phase 1 endpoints), [`frontend/src/phase2/api.js`](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase2/api.js) (Phase 2 API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Player interfaces"]
  node_hub["Login hub<br/>[Hub.jsx]"]
  node_p1ui["Heist interface<br/>[App.jsx]"]
  node_p1api["Phase 1 API client<br/>[api.js]"]
  node_p2ui["Operación Fuga interface<br/>[App.jsx]"]
  node_p2api["Phase 2 API client<br/>[api.js]"]
  node_sharedconfig["API base config<br/>[config.js]"]
end

subgraph group_platform["Shared platform"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth["Session authentication<br/>[auth.py]"]
  node_admin["Account administration<br/>[admin.py]"]
  node_store[("Shared SQLite store<br/>[db.py]")]
  node_models["Platform records<br/>[models.py]"]
end

subgraph group_phase1["Phase 1"]
  node_p1routers["Phase 1 endpoints"]
  node_p1engine["Progress and scoring<br/>[engine.py]"]
  node_p1database["Phase 1 data access<br/>[database.py]"]
  node_p1sqlite["Phase 1 SQLite adapter<br/>[sqlite_store.py]"]
  node_p1scoring["Scoring rules<br/>[scoring.py]"]
  node_p1models["Phase 1 records<br/>[models.py]"]
  node_p1games["Five heist challenges"]
  node_sandbox["Code execution sandbox<br/>[sandbox.py]"]
end

subgraph group_phase2["Phase 2"]
  node_p2routers["Phase 2 endpoints"]
  node_money["Money Trail engine<br/>[engine.py]"]
  node_control["Control Server engine<br/>[engine.py]"]
  node_market["Black Market engine<br/>[engine.py]"]
  node_extraction["Extraction engine<br/>[engine.py]"]
  node_police["Police challenge logic"]
end

node_team(("Team or organizer"))

node_team -->|"signs in"| node_hub
node_team -->|"plays phase"| node_p1ui
node_team -->|"plays phase"| node_p2ui
node_hub -->|"uses login API"| node_p2api
node_p1ui -->|"requests data"| node_p1api
node_p1api -->|"uses base URL"| node_sharedconfig
node_p2ui -->|"requests data"| node_p2api
node_p2api -->|"uses base URL"| node_sharedconfig
node_p1api -->|"calls phase API"| node_app
node_p2api -->|"calls phase API"| node_app
node_app -->|"registers routes"| node_auth
node_app -->|"registers routes"| node_admin
node_app -->|"registers routes"| node_p1routers
node_app -->|"registers routes"| node_p2routers
node_auth -->|"queries sessions"| node_store
node_auth -->|"uses records"| node_models
node_admin -->|"manages accounts"| node_store
node_admin -->|"uses records"| node_models
node_p1routers -->|"delegates progression"| node_p1engine
node_p1routers -->|"loads challenge rules"| node_p1games
node_p1routers -->|"uses scoring"| node_p1scoring
node_p1engine -->|"reads and writes"| node_p1database
node_p1database -->|"uses adapter"| node_p1sqlite
node_p1engine -->|"builds responses"| node_p1models
node_p1sqlite -->|"shares database"| node_store
node_p1games -.->|"may execute code"| node_sandbox
node_p2routers -.->|"uses challenge engine"| node_money
node_p2routers -.->|"uses challenge engine"| node_control
node_p2routers -.->|"uses challenge engine"| node_market
node_p2routers -.->|"uses challenge engine"| node_extraction
node_p2routers -.->|"uses challenge logic"| node_police
node_money -->|"queries records"| node_store

click node_hub "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/hub/Hub.jsx"
click node_p1ui "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase1/App.jsx"
click node_p1api "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase1/api.js"
click node_p2ui "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase2/App.jsx"
click node_p2api "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase2/api.js"
click node_sharedconfig "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/shared/config.js"
click node_app "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/main.py"
click node_auth "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/auth.py"
click node_admin "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/routers/admin.py"
click node_store "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/db.py"
click node_models "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/models.py"
click node_p1routers "https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/phase1/routers"
click node_p1engine "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/engine.py"
click node_p1database "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/database.py"
click node_p1sqlite "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/sqlite_store.py"
click node_p1scoring "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/scoring.py"
click node_p1models "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/models.py"
click node_p1games "https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/phase1/games"
click node_sandbox "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/games/sandbox.py"
click node_p2routers "https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/routers"
click node_money "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/money_trail/engine.py"
click node_control "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/control/engine.py"
click node_market "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/market/engine.py"
click node_extraction "https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/extraction/engine.py"
click node_police "https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/games/police"

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_hub,node_p1ui,node_p1api,node_p2ui,node_p2api,node_sharedconfig toneBlue
class node_app,node_auth,node_admin,node_store,node_models toneAmber
class node_p1routers,node_p1engine,node_p1database,node_p1sqlite,node_p1scoring,node_p1models,node_p1games,node_sandbox toneMint
class node_p2routers,node_money,node_control,node_market,node_extraction,node_police toneRose
class node_team toneIndigo
```

## Components

### Player interfaces

- [Login hub](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/hub/Hub.jsx): `frontend/src/hub/Hub.jsx`
- [Heist interface](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase1/App.jsx): `frontend/src/phase1/App.jsx`
- [Phase 1 API client](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase1/api.js): `frontend/src/phase1/api.js`
- [Operación Fuga interface](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase2/App.jsx): `frontend/src/phase2/App.jsx`
- [Phase 2 API client](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/phase2/api.js): `frontend/src/phase2/api.js`
- [API base config](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/frontend/src/shared/config.js): `frontend/src/shared/config.js`

### Shared platform

- [FastAPI app](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/main.py): `backend/app/main.py`
- [Session authentication](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/auth.py): `backend/app/auth.py`
- [Account administration](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [Shared SQLite store](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/db.py): `backend/app/db.py`
- [Platform records](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/models.py): `backend/app/models.py`

### Phase 1

- [Phase 1 endpoints](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/phase1/routers): `backend/app/phase1/routers`
- [Progress and scoring](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/engine.py): `backend/app/phase1/core/engine.py`
- [Phase 1 data access](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/database.py): `backend/app/phase1/core/database.py`
- [Phase 1 SQLite adapter](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/sqlite_store.py): `backend/app/phase1/core/sqlite_store.py`
- [Scoring rules](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/scoring.py): `backend/app/phase1/core/scoring.py`
- [Phase 1 records](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/core/models.py): `backend/app/phase1/core/models.py`
- [Five heist challenges](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/phase1/games): `backend/app/phase1/games`
- [Code execution sandbox](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/phase1/games/sandbox.py): `backend/app/phase1/games/sandbox.py`

### Phase 2

- [Phase 2 endpoints](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/routers): `backend/app/routers`
- [Money Trail engine](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/money_trail/engine.py): `backend/app/games/money_trail/engine.py`
- [Control Server engine](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/control/engine.py): `backend/app/games/control/engine.py`
- [Black Market engine](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/market/engine.py): `backend/app/games/market/engine.py`
- [Extraction engine](https://github.com/adishshah29-eng/codeverse_merge/blob/merged-sqlite/backend/app/games/extraction/engine.py): `backend/app/games/extraction/engine.py`
- [Police challenge logic](https://github.com/adishshah29-eng/codeverse_merge/tree/merged-sqlite/backend/app/games/police): `backend/app/games/police`

### Other components

- **Team or organizer**

## Connections

- Team or organizer → Login hub: signs in (evidence: `README.md`)
- Team or organizer → Heist interface: plays phase (evidence: `README.md`)
- Team or organizer → Operación Fuga interface: plays phase (evidence: `README.md`)
- Login hub → Phase 2 API client: uses login API (evidence: `frontend/src/hub/Hub.jsx`)
- Heist interface → Phase 1 API client: requests data (evidence: `frontend/src/phase1/App.jsx`)
- Phase 1 API client → API base config: uses base URL (evidence: `frontend/src/phase1/api.js`)
- Operación Fuga interface → Phase 2 API client: requests data (evidence: `frontend/src/phase2/App.jsx`)
- Phase 2 API client → API base config: uses base URL (evidence: `frontend/src/phase2/api.js`)
- Phase 1 API client → FastAPI app: calls phase API (evidence: `README.md`)
- Phase 2 API client → FastAPI app: calls phase API (evidence: `README.md`)
- FastAPI app → Session authentication: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Account administration: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Phase 1 endpoints: registers routes (evidence: `backend/app/main.py`)
- FastAPI app → Phase 2 endpoints: registers routes (evidence: `backend/app/main.py`)
- Session authentication → Shared SQLite store: queries sessions (evidence: `backend/app/auth.py`)
- Session authentication → Platform records: uses records (evidence: `backend/app/auth.py`)
- Account administration → Shared SQLite store: manages accounts (evidence: `backend/app/routers/admin.py`)
- Account administration → Platform records: uses records (evidence: `backend/app/routers/admin.py`)
- Phase 1 endpoints → Progress and scoring: delegates progression (evidence: `backend/app/phase1/routers/games.py`)
- Phase 1 endpoints → Five heist challenges: loads challenge rules (evidence: `backend/app/phase1/routers/games.py`)
- Phase 1 endpoints → Scoring rules: uses scoring (evidence: `backend/app/phase1/routers/games.py`)
- Progress and scoring → Phase 1 data access: reads and writes (evidence: `backend/app/phase1/core/engine.py`)
- Phase 1 data access → Phase 1 SQLite adapter: uses adapter (evidence: `backend/app/phase1/core/database.py`)
- Progress and scoring → Phase 1 records: builds responses (evidence: `backend/app/phase1/core/engine.py`)
- Phase 1 SQLite adapter → Shared SQLite store: shares database (evidence: `README.md`)
- Five heist challenges → Code execution sandbox: may execute code
- Phase 2 endpoints → Money Trail engine: uses challenge engine
- Phase 2 endpoints → Control Server engine: uses challenge engine
- Phase 2 endpoints → Black Market engine: uses challenge engine
- Phase 2 endpoints → Extraction engine: uses challenge engine
- Phase 2 endpoints → Police challenge logic: uses challenge logic
- Money Trail engine → Shared SQLite store: queries records (evidence: `backend/app/games/money_trail/engine.py`)