feat: loading/error-boundary DX, bundle analyzer, golden-paths doc and CLAUDE.md update

Author: martins-itc

CLAUDE.md

@@ -94,9 +94,19 @@ Shared enums in `src/common/enums`: `Role`, `SortOrder`, `CustomTaskStatus`, `Ta
 - Query: `extends PaginationDto` + `@Filterable` decorators (`@FilterSearch`, `@FilterExact`, `@FilterBoolean`, `@FilterDateFrom`, `@FilterDateTo`, `@FilterIn`, `@FilterBetween`)
 - Response: `@ApiProperty` on exposed fields
 
-### Entity Registration (CRITICAL)
+### Entity Registration
 
-New entities MUST be added to BOTH arrays in `apps/backend/src/database/database.module.ts` — failure causes 500 errors.
+`autoLoadEntities: true` is enabled, so a new entity is picked up from any
+`TypeOrmModule.forFeature([...])` — register it in its **feature module** only.
+Never add it to a `forRoot` entities array (there isn't one anymore).
+
+### Error Contract & Logging
+
+- All errors share ONE envelope: `{ success: false, error: { statusCode, message,
+errors?, correlationId, timestamp, path } }` — emitted identically by
+  `ResponseService.error()` and `HttpExceptionFilter`.
+- Every response carries an `x-correlation-id` header (pino logs the same id) —
+  this is the trace key for debugging a reported error.
 
 ### i18n
 
@@ -118,8 +128,11 @@ NEVER use `synchronize: true` in production.
 
 ### Types & Enums
 
-- **ALWAYS** import from `@myorg/api-client` — NEVER create custom interfaces or hardcode enum strings
-- Regenerate after backend changes: `pnpm generate:api`
+- The API client is **orval-generated** (types + Zod + React Query hooks) from the
+  backend OpenAPI spec. **ALWAYS** import types/enums from `@myorg/api-client` —
+  NEVER create custom interfaces or hardcode enum strings.
+- Regenerate after backend changes: `pnpm generate:api` (offline — runs the
+  DB-independent generator into the committed `openapi.json`, then orval).
 
 ### Forms
 
@@ -143,8 +156,24 @@ All private pages: `SectionContainer` + `PageHeader` + `<div className="p-4 lg:p
 
 ### Server Actions
 
-- Place in `_actions/` folders (excluded from routing)
-- Use `revalidatePath()` after mutations
+- Call orval-generated functions (e.g. `usersQueryControllerFindAll(params, cfg)`)
+  and hooks (`useUsersCommandControllerCreate`) — NEVER hand-write fetch/axios.
+- In Server Components / Server Actions, pass `await getServerRequestConfig()`
+  (from `@myorg/api-client/server`) as the last arg so cookies + locale are sent.
+- Wrap every Server Action body in `safeAction(...)` — it returns the typed
+  `{ success, data, message, error }` envelope and never throws on network errors.
+  Errors carry `error.correlationId` (matches the backend `x-correlation-id` header).
+- Place in `_actions/` folders (excluded from routing); `revalidatePath()` after a
+  successful mutation.
+
+### Testing
+
+- **Vitest** for unit/component tests (`*.spec.ts` backend, `*.test.tsx` web),
+  **Playwright** for E2E (`apps/web/e2e/`). `pnpm test` runs them via turbo.
+- Backend: test Actions in isolation with a mocked repository — see
+  `create-user.action.spec.ts` (the golden blueprint). No DB needed.
+- Web: drive components like a user (type + submit) and assert behaviour — see
+  `universal-form.test.tsx`.
 
 ### Routing
 
@@ -173,7 +202,7 @@ app/[locale]/(main)/
 11. `@I18n()` for messages
 12. Soft deletes, UUID keys, indexes on queried columns
 13. `QueryHelper.paginate()` for pagination
-14. Register entities in `database.module.ts` (both arrays)
+14. Register a new entity in its module's `TypeOrmModule.forFeature([...])` — `autoLoadEntities` handles the connection (no more dual-array registration)
 15. Import types/enums from `@myorg/api-client` on frontend
 16. `UniversalForm` + Zod for forms
 17. `date-fns`, `ts-pattern`, `SectionContainer` + `PageHeader`
@@ -187,7 +216,7 @@ app/[locale]/(main)/
 4. `synchronize: true` in production
 5. Return raw entities (use ResponseService/DTOs)
 6. N+1 queries, magic numbers/strings
-7. Forget entity registration in `database.module.ts`
+7. Manually list entities in the `forRoot` array (use `forFeature` + `autoLoadEntities`)
 8. Inline enum arrays in Swagger (creates duplicates)
 9. Custom interfaces/types on frontend for API data
 10. Hardcode enum string values on frontend

apps/web/next.config.ts

@@ -1,6 +1,7 @@
 import os from 'node:os';
 import type { NextConfig } from 'next';
 import createNextIntlPlugin from 'next-intl/plugin';
+import bundleAnalyzer from '@next/bundle-analyzer';
 
 function lanIps(): string[] {
   return Object.values(os.networkInterfaces())
@@ -35,4 +36,7 @@ const nextConfig: NextConfig = {
 };
 
 const withNextIntl = createNextIntlPlugin('./src/i18n/request.ts');
-export default withNextIntl(nextConfig);
+const withBundleAnalyzer = bundleAnalyzer({
+  enabled: process.env.ANALYZE === 'true',
+});
+export default withBundleAnalyzer(withNextIntl(nextConfig));

apps/web/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "dev": "next dev --turbopack -H 0.0.0.0",
     "build": "next build",
+    "analyze": "ANALYZE=true next build",
     "start": "next start",
     "lint": "eslint . --max-warnings=0",
     "typecheck": "tsc --noEmit",
@@ -37,6 +38,7 @@
     "zod": "catalog:"
   },
   "devDependencies": {
+    "@next/bundle-analyzer": "catalog:next",
     "@playwright/test": "^1.60.0",
     "@tailwindcss/postcss": "catalog:",
     "@testing-library/jest-dom": "^6.9.1",

apps/web/src/app/[locale]/(main)/(private)/loading.tsx

@@ -0,0 +1,20 @@
+/**
+ * Route-level loading UI (golden path). Next streams this instantly while a
+ * Server Component awaits data, so navigation never blocks on the network.
+ * Clone this file into any route segment that fetches.
+ */
+export default function Loading() {
+  return (
+    <div className="space-y-4 p-4 lg:p-12">
+      <div className="h-8 w-48 animate-pulse rounded-md bg-muted" />
+      <div className="space-y-2">
+        {Array.from({ length: 6 }).map((_, i) => (
+          <div
+            key={i}
+            className="h-12 w-full animate-pulse rounded-md bg-muted"
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

apps/web/src/app/error.tsx

@@ -84,6 +84,14 @@ export default function Error({ error, reset }: ErrorProps) {
               .
             </p>
           </div>
+
+          {/* Always-visible reference so users can quote it to support and it
+              can be traced to the server logs (Next error digest). */}
+          {error.digest && (
+            <p className="text-center text-xs text-gray-400">
+              Reference: {error.digest}
+            </p>
+          )}
         </CardContent>
       </Card>
     </div>

apps/web/src/components/error-boundary.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { Component, type ReactNode } from 'react';
+
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** Rendered instead of the crashed subtree. */
+  fallback?: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+}
+
+/**
+ * Localized error boundary for widget-level isolation: wrap a panel so one
+ * crashing component degrades to a fallback instead of taking down the page.
+ * (Route-level errors are handled by `error.tsx`; this is for sub-trees.)
+ *
+ * @example
+ * <ErrorBoundary fallback={<p>Couldn't load stats.</p>}>
+ *   <StatsWidget />
+ * </ErrorBoundary>
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  override state: ErrorBoundaryState = { hasError: false };
+
+  static getDerivedStateFromError(): ErrorBoundaryState {
+    return { hasError: true };
+  }
+
+  override componentDidCatch(error: unknown): void {
+    console.error('ErrorBoundary caught:', error);
+  }
+
+  override render(): ReactNode {
+    if (this.state.hasError) {
+      return (
+        this.props.fallback ?? (
+          <div className="rounded-md border border-destructive/40 bg-destructive/5 p-4 text-sm text-destructive">
+            Something went wrong in this section.
+          </div>
+        )
+      );
+    }
+    return this.props.children;
+  }
+}

docs/HARDENING_CHECKLIST.md

@@ -57,8 +57,8 @@ Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked (needs de
 - [x] 5.1 `safeAction` wrapper in api-client (no-throw, returns typed envelope)
 - [x] 5.2 Rewrote all server actions + pages + auth/actions.ts → orval functions + `safeAction` + `getServerRequestConfig` (~14 files). Found/fixed orval generating POST as a query (removed bad `query` override); fixed a bearer-auth spec bug; smart envelope transformer (skip already-enveloped DTOs); `ApiErrorDto.message` → plain `string`.
 - [x] 5.3 Replaced hand-written `UpdateProfileData`/`ChangePasswordData` with aliases to generated DTOs
-- [ ] 5.4 Query-key factory + standardized mutation invalidation
-- [ ] 5.5 `loading.tsx` golden path + reusable `<ErrorBoundary>` + correlation ID in `error.tsx`
+- [x] 5.4 Query keys — orval generates `getXxxQueryKey()` + manages hook keys; invalidate via `queryClient.invalidateQueries({ queryKey: getXxxQueryKey() })`. (No separate factory needed — provided by generation.)
+- [x] 5.5 `loading.tsx` golden path + reusable `<ErrorBoundary>` (`components/error-boundary.tsx`) + always-visible error `digest`/correlation reference in `error.tsx`
 - [x] 5.6 Fixed all frontend `any` (query-client, universal-form generic-forwardRef, table-filters, locale cast, health route, sidebar). **web typecheck 0, lint 0, `next build` ✅**
 
 ## EPIC 6 — Testing (review #4)
@@ -70,10 +70,10 @@ Legend: `[ ]` todo · `[~]` in progress · `[x]` done · `[!]` blocked (needs de
 
 ## EPIC 7 — AI-native docs & polish (review #1.1, #1.3, #3.3, #5.3)
 
-- [ ] 7.1 `docs/golden-paths/` index (one perfect example per artifact) linked from CLAUDE.md
-- [ ] 7.2 Update CLAUDE.md to match new patterns (safeAction, autoload, orval/zod, testing)
+- [x] 7.1 `docs/golden-paths.md` — one exemplar per artifact (Action, controller, server action, form, tests, E2E)
+- [x] 7.2 Updated CLAUDE.md: orval client + `safeAction` + `getServerRequestConfig`, `autoLoadEntities` (footgun removed), unified error contract + correlation IDs, Testing section
 - [x] 7.3 Replace `console.log` banner in `main.ts` with pino logger (done early — backend pass)
-- [ ] 7.4 `pnpm analyze` wiring for `@next/bundle-analyzer`
+- [x] 7.4 `pnpm --filter web analyze` wired via `@next/bundle-analyzer` (gated on `ANALYZE=true`)
 
 ## EPIC 8 — Final verification
 

docs/golden-paths.md

@@ -0,0 +1,47 @@
+# Golden Paths
+
+One flawless, verified example per artifact. When adding a feature, **clone the
+nearest example** below rather than inventing a pattern — every file here passes
+the full typecheck + lint + test gate.
+
+## Backend (NestJS)
+
+| Artifact             | Golden file                                                              |
+| -------------------- | ------------------------------------------------------------------------ |
+| Action (logic)       | `apps/backend/src/modules/users/actions/create-user.action.ts`           |
+| Command controller   | `apps/backend/src/modules/users/controllers/users-command.controller.ts` |
+| Query controller     | `apps/backend/src/modules/users/controllers/users-query.controller.ts`   |
+| Service (DB)         | `apps/backend/src/modules/users/users.service.ts`                        |
+| Entity               | `apps/backend/src/modules/users/entities/user.entity.ts`                 |
+| Create / Query DTO   | `apps/backend/src/modules/users/dto/`                                    |
+| Error envelope       | `apps/backend/src/common/filters/http-exception.filter.ts`               |
+| **Action unit test** | `apps/backend/src/modules/users/actions/create-user.action.spec.ts`      |
+
+Reference module: `apps/backend/src/modules/users/`.
+
+## Frontend (Next.js)
+
+| Artifact               | Golden file                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| Server Action          | `apps/web/src/app/[locale]/(main)/(private)/profile/change-password/_actions/change-password.ts` |
+| Server Component fetch | `apps/web/src/app/[locale]/(main)/(private)/admin/users/(list)/page.tsx`                         |
+| Client form (mutation) | `apps/web/src/app/[locale]/(main)/(private)/admin/add-user-client/_components/add-user-form.tsx` |
+| Form primitive         | `apps/web/src/components/forms/universal-form.tsx`                                               |
+| Route loading skeleton | `apps/web/src/app/[locale]/(main)/(private)/loading.tsx`                                         |
+| Route error boundary   | `apps/web/src/app/[locale]/(main)/(private)/error.tsx`                                           |
+| Widget error boundary  | `apps/web/src/components/error-boundary.tsx`                                                     |
+| **Component test**     | `apps/web/src/components/forms/universal-form.test.tsx`                                          |
+| **E2E test**           | `apps/web/e2e/auth.spec.ts`                                                                      |
+
+## API client (`@myorg/api-client`)
+
+- **Generated** by orval from `packages/api-client/openapi.json` — never edit
+  `src/generated/**` by hand. Regenerate with `pnpm generate:api`.
+- Call generated functions + hooks; wrap Server Actions in `safeAction`; pass
+  `getServerRequestConfig()` from `@myorg/api-client/server` on the server.
+
+## The gate
+
+`pnpm typecheck && pnpm lint && pnpm test && pnpm build` — all green. Enforced
+locally by husky (lint-staged + pre-push typecheck) and in CI
+(`.github/workflows/ci.yml`).