# nabilislam722/hairgames architecture

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

- Interactive diagram: https://gitdiagram.com/nabilislam722/hairgames
- Repository: https://github.com/nabilislam722/hairgames

## Overview

HairGames is a browser-based collection of games with wallet connectivity, on-chain score submissions, points, leaderboards, profiles, and social-account linking. Players enter through the routed client, play a game, and can submit results for server signing or transaction verification; points and rankings are exposed through API routes. Game-specific engines and renderers implement gameplay, while the backend coordinates API handling, persistence, and chain access. The README only documents VPS/database access, so product capabilities are drawn from the source tree and sampled code; unsampled page-to-API wiring is not assumed.

Main entry points: [`client/src/pages`](https://github.com/nabilislam722/hairgames/tree/main/client/src/pages) (Game pages), [`backend/routes/index.js`](https://github.com/nabilislam722/hairgames/blob/main/backend/routes/index.js) (API routes), [`client/src/App.jsx`](https://github.com/nabilislam722/hairgames/blob/main/client/src/App.jsx) (App router), [`backend/controllers/Authcontroller.js`](https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/Authcontroller.js) (Social auth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Game client"]
  node_app["App router<br/>[App.jsx]"]
  node_wallet["Wallet provider<br/>[main.jsx]"]
  node_game_pages["Game pages"]
  node_profile_page["Profile page<br/>[profile.jsx]"]
  node_rank_views["Rank views<br/>[Leaderboard.jsx]"]
end

subgraph group_gameplay["Gameplay engines"]
  node_space_engine["Space shooter<br/>[engine.ts]"]
  node_fruit_engine["Fruit Ninja<br/>[engine.ts]"]
  node_fishing_engine["Fishing game<br/>[GameEngine.js]"]
  node_pop_game["Patience game<br/>[page.tsx]"]
end

subgraph group_backend["Backend API"]
  node_game_api["Game API handlers<br/>[gameController.js]"]
  node_points_api["Points handlers"]
  node_stats_api["Ranking handlers<br/>[statsController.js]"]
  node_auth_api["Social auth<br/>[Authcontroller.js]"]
  node_routes["API routes<br/>[index.js]"]
  node_server["API server<br/>[server.js]"]
  node_watcher["NFT watcher<br/>[nftWatcher.js]"]
end

subgraph group_state["Persistence"]
  node_user_profiles[("User profiles<br/>[UserProfile.js]")]
  node_event_profiles[("Event profiles<br/>[EventProfile.js]")]
  node_oauth_state[("OAuth state<br/>[OAuthState.js]")]
end

subgraph group_integrations["External services"]
  node_db[("MongoDB<br/>[db.js]")]
  node_chain_provider["Chain provider<br/>[provider.js]"]
  node_blockchain[("Game contracts")]
  node_social_services["Social platforms"]
end

node_player(("Player"))

node_player -->|"opens"| node_app
node_app -->|"routes to"| node_game_pages
node_app -->|"routes to"| node_profile_page
node_app -->|"routes to"| node_rank_views
node_player -->|"connects wallet"| node_wallet
node_game_pages -->|"runs gameplay"| node_space_engine
node_game_pages -->|"runs gameplay"| node_fruit_engine
node_game_pages -->|"runs gameplay"| node_fishing_engine
node_game_pages -->|"runs gameplay"| node_pop_game
node_server -->|"connects"| node_db
node_server -->|"mounts API"| node_routes
node_server -->|"starts"| node_watcher
node_routes -->|"dispatches"| node_game_api
node_routes -->|"dispatches"| node_points_api
node_routes -->|"dispatches"| node_stats_api
node_routes -->|"dispatches"| node_auth_api
node_game_api -->|"reads nonce; signs"| node_chain_provider
node_chain_provider -->|"queries chain"| node_blockchain
node_points_api -->|"verifies transactions"| node_chain_provider
node_points_api -->|"reads; updates"| node_user_profiles
node_stats_api -->|"reads rankings"| node_user_profiles
node_stats_api -->|"reads events"| node_event_profiles
node_auth_api -->|"reads; updates"| node_user_profiles
node_auth_api -->|"stores; consumes state"| node_oauth_state
node_auth_api -.->|"OAuth requests"| node_social_services
node_watcher -->|"watches chain"| node_chain_provider

click node_app "https://github.com/nabilislam722/hairgames/blob/main/client/src/App.jsx"
click node_wallet "https://github.com/nabilislam722/hairgames/blob/main/client/src/main.jsx"
click node_game_pages "https://github.com/nabilislam722/hairgames/tree/main/client/src/pages"
click node_profile_page "https://github.com/nabilislam722/hairgames/blob/main/client/src/pages/profile.jsx"
click node_rank_views "https://github.com/nabilislam722/hairgames/blob/main/client/src/components/Leaderboard.jsx"
click node_space_engine "https://github.com/nabilislam722/hairgames/blob/main/client/src/game/engine.ts"
click node_fruit_engine "https://github.com/nabilislam722/hairgames/blob/main/client/src/game/fruit_ninja/engine.ts"
click node_fishing_engine "https://github.com/nabilislam722/hairgames/blob/main/client/src/game/GameEngine.js"
click node_pop_game "https://github.com/nabilislam722/hairgames/blob/main/client/src/proofOfPatience/page.tsx"
click node_game_api "https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/gameController.js"
click node_points_api "https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/pointsController.js"
click node_stats_api "https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/statsController.js"
click node_auth_api "https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/Authcontroller.js"
click node_routes "https://github.com/nabilislam722/hairgames/blob/main/backend/routes/index.js"
click node_server "https://github.com/nabilislam722/hairgames/blob/main/backend/server.js"
click node_watcher "https://github.com/nabilislam722/hairgames/blob/main/backend/services/nftWatcher.js"
click node_user_profiles "https://github.com/nabilislam722/hairgames/blob/main/backend/models/UserProfile.js"
click node_event_profiles "https://github.com/nabilislam722/hairgames/blob/main/backend/models/EventProfile.js"
click node_oauth_state "https://github.com/nabilislam722/hairgames/blob/main/backend/models/OAuthState.js"
click node_db "https://github.com/nabilislam722/hairgames/blob/main/backend/config/db.js"
click node_chain_provider "https://github.com/nabilislam722/hairgames/blob/main/backend/config/provider.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_app,node_wallet,node_game_pages,node_profile_page,node_rank_views toneBlue
class node_space_engine,node_fruit_engine,node_fishing_engine,node_pop_game toneAmber
class node_game_api,node_points_api,node_stats_api,node_auth_api,node_routes,node_server,node_watcher toneMint
class node_user_profiles,node_event_profiles,node_oauth_state toneRose
class node_db,node_chain_provider,node_blockchain,node_social_services,node_player toneIndigo
```

## Components

### Game client

- [App router](https://github.com/nabilislam722/hairgames/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Wallet provider](https://github.com/nabilislam722/hairgames/blob/main/client/src/main.jsx): `client/src/main.jsx`
- [Game pages](https://github.com/nabilislam722/hairgames/tree/main/client/src/pages): `client/src/pages`
- [Profile page](https://github.com/nabilislam722/hairgames/blob/main/client/src/pages/profile.jsx): `client/src/pages/profile.jsx`
- [Rank views](https://github.com/nabilislam722/hairgames/blob/main/client/src/components/Leaderboard.jsx): `client/src/components/Leaderboard.jsx`

### Gameplay engines

- [Space shooter](https://github.com/nabilislam722/hairgames/blob/main/client/src/game/engine.ts): `client/src/game/engine.ts`
- [Fruit Ninja](https://github.com/nabilislam722/hairgames/blob/main/client/src/game/fruit_ninja/engine.ts): `client/src/game/fruit_ninja/engine.ts`
- [Fishing game](https://github.com/nabilislam722/hairgames/blob/main/client/src/game/GameEngine.js): `client/src/game/GameEngine.js`
- [Patience game](https://github.com/nabilislam722/hairgames/blob/main/client/src/proofOfPatience/page.tsx): `client/src/proofOfPatience/page.tsx`

### Backend API

- [Game API handlers](https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/gameController.js): `backend/controllers/gameController.js`
- [Points handlers](https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/pointsController.js): `backend/controllers/pointsController.js`
- [Ranking handlers](https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/statsController.js): `backend/controllers/statsController.js`
- [Social auth](https://github.com/nabilislam722/hairgames/blob/main/backend/controllers/Authcontroller.js): `backend/controllers/Authcontroller.js`
- [API routes](https://github.com/nabilislam722/hairgames/blob/main/backend/routes/index.js): `backend/routes/index.js`
- [API server](https://github.com/nabilislam722/hairgames/blob/main/backend/server.js): `backend/server.js`
- [NFT watcher](https://github.com/nabilislam722/hairgames/blob/main/backend/services/nftWatcher.js): `backend/services/nftWatcher.js`

### Persistence

- [User profiles](https://github.com/nabilislam722/hairgames/blob/main/backend/models/UserProfile.js): `backend/models/UserProfile.js`
- [Event profiles](https://github.com/nabilislam722/hairgames/blob/main/backend/models/EventProfile.js): `backend/models/EventProfile.js`
- [OAuth state](https://github.com/nabilislam722/hairgames/blob/main/backend/models/OAuthState.js): `backend/models/OAuthState.js`

### External services

- [MongoDB](https://github.com/nabilislam722/hairgames/blob/main/backend/config/db.js): `backend/config/db.js`
- [Chain provider](https://github.com/nabilislam722/hairgames/blob/main/backend/config/provider.js): `backend/config/provider.js`
- **Game contracts**
- **Social platforms**

### Other components

- **Player**

## Connections

- Player → App router: opens
- App router → Game pages: routes to
- App router → Profile page: routes to
- App router → Rank views: routes to
- Player → Wallet provider: connects wallet
- Game pages → Space shooter: runs gameplay
- Game pages → Fruit Ninja: runs gameplay
- Game pages → Fishing game: runs gameplay
- Game pages → Patience game: runs gameplay
- API server → MongoDB: connects
- API server → API routes: mounts API
- API server → NFT watcher: starts
- API routes → Game API handlers: dispatches
- API routes → Points handlers: dispatches
- API routes → Ranking handlers: dispatches
- API routes → Social auth: dispatches
- Game API handlers → Chain provider: reads nonce; signs
- Chain provider → Game contracts: queries chain
- Points handlers → Chain provider: verifies transactions
- Points handlers → User profiles: reads; updates
- Ranking handlers → User profiles: reads rankings
- Ranking handlers → Event profiles: reads events
- Social auth → User profiles: reads; updates
- Social auth → OAuth state: stores; consumes state
- Social auth → Social platforms: OAuth requests
- NFT watcher → Chain provider: watches chain