MDK App Toolkit

Introducing the MDK App Toolkit

The MDK App Toolkit is an open-source, reusable package for building applications on top of @tetherto/mdk-ork.

The App Toolkit ships in three parts:

1. Frontend tools.
2. Backend tools.
3. Plugins.

While @tetherto/mdk-ork is entirely unopinionated, the App Toolkit provides a batteries-included application layer. It plugs into existing stacks (leveraging the low-level @tetherto/mdk-client for @tetherto/mdk-ork connectivity) so teams can ship operator-ready dashboards and custom domain logic without rebuilding the App Node from scratch.

The problem

Building an application on top of hardware infrastructure historically forces developers to face four friction points across the full stack:

1. Frontend repeated logic: every frontend developer integrating with backend APIs ends up reinventing solutions to the same plumbing challenges:

   • Throttling fast-moving telemetry streams
   • Managing optimistic UI state transitions
   • Detecting silent communication timeouts

2. Backend repeated logic: every backend developer ends up writing the same App Node plumbing (JWT auth, RBAC, command proxying, and fleet aggregation) before they can ship any custom business logic.

3. The UI rigidity trap: platforms try to solve the repeated logic problem by shipping a UI component library. UI is inherently subjective; when external developers are forced to use generic components, they get locked out of customizing the CSS to match their brand, leading to abandoned toolkits and identical-looking dashboards.

4. The extension bottleneck: when an external manufacturer builds a brand new miner or device, there is no clear path for injecting a custom dashboard widget and custom aggregator into an existing deployment.

The solution

The App Toolkit decouples logic from styling, separates frontend and backend concerns, and provides an explicit plug-and-play extension architecture:

1. It extracts complex API state and caching logic, such as handling server disconnects and buffering data from the App Node gateway, into a purely headless frontend layer (@tetherto/mdk-react-devkit/core).

2. It ships a reusable App Node library that drops into Fastify or Express, handling JWT auth, RBAC, and @tetherto/mdk-ork proxying out of the box, while exposing hooks for developers to plug in their own routes and aggregations.

3. It embraces the shadcn/ui pattern by providing reference UI components that developers copy and paste, giving them full control over CSS and layout while still leveraging the underlying data hooks.

   🚧 Components will soon be available via npm.

4. It provides the MDK-App plugin architecture: an out-of-the-box, extensible shell framework where third-party frontend widgets and backend routes can be injected dynamically at runtime as a single drop-in package.

The scope

While MDK targets Bitcoin mining, the App Toolkit's architecture is deliberately domain-agnostic. Anywhere there is a fleet of devices reporting telemetry, with operators that need real-time visibility and control, the same patterns apply: IoT sensor networks, industrial telemetry, energy grid monitoring, autonomous vehicle fleets, and AI-agent control planes are all natural fits.

The portable layers are everything above the protocol boundary: the headless state machine handles buffering, optimistic UI, and stale detection regardless of what telemetry it receives; the framework adapters translate that state into reactive lifecycles for any React, Vue, or Svelte app; the reference UI primitives and the plug-and-play shell are generic UI building blocks; the App Node middleware library is generic Fastify/Express; and the plugin pattern, register a backend route alongside a widget that consumes it, works for any backend with the same shape.

The MDK-specific glue lives below: @tetherto/mdk-client speaks the MDK Protocol to @tetherto/mdk-ork, the App Node middleware proxies commands over Holepunch RPC, and @tetherto/mdk-react-devkit/foundation adds mining-domain components such as vendor container UIs and the operations centre. Swap that protocol layer and the App Toolkit pattern carries to any domain with the same shape.

Frontend tools

Frontend tools are the building blocks for dashboards on top of @tetherto/mdk-ork. They decompose into three layers: UI Core (headless state), framework adapters (e.g., React bindings), and UI Kit (styled React components), so business logic is shared while styling stays under developer control.

UI Core

The UI Core (@tetherto/mdk-ui-core) is the framework-agnostic headless layer. Headless: the same store logic can back React, Vue, Svelte, or plain JS utilities. Framework adapters bind @tetherto/mdk-ui-core into reactive lifecycles for each UI runtime.

Framework adapters

@tetherto/mdk-ui-core stores do not trigger UI re-renders on their own. Framework adapters subscribe to those stores and expose reactive hooks.

For React, @tetherto/mdk-react-adapter provides <MdkProvider>, store hooks (useAuth, useDevices, useActions, and others), and TanStack Query re-exports. Future adapters (@tetherto/mdk-vue, @tetherto/mdk-svelte, @tetherto/wc) will follow the same pattern.

UI Kit

The toolkit optionally ships styled reference components (for example, <DeviceTile />). These follow the shadcn/ui pattern: they are copy-pasted into the developer's source tree. Developers own the styling completely.

React UI Kit

For React, @tetherto/mdk-react-devkit is a production-tested UI Kit available as a ready-made implementation of this layer. Highlights:

• 100+ production-tested components
• Built on React 19 and shadcn/ui
• Zero CSS-in-JS runtime overhead

Developer entry points

The toolkit can be adopted at any of the following entry points, from most batteries-included to least.

Backend tools

Backend tools are a library for implementing custom business logic on top of @tetherto/mdk-ork, loosely coupled to the App Node and completely plug-and-play. Developers do not have to write the App Node gateway from scratch: the library drops directly into Fastify or Express, ships the boilerplate every operator needs, and exposes hooks for the custom routes and aggregations that make each deployment unique.

Drop-in App Node middleware

Pre-built middleware that wires up the standard App Node responsibilities so developers do not reinvent them:

• Exposing standard /auth endpoints
• Validating incoming user JWTs
• Proxying commands securely down to @tetherto/mdk-ork over Holepunch RPC (HRPC) using @tetherto/mdk-client

Route extension API

Hooks allowing developers to bind new REST or WebSocket endpoints (for example, POST /mining/stats) that perform complex aggregations using @tetherto/mdk-ork capabilities via @tetherto/mdk-client. Custom routes live in a developer-owned package and snap into the middleware without forking it.

Plugins

A plugin pairs a frontend tools widget with a backend tools route as a single drop-in module. For developers looking for an out-of-the-box solution, the toolkit pairs the frontend and backend halves into the MDK-App plugin architecture: an extensible, multi-tenant shell.

The prebuilt shell

Instead of building a custom React layout and a custom Fastify server, developers spin up the MDK UI Shell and MDK Generic App Node. These are ready-to-use binaries fully wired together.

Writing a plugin

External developers write plugins consisting of two tightly coupled pieces of code that register dynamically into the shell at runtime:

1. MDK-App server: a package of business logic that registers custom backend routes (for example, /mining/stats) into the backend tools middleware hooks.
2. MDK-App widget: a custom frontend component that mounts into the MDK UI Shell's grid layout and natively queries /mining/stats.

Plug-and-play reusability: this explicit convention ensures that an external company can build a completely new dashboard widget and backend aggregator for a new device type, publish it as a single npm package, and allow any user to drop it into their existing MDK deployment without modifying upstream source code.

Architecture overview

Next steps

Learn more:

• About MDK
• Architecture: the orchestration kernel
• Connecting intelligent agents
• See the license