Architecture Overview¶

Calimero's architecture consists of four main layers that work together to enable distributed, peer-to-peer applications with automatic conflict-free synchronization.

Four-Layer Architecture¶

flowchart LR
    APP[Application<br/>WASM apps & SDK] --> NODE[Node<br/>Sync & execution]
    NODE --> STORAGE[Storage<br/>CRDT & DAG]
    STORAGE --> NETWORK[Network<br/>P2P & APIs]
    NETWORK -.-> NODE

    style APP fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style NODE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff

Transaction Flow¶

Transaction Flow:

flowchart LR
    CLIENT[Client<br/>RPC call] --> NODE[Node<br/>Execute]
    NODE --> WASM[WASM<br/>Process]
    WASM --> STORAGE[Storage<br/>CRDT ops]
    STORAGE --> NODE
    NODE --> NETWORK[Network<br/>Broadcast]
    NETWORK --> PEER[Peer<br/>~100ms]
    NODE --> CLIENT

    style CLIENT fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style NODE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style WASM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style PEER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff

See core/crates/runtime/README.md for execution details.

Synchronization Flow¶

Calimero uses a dual-path synchronization strategy:

Path 1: Gossipsub Broadcast (Primary)¶

Fast real-time propagation (~100-200ms):

flowchart LR
    TXN[Execute] --> DELTA[Create Delta]
    DELTA --> GOSSIP[Gossipsub]
    GOSSIP --> RECEIVE[Peers receive]
    RECEIVE --> READY{Ready?}
    READY -->|Yes| APPLY[Apply]
    READY -->|No| BUFFER[Buffer]
    APPLY --> EVENTS[Events]

    style TXN fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style DELTA fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style GOSSIP fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style RECEIVE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style READY fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style APPLY fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff
    style EVENTS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style BUFFER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff

Path 2: Periodic P2P Sync (Fallback)¶

Catch-up every 10-30 seconds:

flowchart LR
    TIMER[Timer] --> PEER[Select Peer]
    PEER --> STREAM[Open Stream]
    STREAM --> HEADS[Exchange Heads]
    HEADS --> DIFF{Differ?}
    DIFF -->|Yes| REQUEST[Request Deltas]
    DIFF -->|No| SYNC[Synced]
    REQUEST --> APPLY2[Apply]
    APPLY2 --> SYNC

    style TIMER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style PEER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style STREAM fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style HEADS fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style DIFF fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style REQUEST fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style APPLY2 fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style SYNC fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff

Why both paths? - Gossipsub: Fast (~100-200ms), reliable in good network conditions - Periodic sync: Ensures eventual consistency even with packet loss, partitions, or downtime

See core/crates/node/README.md for sync configuration details.

DAG-Based Causal Ordering¶

The DAG ensures deltas are applied in correct causal order:

flowchart LR
    ROOT[Root] --> A[Delta A]
    ROOT --> B[Delta B]
    A --> MERGE[Merge]
    B --> MERGE

    style ROOT fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff
    style A fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style B fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style MERGE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff

Key properties: - Deltas can arrive in any order - System buffers deltas until their parent dependencies are ready - Once parents are available, deltas are applied automatically in causal order - Concurrent updates create forks that merge automatically

Key Components¶

flowchart LR
    SERVER[Server] --> NODE[Node]
    NODE --> RUNTIME[Runtime]
    NODE --> NETWORK[Network]
    SDK[SDK] --> RUNTIME
    RUNTIME --> STORAGE[Storage]
    STORAGE --> DAG[DAG]

    style SDK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style RUNTIME fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style STORAGE fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style DAG fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style NODE fill:#000000,stroke:#00ff00,stroke-width:4px,color:#ffffff
    style NETWORK fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff
    style SERVER fill:#1a1a1a,stroke:#00ff00,stroke-width:3px,color:#ffffff

Component	Purpose	Repository
SDK	`#[app::state]`, `#[app::logic]`, CRDT collections, events	`core/crates/sdk`
Runtime	WASM execution (Wasmer), sandboxing	`core/crates/runtime`
Storage	CRDT collections, merge semantics	`core/crates/storage`
DAG	Causal delta tracking, dependency resolution	`core/crates/dag`
Node	NodeManager orchestrates sync, events, blobs	`core/crates/node`
Network	libp2p P2P (Gossipsub, streams, DHT)	`core/crates/network`
Server	JSON-RPC API, WebSocket/SSE	`core/crates/server`
merod	Node binary (coordinator/peer)	`core/crates/merod`
meroctl	CLI for node operations	`core/crates/meroctl`

See core/README.md for complete architecture.

Component Details¶

For detailed information on each component, see their README files:

SDK: core/crates/sdk/README.md - Macros, CRDTs, events
Runtime: core/crates/runtime/README.md - WASM execution, sandboxing
Storage: core/crates/storage/README.md - CRDT collections, merging
DAG: core/crates/dag/README.md - Causal ordering, dependency resolution
Node: core/crates/node/README.md - NodeManager, sync, events
Network: core/crates/network/README.md - libp2p, Gossipsub, P2P
Server: core/crates/server/README.md - JSON-RPC, WebSocket, SSE

Deep Dives¶

For detailed architecture information:

DAG Logic: core/crates/dag/README.md - Causal ordering algorithms
Node Architecture: core/crates/node/readme/architecture.md - Complete system design
Sync Protocol: core/crates/node/readme/sync-protocol.md - Delta propagation details
Storage: core/crates/storage/README.md - CRDT types and merge semantics
Network: core/crates/network/README.md - P2P protocols and configuration

Next: Learn about specific concepts: Contexts | Identity | Applications | Nodes