Main Directories and Functions in denoland/celld: A Complete Architecture Guide

The celld repository organizes its distributed systems codebase into three core Rust crates (crates/logic, crates/celld, crates/ltx), plus documentation, examples, and CI/CD workflows.

Understanding the main directories and their functions in denoland/celld is essential for anyone contributing to or deploying this distributed durable object runtime. This guide maps each top-level directory to its architectural purpose, with direct source references from the official repository.

Core Crate: crates/logic — Distributed System Engine

The crates/logic directory contains the cell scheduling, routing, persistence, and replication algorithms that make celld a distributed system. This crate is deliberately storage-agnostic—it operates purely on in-memory state machines and delegates all I/O to the runtime layer.

Key Modules in crates/logic

Module File	Responsibility
cell.rs	Cell lifecycle management—creation, suspension, resumption, and destruction of durable object instances
routing.rs	Peer discovery and request routing—determines which node in the fleet owns a given cell
queue.rs	Queue broker for async message passing between cells
pressure.rs	Back-pressure handling and load shedding when nodes are overloaded
log_tier.rs	Log tiering strategies for efficient replication
sqlite.rs	Persistence logic for SQLite-backed cell state
schedule.rs	Scheduling decisions for cell placement and migration

The crates/logic/lib.rs file serves as the crate's public API surface, re-exporting all core modules for consumers in the runtime layer.

Runtime Crate: crates/celld — Node Process and CLI

The crates/celld directory implements the executable binary, networking stack, CLI interface, and control plane. This crate glues the pure logic layer to external systems: HTTP clients, WebSockets, object storage, and peer-to-peer replication.

Entry Points and Core Files

• main.rs — Parses CLI flags via clap and dispatches to subcommands (dev, deploy, run)
• runtime.rs — Node bootstrap: initializes the listener stack, loads deployment manifests, joins the peer fleet
• protocol.rs — Peer-to-peer wire protocol for handshake, gossip, and replication streaming
• peer_auth.rs — mTLS authentication between nodes in the same fleet
• cli_options.rs — Flag definitions for all celld commands
• storage.rs — Bucket abstraction over S3-compatible object stores
• deploy.rs — Implementation of celld deploy: packages Workers and writes manifests
• dev.rs — Implementation of celld dev: local development server with hot reload

The runtime also implements the Worker listener that executes V8 isolates, providing Cloudflare-compatible Durable Objects and Workers APIs.

Storage Crate: crates/ltx — Durable Write-Ahead Log

The crates/ltx directory defines the LTX (Log Transaction) format—the durable, replicated transaction log that makes cell state survivable across node failures. Every SQLite transaction committed by a cell is captured as an LTX record.

LTX Components

Component	Purpose
ltx.rs	Core encoder/decoder for LTX records—frame format, checksums, compression
client/*	Object store clients (S3, R2, MinIO) for reading/writing LTX segments
compaction.rs	Background compaction of LTX logs to reduce storage and replay time

LTX enables eventual consistency with strong durability: cells replay their LTX stream on startup to reconstruct state, and the replication subsystem streams LTX records to peer nodes for fault tolerance.

Documentation: docs/

The docs/ directory contains human-readable architecture and operational guides:

• README.md — System overview and quickstart
• guarantees.md — Consistency, availability, and durability promises
• cloudflare-compat.md — Mapping between Cloudflare Workers APIs and celld implementations
• telemetry.md — Metrics, logging, and observability configuration

These files power the celld.dev website and serve as the authoritative reference for operators.

Examples: examples/

The examples/ directory provides ready-to-run Wrangler projects demonstrating typical use cases:

Example	Demonstrates
wsecho/	WebSocket server with Durable Object coordination
kv/	Key-value storage patterns
vectordb/	Vector search with embeddings
router/	Request routing and load balancing

Each example can be launched with celld dev for local testing, then deployed with celld deploy . to a production fleet.

CI/CD: .github/workflows/

The .github/workflows/release.yml automates:

• Cross-compilation of Rust binaries for Linux, macOS, and Windows
• Container image builds
• Signed release artifacts with SHA-256 checksums

Workspace Structure: Cargo.toml and Cargo.lock

The root Cargo.toml defines a Cargo workspace unifying the three crates:

[workspace]
members = ["crates/logic", "crates/celld", "crates/ltx"]

[[bin]]
name = "celld"
path = "crates/celld/main.rs"

This structure allows independent versioning of internal APIs while shipping a single binary artifact.

Practical: Navigating the Codebase

To understand cell scheduling logic:

# Start with the public API

cat crates/logic/lib.rs

# Trace into routing decisions

cat crates/logic/routing.rs

# See how runtime invokes logic

cat crates/celld/runtime.rs | grep -A5 "logic::"

To extend the peer protocol:

# Protocol message definitions

cat crates/celld/protocol.rs

# Authentication handshake

cat crates/celld/peer_auth.rs

To modify durable storage format:

# LTX frame layout

cat crates/ltx/src/ltx.rs

# Compaction strategy

cat crates/ltx/src/compaction.rs

Summary

• crates/logic — Pure distributed systems algorithms (cell lifecycle, routing, pressure); no I/O
• crates/celld — Runtime, CLI, networking, and control plane; the executable you run
• crates/ltx — Durable transaction log format and object store clients
• docs/ — Architecture documentation and operational guides
• examples/ — Working Wrangler projects for common patterns
• .github/workflows/ — Automated builds and releases

Frequently Asked Questions

What is the relationship between crates/logic and crates/celld?

The logic crate implements pure algorithms with no external dependencies; celld provides the "impure" runtime that connects logic to networks, disks, and V8. This separation enables testing the distributed system in isolation and swapping storage backends without changing scheduling code.

Where does celld store persistent data?

Persistent data flows through crates/ltx to S3-compatible object stores. The storage.rs module in crates/celld provides the runtime's interface to buckets, while ltx.rs handles the binary format. SQLite databases themselves are ephemeral—reconstructed from LTX on cell startup.

How do I add a new CLI subcommand to celld?

Add flag definitions to crates/celld/cli_options.rs, implement the command handler in a new file (e.g., crates/celld/mycommand.rs), and wire it into the dispatch logic in crates/celld/main.rs. Follow the pattern established by dev.rs and deploy.rs.

What examples should I start with to learn celld?

Begin with examples/wsecho/ for WebSocket and Durable Object basics, then explore examples/kv/ for stateful patterns. Each example includes a wrangler.toml and can run locally with celld dev before deploying to production infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}