# aspen-cloud/triplit architecture

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

- Interactive diagram: https://gitdiagram.com/aspen-cloud/triplit
- Repository: https://github.com/aspen-cloud/triplit

## Overview

#### Purpose and primary entry points
Triplit is a TypeScript monorepo for a local-first, real-time database: clients maintain local data, execute live relational queries, optimistically mutate data offline, and synchronize authorized deltas with a server. Core public entry points are `packages/db/src/index.ts`, `packages/client/src/index.ts`, and `packages/server/src/index.ts`. Developer/project entry points are the CLI at `packages/cli/src/index.ts` and scaffolder at `packages/create-triplit-app/src/index.ts`.

#### Database kernel: data, transactions, and change propagation
`@triplit/db` is the runtime-independent database engine. It combines entity storage, transaction semantics, metadata, an outbox-oriented store, hybrid clocks, and write buffering to support concurrent writers and durable local/server implementations. Key boundaries: logical entity/query APIs versus pluggable KV storage; buffered local writes versus outbound synchronization.
- `packages/db/src/db.ts`
- `packages/db/src/db-transaction.ts`
- `packages/db/src/entity-store-with-outbox.ts`

#### Schema, authorization, and query execution
Schemas define collection shapes, relations, types, and role-based permissions. Queries are built/prepared, simplified and compiled into plans, then evaluated against the entity store; incremental view maintenance updates live results after mutations. Server-side permissions are a critical trust boundary for reads and writes.
- `packages/db/src/schema/builder.ts`
- `packages/db/src/query-planner/query-compiler.ts`
- `packages/db/src/ivm/ivm.ts`

#### Client local-first sync runtime
`TriplitClient` exposes query, subscription, fetch, and mutation APIs over a local DB. Its sync engine coordinates persisted outbox changes, connection state, remote patches, retries/rollback behavior, and subscriptions. Transport is explicitly separated into HTTP and WebSocket implementations, while storage adapters support browser, native, Node, and in-memory use.
- `packages/client/src/client/triplit-client.ts`
- `packages/client/src/sync-engine.ts`
- `packages/client/src/transport/websocket-transport.ts`

#### Sync server and protocol core
`server-core` owns protocol-agnostic sessions, token handling, sync connections, server orchestration, and webhooks. The server package adapts this core to Hono/Node and platform-specific runtimes, applies token/admin middleware, exposes public routes, and selects persistence. Thus protocol/domain behavior stays distinct from HTTP and deployment adapters.
- `packages/server-core/src/triplit-server.ts`
- `packages/server-core/src/sync-connection.ts`
- `packages/server/src/server.ts`

#### Runtimes and persistence infrastructure
The database storage boundary supports memory, IndexedDB, LMDB, SQLite, Expo SQLite, Bun SQLite, SQLite workers, and Cloudflare Durable Objects. Server distribution targets Node/Docker, Bun, and Cloudflare Workers; Cloudflare has standard and hibernating worker modes. This makes deployment/runtime selection an adapter concern rather than a database-core concern.
- `packages/db/src/kv-store/storage/`
- `packages/server/src/cloudflare.ts`
- `packages/cf-worker-server/src/hibernation.ts`

#### User-facing integrations and operations
Framework packages translate reactive client subscriptions into React, Angular, Vue, Svelte, Solid, TanStack, and React Native idioms. The CLI manages local development, auth/project state, schema pushes/diffs, seeding, snapshots, webhooks, and worker deployment. The Console is a separate Vite UI for server/data/schema administration, backed by its server component and Triplit client configuration.
- `packages/react/src/use-query.ts`
- `packages/cli/src/commands/dev.tsx`
- `packages/console/src/App.tsx`

Main entry points: [`packages/db/src/db.ts`](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/db.ts) (Database), [`packages/server/src/server.ts`](https://github.com/aspen-cloud/triplit/blob/main/packages/server/src/server.ts) (Hono/Node server), [`packages/client/src/client/triplit-client.ts`](https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/client/triplit-client.ts) (TriplitClient), [`packages/server-core/src/triplit-server.ts`](https://github.com/aspen-cloud/triplit/blob/main/packages/server-core/src/triplit-server.ts) (Server core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_db["Database kernel"]
  node_db[("Database<br/>[db.ts]")]
  node_transaction["Transactions<br/>transaction layer<br/>[db-transaction.ts]"]
  node_outbox[("Entity store + outbox<br/>change store")]
  node_storage["KV storage adapters<br/>storage boundary"]
  node_schema["Schema &amp; permissions<br/>schema builder<br/>[builder.ts]"]
  node_query["Query compiler<br/>query planner<br/>[query-compiler.ts]"]
  node_ivm["Incremental views<br/>live query engine<br/>[ivm.ts]"]
end

subgraph group_client["Client runtime"]
  node_client_api["TriplitClient<br/>client API<br/>[triplit-client.ts]"]
  node_sync_engine["Sync engine<br/>sync coordinator<br/>[sync-engine.ts]"]
  node_ws_transport["WebSocket transport<br/>transport adapter"]
end

subgraph group_server["Server protocol &amp; runtimes"]
  node_server_core{{"Server core<br/>protocol orchestrator<br/>[triplit-server.ts]"}}
  node_sync_connection["Sync connections<br/>protocol session<br/>[sync-connection.ts]"]
  node_server_adapter["Hono/Node server<br/>HTTP server adapter<br/>[server.ts]"]
  node_cf_runtime["Cloudflare runtime<br/>deployment adapter<br/>[cloudflare.ts]"]
  node_cf_hibernation["Hibernating worker<br/>Cloudflare adapter<br/>[hibernation.ts]"]
end

subgraph group_operations["Integrations &amp; operations"]
  node_react["React integration<br/>framework binding<br/>[use-query.ts]"]
  node_cli["CLI development<br/>developer tool<br/>[dev.tsx]"]
  node_console["Console<br/>admin UI<br/>[App.tsx]"]
end

node_db -->|"executes"| node_transaction
node_transaction -->|"writes"| node_outbox
node_db -->|"persists through"| node_storage
node_outbox -->|"durably stores"| node_storage
node_schema -->|"governs entities"| node_db
node_query -->|"uses relations"| node_schema
node_query -->|"evaluates against"| node_db
node_ivm -->|"maintains plans"| node_query
node_ivm -->|"reacts to mutations"| node_outbox
node_client_api -->|"uses local"| node_db
node_client_api -->|"coordinates through"| node_sync_engine
node_sync_engine -->|"drains and applies"| node_outbox
node_sync_engine -->|"connects via"| node_ws_transport
node_ws_transport -->|"sync protocol"| node_sync_connection
node_sync_connection -->|"belongs to"| node_server_core
node_server_core -->|"serves authorized deltas"| node_db
node_server_core -->|"enforces permissions"| node_schema
node_server_adapter -->|"adapts"| node_server_core
node_server_adapter -->|"selects persistence"| node_storage
node_cf_runtime -->|"deploys"| node_server_adapter
node_cf_hibernation -->|"extends"| node_cf_runtime
node_react -->|"subscribes through"| node_client_api
node_cli -->|"runs and manages"| node_server_adapter
node_console -->|"administers via"| node_client_api
node_console -->|"targets"| node_server_adapter

click node_db "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/db.ts"
click node_transaction "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/db-transaction.ts"
click node_outbox "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/entity-store-with-outbox.ts"
click node_schema "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/schema/builder.ts"
click node_query "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/query-planner/query-compiler.ts"
click node_ivm "https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/ivm/ivm.ts"
click node_client_api "https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/client/triplit-client.ts"
click node_sync_engine "https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/sync-engine.ts"
click node_ws_transport "https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/transport/websocket-transport.ts"
click node_server_core "https://github.com/aspen-cloud/triplit/blob/main/packages/server-core/src/triplit-server.ts"
click node_sync_connection "https://github.com/aspen-cloud/triplit/blob/main/packages/server-core/src/sync-connection.ts"
click node_server_adapter "https://github.com/aspen-cloud/triplit/blob/main/packages/server/src/server.ts"
click node_cf_runtime "https://github.com/aspen-cloud/triplit/blob/main/packages/server/src/cloudflare.ts"
click node_cf_hibernation "https://github.com/aspen-cloud/triplit/blob/main/packages/cf-worker-server/src/hibernation.ts"
click node_react "https://github.com/aspen-cloud/triplit/blob/main/packages/react/src/use-query.ts"
click node_cli "https://github.com/aspen-cloud/triplit/blob/main/packages/cli/src/commands/dev.tsx"
click node_console "https://github.com/aspen-cloud/triplit/blob/main/packages/console/src/App.tsx"

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_db,node_transaction,node_outbox,node_storage,node_schema,node_query,node_ivm toneBlue
class node_client_api,node_sync_engine,node_ws_transport toneAmber
class node_server_core,node_sync_connection,node_server_adapter,node_cf_runtime,node_cf_hibernation toneMint
class node_react,node_cli,node_console toneRose
```

## Components

### Database kernel

Runtime-independent local database and query engine.

- [Database](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/db.ts): database engine · Entity, transaction, metadata, clock, and write-buffer runtime. · `packages/db/src/db.ts`
- [Transactions](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/db-transaction.ts): transaction layer · `packages/db/src/db-transaction.ts`
- [Entity store + outbox](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/entity-store-with-outbox.ts): change store · Buffers local writes for outbound synchronization. · `packages/db/src/entity-store-with-outbox.ts`
- **KV storage adapters**: storage boundary · Memory, browser, native, Node, SQLite, and Durable Object persistence.
- [Schema & permissions](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/schema/builder.ts): schema builder · Defines collections, relations, types, and role permissions. · `packages/db/src/schema/builder.ts`
- [Query compiler](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/query-planner/query-compiler.ts): query planner · Compiles prepared queries into executable plans. · `packages/db/src/query-planner/query-compiler.ts`
- [Incremental views](https://github.com/aspen-cloud/triplit/blob/main/packages/db/src/ivm/ivm.ts): live query engine · Maintains live results after mutations. · `packages/db/src/ivm/ivm.ts`

### Client runtime

Local-first client APIs, synchronization, and transports.

- [TriplitClient](https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/client/triplit-client.ts): client API · Query, subscription, fetch, and mutation facade over a local DB. · `packages/client/src/client/triplit-client.ts`
- [Sync engine](https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/sync-engine.ts): sync coordinator · Coordinates outbox changes, patches, retries, rollback, and subscriptions. · `packages/client/src/sync-engine.ts`
- [WebSocket transport](https://github.com/aspen-cloud/triplit/blob/main/packages/client/src/transport/websocket-transport.ts): transport adapter · Real-time client transport; HTTP is a parallel adapter. · `packages/client/src/transport/websocket-transport.ts`

### Server protocol & runtimes

Protocol core separated from HTTP and deployment adapters.

- [Server core](https://github.com/aspen-cloud/triplit/blob/main/packages/server-core/src/triplit-server.ts): protocol orchestrator · Protocol-agnostic sessions, tokens, orchestration, and webhooks. · `packages/server-core/src/triplit-server.ts`
- [Sync connections](https://github.com/aspen-cloud/triplit/blob/main/packages/server-core/src/sync-connection.ts): protocol session · Authorized delta synchronization connection handling. · `packages/server-core/src/sync-connection.ts`
- [Hono/Node server](https://github.com/aspen-cloud/triplit/blob/main/packages/server/src/server.ts): HTTP server adapter · Applies middleware, routes, and persistence selection. · `packages/server/src/server.ts`
- [Cloudflare runtime](https://github.com/aspen-cloud/triplit/blob/main/packages/server/src/cloudflare.ts): deployment adapter · Cloudflare Workers server mode. · `packages/server/src/cloudflare.ts`
- [Hibernating worker](https://github.com/aspen-cloud/triplit/blob/main/packages/cf-worker-server/src/hibernation.ts): Cloudflare adapter · Durable Object hibernation mode. · `packages/cf-worker-server/src/hibernation.ts`

### Integrations & operations

Framework bindings and developer administration tools.

- [React integration](https://github.com/aspen-cloud/triplit/blob/main/packages/react/src/use-query.ts): framework binding · Maps client subscriptions to React query hooks. · `packages/react/src/use-query.ts`
- [CLI development](https://github.com/aspen-cloud/triplit/blob/main/packages/cli/src/commands/dev.tsx): developer tool · Runs local development and operational workflows. · `packages/cli/src/commands/dev.tsx`
- [Console](https://github.com/aspen-cloud/triplit/blob/main/packages/console/src/App.tsx): admin UI · Vite administration UI for server, data, and schema. · `packages/console/src/App.tsx`

## Connections

- Database → Transactions: executes
- Transactions → Entity store + outbox: writes
- Database → KV storage adapters: persists through
- Entity store + outbox → KV storage adapters: durably stores
- Schema & permissions → Database: governs entities
- Query compiler → Schema & permissions: uses relations
- Query compiler → Database: evaluates against
- Incremental views → Query compiler: maintains plans
- Incremental views → Entity store + outbox: reacts to mutations
- TriplitClient → Database: uses local
- TriplitClient → Sync engine: coordinates through
- Sync engine → Entity store + outbox: drains and applies
- Sync engine → WebSocket transport: connects via
- WebSocket transport → Sync connections: sync protocol
- Sync connections → Server core: belongs to
- Server core → Database: serves authorized deltas
- Server core → Schema & permissions: enforces permissions · Read and write authorization trust boundary.
- Hono/Node server → Server core: adapts
- Hono/Node server → KV storage adapters: selects persistence
- Cloudflare runtime → Hono/Node server: deploys
- Hibernating worker → Cloudflare runtime: extends
- React integration → TriplitClient: subscribes through
- CLI development → Hono/Node server: runs and manages
- Console → TriplitClient: administers via
- Console → Hono/Node server: targets