Architecture
Internal architecture of MDK Core — the backend SDK powering Bitcoin mining operations across all scales
1. Purpose
This document describes the internal architecture of MDK Core — backend SDK powering Bitcoin mining operations across all scales.
MDK is designed to:
- Run as a single process or as distributed microservices
- Support multiple device types
- Scale from one miner to thousands without architectural changes
2. Architecture Goals
MDK is built on the following goals:
- Separation of Concerns — Decouple device logic from runtime and deployment models
- Flexibility — Support multiple deployment models without code duplication
- Developer Experience — Simplify consumption for small sites and open-source developers
- Scalability — Support enterprise-scale deployments with independent scaling
- Standard Interface — Common interface for all device types
3. High-Level Architecture
3.1 Single-process mode
3.2 Multi-process mode
4. Key Components
4.1 Device API Libraries
Each device type (miners, containers, powermeters, sensors) is implemented as a standalone library that exposes a standard interface. Libraries are organized by brand and model (e.g. Whatsminer, Antminer, Bitdeer) and can be consumed via MDK in single-process or microservices mode, or used programmatically as direct lib classes.
4.2 Backend SDK (MDK Core)
The MDK Core bundles all device type libraries and core services (app-node, ork) into a single installable package. It provides one dependency install, all device types under one namespace, and the same API whether running in single-process or microservices mode. Internal services can be run in-process or deployed as separate processes/containers.
4.3 Communication Modes
| Mode | Flow | Overhead |
|---|---|---|
| Single-process | App Node → ORK → Device Libs (direct in-process calls) | No RPC overhead |
| Multi-process (microservices) | All communication via HRPC between processes | Full service isolation and independent scaling |
5. Single-Process Mode
In single-process mode, the API layer, orchestration (ork), and device libraries run in one process. Clients register device libraries and racks; the app-node and ork route requests directly to in-process lib instances. Best for development, home miners, and small sites. Benefits include minimal resource usage, simple debugging, and no orchestration overhead.
6. Multi-Process Mode (Microservices)
In multi-process mode, each logical service runs as its own process: app-node instance (REST API), one or more ork instances (orchestration), and lib-workers (one per device type/rack or cluster). All communication between processes uses HRPC. Configuration (e.g. mdk.config.json) defines the list of services; MDK can generate PM2 or Docker/Kubernetes manifests from this config. No application code changes are required to switch from single-process to multi-process — only deployment configuration.
7. Deployment Flexibility
MDK is a deployment-flexible platform. It can run as:
- Single embedded process — One install, one process; ideal for small sites
- PM2-managed multi-process cluster — Multiple processes on one or more hosts
- Containerized stack — Docker or Kubernetes for production-grade orchestration
Switching between these modes requires only deployment configuration changes.
8. Storage Architecture
MDK provides persistent, local-first storage via an embedded key-value store Hyperbee optimized for time-series data and replication. Use cases include metrics history, device state, configuration snapshots, and event logs. Storage is append-only, crash-resilient, and consistent across restarts.
9. Failure Handling
MDK is designed to fail locally and predictably. Worker crashes do not bring down the runtime; automatic restarts and health/liveness checks are supported. In multi-process deployments, supervisors (PM2, Docker, Kubernetes) handle process restarts, and workers rejoin the system after recovery.
10. Security Model
MDK follows a strict security-by-design approach: explicit interfaces only, no implicit network exposure, authenticated RPC where applicable, and least-privilege permissions for all workers.
11. Extensibility
MDK is extensible by design. New device types, storage backends, communication transports, and orchestration logic can be added without modifying the core runtime.
12. Summary
MDK provides:
- A new, unified backend SDK with a standard interface for all device types
- Flexible deployment — single process, PM2, or Docker/Kubernetes
- Strong isolation, scalability, and long-term maintainability
MDK is designed to evolve alongside the Bitcoin mining ecosystem.