DB Legacy Boundary: apps/web/app/utils/db

This document defines the durable legacy boundary for apps/web/app/utils/db/ while database ownership continues to migrate into the workspace DB package. It is intended as the first stop for future slices that add, move, or review files in this directory.

Scope

apps/web/app/utils/db/ is a legacy server-only database helper area. Files in this tree may contain database access helpers, persistence-oriented business queries, seed-adjacent helpers, and server-side type glue needed by routes or services that have not yet moved to @toolctrl/db.

The directory is not a UI layer, component layer, route module, browser bundle entrypoint, or markup rendering boundary. Treat every file under apps/web/app/utils/db/**/*.ts as server-only application infrastructure until it is migrated or deleted.

Allowed DB and Type Imports

Code in apps/web/app/utils/db/ may import DB-safe types and helpers when they preserve the server-only boundary:

Prisma browser/type boundary imports from @toolctrl/db/prisma-browser are allowed for type-safe model enums and generated Prisma types that are intentionally safe to reference outside the generated client runtime.
Server package helpers from @toolctrl/db/* .server modules are allowed when the importing file remains server-only and does not expose those helpers to browser code.
Local server utilities, validation helpers, and framework request/session types may be used when they support DB access and do not pull UI dependencies into this tree.

Do not restate or depend on generated-client internals here. Prefer package-level exports from @toolctrl/db over deep generated-client paths.

Disallowed UI, React, and Markup Patterns

Files under apps/web/app/utils/db/ must not introduce UI or markup responsibilities. In particular, apps/web/app/utils/db/**/*.ts must not contain:

.tsx files anywhere in the directory tree.
React imports, including react, react/jsx-runtime, @remix-run/react, React component libraries, or UI package component imports.
JSX elements or fragments such as <div>, <Component />, <>...</>, or any returned JSX tree.
HTML/markup construction that belongs in UI code, especially dangerouslySetInnerHTML.
Browser-only DOM APIs used for rendering, hydration, or component behavior.

If a DB helper needs to return display content, return plain data, identifiers, or normalized strings. Route modules and UI components are responsible for rendering that data.

Existing Server-Only Constraints

The legacy boundary assumes server execution. Keep database calls behind server-only modules, use ORM-safe or parameterized access patterns, and validate request-derived values before they reach DB filters or identifiers.

Do not make apps/web/app/utils/db/ importable by client components or shared browser bundles. If a helper is required from both server and browser code, split the safe type-only contract into a package/type module and keep the DB implementation in a .server module.

Checklist for Changes Under apps/web/app/utils/db

Before adding or changing a file under apps/web/app/utils/db/, verify the following:

The file is .ts, not .tsx.
The code has no React, UI component, route-rendering, JSX, fragment, or dangerouslySetInnerHTML usage.
Imports use accepted DB/type boundaries such as @toolctrl/db/prisma-browser or server helpers from @toolctrl/db/* .server rather than generated-client internals.
Inputs from URL params, query params, request bodies, environment variables, or DB identifiers are validated or normalized before DB access.
The helper returns data, not rendered markup.
Any remaining migration concern is documented in the caller or follow-up plan instead of weakening this boundary.

Future Migration Notes

Future slices should move stable DB ownership toward @toolctrl/db server modules and leave apps/web/app/utils/db/ as a shrinking compatibility layer. When moving code, preserve the accepted Prisma browser/type boundary for safe types and keep runtime database clients inside server-only modules.

Static guards for this slice should fail loudly with the violating path and reason whenever .tsx, React imports, JSX/HTML indicators, or dangerouslySetInnerHTML appear in apps/web/app/utils/db/.

4.3 KiB Raw Blame History