Architecture Orientation

This page orients you in the workspace: the two binaries, what is inside a node, and the path a call takes. The full crate list is in the crate guide; each crate’s AGENTS.md has the detail.

Two binaries over libraries

Binary	Crate	Is
merod	crates/merod	A thin command line: it turns flags, MEROD_* variables and config.toml (node_config::NodeArgs) into calimero_node::Config and calls calimero_node::run. Also local, inspect, kms disk-key and attest.
meroctl	crates/meroctl	The command line over calimero-client: every request is attested and sealed.

Everything a node does is in calimero-node (crates/node).

Inside a node

Part	Where	Does
Log engine	calimero-log	Multi-group Raft (openraft) over one sealed RocksDB per node: logs, votes, state, blobs and snapshots.
System group	node/src/system.rs (group 1)	The fleet, app directory, packages and bundle hashes, accounts, passkeys, API keys, refresh tokens, session keys, organizations, teams, invites, quotas, governance. Commands carry their actor and are authorized in apply, so the log decides. Kept in memory, checkpointed with snapshots.
App groups	node/src/app.rs	One Raft group per app instance on its replicas. State lives on disk as hidden rows of the group; only a small head is in memory.
Engine	node/component.rs over calimero-app-engine-wasmtime	Run a call’s component on the leader against the applied state and return { result, diff, events }.
Node	node/src/node.rs, membership.rs	Routing to leaders, placement, system voter promotion, reconciling hosted groups with the directory, xcalls and timers, blob replication, backups.
API	node/src/api.rs	The HTTP routes (router): /auth, /packages, /bundles, /apps, /orgs, /invites, /ops, /internal.
Sealed transport	calimero-sealed	Wraps the router from outside; opens sealed requests and routes them afresh.
Identity	calimero-identity	WebAuthn verification, session tokens, API keys, confirm challenges.
Attestation	calimero-tee-attestation, calimero-client::attest, calimero-tee-release	Quote generation, and the one verification clients and peers share.
Packages	node/src/packages.rs, calimero-bundle, calimero-app-downloader	Signed .mpk verification and registry fetches.
Outbound	calimero-outbound	The gated HTTPS client a run may use.
Search, presence, frontends	services.rs, presence.rs, app_host.rs, calimero-search	Derived in-memory search indexes, ephemeral presence, app frontends on their own origins.
Storage key	node/src/kms.rs, calimero-kms-client	K_r from mero-kms.

The path of a call

▶ Replay

• Calls are linearized per app. The leader serializes proposals, so a diff always applies to the state it was built on (base_index); one built on replaced state applies as a no-op and the call is re-run.
• Reads. A view goes to the leader (strong) or, with minIndex, to any replica that has applied that far.
• Follow-ups queued by an entry (event handlers, xcalls, timer ticks) run once, on the leader, as entries of their own.
• Bundles and blobs are not in the log: they are stored in every node’s sealed blob store (a majority before the answer) and the log records their hash. Log entries are capped at 1 MiB.
• System writes (sign-up, installs, org changes) go to the system leader the same way; authority is checked when they apply.

The app runtime

Apps are calimero:app components (the WIT world in calimero-app-wit, built with calimero-sdk and calimero-app-build); they run on wasmtime (calimero-app-engine-wasmtime) through the host core calimero-app-host. SDK 0.12 apps (core modules on wasmer) are no longer run: the node refuses their bundles, and an app a data directory still holds answers 410 UNSUPPORTED_ENGINE until its owner deletes it.

Note

This is the map, not the territory. Read crates/node/AGENTS.md for the node’s full mental model, and each crate’s src/lib.rs docs before relying on a boundary.