Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
ποΈ Ban data.ts imports from pages: reads go through feature loaders (#2867)
Luke Vella30484fbffd36
diff --git a/CLAUDE.md b/CLAUDE.mdindex 741ff45e0..d1a9d47f9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -207,9 +207,9 @@ These rules prepare the app for Next.js `cacheComponents` (static shell + stream| Reads | `loaders.ts` | `data.ts` || Writes | `actions.ts` | `mutations.ts` |-**Loader placement** β route by default, promote on the second consumer. Page data needs are view shaped, so the server component composes in the route: it calls the session gate loaders (`getActiveSpace()`, `requireUser()` β both trust the session cookie cache, no database read; `getCurrentUser()` is the database-verified read for pages that need DB-fresh user state) and passes proven scope to `data.ts` reads; extract to a route private file only when the page gets long. Never import another route's loader. Promote to `features/<domain>/loaders.ts` only when a second route segment needs the same read β that is evidence of a domain concept, not a view shape. The test: a loader belongs in the feature when its contract is stated in domain terms and every consumer wants exactly that contract; it stays in the route when its shape is "what this page happens to display." Most features never have a `loaders.ts` (today: `space`, `user`).+**Loader placement** β pages, layouts and route-private components never call `data.ts` directly: every read they consume goes through a loader in `features/<domain>/loaders.ts`, so the session gate that proves scope cannot be forgotten at the call site (lint-enforced: `@/features/**/data` is banned in `app/**`; existing violations sit on a shrinking migration allowlist in `apps/web/biome.json`). A loader bundles the gate and the read: `import "server-only"`, named with a `load*` prefix, wrapped in React `cache()` so every consumer in a request shares one read, resolves the actor via the session gates (`requireUser()`, `getActiveSpace()` β both trust the session cookie cache; `getCurrentUser()` is the database-verified read for pages that need DB-fresh user state) and delegates to `data.ts` with proven scope. Reference shape: `features/notifications/loaders.ts` (`loadNotificationPreferences`). Route-private `actions.ts` files are the write side, not pages β they keep calling `data.ts`/`mutations.ts` with proven scope from their safe-action gate (loaders' page semantics, redirects, don't belong in actions) and are exempt from the lint ban.-**DAL enforcement** β `@rallly/database` may only be imported from `features/**/data.ts` and `features/**/mutations.ts` (lint-enforced via `noRestrictedImports`; existing violations sit on a shrinking migration allowlist in `apps/web/biome.json`; `loaders.ts` is absent from the allowlist, so database imports are banned there by default). Parameterized reads take their tenant scope as `spaceId: AuthorizedSpaceId` (from `@/features/space/types`); only the session gate (`createSpaceDTO`) and the API key middleware may cast to it. API routes under `app/api/**` (except tRPC and better-auth) must not import `@/features/**/loaders` β they authenticate their own way and pass proven scope to parameterized reads. `api/private` handlers own serialization and must parse response bodies through their zod schemas.+**DAL enforcement** β `@rallly/database` may only be imported from `features/**/data.ts` and `features/**/mutations.ts` (lint-enforced via `noRestrictedImports`; existing violations sit on a shrinking migration allowlist in `apps/web/biome.json`; `loaders.ts` is absent from the allowlist, so database imports are banned there by default). Parameterized reads take their tenant scope as `spaceId: AuthorizedSpaceId` (from `@/features/space/types`); only the session gate (`createSpaceDTO`) and the API key middleware may cast to it. API routes under `app/api/**` (except tRPC and better-auth) must not import `@/features/**/loaders` β they authenticate their own way and pass proven scope to parameterized reads. The inverse holds for pages: `app/**` (outside `app/api/**` and route-private `actions.ts`) must not import `@/features/**/data` β reads reach pages only through loaders. `api/private` handlers own serialization and must parse response bodies through their zod schemas.**Cross-feature imports** β allowed, public surface only (the vocabulary files above); never reach into another feature's internals. No cycles between features (CI-enforced). For UI, prefer composing multiple features at the page level in `app/` over feature-to-feature component imports.diff --git a/apps/web/biome.json b/apps/web/biome.jsonindex 32d42898b..0e878ca55 100644--- a/apps/web/biome.json+++ b/apps/web/biome.json@@ -127,6 +127,10 @@}},"patterns": [+ {+ "group": ["@/features/**/data"],+ "message": "Pages, layouts and route components read through feature loaders (features/<domain>/loaders.ts), never data.ts directly β the loader owns the session gate that proves scope. Existing violations are on the migration allowlist (see overrides in apps/web/biome.json)."+ },{"group": ["@/utils", "@/utils/**"],"message": "src/utils is dissolved. Generic helpers live in @/lib/utils, infrastructure in @/lib, domain code in the owning feature."@@ -213,6 +217,35 @@}}},+ {+ "includes": ["src/app/**/actions.ts"],+ "linter": {+ "rules": {+ "style": {+ "noRestrictedImports": {+ "level": "error",+ "options": {+ "paths": {+ "dayjs": "Use the formatters in `@/lib/datetime` for display. dayjs is only allowed in files on the migration allowlist (see overrides in biome.json).",+ "@/lib/dayjs": "Use the formatters in `@/lib/datetime` for display. dayjs is only allowed in files on the migration allowlist (see overrides in biome.json).",+ "@rallly/database": "Database access is confined to the DAL: only features/**/data.ts and features/**/mutations.ts may import @rallly/database. Existing violations are on the migration allowlist (see overrides in apps/web/biome.json).",+ "@/lib/posthog": {+ "message": "User-attributed analytics events must go through track() from @/lib/posthog so guest person-profile handling cannot be forgotten at capture sites. The raw client is reserved for non-capture APIs (feature flags, identity merge) in allowlisted files (see overrides in apps/web/biome.json).",+ "importNames": ["posthog"]+ }+ },+ "patterns": [+ {+ "group": ["@/utils", "@/utils/**"],+ "message": "src/utils is dissolved. Generic helpers live in @/lib/utils, infrastructure in @/lib, domain code in the owning feature."+ }+ ]+ }+ }+ }+ }+ }+ },{"includes": ["src/app/*/(optional-space)/new/page.tsx",@@ -250,6 +283,54 @@}}},+ {+ "includes": [+ "src/app/*/(auth)/login/page.tsx",+ "src/app/*/(auth)/login/verify/page.tsx",+ "src/app/*/(optional-space)/layout.tsx",+ "src/app/*/(space)/(dashboard)/layout.tsx",+ "src/app/*/(space)/(dashboard)/polls/page.tsx",+ "src/app/*/(space)/settings/api-keys/components/api-keys-list.tsx",+ "src/app/*/(space)/settings/api-keys/page.tsx",+ "src/app/*/(space)/settings/billing/page.tsx",+ "src/app/*/(space)/settings/profile/components/account-deletion-summary.tsx",+ "src/app/*/(space)/settings/security/page.tsx",+ "src/app/*/(space)/settings/spaces/page.tsx",+ "src/app/*/control-panel/branding/page.tsx",+ "src/app/*/control-panel/license/page.tsx",+ "src/app/*/control-panel/page.tsx",+ "src/app/*/control-panel/settings/page.tsx",+ "src/app/*/e/*/page.tsx",+ "src/app/*/layout.tsx",+ "src/app/*/setup/page.tsx"+ ],+ "linter": {+ "rules": {+ "style": {+ "noRestrictedImports": {+ "level": "error",+ "options": {+ "paths": {+ "dayjs": "Use the formatters in `@/lib/datetime` for display. dayjs is only allowed in files on the migration allowlist (see overrides in biome.json).",+ "@/lib/dayjs": "Use the formatters in `@/lib/datetime` for display. dayjs is only allowed in files on the migration allowlist (see overrides in biome.json).",+ "@rallly/database": "Database access is confined to the DAL: only features/**/data.ts and features/**/mutations.ts may import @rallly/database. Existing violations are on the migration allowlist (see overrides in apps/web/biome.json).",+ "@/lib/posthog": {+ "message": "User-attributed analytics events must go through track() from @/lib/posthog so guest person-profile handling cannot be forgotten at capture sites. The raw client is reserved for non-capture APIs (feature flags, identity merge) in allowlisted files (see overrides in apps/web/biome.json).",+ "importNames": ["posthog"]+ }+ },+ "patterns": [+ {+ "group": ["@/utils", "@/utils/**"],+ "message": "src/utils is dissolved. Generic helpers live in @/lib/utils, infrastructure in @/lib, domain code in the owning feature."+ }+ ]+ }+ }+ }+ }+ }+ },{"includes": ["src/trpc/trpc.ts",