# bustabit/v1-gameserver architecture

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

- Interactive diagram: https://gitdiagram.com/bustabit/v1-gameserver
- Repository: https://github.com/bustabit/v1-gameserver

## Overview

##### Project type and purpose
- Project type: Backend service (no bundled frontend)
- Purpose: Run a provably-fair bitcoin betting game. It exposes HTTP/WebSocket endpoints, manages game logic, records history in Postgres, and interacts with the Bitcoin network (via RPC or Coinbase APIs) and BIP32 keys.

##### File structure
Top-level files:
– server.js (entry point: boots HTTP & WebSocket servers, loads modules)
– populate_hashes.js (precompute commitment hashes script)
– config files: nodemon.json, .gitignore, cert.pem/key.pem (SSL)
– package.json (dependencies, start script)
server/ folder modules:
– config.js (env var loader: DATABASE_URL, BIP32_DERIVED_KEY, COINBASE_*)
– database.js (Postgres client wrapper)
– bitcoin_client.js (RPC or Coinbase API handler)
– game.js (core game rules, spin/wager logic)
– game_history.js (logs results, queries/stores in DB)
– socket.js (WebSocket routes & event broadcasting)
– lib.js (utility functions)
– sorted_array.js (data structure for game odds or bet ordering)

##### README
- Stack: Node.js + Postgres + BIP32 key + optional Coinbase APIs
- Runtime: npm start → server listens on port 3841
- Setup: env vars for DB & external keys, DB schema in server/schema.sql
- No frontend; clients connect via HTTP/WebSocket

## Diagram (Mermaid)

```mermaid
flowchart TD
    clients[Clients]:::external
    clients -->|HTTP/WebSocket| serverEntry

    subgraph "Node.js Server"
        serverEntry["server.js\n(HTTP & WS Listener)"]:::internal
        config["config.js\n(Configuration Loader)"]:::internal
        socket["socket.js\n(WebSocket Routing & Event Broadcasting)"]:::internal
        game["game.js\n(Core Game Logic)"]:::internal
        history["game_history.js\n(Game History Logger)"]:::internal
        databaseModule["database.js\n(Postgres Client Wrapper)"]:::internal
        bitcoinClient["bitcoin_client.js\n(Bitcoin / Coinbase Integration)"]:::internal
        lib["lib.js\n(Utility Functions)"]:::internal
        sortedArray["sorted_array.js\n(Sorted Array Data Structure)"]:::internal
        cert["cert.pem / key.pem\n(SSL Certificates)"]:::internal
        nodemon["nodemon.json\n(Process Supervisor Config)"]:::internal
    end

    serverEntry -->|loads| config
    serverEntry -->|starts| socket
    socket -->|invokes| game
    game -->|uses| sortedArray
    game -->|uses| lib
    game -->|logs results via| history
    history -->|calls| databaseModule
    databaseModule -->|reads/writes| postgres

    game -->|interacts| bitcoinClient
    bitcoinClient -->|RPC calls| bitcoinNode
    bitcoinClient -->|API calls| coinbase

    subgraph "Database"
        postgres[(Postgres DB)]:::db
    end

    subgraph "External Systems"
        bitcoinNode((Bitcoin RPC Node)):::external
        coinbase((Coinbase API)):::external
    end

    populateScript["populate_hashes.js\n(Offline Hash-Population Script)"]:::cli
    populateScript -->|uses| lib
    populateScript -->|uses| sortedArray
    populateScript -->|writes precomputed data to| postgres

    classDef internal fill:#ADD8E6,stroke:#000,color:#000
    classDef db fill:#90EE90,stroke:#000,color:#000
    classDef external fill:#FFA500,stroke:#000,color:#000
    classDef cli fill:#D3D3D3,stroke:#000,color:#000

    click serverEntry "https://github.com/bustabit/v1-gameserver/blob/main/server.js"
    click populateScript "https://github.com/bustabit/v1-gameserver/blob/main/populate_hashes.js"
    click config "https://github.com/bustabit/v1-gameserver/blob/main/server/config.js"
    click databaseModule "https://github.com/bustabit/v1-gameserver/blob/main/server/database.js"
    click bitcoinClient "https://github.com/bustabit/v1-gameserver/blob/main/server/bitcoin_client.js"
    click game "https://github.com/bustabit/v1-gameserver/blob/main/server/game.js"
    click history "https://github.com/bustabit/v1-gameserver/blob/main/server/game_history.js"
    click socket "https://github.com/bustabit/v1-gameserver/blob/main/server/socket.js"
    click lib "https://github.com/bustabit/v1-gameserver/blob/main/server/lib.js"
    click sortedArray "https://github.com/bustabit/v1-gameserver/blob/main/server/sorted_array.js"
    click cert "https://github.com/bustabit/v1-gameserver/blob/main/cert.pem"
    click nodemon "https://github.com/bustabit/v1-gameserver/blob/main/nodemon.json"
```
