# clockworklabs/spacetimedb architecture

> Architecture diagram of the GitHub repository clockworklabs/spacetimedb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clockworklabs/spacetimedb
- Repository: https://github.com/clockworklabs/spacetimedb

## Overview

SpacetimeDB combines a relational database with an application runtime: developers define and upload modules, and clients connect directly to invoke logic and receive live table changes. The graph preserves the documented module lifecycle, transactional data path, subscriptions, durable storage, and client SDK surface. Source excerpts are limited, so internal links are shown only where the README or indexed source references support them; unsampled subsystem connections are omitted.

Main entry points: [`crates/core/src/subscription/module_subscription_manager.rs`](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/subscription/module_subscription_manager.rs) (Subscription manager), [`crates/bindings-typescript/src/server`](https://github.com/clockworklabs/spacetimedb/tree/master/crates/bindings-typescript/src/server) (Application module), [`crates/bindings-typescript/src/sdk/db_connection_impl.ts`](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/sdk/db_connection_impl.ts) (TypeScript SDK), [`crates/core/src/host/module_host.rs`](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/host/module_host.rs) (Module host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_module["Module authoring and runtime"]
  node_module["Application module"]
  node_compile["Module compilation<br/>[lib.rs]"]
  node_host["Module host<br/>[module_host.rs]"]
  node_execution["Transaction execution<br/>[pipelined.rs]"]
  node_cli["SpacetimeDB CLI<br/>[main.rs]"]
end

subgraph group_database["Database and synchronization"]
  node_relational[("Relational database<br/>[engine.rs]")]
  node_storage[("Durable storage<br/>[disk_storage.rs]")]
  node_subscriptions["Subscription manager"]
  node_client_runtime["Client connections"]
  node_messages["Client messages<br/>[messages.rs]"]
end

subgraph group_clients["Client SDKs"]
  node_ts_sdk["TypeScript SDK"]
  node_ts_schema["Schema and query types<br/>[schema.ts]"]
  node_ts_cache[("Client data cache<br/>[client_cache.ts]")]
  node_cpp_sdk["C++ bindings<br/>[table.h]"]
  node_csharp_sdk["C&#35; runtime bindings<br/>[AuthCtx.cs]"]
end

subgraph group_identity["Identity and access"]
  node_rust_auth["Rust identity and tokens<br/>[identity.rs]"]
end

node_developer(("Module developer"))
node_client(("Connected application client"))

node_developer -->|"defines"| node_module
node_module -->|"compiles"| node_compile
node_compile -->|"runs module"| node_host
node_client -->|"connects directly"| node_client_runtime
node_client -->|"calls reducers"| node_host
node_client -->|"subscribes tables"| node_subscriptions
node_subscriptions -->|"references messages"| node_messages
node_subscriptions -->|"references clients"| node_client_runtime
node_subscriptions -->|"references host"| node_host
node_relational -.->|"persists durably"| node_storage
node_relational -->|"provides committed changes"| node_subscriptions
node_subscriptions -->|"pushes updates"| node_client
node_client -->|"uses"| node_ts_sdk
node_client -->|"uses"| node_cpp_sdk
node_client -->|"uses"| node_csharp_sdk
node_ts_sdk -.->|"maintains cache"| node_ts_cache
node_ts_sdk -.->|"uses schema"| node_ts_schema
node_developer -->|"operates"| node_cli
node_module -->|"defines authorization"| node_rust_auth

click node_module "https://github.com/clockworklabs/spacetimedb/tree/master/crates/bindings-typescript/src/server"
click node_compile "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-macro/src/lib.rs"
click node_host "https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/host/module_host.rs"
click node_execution "https://github.com/clockworklabs/spacetimedb/blob/master/crates/execution/src/pipelined.rs"
click node_cli "https://github.com/clockworklabs/spacetimedb/blob/master/crates/cli/src/main.rs"
click node_relational "https://github.com/clockworklabs/spacetimedb/blob/master/crates/dst/src/engine.rs"
click node_storage "https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/host/disk_storage.rs"
click node_subscriptions "https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/subscription/module_subscription_manager.rs"
click node_client_runtime "https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/client/client_connection.rs"
click node_messages "https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/client/messages.rs"
click node_ts_sdk "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/sdk/db_connection_impl.ts"
click node_ts_schema "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/lib/schema.ts"
click node_ts_cache "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/sdk/client_cache.ts"
click node_cpp_sdk "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-cpp/include/spacetimedb/table.h"
click node_csharp_sdk "https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-csharp/Runtime/AuthCtx.cs"
click node_rust_auth "https://github.com/clockworklabs/spacetimedb/blob/master/crates/auth/src/identity.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_module,node_compile,node_host,node_execution,node_cli,node_client toneBlue
class node_relational,node_storage,node_subscriptions,node_client_runtime,node_messages toneAmber
class node_ts_sdk,node_ts_schema,node_ts_cache,node_cpp_sdk,node_csharp_sdk toneMint
class node_rust_auth toneRose
class node_developer toneIndigo
```

## Components

### Module authoring and runtime

- [Application module](https://github.com/clockworklabs/spacetimedb/tree/master/crates/bindings-typescript/src/server): `crates/bindings-typescript/src/server`
- [Module compilation](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-macro/src/lib.rs): `crates/bindings-macro/src/lib.rs`
- [Module host](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/host/module_host.rs): `crates/core/src/host/module_host.rs`
- [Transaction execution](https://github.com/clockworklabs/spacetimedb/blob/master/crates/execution/src/pipelined.rs): `crates/execution/src/pipelined.rs`
- [SpacetimeDB CLI](https://github.com/clockworklabs/spacetimedb/blob/master/crates/cli/src/main.rs): `crates/cli/src/main.rs`

### Database and synchronization

- [Relational database](https://github.com/clockworklabs/spacetimedb/blob/master/crates/dst/src/engine.rs): `crates/dst/src/engine.rs`
- [Durable storage](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/host/disk_storage.rs): `crates/core/src/host/disk_storage.rs`
- [Subscription manager](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/subscription/module_subscription_manager.rs): `crates/core/src/subscription/module_subscription_manager.rs`
- [Client connections](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/client/client_connection.rs): `crates/core/src/client/client_connection.rs`
- [Client messages](https://github.com/clockworklabs/spacetimedb/blob/master/crates/core/src/client/messages.rs): `crates/core/src/client/messages.rs`

### Client SDKs

- [TypeScript SDK](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/sdk/db_connection_impl.ts): `crates/bindings-typescript/src/sdk/db_connection_impl.ts`
- [Schema and query types](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/lib/schema.ts): `crates/bindings-typescript/src/lib/schema.ts`
- [Client data cache](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-typescript/src/sdk/client_cache.ts): `crates/bindings-typescript/src/sdk/client_cache.ts`
- [C++ bindings](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-cpp/include/spacetimedb/table.h): `crates/bindings-cpp/include/spacetimedb/table.h`
- [C# runtime bindings](https://github.com/clockworklabs/spacetimedb/blob/master/crates/bindings-csharp/Runtime/AuthCtx.cs): `crates/bindings-csharp/Runtime/AuthCtx.cs`

### Identity and access

- [Rust identity and tokens](https://github.com/clockworklabs/spacetimedb/blob/master/crates/auth/src/identity.rs): `crates/auth/src/identity.rs`

### Other components

- **Module developer**
- **Connected application client**

## Connections

- Module developer → Application module: defines (evidence: `README.md`)
- Application module → Module compilation: compiles (evidence: `README.md`)
- Module compilation → Module host: runs module (evidence: `README.md`)
- Connected application client → Client connections: connects directly (evidence: `README.md`)
- Connected application client → Module host: calls reducers (evidence: `README.md`)
- Connected application client → Subscription manager: subscribes tables (evidence: `README.md`)
- Subscription manager → Client messages: references messages (evidence: `crates/core/src/subscription/module_subscription_manager.rs`)
- Subscription manager → Client connections: references clients (evidence: `crates/core/src/subscription/module_subscription_manager.rs`)
- Subscription manager → Module host: references host (evidence: `crates/core/src/subscription/module_subscription_manager.rs`)
- Relational database → Durable storage: persists durably
- Relational database → Subscription manager: provides committed changes (evidence: `README.md`)
- Subscription manager → Connected application client: pushes updates (evidence: `README.md`)
- Connected application client → TypeScript SDK: uses (evidence: `README.md`)
- Connected application client → C++ bindings: uses (evidence: `README.md`)
- Connected application client → C# runtime bindings: uses (evidence: `README.md`)
- TypeScript SDK → Client data cache: maintains cache (evidence: `crates/bindings-typescript/src/sdk/db_connection_impl.ts`)
- TypeScript SDK → Schema and query types: uses schema (evidence: `crates/bindings-typescript/src/sdk/db_connection_impl.ts`)
- Module developer → SpacetimeDB CLI: operates (evidence: `README.md`)
- Application module → Rust identity and tokens: defines authorization (evidence: `README.md`)
