Architecture

Full-stack architecture of Weave — identity, Strand, primitives, SDK, applications.

What this page covers

Weave is a layered system. This page walks the stack from identity at the bottom to applications at the top, and explains why each layer exists and where the boundaries are.

Layer responsibilities

Identity & crypto

weave-identity defines the adapter trait. The reference implementation is weave-identity-ed25519. Identities are DIDs; resolution is pluggable.
weave-crypto provides the cryptographic primitives: Ed25519 for signing, BLAKE3 for hashing, X25519 for key exchange, ChaCha20-Poly1305 for stream encryption.

Why this is a layer. Every operation that mutates persistent state is signed. Every block in a Strand has an authorial DID. Every fetched chunk in Weft is verified against a BLAKE3 id. Keeping identity at the bottom of the stack makes it impossible to skip.

Network

weave-dht is a libp2p Kademlia DHT. It uses α = 3 parallel queries per lookup and a 256-bit XOR distance metric over peer ids.
weave-swarm is the connection manager — peer discovery, NAT traversal, topic subscription.
zer0-secret-stream runs the Noise IK handshake and frames application bytes.
Filament is the lower transport (TCP, QUIC, in-process) under the swarm.

Why this is a layer. Each primitive should be able to ship without owning a transport. The network layer is a single dependency at well-defined trait boundaries (DhtKv, ChunkSource, etc.).

Primitives

The primitives are the data and coordination models. Each one is independently usable; the SDK is a convenience.

Primitive	Data model
Strand	Append-only log, signed blocks, Merkle proofs
Lens	B-tree KV
Locus	Distributed filesystem
Nexus	Multi-writer materialized views over Strands
Strand Blobs	Content-addressed binary store
Basis	HNSW vector index
Forum	Linda tuple space
Gnosis	RDF-style knowledge graph
Weft	BLAKE3 Merkle-tree distribution
WOVEN	Signed event log (publish/subscribe)

Why this is a layer. Primitives compose. The tutorials build apps by combining 3–4 of them; Basis on top of Strand on top of Locus is a recommendation system. The boundary between primitives is the Strand: most primitives are an index plus a Strand.

SDK

weave-sdk::WeaveNode is the single object an application talks to. It owns the storage directory, the identity, the network manager, and the per-primitive stores (StrandStore, LensStore, LocusStore, ...).

Why this is a layer. Two reasons:

A single point of configuration and identity binding.
A safe place to manage cross-primitive concerns: replication, peer discovery, lifecycle.

Applications never construct primitives directly in production; they go through the SDK.

Applications

Anything that uses WeaveNode: dBrowser, Loom, the dCLI, your own agent.

Boundary at each layer

Boundary	Trait / type
Application → SDK	`WeaveNode`, `WeaveNodeBuilder`
SDK → Primitive	Direct typed calls (e.g. `Strand::append`, `Basis::add`)
Primitive → Network	`DhtKv`, `ChunkSource`, `ReplicationStream`, `DiscoveryPublisher`
Network → Crypto	`weave_crypto::KeyPair`, `Hash`, signatures
Primitive → Identity	`WeaveIdentityAdapter`

Each boundary is a small, stable trait. Implementations can be swapped without rewriting the layer above.

Data flow: a write

   Application calls node.append("log", b"hello")
        │
        ▼
   WeaveNode::append routes to StrandStore
        │
        ▼
   StrandStore::get_mut("log") returns &mut Strand
        │
        ▼
   Strand::append signs the block, appends to storage, updates Merkle root
        │
        ▼
   If replication is on: ReplicationManager announces the new block
        │
        ▼
   weave-swarm fans out to peers; zer0-secret-stream encrypts
        │
        ▼
   Peer receives, verifies signature, appends to its replica strand

Data flow: a read

   Application calls node.read_block("log", 42)
        │
        ▼
   WeaveNode::read_block routes to StrandStore
        │
        ▼
   StrandStore::get("log") returns &Strand
        │
        ▼
   Strand::get(42) reads from FileStorage (or MemoryStorage)
        │
        ▼
   Returns raw block bytes

Reads are local. There is no fan-out, no consensus. A peer either has the block or doesn't.

Note

The boundary between primitives is the Strand. Most primitives (Lens, Locus, Nexus, Forum, Gnosis, Basis) are an index plus a Strand. If you understand Strand, everything else is a projection.

What Weave is not

Not	Reason
A blockchain	No global consensus; Strands are per-writer total-ordered
A database	No transactions across primitives
A CDN	Weft can act as one over a DHT, but there is no edge cache layer
A messaging system	WOVEN is publish/subscribe; for direct messaging use zer0-secret-stream

Tip

When a workload needs global consensus — staking, settlement, named registries, anchoring artifacts to a single canonical timeline — the chain side of the stack lives in Sigil. Weave carries the bytes; Sigil commits the hashes.

Where to next

Threat Model — what an attacker can and cannot do
Failure Modes — per-primitive crash, partition, and recovery behavior
Weave SDK — the entry point for applications