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

> Explore denoland/celld main directories and functions. Understand the architecture of this distributed systems codebase organized into core Rust crates logic celld and ltx.

- Repository: [Deno/celld](https://github.com/denoland/celld)
- Tags: architecture
- Published: 2026-09-05

---

**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`](https://github.com/denoland/celld/blob/main/cell.rs) | Cell lifecycle management—creation, suspension, resumption, and destruction of durable object instances |
| [`routing.rs`](https://github.com/denoland/celld/blob/main/routing.rs) | Peer discovery and request routing—determines which node in the fleet owns a given cell |
| [`queue.rs`](https://github.com/denoland/celld/blob/main/queue.rs) | Queue broker for async message passing between cells |
| [`pressure.rs`](https://github.com/denoland/celld/blob/main/pressure.rs) | Back-pressure handling and load shedding when nodes are overloaded |
| [`log_tier.rs`](https://github.com/denoland/celld/blob/main/log_tier.rs) | Log tiering strategies for efficient replication |
| [`sqlite.rs`](https://github.com/denoland/celld/blob/main/sqlite.rs) | Persistence logic for SQLite-backed cell state |
| [`schedule.rs`](https://github.com/denoland/celld/blob/main/schedule.rs) | Scheduling decisions for cell placement and migration |

The [`crates/logic/lib.rs`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/main.rs)** — Parses CLI flags via `clap` and dispatches to subcommands (`dev`, `deploy`, `run`)
- **[`runtime.rs`](https://github.com/denoland/celld/blob/main/runtime.rs)** — Node bootstrap: initializes the listener stack, loads deployment manifests, joins the peer fleet
- **[`protocol.rs`](https://github.com/denoland/celld/blob/main/protocol.rs)** — Peer-to-peer wire protocol for handshake, gossip, and replication streaming
- **[`peer_auth.rs`](https://github.com/denoland/celld/blob/main/peer_auth.rs)** — mTLS authentication between nodes in the same fleet
- **[`cli_options.rs`](https://github.com/denoland/celld/blob/main/cli_options.rs)** — Flag definitions for all `celld` commands
- **[`storage.rs`](https://github.com/denoland/celld/blob/main/storage.rs)** — Bucket abstraction over S3-compatible object stores
- **[`deploy.rs`](https://github.com/denoland/celld/blob/main/deploy.rs)** — Implementation of `celld deploy`: packages Workers and writes manifests
- **[`dev.rs`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/README.md) — System overview and quickstart
- [`guarantees.md`](https://github.com/denoland/celld/blob/main/guarantees.md) — Consistency, availability, and durability promises
- [`cloudflare-compat.md`](https://github.com/denoland/celld/blob/main/cloudflare-compat.md) — Mapping between Cloudflare Workers APIs and celld implementations
- [`telemetry.md`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/.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`](https://github.com/denoland/celld/blob/main/Cargo.toml) and `Cargo.lock`

The root [`Cargo.toml`](https://github.com/denoland/celld/blob/main/Cargo.toml) defines a Cargo workspace unifying the three crates:

```toml
[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:**

```bash

# 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:**

```bash

# Protocol message definitions

cat crates/celld/protocol.rs

# Authentication handshake

cat crates/celld/peer_auth.rs

```

**To modify durable storage format:**

```bash

# 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`](https://github.com/denoland/celld/blob/main/storage.rs) module in `crates/celld` provides the runtime's interface to buckets, while [`ltx.rs`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/crates/celld/cli_options.rs), implement the command handler in a new file (e.g., [`crates/celld/mycommand.rs`](https://github.com/denoland/celld/blob/main/crates/celld/mycommand.rs)), and wire it into the dispatch logic in [`crates/celld/main.rs`](https://github.com/denoland/celld/blob/main/crates/celld/main.rs). Follow the pattern established by [`dev.rs`](https://github.com/denoland/celld/blob/main/dev.rs) and [`deploy.rs`](https://github.com/denoland/celld/blob/main/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`](https://github.com/denoland/celld/blob/main/wrangler.toml) and can run locally with `celld dev` before deploying to production infrastructure.