RingLoom Stack — RingLoom

RingLoom is split into a small set of runtime modules. Each module owns a clear layer of the system so broker code, service code, TCP transport, and reusable primitives do not collapse into one dependency graph.

Module map

Module	Purpose	Depends on
`ringloom_common`	Shared substrate: platform helpers, memory layouts, ring buffers, message headers/codecs, config, counters, monitoring, and testable low-level utilities.	no internal modules
`ringloom_tcp`	Broker-to-broker TCP transport: platform I/O engines, connection lifecycle, handshakes, and framed message parsing.	`ringloom_common`
`ringloom_service`	Service-side runtime: `RingLoomEngine`, control agent, message consumer, service clients, discovery, load balancing, and flow-control checks.	`ringloom_common`
`ringloom_broker`	Broker runtime: control loop, sender loop, receiver loop, cluster management, routing, and application bootstrap.	`ringloom_common`, `ringloom_tcp`
`ringloom_testing`	Process harnesses and helpers for end-to-end and performance tests.	`ringloom_common`

The dependency rule is intentional: services do not import broker internals, and the broker does not import application service helpers. They communicate through shared metadata files, ring buffers, and protocol definitions from ringloom_common.

Runtime process model

A typical host runs one broker process and one or more service processes:

service process ── shared memory ── local broker ── TCP ── remote broker ── shared memory ── service process

The broker owns cross-node traffic and cluster state. Services own application handlers and service-specific metadata. Both sides map shared-memory files under the configured storage path and group.

Package boundaries

`ringloom_common`

Common code is the only layer that both broker and service runtimes share directly. It contains:

metadata file layout definitions;
MPSC ring-buffer implementation;
protocol headers for application messages and TCP frames;
control-message codecs;
counters, error logs, and monitoring helpers;
config loading and validation;
platform abstractions for clocks, sleeps, threads, atomics, memory mapping, and process utilities.

`ringloom_service`

The service module is what application services import. It starts a service, registers it with the broker, starts control and message agents, tracks discovered targets, and sends application messages through ServiceClient.

`ringloom_broker`

The broker module is the runtime behind ringloom-broker. It creates broker metadata, initializes event loops, drives service registration/discovery, manages peers, sends and receives TCP frames, and updates operational counters.

`ringloom_tcp`

The TCP module is deliberately separate from the broker. It owns the low-level socket and I/O backend mechanics so the broker can treat TCP as a framed transport.

Build outputs

Common build targets include:

zig build test
zig build e2e
zig build perf
zig build run -- --config path/to/broker.properties
zig build stat
zig build observability
zig build service-c
zig build test-java
zig build test-cpp
zig build test-node

Installed artifacts include the broker executable, monitoring tools, service C ABI library/header, test service binaries, and sample application binaries.

How to navigate this section

Broker explains the broker process, control plane, routing loops, and lifecycle.
Service Runtime explains how services start, discover targets, receive messages, and send through local or remote paths.
TCP Transport explains broker-to-broker framed TCP and platform I/O backends.
Language Bindings explains the C ABI and higher-level Java, C++, and Node.js integrations.

stack Broker

The RingLoom broker control loop, sender loop, receiver loop, and routing engine.

stack Service Runtime

Shared-memory service integration and local broker communication.

stack TCP Transport

Broker-to-broker framed TCP transport with platform-specific I/O engines.

stack Language Bindings

C ABI, Java, Node, and C++ integration surface for RingLoom services.