Scalability

The axes

Three independent numbers describe how big an MDK deployment is:

• Devices per Worker instance: how many devices one running Worker manages. Bounded by the device protocol and the Worker's own connection model, not by Kernel.
• Worker instances per Kernel: how many Worker processes one Kernel coordinates. Kernel places no hard cap; the practical limit is how much command/telemetry traffic one Kernel process can route.
• Kernels per Gateway: today, one. startGateway() connects to exactly one Kernel (kernelKey is a single value), and mdk.yaml declares exactly one Kernel per stack — see what's roadmap, below.

This page is about how many Workers and Kernels a deployment runs, not how those processes are packaged on a host (one process versus many machines). That's a deployment topology choice, made independently of the numbers on this page.

Single-kernel versus multi-kernel

The one topology distinction this page owns: does your deployment run one Kernel serving a site, or several independent Kernels, each serving its own site?

• One Kernel is the default and the right choice until you have a concrete reason to split: a single Kernel process routes commands and telemetry for every Worker registered to it, with no per-Worker partitioning. Each Kernel is paired with its own Gateway (startGateway() connects to exactly one Kernel; mdk.yaml declares exactly one).
• Several Kernels, one per physical site (for example, a Texas site and an Iceland site), is the shape for multi-site operations. Each Kernel is fully isolated: Kernel instances do not federate registries, share queues, or synchronize state with each other, and each runs behind its own Gateway. A crash at one site has zero effect on any other.

When to add a Kernel

Add a second Kernel when you're adding a second physically- or organizationally-distinct site, not to work around a single site's device count. This is a design expectation, not a measured result: no benchmark numbers exist yet for where a single Kernel's routing throughput actually limits out (see the benchmark table below, still pending). What's certain independent of any benchmark: splitting Kernels for a single site forfeits the single registry that makes routing simple, in exchange for isolation that site doesn't need.

What serializing Workers and Kernels means

Workers never share devices: device-to-Worker ownership is a strict, exclusive mapping the registry enforces, so adding Worker instances scales device count linearly with no coordination between them. Kernel routes to whichever Worker owns a deviceId; it does not load-balance a device's traffic across multiple Workers, because only one Worker is ever registered as the owner of a given device at a time.

Where state lives as you grow

See the storage model for the full picture. In short: each Kernel keeps its own separate store: a multi-Kernel deployment means multiple independent stores, not one shared or federated one.

Failure behavior

• A single Worker going offline degrades reads/writes for that Worker's devices only. Kernel continues routing to every other registered Worker normally.
• A Kernel crash is recovered from its own command write-ahead log on restart (recover() sweeps non-terminal command states); it does not need to reconstruct device state, since it never owned it.
• In a multi-Kernel deployment, one site's Kernel going down has no effect on any other site's Kernel: there is no shared state to become inconsistent.

Benchmarks pending

A real benchmark harness exists (backend/tests/benchmark/) and can measure device counts, telemetry throughput, and command latency at a given topology, but no baseline numbers are committed yet. This table reserves the shape for when they are:

Next steps

• Understand the storage model: what grows with device count, and what doesn't
• Choose a deployment topology: how processes are packaged on a host
• Understand architecture: the round trip every command and telemetry pull takes

Next steps

• Understand the storage model
• Choose a deployment topology
• Understand architecture