# bitpolito/mininggame architecture

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

## Overview

Bitcoin Block Mining Simulator is an educational browser game: players compose affordable, fee-maximizing blocks and solve proof-of-work challenges, then build a chain toward a goal. Easy and Hard modes share transaction and game rules; solo play runs locally, while multiplayer adds room creation/joining, independent player chains, host race monitoring, and server-side mine reporting. The graph follows documented capabilities and sampled call references; unsampled subsystems use exact paths from the tree, and their internal links are omitted where evidence is unavailable.

Main entry points: [`src/App.jsx`](https://github.com/bitpolito/mininggame/blob/main/src/App.jsx) (App and session flow), [`src/games/HardGame.jsx`](https://github.com/bitpolito/mininggame/blob/main/src/games/HardGame.jsx) (Hard mode), [`api/room.js`](https://github.com/bitpolito/mininggame/blob/main/api/room.js) (Room handler), [`src/lib/gameEngine.js`](https://github.com/bitpolito/mininggame/blob/main/src/lib/gameEngine.js) (Game engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Game experience"]
  node_app["App and session flow<br/>[App.jsx]"]
  node_easy["Easy mode<br/>[EasyGame.jsx]"]
  node_hard["Hard mode<br/>[HardGame.jsx]"]
  node_gameui["Mining interface"]
  node_mempoolui["Mempool table<br/>[MempoolTable.jsx]"]
  node_guide["How-to-play guide<br/>[HowToPlay.jsx]"]
end

subgraph group_rules["Mining rules"]
  node_engine["Game engine<br/>[gameEngine.js]"]
  node_selection["Transaction selection<br/>[txSelection.js]"]
  node_draft["Game drafts<br/>[gameDraft.js]"]
  node_mempool["Mempool generation<br/>[mempool.js]"]
  node_hashing["Hashing and targets<br/>[targetHash.js]"]
  node_powdice["Nonce challenge<br/>[powDice.js]"]
end

subgraph group_rooms["Multiplayer rooms"]
  node_roominvite["Room invitations<br/>[RoomInvite.jsx]"]
  node_hostdash["Host dashboard<br/>[HostDashboard.jsx]"]
  node_roomapi["Room API client<br/>[roomApi.js]"]
  node_roomjoin["Room joining<br/>[roomJoin.js]"]
  node_roomauth["Room identity<br/>[roomAuth.js]"]
  node_roomconfig["Room configuration<br/>[roomConfig.js]"]
  node_race["Race projection<br/>[raceProjection.js]"]
end

subgraph group_service["Room service"]
  node_server["HTTP server<br/>[server.js]"]
  node_roomhandler["Room handler<br/>[room.js]"]
  node_kv[("Key-value storage<br/>[kv.js]")]
  node_health["Health endpoint<br/>[health.js]"]
end

subgraph group_shared["Shared experience"]
  node_locale["Locale context<br/>[LocaleContext.jsx]"]
  node_focus["Modal focus<br/>[useModalFocus.js]"]
end

node_player(("Player"))

node_player -->|"starts or joins"| node_app
node_app -.->|"opens mode"| node_easy
node_app -.->|"opens mode"| node_hard
node_app -.->|"requests room actions"| node_roomapi
node_easy -.->|"validates mining"| node_engine
node_hard -->|"validates mining"| node_engine
node_hard -->|"reports mine"| node_roomapi
node_easy -.->|"loads game draft"| node_draft
node_hard -->|"loads game draft"| node_draft
node_easy -->|"renders"| node_gameui
node_hard -->|"renders"| node_gameui
node_gameui -->|"renders"| node_mempoolui
node_easy -->|"opens rules"| node_guide
node_hard -->|"opens rules"| node_guide
node_engine -->|"checks selection"| node_selection
node_engine -->|"generates transactions"| node_mempool
node_engine -->|"computes proof"| node_hashing
node_hard -->|"uses nonce challenge"| node_powdice
node_roominvite -->|"builds join link"| node_roomjoin
node_app -->|"reads join code"| node_roomjoin
node_app -.->|"creates room"| node_roomapi
node_hostdash -->|"projects race"| node_race
node_hostdash -->|"reads capacity"| node_roomconfig
node_roomapi -.->|"sends requests"| node_roomhandler
node_server -->|"routes requests"| node_roomhandler
node_roomhandler -->|"reads and writes"| node_kv
node_roomhandler -->|"validates room mining"| node_engine
node_roomhandler -->|"uses room limits"| node_roomconfig
node_roomhandler -->|"checks targets"| node_hashing
node_server -->|"routes health checks"| node_health
node_app -->|"uses translations"| node_locale
node_guide -->|"traps dialog focus"| node_focus
node_roominvite -->|"traps dialog focus"| node_focus

click node_app "https://github.com/bitpolito/mininggame/blob/main/src/App.jsx"
click node_easy "https://github.com/bitpolito/mininggame/blob/main/src/games/EasyGame.jsx"
click node_hard "https://github.com/bitpolito/mininggame/blob/main/src/games/HardGame.jsx"
click node_gameui "https://github.com/bitpolito/mininggame/tree/main/src/components/game"
click node_mempoolui "https://github.com/bitpolito/mininggame/blob/main/src/components/game/MempoolTable.jsx"
click node_guide "https://github.com/bitpolito/mininggame/blob/main/src/HowToPlay.jsx"
click node_engine "https://github.com/bitpolito/mininggame/blob/main/src/lib/gameEngine.js"
click node_selection "https://github.com/bitpolito/mininggame/blob/main/src/lib/txSelection.js"
click node_draft "https://github.com/bitpolito/mininggame/blob/main/src/lib/gameDraft.js"
click node_mempool "https://github.com/bitpolito/mininggame/blob/main/src/lib/mempool.js"
click node_hashing "https://github.com/bitpolito/mininggame/blob/main/src/lib/targetHash.js"
click node_powdice "https://github.com/bitpolito/mininggame/blob/main/src/lib/powDice.js"
click node_roominvite "https://github.com/bitpolito/mininggame/blob/main/src/components/RoomInvite.jsx"
click node_hostdash "https://github.com/bitpolito/mininggame/blob/main/src/components/HostDashboard.jsx"
click node_roomapi "https://github.com/bitpolito/mininggame/blob/main/src/lib/roomApi.js"
click node_roomjoin "https://github.com/bitpolito/mininggame/blob/main/src/lib/roomJoin.js"
click node_roomauth "https://github.com/bitpolito/mininggame/blob/main/src/lib/roomAuth.js"
click node_roomconfig "https://github.com/bitpolito/mininggame/blob/main/src/lib/roomConfig.js"
click node_race "https://github.com/bitpolito/mininggame/blob/main/src/lib/raceProjection.js"
click node_server "https://github.com/bitpolito/mininggame/blob/main/server.js"
click node_roomhandler "https://github.com/bitpolito/mininggame/blob/main/api/room.js"
click node_kv "https://github.com/bitpolito/mininggame/blob/main/api/kv.js"
click node_health "https://github.com/bitpolito/mininggame/blob/main/api/health.js"
click node_locale "https://github.com/bitpolito/mininggame/blob/main/src/i18n/LocaleContext.jsx"
click node_focus "https://github.com/bitpolito/mininggame/blob/main/src/hooks/useModalFocus.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_easy,node_hard,node_gameui,node_mempoolui,node_guide toneBlue
class node_engine,node_selection,node_draft,node_mempool,node_hashing,node_powdice toneAmber
class node_roominvite,node_hostdash,node_roomapi,node_roomjoin,node_roomauth,node_roomconfig,node_race toneMint
class node_server,node_roomhandler,node_kv,node_health toneRose
class node_locale,node_focus,node_player toneIndigo
```

## Components

### Game experience

- [App and session flow](https://github.com/bitpolito/mininggame/blob/main/src/App.jsx): `src/App.jsx`
- [Easy mode](https://github.com/bitpolito/mininggame/blob/main/src/games/EasyGame.jsx): `src/games/EasyGame.jsx`
- [Hard mode](https://github.com/bitpolito/mininggame/blob/main/src/games/HardGame.jsx): `src/games/HardGame.jsx`
- [Mining interface](https://github.com/bitpolito/mininggame/tree/main/src/components/game): `src/components/game`
- [Mempool table](https://github.com/bitpolito/mininggame/blob/main/src/components/game/MempoolTable.jsx): `src/components/game/MempoolTable.jsx`
- [How-to-play guide](https://github.com/bitpolito/mininggame/blob/main/src/HowToPlay.jsx): `src/HowToPlay.jsx`

### Mining rules

- [Game engine](https://github.com/bitpolito/mininggame/blob/main/src/lib/gameEngine.js): `src/lib/gameEngine.js`
- [Transaction selection](https://github.com/bitpolito/mininggame/blob/main/src/lib/txSelection.js): `src/lib/txSelection.js`
- [Game drafts](https://github.com/bitpolito/mininggame/blob/main/src/lib/gameDraft.js): `src/lib/gameDraft.js`
- [Mempool generation](https://github.com/bitpolito/mininggame/blob/main/src/lib/mempool.js): `src/lib/mempool.js`
- [Hashing and targets](https://github.com/bitpolito/mininggame/blob/main/src/lib/targetHash.js): `src/lib/targetHash.js`
- [Nonce challenge](https://github.com/bitpolito/mininggame/blob/main/src/lib/powDice.js): `src/lib/powDice.js`

### Multiplayer rooms

- [Room invitations](https://github.com/bitpolito/mininggame/blob/main/src/components/RoomInvite.jsx): `src/components/RoomInvite.jsx`
- [Host dashboard](https://github.com/bitpolito/mininggame/blob/main/src/components/HostDashboard.jsx): `src/components/HostDashboard.jsx`
- [Room API client](https://github.com/bitpolito/mininggame/blob/main/src/lib/roomApi.js): `src/lib/roomApi.js`
- [Room joining](https://github.com/bitpolito/mininggame/blob/main/src/lib/roomJoin.js): `src/lib/roomJoin.js`
- [Room identity](https://github.com/bitpolito/mininggame/blob/main/src/lib/roomAuth.js): `src/lib/roomAuth.js`
- [Room configuration](https://github.com/bitpolito/mininggame/blob/main/src/lib/roomConfig.js): `src/lib/roomConfig.js`
- [Race projection](https://github.com/bitpolito/mininggame/blob/main/src/lib/raceProjection.js): `src/lib/raceProjection.js`

### Room service

- [HTTP server](https://github.com/bitpolito/mininggame/blob/main/server.js): `server.js`
- [Room handler](https://github.com/bitpolito/mininggame/blob/main/api/room.js): `api/room.js`
- [Key-value storage](https://github.com/bitpolito/mininggame/blob/main/api/kv.js): `api/kv.js`
- [Health endpoint](https://github.com/bitpolito/mininggame/blob/main/api/health.js): `api/health.js`

### Shared experience

- [Locale context](https://github.com/bitpolito/mininggame/blob/main/src/i18n/LocaleContext.jsx): `src/i18n/LocaleContext.jsx`
- [Modal focus](https://github.com/bitpolito/mininggame/blob/main/src/hooks/useModalFocus.js): `src/hooks/useModalFocus.js`

### Other components

- **Player**

## Connections

- Player → App and session flow: starts or joins
- App and session flow → Easy mode: opens mode (evidence: `src/App.jsx`)
- App and session flow → Hard mode: opens mode (evidence: `src/App.jsx`)
- App and session flow → Room API client: requests room actions (evidence: `src/App.jsx`)
- Easy mode → Game engine: validates mining (evidence: `src/games/EasyGame.jsx`)
- Hard mode → Game engine: validates mining (evidence: `src/games/HardGame.jsx`)
- Hard mode → Room API client: reports mine (evidence: `src/games/HardGame.jsx`)
- Easy mode → Game drafts: loads game draft (evidence: `src/games/EasyGame.jsx`)
- Hard mode → Game drafts: loads game draft (evidence: `src/games/HardGame.jsx`)
- Easy mode → Mining interface: renders (evidence: `src/games/EasyGame.jsx`)
- Hard mode → Mining interface: renders (evidence: `src/games/HardGame.jsx`)
- Mining interface → Mempool table: renders (evidence: `src/games/HardGame.jsx`)
- Easy mode → How-to-play guide: opens rules (evidence: `src/games/EasyGame.jsx`)
- Hard mode → How-to-play guide: opens rules (evidence: `src/games/HardGame.jsx`)
- Game engine → Transaction selection: checks selection (evidence: `src/lib/gameEngine.js`)
- Game engine → Mempool generation: generates transactions (evidence: `src/lib/gameEngine.js`)
- Game engine → Hashing and targets: computes proof (evidence: `src/lib/gameEngine.js`)
- Hard mode → Nonce challenge: uses nonce challenge (evidence: `src/games/HardGame.jsx`)
- Room invitations → Room joining: builds join link (evidence: `src/components/RoomInvite.jsx`)
- App and session flow → Room joining: reads join code (evidence: `src/App.jsx`)
- App and session flow → Room API client: creates room (evidence: `src/App.jsx`)
- Host dashboard → Race projection: projects race (evidence: `src/components/HostDashboard.jsx`)
- Host dashboard → Room configuration: reads capacity (evidence: `src/components/HostDashboard.jsx`)
- Room API client → Room handler: sends requests
- HTTP server → Room handler: routes requests (evidence: `server.js`)
- Room handler → Key-value storage: reads and writes (evidence: `api/room.js`)
- Room handler → Game engine: validates room mining (evidence: `api/room.js`)
- Room handler → Room configuration: uses room limits (evidence: `api/room.js`)
- Room handler → Hashing and targets: checks targets (evidence: `api/room.js`)
- HTTP server → Health endpoint: routes health checks (evidence: `server.js`)
- App and session flow → Locale context: uses translations (evidence: `src/App.jsx`)
- How-to-play guide → Modal focus: traps dialog focus (evidence: `src/HowToPlay.jsx`)
- Room invitations → Modal focus: traps dialog focus (evidence: `src/components/RoomInvite.jsx`)