# SpacetimeDB Architecture Overview: Database, WASM Runtime, and Real-Time Networking

> Explore the SpacetimeDB architecture. Discover its unified database, WASM runtime, and real-time networking capabilities in one powerful binary for efficient, durable applications.

- Repository: [Clockwork Labs/SpacetimeDB](https://github.com/clockworklabs/SpacetimeDB)
- Tags: architecture
- Published: 2026-03-09

---

**SpacetimeDB is a unified relational database, WebAssembly/JavaScript runtime, and real-time networking layer packaged into a single binary that runs modules in RAM with ACID durability via an append-only commit log.**

This SpacetimeDB architecture overview examines how the `clockworklabs/SpacetimeDB` codebase combines these distinct systems into one platform. The design centers on a **Host** process that orchestrates independent database replicas, executes user logic inside sandboxed modules, and streams live updates to clients over persistent WebSocket connections.

## Core Architectural Components

### Host and HostController

The **Host** is the root server process capable of running multiple independent databases simultaneously. It owns the on-disk data directory, manages the thread pool for module execution, and hosts the metrics subsystem. The orchestration logic resides in [`crates/core/src/host/host_controller.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/core/src/host/host_controller.rs), where the `HostController` struct handles the lifecycle of hosts, replica creation, module loading, hot-swap updates, and persistence integration.

### Database (Replica)

Each logical application instance is a **Database** or **Replica** that maintains its own isolated in-memory state and persistent commit log. The implementation in [`crates/db/src/relational_db.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/db/src/relational_db.rs) provides the relational engine where all mutable table data resides in RAM for ultra-low latency access.

### Modules and Runtime Engines

Business logic is packaged as a **Module**—a WASM blob or V8 JavaScript bundle compiled from Rust, C#, TypeScript, or C++. The module representation and entry points (`__init__`, reducers, procedures) are defined in [`crates/vm/src/program.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/vm/src/program.rs).

SpacetimeDB supports two interchangeable runtime engines selected by the module’s `HostType`:

- **Wasmtime**: The WebAssembly runtime implementation located in [`crates/host/src/wasmtime.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/wasmtime.rs)
- **V8**: The JavaScript/TypeScript runtime implementation located in [`crates/host/src/v8.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/v8.rs)

### Tables, Reducers, Procedures, and Views

Within a module, developers define:

- **Tables**: SQL-style structures storing all state in RAM (documented in [`docs/versioned_docs/version-1.12.0/00100-intro/00100-getting-started/00400-key-architecture.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/docs/versioned_docs/version-1.12.0/00100-intro/00100-getting-started/00400-key-architecture.md))
- **Reducers**: RPC-style functions that mutate tables inside single ACID transactions
- **Procedures**: I/O-capable functions (e.g., HTTP requests) that manage their own transaction boundaries
- **Views**: Read-only computed data that clients can subscribe to for live updates

### Client SDKs and Identity

Language-specific **Client SDKs** (TypeScript, Rust, C#, C++) open WebSocket connections to the Host, authenticate an **Identity**, and expose generated stubs for tables, reducers, procedures, and views. The underlying API implementation is in [`crates/client-api/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/client-api/src/lib.rs).

### Commit Log and Durability

All mutations append to an on-disk **Commit Log** (`spacetimedb_commitlog`) managed by the durability layer in [`crates/durability/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/durability/src/lib.rs). On restart, the system replays this log to reconstruct the exact in-memory state, providing the speed of RAM with the durability of a write-ahead log.

### Subscription Manager

The **Subscription Manager** in [`crates/subscription/src/module_subscription_manager.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/subscription/src/module_subscription_manager.rs) tracks which clients subscribe to which tables or views and pushes incremental delta updates over WebSocket connections whenever data changes.

### Energy Metering

To protect against runaway computation, the **Energy** system in [`crates/energy/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/energy/src/lib.rs) implements a lightweight gas-like quota. Every reducer call consumes a bounded amount of Energy; the system aborts execution if the quota is exhausted.

### Scheduler

The **Scheduler** in [`crates/scheduler/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/scheduler/src/lib.rs) handles periodic or repeating reducers, enabling "tick" logic and time-based events within a replica.

## Data Flow and Lifecycle

The following sequence describes how a module becomes a live, reactive database:

1. **Publish**: The developer runs `spacetime publish <module>`; the CLI uploads the compiled WASM/JS bundle to the Host.

2. **Instantiation**: The `HostController` creates a `Host` (if not already running) and a `Replica` for the database.

3. **Module Loading**: The `ModuleHost` loads the appropriate runtime (Wasmtime or V8) and instantiates the module.

4. **Initialization**: The module’s `__init__` reducer runs to create tables and seed initial data.

5. **Client Connection**: Clients connect via the SDK, receive an `Identity`, and open a WebSocket.

6. **Transaction Execution**: Calls to reducers are serialized into a transaction, mutate in-memory tables, and append to the commit log.

7. **Live Updates**: When a table changes, the Subscription Manager pushes delta updates to all subscribed clients, including derived view updates.

8. **Recovery**: On host shutdown or crash, the commit log replays to rebuild the exact in-memory state, guaranteeing ACID semantics.

## Code Examples

### Defining Tables and Reducers in Rust

```rust
#[spacetimedb::table(name = players, public)]
pub struct Player {
    #[primary_key]
    #[auto_inc]
    id: u64,
    name: String,
    score: i32,
    user: Identity,
}

#[spacetimedb::reducer]
pub fn set_score(ctx: &spacetimedb::ReducerContext, id: u64, score: i32) {
    ctx.db.players().update(|row| row.id == id, |row| row.score = score);
}

```

*Source pattern documented in [`00100-key-architecture.md`](https://github.com/clockworklabs/SpacetimeDB/blob/main/00100-key-architecture.md) and compiled by [`crates/vm/src/program.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/vm/src/program.rs).*

### TypeScript Client Integration

```typescript
import { useTable, useReducer } from "spacetimedb/client";

function Chat() {
  const [players] = useTable(tables.player);
  const setScore = useReducer(reducers.setScore);

  const onScore = (id: bigint, pts: number) => setScore(id, pts);

  return (
    <ul>
      {players.map(p => (
        <li key={p.id.toString()}>
          {p.name} – {p.score}
          <button onClick={() => onScore(p.id, p.score + 1)}>+1</button>
        </li>
      ))}
    </ul>
  );
}

```

*Source: Generated client API in [`crates/client-api/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/client-api/src/lib.rs).*

### Manual Host Creation (Advanced)

```rust
use spacetimedb::host::HostController;
use spacetimedb::paths::server::ServerDataDir;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let data_dir = Arc::new(ServerDataDir::new("./data"));
    let controller = HostController::new(
        data_dir,
        Default::default(),          // DB config
        Default::default(),          // program storage
        Arc::new(spacetimedb::energy::NullEnergyMonitor),
        Arc::new(spacetimedb::persistence::NullProvider),
        Default::default(),          // job cores
    );

    // Host now ready to accept publish / client connections.
    // In practice the `spacetime` CLI calls the same path.
    Ok(())
}

```

*Source: Construction logic in [`crates/core/src/host/host_controller.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/core/src/host/host_controller.rs).*

## Summary

- **SpacetimeDB** merges a relational database, WASM/JavaScript runtime, and real-time networking into one binary according to the `clockworklabs/SpacetimeDB` source code.
- The **HostController** in [`crates/core/src/host/host_controller.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/core/src/host/host_controller.rs) orchestrates multiple database replicas, each maintaining in-memory state backed by the **Commit Log** in [`crates/durability/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/durability/src/lib.rs).
- Modules execute in either **Wasmtime** or **V8** runtimes, defined in [`crates/host/src/wasmtime.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/wasmtime.rs) and [`crates/host/src/v8.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/v8.rs), with logic represented in [`crates/vm/src/program.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/vm/src/program.rs).
- **Reducers** provide ACID transactions while **Views** enable reactive client subscriptions managed by the **Subscription Manager** in [`crates/subscription/src/module_subscription_manager.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/subscription/src/module_subscription_manager.rs).
- The **Energy** system in [`crates/energy/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/energy/src/lib.rs) prevents resource exhaustion by metering computation quotas per call.

## Frequently Asked Questions

### What is the difference between a Host and a Database in SpacetimeDB?

The **Host** is the top-level server process that can run many independent databases simultaneously, owning shared resources like the thread pool and data directory. A **Database** (or Replica) represents one logical application instance containing isolated in-memory tables and its own commit log. The Host manages the lifecycle of these replicas through the `HostController`, as implemented in [`crates/core/src/host/host_controller.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/core/src/host/host_controller.rs).

### How does SpacetimeDB ensure durability if all data is in RAM?

SpacetimeDB persists every mutation to an append-only **Commit Log** on disk, implemented in [`crates/durability/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/durability/src/lib.rs). When the system restarts, it replays this log to reconstruct the exact in-memory state, providing the performance benefits of RAM storage with the crash-recovery guarantees of a write-ahead log.

### What runtime environments does SpacetimeDB support for modules?

SpacetimeDB supports two interchangeable runtimes selected by the module's `HostType`: **Wasmtime** for WebAssembly modules (located in [`crates/host/src/wasmtime.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/wasmtime.rs)) and **V8** for JavaScript/TypeScript modules (located in [`crates/host/src/v8.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/host/src/v8.rs)). Both runtimes execute within the ModuleHost sandbox defined in [`crates/vm/src/program.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/vm/src/program.rs).

### How does the Energy system protect the host from infinite loops?

The **Energy** system, found in [`crates/energy/src/lib.rs`](https://github.com/clockworklabs/SpacetimeDB/blob/main/crates/energy/src/lib.rs), implements a gas-like quota that bounds the computation cost of each reducer call. The runtime decrements Energy units during execution and aborts the call if the quota is exhausted, preventing runaway modules from consuming excessive Host resources.