aspen-cloud/triplit

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