Runtime & Collections

This page covers the non-entity runtime of @life-manager/db.

Core Files

File	Responsibility
core.ts	stable runtime export surface
schema.ts	PowerSync schema definition
collection-registry.ts	creates collections and cross-entity live query collections
init.ts	initializes and stores the singleton DB + collection registry
context.tsx	injects adapters and user context into the DB layer
BaseConnector.ts	shared PowerSync backend connector using Supabase auth/session
PowerSyncProvider.tsx	PowerSync status context

Initialization Flow

create PowerSync database
  -> initCollections(db)
  -> mount CollectionsProvider
  -> query hooks read from getCollections()
  -> action and mutation hooks read adapters from useCollectionsDeps()

Collection Bootstrapping

createAllCollections() builds the collection registry from:

• the PowerSync table schema
• Zod schema/deserialization definitions from @life-manager/db/schemas
• a set of live-query collections for cross-table joins and derived views

Relevant API pages:

• createAllCollections
• CollectionRegistry
• getCollections

Runtime Context

The collections context provides app-level dependencies to the DB package:

• userId
• notification adapter
• confirmation adapter
• selection adapter

That context is consumed indirectly by action and mutation hooks through useMutationContext() from @life-manager/db/shared.

Relevant API pages:

• CollectionsProvider
• useCollectionsDeps

Sync Boundary

BaseSupabaseConnector is the shared connector layer between local PowerSync state and Supabase.

It is responsible for:

• session bootstrap
• credential fetching for PowerSync
• login/logout/register helpers
• CRUD upload handling from local transactions to Supabase
• fatal error classification for unrecoverable Postgres responses

Relevant API pages:

• BaseSupabaseConnector
• SupabaseConfig

PowerSync Status

The package exposes a small PowerSync status context for apps that need to render connection state or reconnect flows.

Relevant API pages:

• PowerSyncContext
• usePowerSyncStatus

Runtime Model Around Entities

The core runtime does not bypass the entity system. Entity writes still go through:

query state
  -> action hook
  -> workflow resolution
  -> mutation enforcement
  -> raw mutation
  -> local DB write
  -> sync upload

That division is important:

• the runtime bootstraps collections and sync
• the entity layer decides what operations are allowed and how the UI should react

What Apps Should Import From Here

App initialization code should usually import from @life-manager/db/core and @life-manager/db/context, not from deep runtime files.

Typical consumers:

• app boot code
• PowerSync provider setup
• platform-specific connector implementations