Architecture

This document provides a comprehensive overview of MiningOS architecture, covering the system design, components, communication model, and data flow.

---

1. Overview

MiningOS follows a distributed, worker-based architecture where specialized components handle specific responsibilities and communicate via peer-to-peer RPC.

High-Level Architecture Diagram

For installation of these components, see the Installation Guide. For supported hardware, see Supported Devices.

Object Model Diagram

The diagram below represents the UML class hierarchy showing inheritance relationships. Each node represents a single repository in the ecosystem. For detailed repository conventions, see Repository Structure.

Diagram Legend:

• Stadium-shaped nodes with italic labels are abstract classes that are automatically acquired as dependencies

• Square nodes are concrete implementations that must be explicitly downloaded, installed, and configured

• Square nodes highlighted in green are workers for miners or containers (at least one required for any mining setup)

• Square nodes highlighted in brown are required dependencies that must be manually installed

• Disconnected nodes are not part of the inheritance chain

For creating new workers in this hierarchy, see Adding New Worker Type.

---

2. Core Architecture

Key Architectural Principles

2.1 Hierarchical Abstraction

MiningOS uses a multi-level class hierarchy where abstract templates provide common functionality and concrete implementations handle vendor-specific details. For detailed documentation of this hierarchy, see Repository Structure.

For naming conventions, see Repository Structure — Naming Conventions.

2.2 Separation of Concerns

Layer	Responsibility	Documentation
Base Layer	Process management, RPC server, lifecycle hooks	Repository Structure
Thing Layer	Mining-specific abstractions, statistics, logging	Adding New Worker — Level 3
Type Layer	Device type abstractions (miner, container, sensor)	Adding New Worker — Level 4
Implementation Layer	Vendor-specific API integrations	Adding New Worker — Level 5

2.3 Distributed State

• No central database—each worker maintains its own state

• Data aggregated on-demand by the Orchestrator

• Hyperbee provides persistent, replicated storage

---

3. System Components

MiningOS consists of four main component types:

3.1 Workers

Specialized processes that communicate with physical devices or external APIs. Each worker:

• Manages a subset of devices (called a "rack")

• Collects data at configurable intervals

• Exposes RPC methods for control and monitoring (see RPC Method Implementation)

• Persists data locally using Hyperbee

For worker implementation details, see Worker Implementation Files.

3.2 Orchestrator (Ork)

The coordination layer that:

• Aggregates data from all workers

• Manages action queues for device operations (see Requests & Approvals)

• Maintains distributed state across the infrastructure

• Provides a unified interface for the App Node

For Ork installation, see Installation — Ork.

3.3 App Node

The HTTP API gateway that:

• Authenticates and authorizes users (OAuth2 + RBAC) — see User Management

• Translates HTTP requests to RPC calls

• Caches frequently accessed data

• Exposes REST endpoints for the frontend

For App Node setup, see Installation — App Node.

3.4 App UI

The React-based web dashboard that:

• Provides real-time monitoring visualizations — see Dashboard

• Enables device configuration and control — see Explorer

• Displays alerts and notifications — see Alerts Manual

• Supports multiple user roles — see Settings

For UI installation, see Installation — React Web App UI.

Component Diagram

Notes:

• Brown highlights indicate required dependencies

• Nodes previously highlighted in green are contained in the "Device Specific Workers" stack

• DHCP Worker is recommended only for very large operations

---

4. Communication Model

4.1 Hyperswarm P2P Network

MiningOS uses Hyperswarm for worker-to-worker communication, providing:

• NAT Traversal: Workers can communicate across networks without port forwarding

• Encryption: All communication is encrypted end-to-end

• Decentralization: No central server required for coordination

• Resilience: Network automatically heals when nodes join/leave

4.2 RPC Protocol

Workers communicate using a simple RPC protocol. For implementing RPC methods, see RPC Method Implementation Pattern.

// Example: Get miner status
hp-rpc-cli -s <worker-public-key> -m getMinerStatus -d '{"ip": "192.168.1.100"}'

// Example: Set power mode
hp-rpc-cli -s <worker-public-key> -m setPowerMode -d '{"ip": "192.168.1.100", "mode": "low"}'

For power mode options per miner model, see Power Mode Support Table.

4.3 Network Topology

4.4 Rack System (Scalability)

To ensure the highest level of scalability, core workers that interact with the mining infrastructure use the concept of rack. It would be impossible to have a single Node.js worker that connects to 10,000 miners, so the allocation (address space of miners) is split across multiple workers.

This is achieved through the thingMap, which specifies ranges of IPv4 addresses and their relative shard.

Each rack worker manages a collection of "things" (devices or services) and exposes them through a unified RPC interface. The orchestrator aggregates data across all racks, coordinates write operations through a voting system (see Requests & Approvals), and provides historical query capabilities.

---

5. Data Flow

5.1 Collection Flow

Data is displayed in the Dashboard and Explorer.

5.2 Action Flow

For the action authorization workflow, see Requests & Approvals.

5.3 Data Persistence

Each component stores data using Hyperbee:

Data Type	Storage Location	Retention	Related Documentation
Device snapshots	Worker	Configurable	Worker Implementation
Aggregated stats	Ork	Configurable	Dashboard
User data	App Node	Persistent	Settings
Historical data	All levels	Replicated across Hyperbee	Historical Movements

---

6. Components Deep Dive

6.1 Workers

Workers are the fundamental building blocks of MiningOS. Each worker is responsible for communicating with a specific type of device.

Worker Types

Category	Worker	Purpose	Installation
Miners	miningos-wrk-miner-antminer	Bitmain Antminer devices	Antminer Setup
	miningos-wrk-miner-whatsminer	MicroBT Whatsminer devices	Whatsminer Setup
	miningos-wrk-miner-avalon	Canaan Avalon devices	Avalon Setup
Containers	miningos-wrk-container-antspace	Bitmain Antspace containers	Antspace Setup
	miningos-wrk-container-bitdeer	Bitdeer containers	Bitdeer Setup
	miningos-wrk-container-microbt	MicroBT containers	MicroBT Setup
Power	miningos-wrk-powermeter-abb	ABB power meters	ABB Setup
	miningos-wrk-powermeter-schneider	Schneider power meters	Schneider Setup
	miningos-wrk-powermeter-satec	Satec power meters	Satec Setup
Sensors	miningos-wrk-sensor-temp-seneca	Seneca temperature sensors	Seneca Setup
External	miningos-wrk-ext-mempool	Bitcoin mempool data	Mempool Setup
	miningos-wrk-ext-openweather	Weather data for containers	Openweather Setup
Pools	miningos-wrk-minerpool-ocean	Ocean pool statistics	Ocean Setup
	miningos-wrk-minerpool-f2pool	F2Pool statistics	F2Pool Setup

For detailed device specifications, see Supported Devices.

Rack Configuration Example

This architecture enables:

• Scalability: Add workers as your operation grows

• Fault Isolation: Issues in one rack don't affect others

• Parallel Processing: Each worker operates independently

6.2 Orchestrator (Ork)

The Ork (Orchestrator) is the central coordination layer of MiningOS.

Responsibilities

Function	Description	Related UI
Data Aggregation	Collects and combines data from all workers	Dashboard
Action Queues	Manages pending operations on devices	Requests & Approvals
State Management	Maintains distributed state across infrastructure	Explorer
Worker Coordination	Routes requests to appropriate workers	Header — Actions Chart

6.3 App Node

The App Node serves as the HTTP API gateway between the web frontend and the distributed worker network.

Features

Feature	Description	Related Documentation
Authentication	OAuth2 with multiple providers	Installation — App Node
Authorization	Role-based access control	User Management
API Gateway	RESTful endpoints for all operations	Backend Operations
Caching	Reduces load on workers	—
WebSocket	Real-time updates to frontend	Dashboard

6.4 App UI

The App UI is a React-based web dashboard providing the primary user interface.

Features

Feature	Description	Documentation
Dashboard	Real-time overview of all devices	Dashboard
Device Views	Detailed views for miners, containers, etc.	Explorer, Container Examples
Actions	Control panel for device operations	Requests & Approvals
Alerts	Notification center for issues	Alerts Manual
Reports	Historical data and analytics	Heatmaps

---

7. Repository Structure

MiningOS is organized across multiple GitHub repositories, structured by abstraction level. For complete repository documentation, see Repository Structure.

Level 1: Foundation

Repository	Type	Description
bfx-wrk-base	Dependency	Core worker class from Bitfinex
miningos-lib-stats	Dependency	Statistics calculation library
miningos-app-ui	User Install	React web dashboard
miningos-cli	User Install	Command-line administration tool

Level 2: Infrastructure

Repository	Type	Description
tether-wrk-base	Dependency	Tether-specific worker extensions
miningos-wrk-dhcp	Optional	DHCP server integration (large operations)

Level 3: Core

Repository	Type	Description
miningos-wrk-ork	Required	Central orchestrator
miningos-app-node	Required	HTTP API backend
miningos-wrk-ext-mempool	Optional	Bitcoin mempool data
miningos-wrk-ext-openweather	Optional	Weather data (outdoor containers)
miningos-wrk-inventory	Optional	Inventory management
miningos-tpl-wrk-thing	Dependency	Base template for device workers

Level 4: Templates

Repository	Type	Description	Creating New
miningos-tpl-wrk-miner	Dependency	Miner worker template	Level 4 Guide
miningos-tpl-wrk-container	Dependency	Container worker template	Level 4 Guide
miningos-tpl-wrk-powermeter	Dependency	Power meter template	Level 4 Guide
miningos-tpl-wrk-sensor	Dependency	Sensor template	Level 4 Guide
miningos-tpl-wrk-electricity	Dependency	Electrical infrastructure template	Level 4 Guide
miningos-tpl-wrk-switchgear	Dependency	Switchgear template	Level 4 Guide

Level 5: Device Implementations

Category	Repositories	Specifications
Miners	miningos-wrk-miner-antminer, miningos-wrk-miner-whatsminer, miningos-wrk-miner-avalon	Supported Miners
Containers	miningos-wrk-container-antspace, miningos-wrk-container-bitdeer, miningos-wrk-container-microbt	Supported Containers
Power Meters	miningos-wrk-powermeter-abb, miningos-wrk-powermeter-schneider, miningos-wrk-powermeter-satec	Supported Power Meters
Sensors	miningos-wrk-sensor-temp-seneca	Supported Sensors
Mining Pools	miningos-wrk-minerpool-ocean, miningos-wrk-minerpool-f2pool	Pool Manager

For creating new Level 5 implementations, see Adding New Worker — Level 5.

---

8. Class Hierarchy

8.1 Physical Device Workers

bfx-wrk-base (Generic Worker)
    │
    └── tether-wrk-base (Tether Infrastructure)
            │
            └── miningos-tpl-wrk-thing (MiningOS Base Thing)
                    │
                    ├── miningos-tpl-wrk-miner
                    │       ├── miningos-wrk-miner-antminer
                    │       ├── miningos-wrk-miner-whatsminer
                    │       └── miningos-wrk-miner-avalon
                    │
                    ├── miningos-tpl-wrk-container
                    │       ├── miningos-wrk-container-antspace
                    │       ├── miningos-wrk-container-bitdeer
                    │       └── miningos-wrk-container-microbt
                    │
                    ├── miningos-tpl-wrk-powermeter
                    │       ├── miningos-wrk-powermeter-abb
                    │       └── miningos-wrk-powermeter-schneider
                    │
                    └── miningos-tpl-wrk-sensor
                            └── miningos-wrk-sensor-temp-seneca

8.2 External API Workers

bfx-wrk-base (Generic Worker)
    │
    └── tether-wrk-base (Tether Infrastructure)
            │
            ├── miningos-wrk-ext-mempool
            └── miningos-wrk-ext-openweather

8.3 Infrastructure Workers

bfx-wrk-base (Generic Worker)
    │
    └── tether-wrk-base (Tether Infrastructure)
            │
            ├── miningos-wrk-ork
            ├── miningos-wrk-dhcp
            └── miningos-wrk-inventory

---

MiningOS is developed by Tether and released under the Apache 2.0 license.