business-data-access

Call a service from @chatbotx.io/business or a repository from @chatbotx.io/database/repositories instead of importing db. Services handle business semantics, cache invalidation, and events, while repositories cover low-level persistence like shard routing and pagination.

Use a service when the method has business semantics, authorization constraints, cache invalidation, event emission, or cross-table composition. Use a repository for low-level persistence concerns such as shard routing, specialized pagination, or reusable raw query mechanics.

Direct db imports are allowed only in packages/business/src and packages/database/src/repositories. The apps/builder, apps/worker, and integrations layers must go through services or repositories, and legacy direct imports are exceptions rather than patterns to copy.

Accept an optional tx parameter of type DatabaseClient in service methods and default it to db with const { tx = db } = props. Pass the same tx through nested service and repository calls so composed operations share one transaction.

Services extend BaseService to call invalidateCacheTags with workspace-scoped tag keys after mutations. They emit domain events when mutations affect downstream workflows, and fire-and-forget events should attach .catch(() => {}) where the local pattern does.