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.
NetworkManager actor wrapping the composed libp2p behaviour stack (gossipsub, Kademlia, mDNS, relay, rendezvous, hole-punching, streams). Moves opaque bytes only.
crates/runtime
Wasmer + Cranelift WASM execution engine. Builds a VMLogic per call, runs the exported method, and returns an Outcome (return value, logs, events, storage delta). 50+ host functions.
crates/store
Column-family key-value abstraction over RocksDB via the Database trait; typed keys with compile-time size/column guarantees.
crates/store/impl/rocksdb
The RocksDB-backed implementation of the Database trait.
crates/store/blobs
Blob store (calimero-blobstore) for large binary artifacts.
crates/store/encryption
Optional transparent AES-GCM encryption of values at rest.
crates/storage (+ storage-macros)
CRDT storage collections and the derive macros that wire app state into the storage subtree.
crates/search
Node-local full-text search. The context manager stages a dirty row with each committed write of an app that exports __calimero_search_extract; a background indexer turns rows into tantivy commits in the SearchIndex column and rebuilds when state moved without one; the runtime’s search_query host function reads it from views. Derived data: never synced, never in the root hash.
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.
