Architecture at a glance
Calimero has a small number of moving parts. This page is the map; each layer ends with a link into the Core reference for the full detail. For the deeper conceptual pages, see Core Concepts.
The stack at a glance
Section titled “The stack at a glance”Applications
Section titled “Applications”You write an app in Rust using the SDK, declare your state as CRDT collections (maps, sets, counters, lists), and compile to a single WebAssembly module. The runtime executes it in a sandbox with resource limits — deterministic, so every node produces the same result from the same operations. Apps expose views (read) and mutations (write), and can emit events that clients subscribe to.
Contexts
Section titled “Contexts”A context is a running instance of an app with its own isolated, encrypted state, shared among its members. Think of it as a private network for one app and one group. Membership, access control, and upgrades are governed by signed operations that propagate to every member. A node can participate in many contexts at once.
Shared state: CRDTs over a causal DAG
Section titled “Shared state: CRDTs over a causal DAG”Every mutation becomes a signed operation with references to the operations it causally followed — forming a DAG (directed acyclic graph), not a linear chain. Operations replicate to peers; each node folds the DAG it has into state and a root hash. Because the state types are CRDTs, the fold is order-independent: peers that have seen the same operations agree, and peers that diverged reconcile when the missing operations arrive. Divergence is detected (via the root hash), never prevented by locking.
Sync: two paths
Section titled “Sync: two paths”Calimero replicates on two complementary paths:
- Broadcast — new operations gossip to context members in ~100–200ms for real-time feel.
- Catch-up sync — nodes periodically reconcile directly, so a peer that was offline or missed a broadcast still converges. This is what makes the system resilient to partitions and restarts.
Identity, encryption & the network
Section titled “Identity, encryption & the network”Identities are hierarchical keypairs — a root identity delegates per-device keys — and every operation is signed. Context state is end-to-end encrypted; keys are delivered to members and rotated on membership changes, so a removed member cannot read future state. Transport is libp2p (gossip, direct streams, peer discovery).