Architecture

The mental model

VOLT is organized in three layers:

the workspace layer is the application the team interacts with,
the runtime layer is the daemon running on connected machines,
and the native/tooling layer is the C++ and SDK ecosystem powering parsing, analysis, 3D export, and automation.

This separation enables coordinated operations across distributed infrastructure while keeping data and execution local to team-controlled machines.

At the top is the main VOLT application: a React client and an Express-based server. This layer handles the things you would expect from a team workspace: authentication, team state, permissions, conversations, routes, APIs, and the real-time event flow the UI depends on.

It is also where domain modules such as trajectories, analysis, containers, scripting, LaTeX, chat, notifications, and AI are coordinated.

This layer coordinates operations but does not store simulation data permanently.

The cluster daemon layer

ClusterDaemon is the runtime that executes operations on cluster infrastructure.

It connects outward to VOLT over a reverse control channel, so the cluster does not need to expose inbound HTTP services. Once connected, it can:

receive analysis requests,
maintain heartbeats and metrics,
orchestrate job queues,
parse and preprocess trajectories,
generate GLB models and preview rasters,
create Jupyter runtimes,
manage remote-access bridges,
import trajectories over SSH,
and coordinate artifacts and exports.

The server coordinates operations; the daemon executes them on cluster infrastructure.

Data flow for analysis

The daemon transforms plugin output into MessagePack data, listings, exports, and 3D artifacts for the viewer.

Data flow for trajectories

Trajectory handling follows the same layered pattern. The full processing pipeline is documented in Trajectories.

Workflow runtime versus plugin binaries

In VOLT, a plugin is a node-based workflow with arguments, context, iteration, exposures, and exports. The runtime resolves that workflow into one or more binary or Python execution steps. The workflow engine handles the structural logic around context, forEach, arguments, and branching nodes. The job runtime turns the plan into frame-level work: it downloads inputs, resolves the plugin payload, executes it, and processes the resulting artifacts. See Plugin System for node-level details.

Native tooling and open-source layers

Several capabilities are powered by the open-source ecosystem around VOLT.

Tool	Role in the Runtime
CoreToolkit	Shared C++ foundation used by the scientific plugin binaries
LammpsIO	Native parsing of LAMMPS-oriented data
SpatialAssembler	Conversion of structured output into GLB geometry
HeadlessRasterizer	Rendering of GLB assets into PNG previews
VoltSDK	Programmatic access for external automation and notebooks

Documentation covers both the application and the native tooling ecosystem.

Networking and operational shape

Connection	Direction	Why It Exists
Client to Server	HTTPS and WSS	UI, auth, APIs, and live updates
Server to Daemon	Reverse control over WebSocket	Job dispatch, remote operations, cluster lifecycle
Daemon to MinIO	HTTP(S)	Artifact and dump upload/download
Daemon to MongoDB	TCP	Metadata and listings
Daemon to Redis	TCP	Queues, state, and caching
Daemon to Docker	Unix socket	Containers and Jupyter runtimes

The reverse channel between the server and the daemon eliminates the need to open inbound ports on the cluster.

Bootstrap plane vs control plane

The cluster lifecycle has two phases:

The bootstrap plane installs and enrolls the cluster.
The control plane keeps it operational after enrollment.

Bootstrap covers install material generation, environment and compose file writing, local service startup, and initial daemon announcement. The control plane handles heartbeats, reverse-channel commands, job dispatch, remote access, notebook sessions, exposure registry updates, and lifecycle events through the daemon connection.

A cluster can fail in one phase but not the other: a machine may install correctly yet never become a healthy control-plane participant, or it may bootstrap once and later disconnect.

Daemon startup order

ClusterDaemon starts in this sequence:

load configuration,
create the local platform module,
create runtime modules such as metrics, trajectory-native, workflow, Jupyter, SSH import, job runtime, cloud control, and artifacts,
connect local dependencies first,
start memory monitoring,
connect to VoltCloud,
start the exposure registry,
start the workers for analysis, GLB generation, rasterization, and SSH import.

If MongoDB, Redis, MinIO, or Docker are unavailable locally, the daemon fails before the cloud side sees a meaningful runtime.

Memory-aware runtime behavior

The daemon launcher calculates heap size from available memory and enables manual garbage collection. The runtime monitors memory pressure and may delay or requeue jobs under stress, instead of continuing to dispatch work onto an unhealthy process. A delayed job is not necessarily a queue bug — it can be the daemon backing off.

Exposure registry and service discovery

The exposure registry inspects managed containers, reads their labels, determines which services should be reachable through VOLT, and periodically publishes snapshots back to the server. This drives proxied HTTP services, notebook targets, and remote-desktop flows without manual endpoint registration.

Shutdown behavior

On shutdown the daemon stops memory monitoring, winds down debug and worker activity, stops exposure sync, disconnects the cloud channel, closes queue state, and releases its local dependencies. A clean stop looks different from a crash in the logs.

Failure checklist

When VOLT misbehaves, check:

cluster connection state,
local platform dependency health,
daemon memory pressure,
worker process state,
and reverse channel liveness.