Repository Structure

This document provides a comprehensive overview of the MiningOS repositories. It explains the organizational patterns, inheritance hierarchy, and standard conventions used across all worker repositories.

For the system architecture and component relationships, see Architecture. For contribution workflow, see Contribution Workflow.

---

Overview

MiningOS follows a modular, inheritance-based architecture. Functionality is distributed across multiple Git repositories. Each repository serves a specific purpose in the hierarchy, from foundational worker utilities to concrete device implementations.

Design Philosophy

The repository structure embodies several key principles:

Principle	Description	Related Documentation
Inheritance over composition	Base classes provide core functionality that specialized workers extend	Adding New Worker
Convention over configuration	Standard directory layouts and naming patterns reduce cognitive overhead	Standard Directory Structure
Separation of concerns	Each repository focuses on a single abstraction level or device category	Architecture — Core Architecture
Reusability	Common patterns are extracted into template repositories for maximum code sharing	Repository Hierarchy

Repository Hierarchy

Regarding the workers for physical devices, the MiningOS ecosystem consists of repositories organized into five distinct levels. For the complete architecture diagram, see Architecture — Object Model.

Level 1: Foundation
└── bfx-wrk-base                    # Core worker primitives

Level 2: Platform Base
└── tether-wrk-base                 # Tether/MiningOS worker foundation

Level 3: Thing Management
└── miningos-tpl-wrk-thing          # Abstract "thing" device management

Level 4: Device Category Templates
├── miningos-tpl-wrk-miner          # Mining hardware template
├── miningos-tpl-wrk-container      # Container infrastructure template
├── miningos-tpl-wrk-sensor         # Environmental sensor template
├── miningos-tpl-wrk-powermeter     # Power monitoring template
└── miningos-tpl-wrk-electricity    # Electricity usage 

Level 5: Concrete Implementations
├── miningos-wrk-miner-whatsminer   # WhatsMiner devices (like m53s)
├── miningos-wrk-miner-antminer     # Antminer devices (like s19xp)
├── miningos-wrk-miner-avalon       # Avalon devices (like a1346)
├── miningos-wrk-container-antspace # Antspace miner containers (like hk3)
├── miningos-wrk-container-microbt  # MicroBT miner containers (like kehua)
├── miningos-wrk-sensor-temp-seneca # Seneca temperature sensors
├── miningos-wrk-powermeter-satec   # Satec power meters (like PM180)
└── miningos-wrk-powermeter-schneider # Schneider power meters (like PM5340)

For creating new workers at each level, see Adding New Worker Type. For supported device specifications, see Supported Devices.

Standard Directory Structure

All MiningOS worker repositories follow a consistent directory layout. Below is the canonical structure:

.
├── config/                              # [REQUIRED] Configuration directory
│   ├── common.json.example              # [REQUIRED] Worker-wide settings
│   ├── base.thing.json.example          # [COMMON LEVEL 3+] Thing-specific configuration
│   ├── <worker>.json.example            # [OPTIONAL] Worker-specific settings
│   └── facs/                            # [REQUIRED] Facilities configuration
│       ├── net.config.json.example      # [REQUIRED] Network/RPC server configuration
│       ├── store.config.json.example    # [COMMON LEVEL 3+] Hyperbee storage configuration
│       └── miningos-net.config.json.example # [OPTIONAL] MiningOS network (DHCP workers only)
│
├── mock/                                # [OPTIONAL] Mock implementations for testing
│   └── mock-control-agent.js            # [COMMON] Simulated device controller
│
├── tests/                               # [OPTIONAL] Test suite
│   ├── cases/                           # Test case definitions
│   │   └── stats.js                     # Statistics test cases
│   ├── schema/                          # Response schema validators
│   │   └── stats.js                     # Statistics schema
│   ├── executors.js                     # Test execution utilities
│   ├── utils.js                         # Test helpers
│   └── <worker>.test.js                 # Main test file
│
├── workers/                             # [REQUIRED] Worker implementation directory
│   ├── lib/                             # [REQUIRED] Shared library modules
│   │   ├── base.js                      # [COMMON] Base device class
│   │   ├── alerts.js                    # [COMMON LEVEL 3+] Alert definitions
│   │   ├── constants.js                 # [OPTIONAL] Worker constants
│   │   ├── stats.js                     # [COMMON] Statistics collection logic
│   │   ├── utils.js                     # [COMMON] Utility functions
│   │   └── wrk-fun-stats.js             # [OPTIONAL] Statistics persistence
│   │
│   └── rack.<device>.wrk.js             # [REQUIRED] Main worker class
│
├── worker.js                            # [REQUIRED] Entry point
├── package.json                         # [REQUIRED] Node.js project metadata
├── package-lock.json                    # [REQUIRED] Locked dependency versions (derived file)
├── LICENSE                              # [REQUIRED] Apache 2.0 license
├── README.md                            # [REQUIRED] Repository documentation
├── setup-config.sh                      # [REQUIRED] Config file initialization
└── upstream-merge.sh                    # [COMMON] Parent repository merge script

For testing guidelines, see Testing & Linting Guidelines. For documentation standards, see Code Documentation Standards.

Directory Purpose Reference

Directory/File	Purpose	Related Documentation
config/	All configuration files with .example templates	Installation — Configuration
config/facs/	Facility-specific configuration (network, storage)	Key Files Explained
mock/	Test doubles for device simulation	Testing Guidelines
tests/	Brittle test framework test suite	Testing Guidelines
workers/	Core worker implementation	Worker Implementation Files
workers/lib/	Shared utilities and base classes	Adding New Worker
worker.js	CLI entry point for worker startup	Installation
setup-config.sh	Copies .example files to active configs	Contribution Workflow — Configure the Worker
upstream-merge.sh	Merges changes from parent template	Branching Conventions — Upstream Synchronization

Naming Conventions

Repository names

Pattern	Example	Description	Documentation
bfx-wrk-base	—	Bitfinex foundation worker	Architecture — Level 1
tether-wrk-base	—	Tether platform base	Architecture — Level 2
miningos-tpl-wrk-<type>	miningos-tpl-wrk-miner	Template/abstract worker	Adding New Worker — Level 4
miningos-wrk-<type>-<brand>	miningos-wrk-miner-whatsminer	Concrete implementation	Adding New Worker — Level 5
miningos-wrk-ext-<service>	miningos-wrk-ext-mempool	External service integration	Architecture — External API Workers

Class names

Component	Convention	Example	Documentation
Worker class	Wrk<Device>Rack	WrkMinerRack	Adding New Worker
Base device class	Base<Device>	BaseMiner	Adding New Worker — Level 4
Device controller	<Brand><Device>	WhatsminerMiner	Adding New Worker — Level 5
Model-specific worker class	Wrk<Device>Rack<Model>	WrkMinerRackM56s	Adding New Worker — Level 5

Key files explained

File	Purpose	Related Documentation
worker.js	The entry point for all workers. This file is minimal and delegates to the bfx-svc-boot-js framework	Adding New Worker — Worker Entry Point
package.json	Standard Node.js package manifest with MiningOS-specific conventions	Adding New Worker — Package.json Structure
setup-config.sh	Utility script that creates active configuration files from '.example' files	Contribution Workflow — Configure the Worker
upstream-merge.sh	Merges changes from parent template	Branching Conventions — Upstream Synchronization
config/base.thing.json	Configures thing management behavior	Adding New Worker — Configuration Templates
config/facs/net.config.json	Configures RPC server and network access. Structure varies by repository	Architecture — RPC Protocol
config/facs/store.config.json	Configures Hyperbee persistent storage. This facility typically requires no additional configuration	Architecture — Data Persistence

Worker implementation files

File	Purpose	Related Documentation
workers/[model].rack.[device].wrk.js	The main worker class implementing device-specific logic	Adding New Worker — Main Worker Implementation
workers/lib/base.js	Base class for device interactions	Adding New Worker — Device Library Class
workers/lib/alerts.js	Alert definitions for the device type	Alerts Manual
workers/lib/constants.js	Worker constants and configuration values	Code Documentation — Constants Documentation
workers/lib/stats.js	Statistics collection and aggregation logic	Dashboard
workers/lib/utils.js	Utility functions shared across the worker	Code Documentation

---

Related Documentation

Contributor Guide

• Contribution Workflow — Development environment and PR process

• Branching & PR Conventions — Git workflow and naming conventions

• Testing & Linting Guidelines — Test framework and code style

• Code Documentation Standards — JSDoc and inline comments

• Adding New Worker Type — Creating Level 4 and Level 5 workers

General Documentation

• Overview — What is MiningOS

• Architecture — System design and component hierarchy

• Supported Devices — Hardware compatibility list

• Installation — Setup instructions for all workers

Operator Manual

• Dashboard — Main monitoring interface

• Explorer — Device search and management

• Alerts Manual — Alert types and troubleshooting