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-ui-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-ui-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 two products: UI Core (the headless brain) and UI Kit (styled components), with framework adapters bridging the two for any UI framework. This ensures that business logic is never reinvented while leaving UI styling entirely under developer control.

UI Core

The UI Core (@tetherto/mdk-ui-core) is the headless brain that connects to the developer's App Node API.

It manages stateful logic that every UI needs but renders nothing:

• Subscriptions: buffers rapid backend telemetry streams (for example, max 2 renders per second)
• Stale detection: emits stale events if the connection drops for 30 seconds
• History: maintains an internal ring buffer tailored for sparkline charts
• Optimistic UI: manages command states (pending, confirmed, failed, timeout) locally before the server responds

Framework adapters

@tetherto/mdk-ui-core generates raw JavaScript state objects, which do not automatically trigger UI re-renders. To bridge this gap, the toolkit provides thin framework adapters that translate the headless state machine into framework-native reactive lifecycles (React useState, Vue ref, Svelte stores).

By calling standardized hooks like useTelemetry(deviceId) or useCommand, a UI component automatically receives perfectly buffered, reactive data without the developer ever touching the underlying connection or state manager.

Adapters: @tetherto/mdk-react, @tetherto/mdk-vue, @tetherto/mdk-svelte, @tetherto/wc (Web Components). All expose one consistent hook surface across every supported framework.

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-ui-devkit-react 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

UI Kits for other frameworks (Vue, Svelte, and so on) will follow the same pattern and ship alongside their framework adapters.

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:

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