# ahmed-kabeer-dev/reef-muncher architecture

> Architecture diagram of the GitHub repository ahmed-kabeer-dev/reef-muncher, 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/ahmed-kabeer-dev/reef-muncher
- Repository: https://github.com/ahmed-kabeer-dev/reef-muncher

## Overview

Reef Muncher is a browser-based marine-themed game with accounts, habitat conditions, puzzle-driven runs, and player statistics. The main gameplay flow is the play page coordinating a run controller and canvas engine; the server prepares puzzle/condition data, checks bites, and records completed runs. Separate pages expose habitats, career stats, and leaderboard data. The excerpts and source index support the main internal calls, but do not show the client API’s endpoint wiring, so those connections are omitted.

Main entry points: [`app/play/page.js`](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/play/page.js) (Play page), [`lib/game/engine.js`](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/engine.js) (Canvas engine), [`lib/server/puzzleManager.js`](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/puzzleManager.js) (Puzzle manager), [`lib/server/conditions.js`](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/conditions.js) (Habitat conditions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Player experience"]
  node_play["Play page<br/>[page.js]"]
  node_account["Account pages<br/>[page.js]"]
  node_habitatpage["Habitats page<br/>[page.js]"]
  node_careerpage["Career page<br/>[page.js]"]
  node_leaderboardpage["Leaderboard page<br/>[page.js]"]
  node_api["Client API<br/>[api.js]"]
end

subgraph group_gameplay["Game runtime"]
  node_controller["Run controller<br/>[runController.js]"]
  node_engine["Canvas engine<br/>[engine.js]"]
  node_hazards["Hazards<br/>[hazards.js]"]
  node_rules["Game rules<br/>[rules.js]"]
  node_events["Event bus<br/>[eventBus.js]"]
  node_ui["Game overlays<br/>[ResultOverlay.js]"]
end

subgraph group_server["Server services"]
  node_authroutes["Auth routes"]
  node_runroutes["Run routes"]
  node_statsroutes["Stats routes<br/>[route.js]"]
  node_habitatroute["Habitat route<br/>[route.js]"]
  node_auth["Session auth<br/>[auth.js]"]
  node_puzzles["Puzzle manager<br/>[puzzleManager.js]"]
  node_runservice["Run service<br/>[runService.js]"]
  node_conditions["Habitat conditions<br/>[conditions.js]"]
  node_stats["Career statistics<br/>[stats.js]"]
  node_database[("SQLite store<br/>[index.js]")]
end

subgraph group_integrations["External data"]
  node_fish["Fish puzzle API<br/>[fishClient.js]"]
  node_marine["Marine data API<br/>[marineClient.js]"]
  node_sun["Sunrise API<br/>[sunClient.js]"]
  node_http["HTTP helpers<br/>[http.js]"]
end

node_player(("Player"))

node_player -->|"plays"| node_play
node_player -->|"manages account"| node_account
node_play -->|"coordinates"| node_controller
node_play -->|"controls"| node_engine
node_play -->|"requests data"| node_api
node_play -->|"renders"| node_ui
node_controller -->|"starts run"| node_engine
node_controller -->|"publishes events"| node_events
node_controller -->|"builds difficulty"| node_rules
node_engine -->|"delegates hazards"| node_hazards
node_engine -->|"uses rules"| node_rules
node_engine -->|"publishes events"| node_events
node_authroutes -->|"authenticates"| node_auth
node_auth -->|"reads and writes sessions"| node_database
node_runroutes -->|"authenticates"| node_auth
node_runroutes -->|"starts puzzles"| node_puzzles
node_runroutes -->|"finishes runs"| node_runservice
node_puzzles -->|"fetches puzzles"| node_fish
node_puzzles -->|"loads conditions"| node_conditions
node_puzzles -->|"stores answers"| node_database
node_runservice -->|"saves results"| node_database
node_runservice -->|"releases run"| node_puzzles
node_statsroutes -->|"authenticates"| node_auth
node_statsroutes -->|"builds rankings"| node_stats
node_careerpage -->|"requests career data"| node_api
node_leaderboardpage -.->|"requests rankings"| node_api
node_habitatpage -->|"requests habitats"| node_api
node_habitatroute -->|"authenticates"| node_auth
node_habitatroute -->|"loads conditions"| node_conditions
node_conditions -->|"fetches sea data"| node_marine
node_conditions -->|"fetches sun data"| node_sun
node_conditions -->|"classifies conditions"| node_rules
node_stats -->|"reads run history"| node_database
node_fish -->|"fetches responses"| node_http
node_marine -->|"fetches responses"| node_http
node_sun -->|"fetches responses"| node_http

click node_play "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/play/page.js"
click node_account "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/login/page.js"
click node_habitatpage "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/habitats/page.js"
click node_careerpage "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/career/page.js"
click node_leaderboardpage "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/leaderboard/page.js"
click node_api "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/client/api.js"
click node_controller "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/runController.js"
click node_engine "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/engine.js"
click node_hazards "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/hazards.js"
click node_rules "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/rules.js"
click node_events "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/events/eventBus.js"
click node_ui "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/components/ResultOverlay.js"
click node_authroutes "https://github.com/ahmed-kabeer-dev/reef-muncher/tree/main/app/api/auth"
click node_runroutes "https://github.com/ahmed-kabeer-dev/reef-muncher/tree/main/app/api/run"
click node_statsroutes "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/api/leaderboard/route.js"
click node_habitatroute "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/api/habitats/route.js"
click node_auth "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/auth.js"
click node_puzzles "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/puzzleManager.js"
click node_runservice "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/runService.js"
click node_conditions "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/conditions.js"
click node_stats "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/stats.js"
click node_database "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/db/index.js"
click node_fish "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/fishClient.js"
click node_marine "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/marineClient.js"
click node_sun "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/sunClient.js"
click node_http "https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/http.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_play,node_account,node_habitatpage,node_careerpage,node_leaderboardpage,node_api toneBlue
class node_controller,node_engine,node_hazards,node_rules,node_events,node_ui toneAmber
class node_authroutes,node_runroutes,node_statsroutes,node_habitatroute,node_auth,node_puzzles,node_runservice,node_conditions,node_stats,node_database toneMint
class node_fish,node_marine,node_sun,node_http toneRose
class node_player toneIndigo
```

## Components

### Player experience

- [Play page](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/play/page.js): `app/play/page.js`
- [Account pages](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/login/page.js): `app/login/page.js`
- [Habitats page](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/habitats/page.js): `app/habitats/page.js`
- [Career page](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/career/page.js): `app/career/page.js`
- [Leaderboard page](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/leaderboard/page.js): `app/leaderboard/page.js`
- [Client API](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/client/api.js): `lib/client/api.js`

### Game runtime

- [Run controller](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/runController.js): `lib/game/runController.js`
- [Canvas engine](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/engine.js): `lib/game/engine.js`
- [Hazards](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/hazards.js): `lib/game/hazards.js`
- [Game rules](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/game/rules.js): `lib/game/rules.js`
- [Event bus](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/events/eventBus.js): `lib/events/eventBus.js`
- [Game overlays](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/components/ResultOverlay.js): `components/ResultOverlay.js`

### Server services

- [Auth routes](https://github.com/ahmed-kabeer-dev/reef-muncher/tree/main/app/api/auth): `app/api/auth`
- [Run routes](https://github.com/ahmed-kabeer-dev/reef-muncher/tree/main/app/api/run): `app/api/run`
- [Stats routes](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/api/leaderboard/route.js): `app/api/leaderboard/route.js`
- [Habitat route](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/app/api/habitats/route.js): `app/api/habitats/route.js`
- [Session auth](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/auth.js): `lib/server/auth.js`
- [Puzzle manager](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/puzzleManager.js): `lib/server/puzzleManager.js`
- [Run service](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/runService.js): `lib/server/runService.js`
- [Habitat conditions](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/conditions.js): `lib/server/conditions.js`
- [Career statistics](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/server/stats.js): `lib/server/stats.js`
- [SQLite store](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/db/index.js): `lib/db/index.js`

### External data

- [Fish puzzle API](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/fishClient.js): `lib/services/fishClient.js`
- [Marine data API](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/marineClient.js): `lib/services/marineClient.js`
- [Sunrise API](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/sunClient.js): `lib/services/sunClient.js`
- [HTTP helpers](https://github.com/ahmed-kabeer-dev/reef-muncher/blob/main/lib/services/http.js): `lib/services/http.js`

### Other components

- **Player**

## Connections

- Player → Play page: plays
- Player → Account pages: manages account
- Play page → Run controller: coordinates (evidence: `app/play/page.js`)
- Play page → Canvas engine: controls (evidence: `app/play/page.js`)
- Play page → Client API: requests data (evidence: `app/play/page.js`)
- Play page → Game overlays: renders (evidence: `app/play/page.js`)
- Run controller → Canvas engine: starts run (evidence: `lib/game/runController.js`)
- Run controller → Event bus: publishes events (evidence: `lib/game/runController.js`)
- Run controller → Game rules: builds difficulty (evidence: `lib/game/runController.js`)
- Canvas engine → Hazards: delegates hazards (evidence: `lib/game/engine.js`)
- Canvas engine → Game rules: uses rules (evidence: `lib/game/engine.js`)
- Canvas engine → Event bus: publishes events (evidence: `lib/game/engine.js`)
- Auth routes → Session auth: authenticates (evidence: `app/api/auth/login/route.js`)
- Session auth → SQLite store: reads and writes sessions (evidence: `lib/server/auth.js`)
- Run routes → Session auth: authenticates (evidence: `app/api/run/finish/route.js`)
- Run routes → Puzzle manager: starts puzzles (evidence: `app/api/run/start/route.js`)
- Run routes → Run service: finishes runs (evidence: `app/api/run/finish/route.js`)
- Puzzle manager → Fish puzzle API: fetches puzzles (evidence: `lib/server/puzzleManager.js`)
- Puzzle manager → Habitat conditions: loads conditions (evidence: `lib/server/puzzleManager.js`)
- Puzzle manager → SQLite store: stores answers (evidence: `lib/server/puzzleManager.js`)
- Run service → SQLite store: saves results (evidence: `lib/server/runService.js`)
- Run service → Puzzle manager: releases run (evidence: `lib/server/runService.js`)
- Stats routes → Session auth: authenticates (evidence: `app/api/leaderboard/route.js`)
- Stats routes → Career statistics: builds rankings (evidence: `app/api/leaderboard/route.js`)
- Career page → Client API: requests career data
- Leaderboard page → Client API: requests rankings
- Habitats page → Client API: requests habitats (evidence: `app/habitats/page.js`)
- Habitat route → Session auth: authenticates (evidence: `app/api/habitats/route.js`)
- Habitat route → Habitat conditions: loads conditions (evidence: `app/api/habitats/route.js`)
- Habitat conditions → Marine data API: fetches sea data (evidence: `lib/server/conditions.js`)
- Habitat conditions → Sunrise API: fetches sun data (evidence: `lib/server/conditions.js`)
- Habitat conditions → Game rules: classifies conditions (evidence: `lib/server/conditions.js`)
- Career statistics → SQLite store: reads run history (evidence: `lib/server/stats.js`)
- Fish puzzle API → HTTP helpers: fetches responses (evidence: `lib/services/fishClient.js`)
- Marine data API → HTTP helpers: fetches responses (evidence: `lib/services/marineClient.js`)
- Sunrise API → HTTP helpers: fetches responses (evidence: `lib/services/sunClient.js`)
