System architecture

System architecture

Elah's intended architecture separates gameplay from coordination.

Minecraft client
       |
       v
Velocity proxy and Sling
       |
       v
ElahFolia workers
       ^
       |
     elahd

This is a future runtime target. The current release does not provide Sling or ElahFolia.

Planned components

Component	Responsibility
elahd	Control-plane membership, topology, future cell ownership, and ownership epochs.
elah	Administrator command-line interface, including Observer.
ElahFolia	Thin Folia integration for Minecraft worker processes.
Sling	Velocity integration for routing, backend switching, handoff retries, and handoff visibility.
Shepherd	Future placement and workload scheduler inside elahd.
Stone	Future persistent world-storage service.
Brook	Future generation and pregeneration service.

Infrastructure boundary

The guiding rule is:

Generic infrastructure manages machines. Elah manages Minecraft.

Shepherd will eventually decide what Minecraft needs. A Runtime Provider will translate that decision into a native process, Docker container, or authenticated request to an external infrastructure system.

Minecraft state
      |
      v
   Shepherd
      |
      v
Runtime Provider
  /    |    \
Native Docker External

The provider can report capacity and manage worker lifecycle. It cannot assign a cell, advance an ownership epoch, move a player, split a cell, or write authoritative world state.

Planned provider order is Native, Docker, then External integrations. Kubernetes, hosting panels, cloud systems, and custom provisioners remain optional adapters underneath Elah.

Horizontal and vertical work

Folia is planned to handle vertical concurrency inside one worker process. Elah is planned to handle horizontal coordination between worker processes and machines.

Keeping those responsibilities separate avoids placing distributed coordination inside normal tick paths without evidence.

Elastic worker states

Future workers use three lifecycle states:

• COLD: no worker process exists;
• WARM: a compatible worker has joined its cluster and owns no authoritative cells;
• HOT: the worker owns and serves one or more authoritative cells.

A HOT worker cannot stop or be reclaimed until Elah proves that it owns zero cells. An uncertain drain leaves the worker allocated.

Future capacity policy distinguishes GUARANTEED, BURST, and PREEMPTIBLE capacity. Capacity class changes availability policy, not ownership strength.

Control plane

The control plane manages identities, protocol versions, worker sessions, health, topology, and future ownership decisions. It must not carry normal gameplay messages such as movement, block changes, inventory clicks, entity ticks, or chunk packets.

Data plane

The data plane stays on the path between the Minecraft client, Velocity, Sling, and the current worker. This keeps ordinary gameplay away from controller latency.

Ownership model

The design assigns each active (world, dimension, cell) to exactly one authoritative worker at an ownership epoch. A stale worker must be rejected. Read-only neighboring state may exist later, but it must never become a second authority.

Repository shape

The monorepo keeps Rust, Java, JavaScript, TypeScript, Protocol Buffers, schemas, and laboratories versioned together. Protocol changes can therefore be generated and tested across languages in one release gate.

Cluster and fleet scopes

One Elah cluster is one administrative and ownership domain. A hosting provider may eventually run many isolated clusters over a shared fleet through Runtime Providers.

Clusters must not share controller authority, credentials, storage namespaces, networks, metrics, or ownership state. Customer accounts, billing, and generic fleet management remain outside Elah.

Read the complete Runtime Provider design.