Repository Structure

Overview of MiningOS repository organization, inheritance hierarchy, and naming conventions.

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

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

Repository Structure

On this page