This page orients you in the workspace: first the actor model that drives a
running node, then the crate map grouped by layer. For the protocol-level
model (the signed-op DAG and the deterministic fold) see the
Protocol Reference.
A running node is organized as a small set of Actix actors that talk to each
other through typed messages, plus a couple of long-lived async tasks. The
actors never reach into each other’s state directly — they exchange messages and
go through thin client façades (NodeClient, ContextClient,
NetworkClient) that wrap message recipients.
Actor / task
Crate
Role
NodeManager
crates/node
Central orchestrator. Receives network events, routes incoming state deltas to contexts, handles blob caching (multi-phase LRU), heartbeats, and key delivery. Handles NodeMessage.
ContextManager
crates/context
Manages contexts (application instances), groups (governance units), and per-namespace governance DAGs. 30+ message handlers covering execution, governance, membership, and upgrades. Handles ContextMessage.
NetworkManager
crates/network
Owns and drives the libp2p Swarm. Publishes/subscribes gossipsub topics, runs the Kademlia DHT, mDNS, relay, and request/response streams. Handles NetworkMessage.
SyncManager
crates/node
Not an actor — a long-lived async task spawned at startup. Runs periodic and on-demand sync cycles, selecting a sync protocol from handshake-negotiated divergence metrics.
GarbageCollector
crates/node
Background actor that cleans up storage tombstones.
How they talk, end to end:
External clients hit the Server layer (crates/server) over REST /
JSON-RPC / WebSocket / SSE. The server holds no business logic — it delegates
to ContextClient and NodeClient.
NodeManager routes work: an execution request goes to ContextManager,
which runs a WASM method on the runtime (crates/runtime) and produces a
state delta.
Deltas are recorded in the causal DAG (crates/dag), persisted through
the storage layer (crates/store + crates/storage), and broadcast to
peers via NetworkManager.
Inbound network events flow the other way: NetworkManager → NodeManager →
the right context, where deltas are applied and convergence is reconciled by
SyncManager.
The workspace layers from external surfaces at the top down to shared primitives
at the bottom. Binaries depend on the server and node crates, which fan out
through the core libraries, all converging on primitives.
Single Axum HTTP server mounting all public surfaces: Admin REST API, JSON-RPC 2.0, WebSocket, SSE, Prometheus metrics, and the embedded admin dashboard SPA.
crates/auth (mero-auth)
Forward-auth service: JWT issuing/verification, pluggable providers (user_password is the only shipped provider). Runs embedded in the server or behind a reverse proxy.
crates/client
Trait-based client library for talking to Calimero APIs (auth, storage abstractions) — used by tooling and integrations.
Pure causal DAG for delta tracking with automatic dependency resolution — no network or storage deps. Orders state changes correctly even when messages arrive out of order.
crates/governance-types
Signed group-operation types for local (no-chain) group governance.
crates/governance-store
Apply pipeline, broadcast/ack flow, metrics, and notifications for the local group-governance domain (extracted from calimero-context).
crates/op
The unified Op envelope for the causal log — one operation type for data writes, writer-set rotation, membership, and policy changes.
crates/projection
ScopeState — the single deterministic projection (materializer) of a scope’s op-log into values plus a root hash.
crates/authz
The single authorization fold over the op-log: authorize is one match over the op payload against an ACL view resolved at the op’s causal cut.
