DB Package

@life-manager/db is the shared offline-first data package for the web and mobile apps.

This section in the docs app is the human-facing source of truth for the package. It explains the package structure, the entity system, and how the public API is intended to be used. The generated API reference under /api/db/ is complementary and only covers the Typedoc entrypoints.

What The Package Owns

• PowerSync schema in @life-manager/db/schema
• core runtime setup in @life-manager/db/core
• entity modules in packages/db/src/entities
• query and action hook barrels in @life-manager/db/hooks/*
• shared guard, workflow, and mutation infrastructure in @life-manager/db/shared
• Supabase-generated database types in @life-manager/db/supabase
• domain type barrels in @life-manager/db/types/*

Current Package Shape

packages/db/src/
  core.ts
  schema.ts
  supabase.types.ts
  init.ts
  collection-registry.ts
  context.tsx
  BaseConnector.ts
  PowerSyncProvider.tsx
  collections-types.ts
  shared/
  entities/
    finance/   # 8 entity modules
    work/      # 5 entity modules
    system/    # 3 entity modules
  hooks/
    actions/
    queries/
  types/
  schemas/
  guards/
  workflows/

There are currently 16 entity modules:

• finance: bank-account, contact, finance-project, payout, project-adjustment, recurring-cashflow, single-cashflow, tag
• work: appointment, folder, project, time-entry, time-tracker
• system: notification, profile, settings

Runtime Model

The practical write path in the package is:

query state
  -> action input builder
  -> workflow resolution
  -> mutation enforcement
  -> local DB write
  -> PowerSync sync

That layered model is what keeps UI interaction logic, domain policy, and hard write safety separate.

How To Read This Section

• Start with Public API for import paths and package boundaries.
• Read Runtime & Collections for initialization and sync setup.
• Read Schema & Types for tables, schema, and domain type barrels.
• Read Entities for the actual entity system and module contract.

API Reference

The generated API reference lives under /api/db/.

Use it for:

• exact exported types from the root entrypoint
• core runtime functions like initCollections
• shared exported types like CollectionRegistry
• schema/runtime exports like AppSchema and PowerSyncDatabase

Do not treat the generated API pages as the full package guide. They do not currently document the entity-level hook subpaths such as @life-manager/db/hooks/actions/work or @life-manager/db/entities/work/project.