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.

Workload engines

Elah's current architecture is the Distributed World Engine. Its unit of ownership and placement is a cell inside one logical world.

The architecture also reserves a future Instance Fleet Engine for whole independent Minecraft servers. Its unit would be an entire instance, with no shared cell map or distributed simulation.

                    small shared substrate
          hosts, capacity, lifecycle, health,
             admission, network, observability
                   /                  \
                  /                    \
     Distributed World Engine     Instance Fleet Engine
          current focus         Future / Not Yet Implemented
                  |                      |
                cells             whole instances

Ownership epochs, ghost boundaries, cell migration, world consistency, and player or entity handoff remain specialized Distributed World Engine concepts. The shared substrate grows only when a capability improves current work on its own merits.

Instance Fleet Mode is not Fleet Integration. Fleet Integration means many isolated Elah clusters share an infrastructure pool. Instance Fleet Mode would be one future engine managing independent server processes.

Read the complete Runtime Provider design.

Read the Instance Fleet Mode reservation.