# blinkhash/foundation-v1-server architecture

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

- Interactive diagram: https://gitdiagram.com/blinkhash/foundation-v1-server
- Repository: https://github.com/blinkhash/foundation-v1-server

## Overview

##### Project Type & Purpose
- This is a back-end Node.js application (“foundation-server”) that provides:
– A Stratum‐protocol pool server for miners
– Share validation and persistence
– Reward/payment calculation and dispatch
– Statistics collection and HTTP API for monitoring/management
- There’s no built-in front end; a separate client will interact via the API and Stratum.

##### File Structure
- configs/ – JSON/JS files: main platform settings, pool definitions
- certificates/ – SSL/TLS certs for securing Stratum or API endpoints
- scripts/main/
– server.js: orchestrates startup, exposes HTTP & Stratum services
– stratum.js: Stratum protocol server for miners
– api.js: HTTP REST RPC for operator queries & stats
– database.js: DB connection layer (MySQL/PostgreSQL)
– loader.js: Polls external coin daemons (block height, difficulty)
– builder.js: Constructs new mining jobs, handles job queues
– shares.js: Validates and records miner shares
– payments.js: Calculates payouts, submits transactions to coin daemons
– statistics.js: Aggregates real-time metrics (hashrate, shares, blocks)
– logger.js: Centralized logging
– threads.js & workers.js: Worker thread management for CPU-bound tasks
– utils.js: Shared helpers
- scripts/test/: Unit and integration tests
- package.json: Node.js dependencies (e.g., “stratum-pool,” ORM, worker threads)

##### Extract Key Architecture Notes from README
- All-in-one, highly scalable, Node.js
- Core features: stratum pool, share processing, payout engine
- Configuration-driven (per-coin configs in “configs/”)
- External docs & configs live in separate repos
- Licensed GPL-2.0

##### Main Components & Boundaries
A. External Actors/Systems
1. Miners (via TCP Stratum protocol)
2. Coin Daemon(s) (via JSON-RPC over HTTP)
3. Operator/Client UIs (via HTTP REST API)
B. Foundation-Server Core
1. Configuration Loader (reads configs/*, certificates/*)
2. Stratum Server Module (scripts/main/stratum.js)
3. Job Builder Module (builder.js)
4. Share Validator & Persister (shares.js → database)
5. Payment Engine (payments.js → daemon RPC)
6. Blockchain Loader (loader.js → daemon RPC)
7. Statistics Engine (statistics.js → database or in‐

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        Miners["Miners\n(TCP Stratum)"]:::external
        Daemon["Coin Daemon(s)\n(JSON-RPC)"]:::external
        Operator["Operator UI\n(HTTP REST API)"]:::external
    end

    subgraph "Foundation-Server Core"
        Config["Configuration Loader"]:::config
        Server["Server Orchestrator\n(HTTP & Stratum entry)"]:::service
        Stratum["Stratum Server Module"]:::service
        API["HTTP REST API Module"]:::service
        JobBuilder["Job Builder Module"]:::service
        ShareVal["Share Validator & Persister"]:::service
        Payment["Payment Engine"]:::service
        Loader["Blockchain Loader Module"]:::service
        Stats["Statistics Engine"]:::service
        DB["Database Connection Layer"]:::db
        Logger["Centralized Logging Module"]:::service
        Threads["Worker Threads Manager"]:::service
        Workers["Worker Threads"]:::service
        Utils["Utility Functions"]:::service
    end

    %% Data Flows
    Miners -->|"shares/jobs"| Stratum
    Server -->|"init services"| Stratum
    Server -->|"init services"| API
    Config -->|loads settings| Stratum
    Config -->|loads settings| API
    Config -->|loads settings| JobBuilder
    Config -->|loads settings| Payment
    Config -->|loads settings| Loader
    Stratum -->|"new job"| JobBuilder
    JobBuilder -->|"job payload"| Stratum
    JobBuilder -->|"validate share"| ShareVal
    ShareVal -->|"record share"| DB
    Payment -->|"submit tx"| Daemon
    Loader -->|"fetch block data"| Daemon
    Stats -->|"store stats"| DB
    API -->|"query stats"| Stats
    API -->|"query data"| DB

    %% Logging
    Stratum --> Logger
    API --> Logger
    JobBuilder --> Logger
    ShareVal --> Logger
    Payment --> Logger
    Loader --> Logger
    Stats --> Logger
    Server --> Logger

    %% Worker Threads and Utils
    Threads --> ShareVal
    Threads --> JobBuilder
    Threads --> Payment
    Threads --> Loader
    Workers --> Threads
    Utils --> Config
    Utils --> JobBuilder
    Utils --> ShareVal
    Utils --> Payment
    Utils --> Loader
    Utils --> API
    Utils --> Server

    %% Click Events
    click Config "https://github.com/blinkhash/foundation-v1-server/tree/master/configs/"
    click Stratum "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/stratum.js"
    click JobBuilder "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/builder.js"
    click ShareVal "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/shares.js"
    click Payment "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/payments.js"
    click Loader "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/loader.js"
    click Stats "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/statistics.js"
    click Server "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/server.js"
    click API "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/api.js"
    click DB "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/database.js"
    click Logger "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/logger.js"
    click Threads "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/threads.js"
    click Workers "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/workers.js"
    click Utils "https://github.com/blinkhash/foundation-v1-server/blob/master/scripts/main/utils.js"

    classDef external fill:#ccf,stroke:#003,stroke-width:1px
    classDef service fill:#cfc,stroke:#060,stroke-width:1px
    classDef db fill:#fcf,stroke:#909,stroke-width:1px
    classDef config fill:#cff,stroke:#099,stroke-width:1px
```
