55 lines
4.3 KiB
Markdown
55 lines
4.3 KiB
Markdown
# 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:
|
|
|
|
1. The file is `.ts`, not `.tsx`.
|
|
2. The code has no React, UI component, route-rendering, JSX, fragment, or `dangerouslySetInnerHTML` usage.
|
|
3. Imports use accepted DB/type boundaries such as `@toolctrl/db/prisma-browser` or server helpers from `@toolctrl/db/* .server` rather than generated-client internals.
|
|
4. Inputs from URL params, query params, request bodies, environment variables, or DB identifiers are validated or normalized before DB access.
|
|
5. The helper returns data, not rendered markup.
|
|
6. 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/`.
|