File Structure

Every entity module lives in packages/db/src/entities/<domain>/<entity>/.

Canonical Entity Folder

<entity>/
  index.ts                   # Full entity export barrel
  <entity>.types.ts          # Entity-local types and derived models
  <entity>.schema.ts         # Zod validation and deserialization
  <entity>.guards.ts         # Pure domain evaluation
  <entity>.workflows.ts      # Domain evaluation -> interaction resolutions
  <entity>.mutations.ts      # Raw transaction-based writes
  <entity>.actions.ts        # Query-aware orchestration hook
  use-<entity>-mutations.ts  # Write orchestration + hard invariant enforcement
  use-<entity>-query.ts      # Live query hooks

Why Everything Is Co-located

The entity folder is the unit of ownership for that domain model:

• runtime types
• validation
• read hooks
• write hooks
• raw DB mutations
• domain policy
• UI-resolution policy

That keeps rules close to the data they protect.

Barrel Behavior

Each entity index.ts re-exports the full local surface, so callers can import from the entity subpath directly:

import {
  useWorkProjectActions,
  useWorkProjectMutations,
  useWorkProjects,
  resolveWorkProjectDelete,
} from "@life-manager/db/entities/work/project";

Simple vs Complex

Simple and complex entities follow the same folder contract.

The difference is only the amount of domain logic inside the files:

• simple entity: trivial guard input, straightforward edit resolution, generic confirmation workflow
• complex entity: multiple operation-specific inputs, branching workflows, field editability, mutation-time enforcement