@synergyerp/frontend-standards 1.1.2 → 1.1.4

package/FRONTEND_STANDARDS.md

@@ -45,9 +45,9 @@
 
 This document is split into two distinct parts:
 
-| Part | Focus | Audience |
-|------|-------|----------|
-| **Frontend Standards** (Sections 2-9) | Code structure, linting, UI components, testing, git | Developers, Tech Leads |
+| Part                                    | Focus                                                    | Audience               |
+| --------------------------------------- | -------------------------------------------------------- | ---------------------- |
+| **Frontend Standards** (Sections 2-9)   | Code structure, linting, UI components, testing, git     | Developers, Tech Leads |
 | **CI/CD & Deployment** (Sections 10-14) | Pipelines, code review, deployment, monitoring, security | DevOps, QA, Tech Leads |
 
 ---
@@ -56,41 +56,41 @@ This document is split into two distinct parts:
 
 ### 2.1 Framework & Runtime
 
-| Layer | Recommended | Alternative | Notes |
-|-------|------------|-------------|-------|
-| **Framework** | React 19 + Vite | Next.js(if SSR/SEO needed) | Choose based on project needs. Lovable generates React components natively. |
-| **Language** | TypeScript 5.5+ (strict mode) | -- | Non-negotiable. No plain JavaScript in new projects. |
-| **Build Tool** | Vite 6 | Turbopack (Next.js only) | Fastest build times. |
-| **Package Manager** | Any (pnpm 9+ preferred) | npm 10+, yarn, bun | Developers may use any manager locally; however, **pnpm** is preferred for CI/CD and deployment for performance and consistency. |
+| Layer               | Recommended                   | Alternative                | Notes                                                                                                                            |
+| ------------------- | ----------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| **Framework**       | React 19 + Vite               | Next.js(if SSR/SEO needed) | Choose based on project needs. Lovable generates React components natively.                                                      |
+| **Language**        | TypeScript 5.5+ (strict mode) | --                         | Non-negotiable. No plain JavaScript in new projects.                                                                             |
+| **Build Tool**      | Vite 6                        | Turbopack (Next.js only)   | Fastest build times.                                                                                                             |
+| **Package Manager** | Any (pnpm 9+ preferred)       | npm 10+, yarn, bun         | Developers may use any manager locally; however, **pnpm** is preferred for CI/CD and deployment for performance and consistency. |
 
 ### 2.2 UI & Styling
 
-| Layer | Recommendation | Notes |
-|-------|---------------|-------|
-| **UI Components** | Lovable.ai generated + Radix UI primitives | Lovable generates the initial templates and components. Hand-roll custom logic on top. |
-| **Styling** | Tailwind CSS v4 | Utility-first. Compatible with Lovable output. |
-| **Component Library** | Shadcn UI (or custom) | Copy-pasteable components, fully customizable. |
-| **Icons** | Lucide React | Consistent, tree-shakeable. |
-| **Animations** | Framer Motion / tw-animate-css | For complex animations vs simple transitions. |
+| Layer                 | Recommendation                             | Notes                                                                                  |
+| --------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------- |
+| **UI Components**     | Lovable.ai generated + Radix UI primitives | Lovable generates the initial templates and components. Hand-roll custom logic on top. |
+| **Styling**           | Tailwind CSS v4                            | Utility-first. Compatible with Lovable output.                                         |
+| **Component Library** | Shadcn UI (or custom)                      | Copy-pasteable components, fully customizable.                                         |
+| **Icons**             | Lucide React                               | Consistent, tree-shakeable.                                                            |
+| **Animations**        | Framer Motion / tw-animate-css             | For complex animations vs simple transitions.                                          |
 
 ### 2.3 State & Data
 
-| Layer | Recommendation | Notes |
-|-------|---------------|-------|
-| **Server State** | TanStack React Query (v5) | Caching, refetching, optimistic updates. |
-| **Client State** | Zustand | Lightweight, no boilerplate. |
-| **Forms** | React Hook Form + Zod | Validation schema-driven. |
-| **Routing** | React Router v7 / Next.js App Router | Depends on framework choice. |
+| Layer            | Recommendation                       | Notes                                    |
+| ---------------- | ------------------------------------ | ---------------------------------------- |
+| **Server State** | TanStack React Query (v5)            | Caching, refetching, optimistic updates. |
+| **Client State** | Zustand                              | Lightweight, no boilerplate.             |
+| **Forms**        | React Hook Form + Zod                | Validation schema-driven.                |
+| **Routing**      | React Router v7 / Next.js App Router | Depends on framework choice.             |
 
 ### 2.4 Testing
 
-| Layer | Tool | Notes |
-|-------|------|-------|
-| **Unit / Component** | Vitest (preferred) or Jest 29 | Vitest is faster, native ESM, Vite-compatible. |
-| **Component Testing** | Testing Library + jsdom | Test behavior, not implementation. |
-| **E2E** | Playwright | Cross-browser, reliable, parallel. |
-| **Visual Regression** | Playwright / Chromatic | For UI component libraries. |
-| **Coverage** | c8 / istanbul | Minimum 80% line/branch. |
+| Layer                 | Tool                          | Notes                                          |
+| --------------------- | ----------------------------- | ---------------------------------------------- |
+| **Unit / Component**  | Vitest (preferred) or Jest 29 | Vitest is faster, native ESM, Vite-compatible. |
+| **Component Testing** | Testing Library + jsdom       | Test behavior, not implementation.             |
+| **E2E**               | Playwright                    | Cross-browser, reliable, parallel.             |
+| **Visual Regression** | Playwright / Chromatic        | For UI component libraries.                    |
+| **Coverage**          | c8 / istanbul                 | Minimum 80% line/branch.                       |
 
 ---
 
@@ -165,14 +165,14 @@ All domain-specific files across **every** directory (`services/`, `hooks/`, `st
 
 Every domain subdirectory **must** expose its contents via an `index.ts` barrel file. Parent code imports from the barrel, never from individual files within a domain.
 
-| Directory | Modularization Rule | Barrel Required |
-|-----------|---------------------|:---:|
-| `services/` | One subdirectory per domain (e.g., `services/employee/`, `services/auth/`). Only `api-client.ts` may live at the root. | Yes |
-| `hooks/` | Domain-specific hooks in `hooks/<domain>/`. Shared utility hooks (`useDebounce`) may live at root. | Yes |
-| `store/` | Domain-specific Zustand stores in `store/<domain>/`. Cross-cutting stores only at root. | Yes |
-| `components/` | Domain-specific components in `components/<domain>/`. Shared UI primitives in `components/ui/`. | Yes |
-| `lib/` | Domain-specific utilities in `lib/<domain>/`. Cross-domain utilities may live at root. | Yes |
-| `types/` | Domain-specific types in `types/<domain>/`. Shared types at root (`types/user.ts`). | Yes |
+| Directory     | Modularization Rule                                                                                                    | Barrel Required |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------- | :-------------: |
+| `services/`   | One subdirectory per domain (e.g., `services/employee/`, `services/auth/`). Only `api-client.ts` may live at the root. |       Yes       |
+| `hooks/`      | Domain-specific hooks in `hooks/<domain>/`. Shared utility hooks (`useDebounce`) may live at root.                     |       Yes       |
+| `store/`      | Domain-specific Zustand stores in `store/<domain>/`. Cross-cutting stores only at root.                                |       Yes       |
+| `components/` | Domain-specific components in `components/<domain>/`. Shared UI primitives in `components/ui/`.                        |       Yes       |
+| `lib/`        | Domain-specific utilities in `lib/<domain>/`. Cross-domain utilities may live at root.                                 |       Yes       |
+| `types/`      | Domain-specific types in `types/<domain>/`. Shared types at root (`types/user.ts`).                                    |       Yes       |
 
 **Barrel File (`index.ts`) Convention**:
 
@@ -243,7 +243,7 @@ These options ensure a modern, strict, and performant TypeScript environment:
 - **noEmit: true**: Relies on the bundler (Vite) for emission, using tsc only for type checking.
 - **jsx: react-jsx**: Enables the modern React JSX transform.
 - **baseUrl: .**: Sets the root for non-relative module resolution.
-- **paths**: Configures path aliases (e.g., @/*) for cleaner imports.
+- **paths**: Configures path aliases (e.g., @/\*) for cleaner imports.
 
 ```jsonc
 {
@@ -261,8 +261,8 @@ These options ensure a modern, strict, and performant TypeScript environment:
     "noEmit": true,
     "jsx": "react-jsx",
     "baseUrl": ".",
-    "paths": { "@/*": ["src/*"] }
-  }
+    "paths": { "@/*": ["src/*"] },
+  },
 }
 ```
 
@@ -279,17 +279,17 @@ These options ensure a modern, strict, and performant TypeScript environment:
 
 ### 5.1 ESLint (v9 Flat Config) - Required Plugins
 
-| Plugin | Purpose |
-|--------|---------|
-| @eslint/js | ESLint recommended rules |
-| typescript-eslint | TypeScript-specific rules |
-| eslint-plugin-react | React-specific rules |
-| eslint-plugin-react-hooks | React Hooks rules |
-| eslint-plugin-import | Import ordering |
-| eslint-plugin-unicorn | Modern JS best practices |
-| eslint-plugin-prettier | Prettier as ESLint rule |
-| eslint-plugin-jsx-a11y | Accessibility checks |
-| eslint-plugin-boundaries | Enforce domain-based modularization and folder dependency rules |
+| Plugin                    | Purpose                                                         |
+| ------------------------- | --------------------------------------------------------------- |
+| @eslint/js                | ESLint recommended rules                                        |
+| typescript-eslint         | TypeScript-specific rules                                       |
+| eslint-plugin-react       | React-specific rules                                            |
+| eslint-plugin-react-hooks | React Hooks rules                                               |
+| eslint-plugin-import      | Import ordering                                                 |
+| eslint-plugin-unicorn     | Modern JS best practices                                        |
+| eslint-plugin-prettier    | Prettier as ESLint rule                                         |
+| eslint-plugin-jsx-a11y    | Accessibility checks                                            |
+| eslint-plugin-boundaries  | Enforce domain-based modularization and folder dependency rules |
 
 ### 5.2 Naming Conventions -- Complete Reference
 
@@ -298,44 +298,46 @@ These options ensure a modern, strict, and performant TypeScript environment:
 A variable name should tell you what it contains, not how it's implemented. If you need a comment to explain what a variable holds, the name is wrong.
 
 **Single-letter variables are strictly prohibited** except:
+
 - Loop index i, j, k inside a for loop
-- Array callback _ for unused parameters
+- Array callback \_ for unused parameters
 - Math coordinates x, y, z (must be documented)
 
 #### Naming Reference Table
 
-| Entity | Convention | Good Example | Bad Example |
-|--------|-----------|-------------|-------------|
-| Files (General) | kebab-case | user-service.ts | UserService.ts |
-| Files (React Components) | PascalCase | UserProfile.tsx | user-profile.tsx |
-| Directories | kebab-case | user-profile/ | UserProfile/ |
-| Variables (general) | camelCase | userCount, isLoading | uc, l, data |
-| Booleans | camelCase + prefix | isLoading, hasError, canEdit | loading, error |
-| Functions | camelCase (verb+noun) | getUserById(), handleSubmit() | get(), doStuff() |
-| Constants (module) | UPPER_SNAKE_CASE | MAX_RETRY_COUNT | maxRetryCount |
-| Types/Interfaces | PascalCase | UserProfileProps | userProfile |
-| Enums | PascalCase + UPPER values | Role.ADMIN | role.admin |
-| Event handlers | handle + Event | handleSubmit | submitHandler |
-| Handler props | on + Event | onSubmit, onClick | submit, clicked |
-| Env variables | UPPER_SNAKE + prefix | VITE_API_URL | apiUrl |
-| Mock data | mock + Entity | mockUser, mockResponse | testData |
+| Entity                   | Convention                | Good Example                  | Bad Example      |
+| ------------------------ | ------------------------- | ----------------------------- | ---------------- |
+| Files (General)          | kebab-case                | user-service.ts               | UserService.ts   |
+| Files (React Components) | PascalCase                | UserProfile.tsx               | user-profile.tsx |
+| Directories              | kebab-case                | user-profile/                 | UserProfile/     |
+| Variables (general)      | camelCase                 | userCount, isLoading          | uc, l, data      |
+| Booleans                 | camelCase + prefix        | isLoading, hasError, canEdit  | loading, error   |
+| Functions                | camelCase (verb+noun)     | getUserById(), handleSubmit() | get(), doStuff() |
+| Constants (module)       | UPPER_SNAKE_CASE          | MAX_RETRY_COUNT               | maxRetryCount    |
+| Types/Interfaces         | PascalCase                | UserProfileProps              | userProfile      |
+| Enums                    | PascalCase + UPPER values | Role.ADMIN                    | role.admin       |
+| Event handlers           | handle + Event            | handleSubmit                  | submitHandler    |
+| Handler props            | on + Event                | onSubmit, onClick             | submit, clicked  |
+| Env variables            | UPPER_SNAKE + prefix      | VITE_API_URL                  | apiUrl           |
+| Mock data                | mock + Entity             | mockUser, mockResponse        | testData         |
 
 #### Banned Variable Names
 
-| Banned | Why | Use Instead |
-|--------|-----|-------------|
-| const data | Means anything | const users, const response |
-| const temp | Temporary to whom? | const formattedDate |
-| const arr | Hungarian + meaningless | const permissions |
-| const obj | Everything is an object | const config |
-| const str | Hungarian notation | const message |
-| const result | All functions return a result | const validationResult |
-| const myVar | my prefix adds nothing | const username |
-| function handle() | Handle what? | function handleFormSubmit() |
+| Banned            | Why                           | Use Instead                 |
+| ----------------- | ----------------------------- | --------------------------- |
+| const data        | Means anything                | const users, const response |
+| const temp        | Temporary to whom?            | const formattedDate         |
+| const arr         | Hungarian + meaningless       | const permissions           |
+| const obj         | Everything is an object       | const config                |
+| const str         | Hungarian notation            | const message               |
+| const result      | All functions return a result | const validationResult      |
+| const myVar       | my prefix adds nothing        | const username              |
+| function handle() | Handle what?                  | function handleFormSubmit() |
 
 #### Boolean Naming
 
 Booleans must use a prefix that makes true/false obvious:
+
 ```
 GOOD: isLoading, hasPermission, canSubmit, shouldRender, isVisible, wasProcessed
 BAD:  loading, permission, submit, render, visible, processed
@@ -376,67 +378,67 @@ Configuration for enforcing domain-based folder modularization across **all** di
 
 ```javascript
 // eslint.config.js (flat config)
-import boundaries from "eslint-plugin-boundaries";
-import importPlugin from "eslint-plugin-import";
+import boundaries from 'eslint-plugin-boundaries';
+import importPlugin from 'eslint-plugin-import';
 
 export default [
   // ... other configs
   {
     plugins: { boundaries, import: importPlugin },
     settings: {
-      "boundaries/include": ["src/**/*"],
-      "boundaries/elements": [
+      'boundaries/include': ['src/**/*'],
+      'boundaries/elements': [
         // Shared/global files (can be imported by any domain)
         {
-          mode: "full",
-          type: "shared",
+          mode: 'full',
+          type: 'shared',
           pattern: [
-            "src/services/api-client.ts",
-            "src/hooks/use-debounce.ts",
-            "src/hooks/use-media-query.ts",
-            "src/components/ui/**",
-            "src/lib/*.ts",
-            "src/lib/*.tsx",
-            "src/types/!(*/**).ts",
+            'src/services/api-client.ts',
+            'src/hooks/use-debounce.ts',
+            'src/hooks/use-media-query.ts',
+            'src/components/ui/**',
+            'src/lib/*.ts',
+            'src/lib/*.tsx',
+            'src/types/!(*/**).ts',
           ],
         },
         // Employee domain -- all directories
         {
-          mode: "full",
-          type: "employee",
+          mode: 'full',
+          type: 'employee',
           pattern: [
-            "src/services/employee/**",
-            "src/hooks/employee/**",
-            "src/store/employee/**",
-            "src/components/employee/**",
-            "src/lib/employee/**",
-            "src/types/employee/**",
+            'src/services/employee/**',
+            'src/hooks/employee/**',
+            'src/store/employee/**',
+            'src/components/employee/**',
+            'src/lib/employee/**',
+            'src/types/employee/**',
           ],
         },
         // Auth domain -- all directories
         {
-          mode: "full",
-          type: "auth",
+          mode: 'full',
+          type: 'auth',
           pattern: [
-            "src/services/auth/**",
-            "src/hooks/auth/**",
-            "src/store/auth/**",
-            "src/components/auth/**",
-            "src/lib/auth/**",
-            "src/types/auth/**",
+            'src/services/auth/**',
+            'src/hooks/auth/**',
+            'src/store/auth/**',
+            'src/components/auth/**',
+            'src/lib/auth/**',
+            'src/types/auth/**',
           ],
         },
         // Users domain -- all directories
         {
-          mode: "full",
-          type: "users",
+          mode: 'full',
+          type: 'users',
           pattern: [
-            "src/services/users/**",
-            "src/hooks/users/**",
-            "src/store/users/**",
-            "src/components/users/**",
-            "src/lib/users/**",
-            "src/types/users/**",
+            'src/services/users/**',
+            'src/hooks/users/**',
+            'src/store/users/**',
+            'src/components/users/**',
+            'src/lib/users/**',
+            'src/types/users/**',
           ],
         },
       ],
@@ -445,44 +447,48 @@ export default [
       // === BOUNDARIES RULES ===
 
       // BLOCK: flat/orphaned domain files at directory roots (enforces subdirectory pattern)
-      "boundaries/entry-point": [
-        "error",
+      'boundaries/entry-point': [
+        'error',
         {
-          default: "disallow",
+          default: 'disallow',
           rules: [
             // Allow ONLY api-client.ts at the services/ root level
             {
-              target: ["src/services/**/*.ts"],
-              allow: "src/services/api-client.ts",
+              target: ['src/services/**/*.ts'],
+              allow: 'src/services/api-client.ts',
             },
             // Allow shared utility hooks at root but NOT domain-specific ones
             {
-              target: ["src/hooks/use-employee*.ts", "src/hooks/use-auth*.ts", "src/hooks/use-user*.ts"],
-              disallow: "src/hooks/",
+              target: [
+                'src/hooks/use-employee*.ts',
+                'src/hooks/use-auth*.ts',
+                'src/hooks/use-user*.ts',
+              ],
+              disallow: 'src/hooks/',
             },
             // No domain-specific files at store/ root
             {
-              target: ["src/store/**/*.ts"],
-              allow: "src/store/index.ts",
+              target: ['src/store/**/*.ts'],
+              allow: 'src/store/index.ts',
             },
           ],
         },
       ],
 
       // BLOCK: cross-domain imports (e.g., employee component cannot import from auth services)
-      "boundaries/element-types": [
-        "error",
+      'boundaries/element-types': [
+        'error',
         {
-          default: "disallow",
+          default: 'disallow',
           rules: [
             // Shared files can be imported by any domain
-            { from: ["employee", "auth", "users"], allow: ["shared"] },
+            { from: ['employee', 'auth', 'users'], allow: ['shared'] },
             // Domains cannot import from other domains
-            { from: ["employee"], disallow: ["auth", "users"] },
-            { from: ["auth"], disallow: ["employee", "users"] },
-            { from: ["users"], disallow: ["employee", "auth"] },
+            { from: ['employee'], disallow: ['auth', 'users'] },
+            { from: ['auth'], disallow: ['employee', 'users'] },
+            { from: ['users'], disallow: ['employee', 'auth'] },
             // Shared can import from shared
-            { from: ["shared"], allow: ["shared"] },
+            { from: ['shared'], allow: ['shared'] },
           ],
         },
       ],
@@ -490,47 +496,49 @@ export default [
       // === IMPORT RULES: BLOCK deep imports bypassing barrel files ===
 
       // BLOCK: importing from a non-index file inside a domain subdirectory
-      "import/no-internal-modules": [
-        "error",
+      'import/no-internal-modules': [
+        'error',
         {
           allow: [
             // Only allow importing the barrel (index.ts) from each domain directory
-            "src/services/*/index",
-            "src/hooks/*/index",
-            "src/store/*/index",
-            "src/components/*/index",
-            "src/lib/*/index",
-            "src/types/*/index",
+            'src/services/*/index',
+            'src/hooks/*/index',
+            'src/store/*/index',
+            'src/components/*/index',
+            'src/lib/*/index',
+            'src/types/*/index',
             // Allow shared/utility files
-            "src/services/api-client",
-            "src/hooks/use-debounce",
-            "src/hooks/use-media-query",
-            "src/components/ui/**",
-            "src/lib/*",
-            "src/types/*",
+            'src/services/api-client',
+            'src/hooks/use-debounce',
+            'src/hooks/use-media-query',
+            'src/components/ui/**',
+            'src/lib/*',
+            'src/types/*',
             // Allow root-level globals
-            "src/app/**",
-            "src/styles/**",
-            "src/test/**",
+            'src/app/**',
+            'src/styles/**',
+            'src/test/**',
           ],
         },
       ],
 
       // BLOCK: importing from index files across domain boundaries (backup for boundaries plugin)
-      "import/no-restricted-paths": [
-        "error",
+      'import/no-restricted-paths': [
+        'error',
         {
           zones: [
             // Employee domain may not import from other domains
             {
-              target: "./src/**/employee/**",
-              from: "./src/**/auth/**",
-              message: "Employee domain must not import from Auth domain. Use shared interfaces instead.",
+              target: './src/**/employee/**',
+              from: './src/**/auth/**',
+              message:
+                'Employee domain must not import from Auth domain. Use shared interfaces instead.',
             },
             {
-              target: "./src/**/employee/**",
-              from: "./src/**/users/**",
-              message: "Employee domain must not import from Users domain. Use shared interfaces instead.",
+              target: './src/**/employee/**',
+              from: './src/**/users/**',
+              message:
+                'Employee domain must not import from Users domain. Use shared interfaces instead.',
             },
             // (repeat for each domain pair)
           ],
@@ -543,12 +551,12 @@ export default [
 
 **Enforcement Summary**:
 
-| Rule | What It Catches | Severity |
-|------|----------------|----------|
-| `boundaries/entry-point` | Flat domain files at directory roots (e.g., `services/employeeService.ts` instead of `services/employee/`) | `error` |
-| `boundaries/element-types` | Cross-domain imports (e.g., `employee` component importing from `auth` services) | `error` |
-| `import/no-internal-modules` | **Deep imports bypassing barrel files** (e.g., `from '@/services/employee/employee-bio-detail.service'` instead of `from '@/services/employee'`) | `error` |
-| `import/no-restricted-paths` | Backup enforcement of cross-domain import restrictions | `error` |
+| Rule                         | What It Catches                                                                                                                                  | Severity |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `boundaries/entry-point`     | Flat domain files at directory roots (e.g., `services/employeeService.ts` instead of `services/employee/`)                                       | `error`  |
+| `boundaries/element-types`   | Cross-domain imports (e.g., `employee` component importing from `auth` services)                                                                 | `error`  |
+| `import/no-internal-modules` | **Deep imports bypassing barrel files** (e.g., `from '@/services/employee/employee-bio-detail.service'` instead of `from '@/services/employee'`) | `error`  |
+| `import/no-restricted-paths` | Backup enforcement of cross-domain import restrictions                                                                                           | `error`  |
 
 **Barrel File Enforcement Flow**:
 
@@ -567,6 +575,7 @@ export default [
 ```
 
 **Adding a New Domain**:
+
 1. Create the domain subdirectories across all folders:
    ```
    services/<domain>/
@@ -601,17 +610,17 @@ Is it a transformer?--> format/convert prefix
 const d = new Date();
 const r = await fetch('/api/users');
 const arr = [1, 2, 3];
-const temp = users.filter(u => u.active);
-function get() { }
-function handle() { }
+const temp = users.filter((u) => u.active);
+function get() {}
+function handle() {}
 
 // GOOD -- Self-documenting
 const currentDate = new Date();
 const response = await fetch('/api/users');
 const userIds = [1, 2, 3];
-const activeUsers = users.filter(user => user.isActive);
-function getActiveUsers() { }
-function handleFormSubmit() { }
+const activeUsers = users.filter((user) => user.isActive);
+function getActiveUsers() {}
+function handleFormSubmit() {}
 ```
 
 ### 5.3 Import Order Standard
@@ -632,6 +641,7 @@ import { UserCard } from './user-card';
 ### 5.4 Lovable-Generated Code Handling
 
 When Lovable generates UI templates, always:
+
 1. Run generated code through ESLint + Prettier before committing.
 2. Extract reusable components into components/shared/ directory.
 3. Add proper TypeScript types to any untyped props.
@@ -663,6 +673,7 @@ export default {
 ### 6.2 Format-On-Save (VS Code)
 
 Every project must have .vscode/settings.json:
+
 ```json
 {
   "editor.formatOnSave": true,
@@ -741,7 +752,10 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
   }
 
   componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
-    logger.error('ErrorBoundary caught an error', { error, componentStack: errorInfo.componentStack });
+    logger.error('ErrorBoundary caught an error', {
+      error,
+      componentStack: errorInfo.componentStack,
+    });
     this.props.onError?.(error, errorInfo);
   }
 
@@ -754,7 +768,10 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
         <div role="alert" className="flex flex-col items-center justify-center min-h-[400px] p-8">
           <h2 className="text-xl font-semibold mb-2">Something went wrong</h2>
           <p className="text-muted-foreground mb-4">An unexpected error occurred.</p>
-          <button onClick={this.handleReset} className="px-4 py-2 bg-primary text-primary-foreground rounded-md">
+          <button
+            onClick={this.handleReset}
+            className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
+          >
             Try Again
           </button>
         </div>
@@ -766,6 +783,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 ```
 
 **Usage**:
+
 ```tsx
 // Route-level wrapping
 <ErrorBoundary onError={(err) => captureException(err)}>
@@ -774,6 +792,7 @@ export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundarySt
 ```
 
 **Rules**:
+
 - One ErrorBoundary per route (not per component) for granularity
 - Log errors to Sentry via `onError` callback
 - Never wrap individual small components (<50 lines) in their own ErrorBoundary
@@ -806,6 +825,7 @@ export function EmployeeRoutes() {
 ```
 
 **Rules**:
+
 - Every page/route component must use `React.lazy()` + dynamic `import()`
 - Every lazy route must have a `<Suspense>` wrapper with a skeleton fallback
 - Prefetch critical routes (dashboard, home) on link hover or visibility
@@ -816,12 +836,12 @@ export function EmployeeRoutes() {
 
 **Loading States**:
 
-| Context | Pattern | When |
-|---------|---------|------|
-| Page load | Skeleton screen | Initial page navigation |
-| Table/list data | Skeleton rows or spinner overlay | Data fetching |
-| Button action | Spinner inside button + disabled state | Form submit, save, delete |
-| File upload | Progress bar | Large uploads |
+| Context         | Pattern                                | When                      |
+| --------------- | -------------------------------------- | ------------------------- |
+| Page load       | Skeleton screen                        | Initial page navigation   |
+| Table/list data | Skeleton rows or spinner overlay       | Data fetching             |
+| Button action   | Spinner inside button + disabled state | Form submit, save, delete |
+| File upload     | Progress bar                           | Large uploads             |
 
 Debounce loader appearance: do not show any loading indicator for fetches that resolve in < 300ms (avoid flash).
 
@@ -832,7 +852,8 @@ function EmployeePage() {
 
   if (isLoading) return <PageSkeleton />;
   if (isError) return <ErrorState error={error} onRetry={refetch} />;
-  if (!data) return <EmptyState message="No employee data found" action={<CreateEmployeeButton />} />;
+  if (!data)
+    return <EmptyState message="No employee data found" action={<CreateEmployeeButton />} />;
 
   return <EmployeeProfile employee={data} />;
 }
@@ -849,14 +870,22 @@ interface ErrorStateProps {
 
 export function ErrorState({ error, onRetry, title = 'Something went wrong' }: ErrorStateProps) {
   return (
-    <div role="alert" className="flex flex-col items-center justify-center min-h-[300px] p-6 text-center">
+    <div
+      role="alert"
+      className="flex flex-col items-center justify-center min-h-[300px] p-6 text-center"
+    >
       <AlertTriangle className="w-12 h-12 text-destructive mb-4" />
       <h3 className="text-lg font-semibold mb-1">{title}</h3>
       <p className="text-muted-foreground mb-4 max-w-md">
-        {typeof error === 'string' ? error : error?.message || 'An unexpected error occurred. Please try again.'}
+        {typeof error === 'string'
+          ? error
+          : error?.message || 'An unexpected error occurred. Please try again.'}
       </p>
       {onRetry && (
-        <button onClick={onRetry} className="px-4 py-2 bg-primary text-primary-foreground rounded-md">
+        <button
+          onClick={onRetry}
+          className="px-4 py-2 bg-primary text-primary-foreground rounded-md"
+        >
           Try Again
         </button>
       )}
@@ -869,16 +898,16 @@ export function ErrorState({ error, onRetry, title = 'Something went wrong' }: E
 
 Every UI component must meet WCAG 2.1 AA standards. The following are **non-negotiable**:
 
-| Requirement | Implementation |
-|-------------|---------------|
-| Color contrast | Minimum 4.5:1 for text, 3:1 for large text. Verify with axe DevTools. |
-| Keyboard navigation | All interactive elements reachable via Tab. Logical tab order. Visible focus ring. |
-| Skip link | Skip-to-content link as first focusable element on every page. |
-| Screen reader | `aria-label` on icon-only buttons. `aria-describedby` linking inputs to error messages. |
-| Form accessibility | Every `<input>` must have an associated `<label>`. Error messages linked via `aria-describedby`. |
-| Modals/Dialogs | Focus trap inside modal. Escape to close. `aria-modal="true"`. |
-| Images | All `<img>` must have `alt` attribute (descriptive or empty for decorative). |
-| Landmarks | Use semantic HTML: `<header>`, `<main>`, `<nav>`, `<footer>`. |
+| Requirement         | Implementation                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| Color contrast      | Minimum 4.5:1 for text, 3:1 for large text. Verify with axe DevTools.                            |
+| Keyboard navigation | All interactive elements reachable via Tab. Logical tab order. Visible focus ring.               |
+| Skip link           | Skip-to-content link as first focusable element on every page.                                   |
+| Screen reader       | `aria-label` on icon-only buttons. `aria-describedby` linking inputs to error messages.          |
+| Form accessibility  | Every `<input>` must have an associated `<label>`. Error messages linked via `aria-describedby`. |
+| Modals/Dialogs      | Focus trap inside modal. Escape to close. `aria-modal="true"`.                                   |
+| Images              | All `<img>` must have `alt` attribute (descriptive or empty for decorative).                     |
+| Landmarks           | Use semantic HTML: `<header>`, `<main>`, `<nav>`, `<footer>`.                                    |
 
 **Required tools**: axe DevTools browser extension, eslint-plugin-jsx-a11y (already enforced via ESLint).
 
@@ -891,6 +920,7 @@ Every UI component must meet WCAG 2.1 AA standards. The following are **non-nego
 Every data table MUST support sortable column headers, global and per-column filtering, debounced search, persistent sort preference, visible active filters, and a no-results state.
 
 Required table features:
+
 - Sort on click for all non-action columns with sort direction indicator
 - Filter input above table with 300-400ms debounce
 - Column visibility toggle
@@ -903,6 +933,7 @@ Required table features:
 #### Jump-to-Top Button (Required on Long Pages)
 
 Pages taller than 2x viewport MUST include a fixed back-to-top button:
+
 - Appears after scrolling 500px
 - Smooth scroll to top
 - Hidden when at top
@@ -912,6 +943,7 @@ Pages taller than 2x viewport MUST include a fixed back-to-top button:
 #### Go Back / Go to Previous (Context-Aware Navigation)
 
 Every page except the home/landing page MUST provide navigation aids:
+
 - Breadcrumbs showing full path: Home > Reports > Financial > Q1 2026
 - Back button returning to parent list or previous page
 - Context-aware return preserving list filters and pagination via query params
@@ -919,6 +951,7 @@ Every page except the home/landing page MUST provide navigation aids:
 #### Corporate Branding (Required)
 
 Every application MUST implement consistent corporate branding:
+
 - Primary logo in header/sidebar, clickable to home, with favicon and Apple touch icon
 - Brand colors defined in Tailwind config with minimum 4.5:1 contrast ratio
 - Typography: Inter or system fonts, defined heading scale, 1rem base body text
@@ -928,7 +961,6 @@ Every application MUST implement consistent corporate branding:
 
 ---
 
-
 ---
 
 ## 8. Testing Standards
@@ -947,12 +979,12 @@ Every application MUST implement consistent corporate branding:
 
 ### 8.2 Coverage Requirements
 
-| Level | Minimum Coverage | Notes |
-|-------|-----------------|-------|
-| Line | 80% | Enforced in CI pipeline |
-| Branch | 75% | Enforced in CI pipeline |
-| New Code | 90% | PR checks must pass |
-| Critical Paths | 100% | Auth, payments, data export |
+| Level          | Minimum Coverage | Notes                       |
+| -------------- | ---------------- | --------------------------- |
+| Line           | 80%              | Enforced in CI pipeline     |
+| Branch         | 75%              | Enforced in CI pipeline     |
+| New Code       | 90%              | PR checks must pass         |
+| Critical Paths | 100%             | Auth, payments, data export |
 
 ### 8.3 Test Structure
 
@@ -1011,6 +1043,7 @@ main              # Production-ready code
 **Types**: feat, fix, security, perf, docs, style, refactor, test, chore
 
 **Examples**:
+
 ```
 feat(auth): add JWT refresh token flow
 fix(profile): resolve avatar upload timeout
@@ -1020,13 +1053,14 @@ chore(deps): upgrade React to v19
 
 ### 9.3 Git Hooks (Husky)
 
-| Hook | Action | Tool |
-|------|--------|------|
-| pre-commit | Lint staged files | lint-staged |
-| commit-msg | Validate commit message | commitlint |
-| pre-push | Run lint + modularization + type check + tests | eslint + check-modularization + tsc + vitest |
+| Hook       | Action                                         | Tool                                         |
+| ---------- | ---------------------------------------------- | -------------------------------------------- |
+| pre-commit | Lint staged files                              | lint-staged                                  |
+| commit-msg | Validate commit message                        | commitlint                                   |
+| pre-push   | Run lint + modularization + type check + tests | eslint + check-modularization + tsc + vitest |
 
 **lint-staged config**:
+
 ```json
 {
   "src/**/*.{ts,tsx}": ["eslint --fix", "prettier --write"],
@@ -1058,9 +1092,11 @@ chore(deps): upgrade React to v19
 
 ```markdown
 ## Description
+
 [Brief description of the change]
 
 ## Type of Change
+
 - [ ] feat: New feature
 - [ ] fix: Bug fix
 - [ ] refactor: Code restructure
@@ -1069,6 +1105,7 @@ chore(deps): upgrade React to v19
 - [ ] chore: Build/tooling
 
 ## Testing Done
+
 - [ ] Unit tests added/updated
 - [ ] Manual testing performed
 - [ ] E2E tests (if applicable)
@@ -1076,6 +1113,7 @@ chore(deps): upgrade React to v19
 ## Screenshots (if UI change)
 
 ## Checklist
+
 - [ ] Code follows project style guidelines
 - [ ] Self-review completed
 - [ ] No breaking changes (or documented)
@@ -1086,31 +1124,37 @@ chore(deps): upgrade React to v19
 ### 10.3 Review Checklist
 
 **Functional**:
+
 - Does the code do what its supposed to?
 - Are edge cases handled (loading, empty, error states)?
 - Are there appropriate tests?
 
 **Architecture**:
+
 - Is the component properly decomposed?
 - Is business logic separated from UI?
 - Are state management decisions appropriate?
 
 **Security**:
+
 - Are user inputs validated and sanitized?
 - Are secrets exposed anywhere?
 - Is authentication/authorization enforced?
 
 **Performance**:
+
 - Are there unnecessary re-renders?
 - Are large lists properly virtualized?
 - Are images optimized?
 
 **Accessibility**:
+
 - Are all interactive elements keyboard-accessible?
 - Do images have alt text?
 - Is color contrast sufficient?
 
 **Lovable Code**:
+
 - Has the generated code been cleaned up (no unused imports, proper types)?
 - Are generated components properly integrated?
 
@@ -1186,7 +1230,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
-        with: { node-version: "20" }
+        with: { node-version: '20' }
       - uses: pnpm/action-setup@v2
         with: { version: 9 }
 
@@ -1244,11 +1288,11 @@ CMD ["node", "dist/server.js"]
 
 ### 12.2 Environment Strategy
 
-| Environment | Purpose | Deploy Trigger | Replicas |
-|-------------|---------|---------------|----------|
-| Dev | Developer testing | Push to develop | 1 |
-| Staging | QA + UAT | Push to main | 2 |
-| Production | Live | Manual approval | 3+ (auto-scale) |
+| Environment | Purpose           | Deploy Trigger  | Replicas        |
+| ----------- | ----------------- | --------------- | --------------- |
+| Dev         | Developer testing | Push to develop | 1               |
+| Staging     | QA + UAT          | Push to main    | 2               |
+| Production  | Live              | Manual approval | 3+ (auto-scale) |
 
 ### 12.3 Deployment Checklist
 
@@ -1267,17 +1311,17 @@ CMD ["node", "dist/server.js"]
 
 ### 13.1 Mandatory Security Measures
 
-| Measure | Implementation | Priority |
-|---------|---------------|----------|
-| HTTPS | Enforced at ingress level | Critical |
-| CSP Headers | Content Security Policy via server headers | Critical |
-| Input Validation | Zod schemas for all user inputs | Critical |
-| XSS Protection | React escaping + DOMPurify for raw HTML | Critical |
-| CSRF Protection | SameSite cookies + CSRF tokens | High |
-| Rate Limiting | API endpoints (especially auth) | High |
-| Dependency Scanning | npm audit / Snyk in CI | High |
-| Secret Scanning | GitLeaks / TruffleHog in CI | Medium |
-| CORS | Whitelist allowed origins | High |
+| Measure             | Implementation                             | Priority |
+| ------------------- | ------------------------------------------ | -------- |
+| HTTPS               | Enforced at ingress level                  | Critical |
+| CSP Headers         | Content Security Policy via server headers | Critical |
+| Input Validation    | Zod schemas for all user inputs            | Critical |
+| XSS Protection      | React escaping + DOMPurify for raw HTML    | Critical |
+| CSRF Protection     | SameSite cookies + CSRF tokens             | High     |
+| Rate Limiting       | API endpoints (especially auth)            | High     |
+| Dependency Scanning | npm audit / Snyk in CI                     | High     |
+| Secret Scanning     | GitLeaks / TruffleHog in CI                | Medium   |
+| CORS                | Whitelist allowed origins                  | High     |
 
 ### 13.2 Secrets NEVER Committed
 
@@ -1316,23 +1360,28 @@ Console and debugger rules: `console.log`, `console.debug`, `console.info`, `con
 Allowed only: `console.warn()` and `console.error()`. Use a structured logger instead.
 
 ESLint rules:
+
 ```
 'no-console': ['error', { allow: ['warn', 'error'] }],
 'no-debugger': 'error',
 ```
 
 Structured logger replacement:
+
 ```typescript
 const isDev = import.meta.env.DEV;
 
 export const logger = {
-  debug: (...args: unknown[]) => { if (isDev) console.debug('[DEBUG]', ...args); },
+  debug: (...args: unknown[]) => {
+    if (isDev) console.debug('[DEBUG]', ...args);
+  },
   warn: (...args: unknown[]) => console.warn('[WARN]', ...args),
   error: (...args: unknown[]) => console.error('[ERROR]', ...args),
 };
 ```
 
 Production stripping (Vite/Terser):
+
 ```typescript
 build: {
   minify: 'terser',
@@ -1354,6 +1403,7 @@ build: {
 Sensitive fields must NEVER appear in network responses visible in the browser Network tab.
 
 Mask these data types:
+
 - Auth tokens (JWT, session IDs)
 - Passwords, password hashes, salts
 - PII (SSN, phone, address, email)
@@ -1364,15 +1414,30 @@ Mask these data types:
 Strategy 1: Use public DTOs in service layer so the backend only returns safe fields.
 
 Strategy 2: Global response interceptor masking sensitive fields.
+
 ```typescript
 class ApiClient {
   private SENSITIVE_PATTERNS = [
-    'password', 'passwordhash', 'salt',
-    'ssn', 'socialsecurity', 'nationalid',
-    'internalid', 'databaseid', 'legacyid',
-    'creditcardnumber', 'cvv', 'bankaccount',
-    'apikey', 'privatekey', 'token', 'sessionid',
-    'salary', 'income', 'debt', 'revenue',
+    'password',
+    'passwordhash',
+    'salt',
+    'ssn',
+    'socialsecurity',
+    'nationalid',
+    'internalid',
+    'databaseid',
+    'legacyid',
+    'creditcardnumber',
+    'cvv',
+    'bankaccount',
+    'apikey',
+    'privatekey',
+    'token',
+    'sessionid',
+    'salary',
+    'income',
+    'debt',
+    'revenue',
   ];
 
   constructor() {
@@ -1384,11 +1449,11 @@ class ApiClient {
 
   private maskSensitiveData(data: unknown): unknown {
     if (typeof data !== 'object' || data === null) return data;
-    if (Array.isArray(data)) return data.map(item => this.maskSensitiveData(item));
+    if (Array.isArray(data)) return data.map((item) => this.maskSensitiveData(item));
     const masked: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(data)) {
       const lowerKey = key.toLowerCase();
-      if (this.SENSITIVE_PATTERNS.some(p => lowerKey.includes(p))) {
+      if (this.SENSITIVE_PATTERNS.some((p) => lowerKey.includes(p))) {
         masked[key] = '[REDACTED]';
       } else if (typeof value === 'object' && value !== null) {
         masked[key] = this.maskSensitiveData(value);
@@ -1402,6 +1467,7 @@ class ApiClient {
 ```
 
 Strategy 3: Disable caching for sensitive endpoints.
+
 ```typescript
 export const sensitiveService = {
   getFinancialData: () =>
@@ -1412,22 +1478,24 @@ export const sensitiveService = {
 ```
 
 Production verification checklist:
+
 - Open DevTools > Network tab
 - Verify no Authorization header visible (use httpOnly cookies)
 - Verify no passwords, SSNs, or internal IDs in request bodies
 - Verify masked responses show [REDACTED] for sensitive fields
 
-
 ### 13.6 Authorization: RBAC, ABAC, Guards, and DevMode Safety
 
 Required authorization model: RBAC baseline, ABAC for policy restrictions. Enforced in route guards, component guards, and data/service guards. Backend must also enforce policy independently.
 
 Core rules:
+
 - No feature, page, action, button, table row, or API call may be rendered or executed without an authorization check
 - Authorized state MUST NOT be derivable from the UI alone in developer mode
 - Authorization checks MUST be centralized
 
 RBAC structure:
+
 ```tsx
 export enum Role {
   SUPER_ADMIN = 'super_admin',
@@ -1448,6 +1516,7 @@ export enum Permission {
 ```
 
 ABAC structure:
+
 ```tsx
 export type AbacContext = {
   role: Role;
@@ -1475,13 +1544,14 @@ export const canAccessResource: AbacPolicy = (ctx, action, resource) => {
 ```
 
 Route guards:
+
 ```tsx
 export function RequireAuth({ roles, permissions, abacCheck, children }: RequireAuthProps) {
   const auth = useAuth();
   const location = useLocation();
-  if (!auth.isAuthenticated) return <Navigate to='/login' state={{ from: location }} replace />;
+  if (!auth.isAuthenticated) return <Navigate to="/login" state={{ from: location }} replace />;
   const hasRole = roles ? roles.includes(auth.role) : true;
-  const hasPermission = permissions ? permissions.every(p => auth.permissions.includes(p)) : true;
+  const hasPermission = permissions ? permissions.every((p) => auth.permissions.includes(p)) : true;
   const abacPass = abacCheck ? abacCheck(auth.abacContext) : true;
   if (!hasRole || !hasPermission || !abacPass) return <Forbidden />;
   return <>{children}</>;
@@ -1489,11 +1559,12 @@ export function RequireAuth({ roles, permissions, abacCheck, children }: Require
 ```
 
 Component guards:
+
 ```tsx
 export function Can({ roles, permissions, abacCheck, fallback = null, children }: CanProps) {
   const auth = useAuth();
   const hasRole = roles ? roles.includes(auth.role) : true;
-  const hasPermission = permissions ? permissions.some(p => auth.permissions.includes(p)) : true;
+  const hasPermission = permissions ? permissions.some((p) => auth.permissions.includes(p)) : true;
   const abacPass = abacCheck ? abacCheck(auth.abacContext) : true;
   if (!hasRole || !hasPermission || !abacPass) return <>{fallback}</>;
   return <>{children}</>;
@@ -1501,6 +1572,7 @@ export function Can({ roles, permissions, abacCheck, fallback = null, children }
 ```
 
 Data guards:
+
 ```tsx
 export function useAuthorizedUser(id: string) {
   const auth = useAuth();
@@ -1508,7 +1580,13 @@ export function useAuthorizedUser(id: string) {
     queryKey: ['user', id],
     queryFn: async () => {
       const data = await usersService.getById(id);
-      if (!canAccessResource(auth.abacContext, 'users:read', { type: 'user', id, tenantId: data.tenantId })) {
+      if (
+        !canAccessResource(auth.abacContext, 'users:read', {
+          type: 'user',
+          id,
+          tenantId: data.tenantId,
+        })
+      ) {
         throw new Error('Forbidden');
       }
       return data;
@@ -1518,11 +1596,13 @@ export function useAuthorizedUser(id: string) {
 ```
 
 DevMode safety:
+
 - Dev-only endpoints, hidden buttons, debug flags MUST NOT bypass authorization
 - Hardcoded ADMIN=true query params, secret URL paths MUST be treated as security bugs
 - Impersonation and elevated roles MUST be logged and auditable
 
 ESLint enforcement:
+
 ```
 no-restricted-syntax: ['error', {
   selector: "MemberExpression[property.name='role']",
@@ -1531,30 +1611,32 @@ no-restricted-syntax: ['error', {
 ```
 
 Authorization code review checklist:
+
 - Every protected route uses RequireAuth
 - Every sensitive action uses Can
 - ABAC policies for tenant, ownership, region, or time restrictions
 - No inline role/permission checks in JSX
 - No hidden dev paths bypassing authorization
 - No mock authorization used outside tests
+
 ## 14. Monitoring & Observability
 
 ### 14.1 Required Instrumentation
 
-| Tool | Purpose | Implementation |
-|------|---------|---------------|
-| Sentry | Error tracking (frontend) | @sentry/react |
-| Lighthouse CI | Performance budget | GitHub Action |
-| Console Logging | Structured logging | No console.log in production |
+| Tool            | Purpose                   | Implementation               |
+| --------------- | ------------------------- | ---------------------------- |
+| Sentry          | Error tracking (frontend) | @sentry/react                |
+| Lighthouse CI   | Performance budget        | GitHub Action                |
+| Console Logging | Structured logging        | No console.log in production |
 
 ### 14.2 Performance Budget
 
-| Metric | Budget | Enforcement |
-|--------|--------|-------------|
-| First Contentful Paint (FCP) | < 1.5s | Lighthouse CI |
-| Largest Contentful Paint (LCP) | < 2.5s | Lighthouse CI |
-| Time to Interactive (TTI) | < 3.5s | Lighthouse CI |
-| Bundle Size (initial) | < 200KB gzipped | size-limit package |
+| Metric                         | Budget          | Enforcement        |
+| ------------------------------ | --------------- | ------------------ |
+| First Contentful Paint (FCP)   | < 1.5s          | Lighthouse CI      |
+| Largest Contentful Paint (LCP) | < 2.5s          | Lighthouse CI      |
+| Time to Interactive (TTI)      | < 3.5s          | Lighthouse CI      |
+| Bundle Size (initial)          | < 200KB gzipped | size-limit package |
 
 ---
 
@@ -1562,21 +1644,23 @@ Authorization code review checklist:
 
 ### 15.1 Minimum Required Docs
 
-| File | Purpose | Required |
-|------|---------|----------|
-| README.md | Project overview, setup, commands | Yes |
-| CONTRIBUTING.md | How to contribute, coding standards | Yes |
-| .env.example | All required environment variables | Yes |
-| docs/architecture.md | High-level architecture decisions | For complex projects |
-| docs/onboarding.md | Setup checklist for new developers | For monorepos |
+| File                 | Purpose                             | Required             |
+| -------------------- | ----------------------------------- | -------------------- |
+| README.md            | Project overview, setup, commands   | Yes                  |
+| CONTRIBUTING.md      | How to contribute, coding standards | Yes                  |
+| .env.example         | All required environment variables  | Yes                  |
+| docs/architecture.md | High-level architecture decisions   | For complex projects |
+| docs/onboarding.md   | Setup checklist for new developers  | For monorepos        |
 
 ### 15.2 README Template
 
-```markdown
+````markdown
 # Project Name
+
 [Brief description]
 
 ## Quick Start
+
 ```bash
 git clone <repo>
 cd project
@@ -1584,8 +1668,10 @@ pnpm install
 cp .env.example .env
 pnpm dev
 ```
+````
 
 ## Available Scripts
+
 | Command | Description |
 | pnpm dev | Start development server |
 | pnpm build | Build for production |
@@ -1593,8 +1679,10 @@ pnpm dev
 | pnpm lint | Lint code |
 
 ## Environment Variables
+
 [Table of required env vars]
-```
+
+````
 
 ---
 
@@ -1611,7 +1699,7 @@ pnpm lint             # Lint all files
 pnpm format           # Format with Prettier
 pnpm check-types      # TypeScript type checking
 pnpm audit            # Security audit
-```
+````
 
 ### 16.2 File Naming Reference
 
@@ -1627,19 +1715,19 @@ constants/auth.ts         # Constants
 
 ### 16.3 Key Config Files
 
-| File | Purpose |
-|------|---------|
-| tsconfig.json | TypeScript configuration |
-| vite.config.ts | Vite build configuration |
-| eslint.config.js | ESLint configuration |
-| .prettierrc | Prettier formatting rules |
-| .husky/pre-commit | Pre-commit hook (lint-staged) |
-| commitlint.config.js | Conventional commit rules |
-| .github/workflows/ci.yml | CI pipeline |
-| .github/workflows/cd.yml | CD pipeline |
-| Dockerfile | Container build |
-| docker-compose.yml | Local development |
-| .env.example | Documented env variables |
+| File                     | Purpose                       |
+| ------------------------ | ----------------------------- |
+| tsconfig.json            | TypeScript configuration      |
+| vite.config.ts           | Vite build configuration      |
+| eslint.config.js         | ESLint configuration          |
+| .prettierrc              | Prettier formatting rules     |
+| .husky/pre-commit        | Pre-commit hook (lint-staged) |
+| commitlint.config.js     | Conventional commit rules     |
+| .github/workflows/ci.yml | CI pipeline                   |
+| .github/workflows/cd.yml | CD pipeline                   |
+| Dockerfile               | Container build               |
+| docker-compose.yml       | Local development             |
+| .env.example             | Documented env variables      |
 
 ### 16.4 Package.json Scripts Template
 
@@ -1805,8 +1893,7 @@ import type { EmployeeBio } from '@/types';
 const ENDPOINT = '/employees';
 
 export const employeeBioDetailService = {
-  getBio: (employeeId: string) =>
-    apiClient.get<EmployeeBio>(`${ENDPOINT}/${employeeId}/bio`),
+  getBio: (employeeId: string) => apiClient.get<EmployeeBio>(`${ENDPOINT}/${employeeId}/bio`),
   updateBio: (employeeId: string, data: Partial<EmployeeBio>) =>
     apiClient.put<EmployeeBio>(`${ENDPOINT}/${employeeId}/bio`, data),
 };
@@ -1852,8 +1939,8 @@ export function useUsers(page = 1) {
   return useQuery({
     queryKey: userKeys.list({ page }),
     queryFn: () => usersService.getAll(page),
-    staleTime: 5 * 60 * 1000,          // Fresh for 5 minutes
-    gcTime: 30 * 60 * 1000,             // Keep cache for 30 minutes
+    staleTime: 5 * 60 * 1000, // Fresh for 5 minutes
+    gcTime: 30 * 60 * 1000, // Keep cache for 30 minutes
     refetchOnWindowFocus: true,
     retry: 3,
   });
@@ -1871,15 +1958,16 @@ export function useCreateUser() {
 
 ### 17.6 Client-Side Caching Strategy
 
-| Cache Layer | Technology | Use Case | Persistence |
-|-------------|-----------|----------|-------------|
-| Server State | TanStack React Query | API caching, dedup, background refetch | In-memory |
-| Persistent Storage | localStorage | User preferences, theme, auth tokens | Disk |
-| Large Data | IndexedDB via Dexie.js | Offline data, large datasets | Disk |
-| Route Prefetch | Router loaders | Anticipatory data loading | In-memory |
-| Service Worker | Workbox | Full offline support | Cache Storage API |
+| Cache Layer        | Technology             | Use Case                               | Persistence       |
+| ------------------ | ---------------------- | -------------------------------------- | ----------------- |
+| Server State       | TanStack React Query   | API caching, dedup, background refetch | In-memory         |
+| Persistent Storage | localStorage           | User preferences, theme, auth tokens   | Disk              |
+| Large Data         | IndexedDB via Dexie.js | Offline data, large datasets           | Disk              |
+| Route Prefetch     | Router loaders         | Anticipatory data loading              | In-memory         |
+| Service Worker     | Workbox                | Full offline support                   | Cache Storage API |
 
 **Rules**:
+
 - Never cache sensitive data (tokens, PII) in localStorage without encryption
 - Always set staleTime / gcTime for API responses
 - Invalidate caches on mutations (create, update, delete)
@@ -1893,6 +1981,7 @@ export function useCreateUser() {
 ### 18.1 The Golden Rule
 
 > **Hooks are for behavior, not data.** If data comes from an API, use React Query + your service layer. Reserve hooks for:
+>
 > - Connecting UI to data (React Query hooks)
 > - Encapsulating complex browser APIs (resize, scroll, geolocation)
 > - Reusable form logic
@@ -1901,12 +1990,14 @@ export function useCreateUser() {
 ### 18.2 useEffect -- When and How
 
 **DO use useEffect for**:
+
 - Synchronizing with external systems (WebSocket, browser APIs, analytics)
 - Setting up subscriptions with proper cleanup
 - Managing non-React state (syncing to localStorage)
 - Imperative operations (focus management, scroll restoration)
 
 **DO NOT use useEffect for**:
+
 - Fetching data on mount --> Use React Query
 - Deriving state from props --> Use useMemo
 - Responding to user actions --> Use event handlers directly
@@ -1921,20 +2012,28 @@ useEffect(() => {
 }, [url]);
 
 // BAD: Fetching data manually (use React Query instead)
-useEffect(() => { fetch('/api/users').then(r => r.json()).then(setUsers); }, []);
+useEffect(() => {
+  fetch('/api/users')
+    .then((r) => r.json())
+    .then(setUsers);
+}, []);
 
 // BAD: Deriving state from props
-useEffect(() => { setFullName(`${firstName} ${lastName}`); }, [firstName, lastName]);
+useEffect(() => {
+  setFullName(`${firstName} ${lastName}`);
+}, [firstName, lastName]);
 // FIX: const fullName = `${firstName} ${lastName}`;
 ```
 
 ### 18.3 useMemo -- When to Memoize
 
 **DO use useMemo for**:
+
 - Expensive computations (filtering/sorting large lists, complex data transformation)
 - Creating stable object references for child component props (prevents re-renders)
 
 **DO NOT use useMemo for**:
+
 - Simple calculations (firstName + lastName)
 - Values used once or in a single render
 - Premature optimization -- measure first, then memoize
@@ -1942,9 +2041,7 @@ useEffect(() => { setFullName(`${firstName} ${lastName}`); }, [firstName, lastNa
 ```typescript
 // GOOD: Expensive computation memoized
 const filteredUsers = useMemo(() => {
-  return users
-    .filter((u) => u.role === selectedRole)
-    .sort((a, b) => a.name.localeCompare(b.name));
+  return users.filter((u) => u.role === selectedRole).sort((a, b) => a.name.localeCompare(b.name));
 }, [users, selectedRole]);
 
 // GOOD: Stable object reference for child
@@ -1958,11 +2055,13 @@ const greeting = useMemo(() => `Hello, ${name}!`, [name]);
 ### 18.4 useCallback -- When to Memoize Functions
 
 **DO use useCallback for**:
+
 - Callback props passed to memoized children (React.memo)
 - Functions in useEffect dependency arrays
 - Functions passed to context providers
 
 **DO NOT use useCallback for**:
+
 - Event handlers on native HTML elements (<button onClick>)
 - Functions used in a single parent component with no memoized children
 - Premature optimization
@@ -2028,6 +2127,7 @@ function Dashboard() {
 ```
 
 **When to use**:
+
 - Search fields with large result sets
 - Tab switching with heavy content
 - Chart/table rendering blocking the UI thread
@@ -2068,18 +2168,18 @@ function SearchUsers() {
 
 ### 18.7 Performance Decision Guide
 
-| Situation | Solution | Why |
-|-----------|----------|-----|
-| Fetching API data | React Query (useQuery) | Built-in caching, dedup, retry, stale-while-revalidate |
-| Mutating server data | React Query (useMutation) | Optimistic updates, cache invalidation, rollback |
-| Expensive calculation on props change | useMemo | Only re-computes when dependencies change |
-| Stable callback for memoized child | useCallback | Prevents unnecessary child re-renders |
-| Debouncing user input | Custom useDebounce hook | Reduces API calls during rapid typing |
-| Non-urgent state update | useTransition | Keeps UI responsive during heavy renders |
-| Deferring slow component re-render | useDeferredValue | Shows stale content while new renders |
-| Subscribing to browser API | useEffect with cleanup | Proper lifecycle management |
-| Form state | React Hook Form | Built-in validation, minimal re-renders |
-| Global state | Zustand | No providers, selective subscriptions |
+| Situation                             | Solution                  | Why                                                    |
+| ------------------------------------- | ------------------------- | ------------------------------------------------------ |
+| Fetching API data                     | React Query (useQuery)    | Built-in caching, dedup, retry, stale-while-revalidate |
+| Mutating server data                  | React Query (useMutation) | Optimistic updates, cache invalidation, rollback       |
+| Expensive calculation on props change | useMemo                   | Only re-computes when dependencies change              |
+| Stable callback for memoized child    | useCallback               | Prevents unnecessary child re-renders                  |
+| Debouncing user input                 | Custom useDebounce hook   | Reduces API calls during rapid typing                  |
+| Non-urgent state update               | useTransition             | Keeps UI responsive during heavy renders               |
+| Deferring slow component re-render    | useDeferredValue          | Shows stale content while new renders                  |
+| Subscribing to browser API            | useEffect with cleanup    | Proper lifecycle management                            |
+| Form state                            | React Hook Form           | Built-in validation, minimal re-renders                |
+| Global state                          | Zustand                   | No providers, selective subscriptions                  |
 
 ### 18.8 Common Anti-Patterns to Avoid
 
@@ -2143,6 +2243,7 @@ Is the UI freezing during state updates?
   |
 You probably don't need any hook. Write plain JS/TS.
 ```
+
 ### 18.10 Form Validation & Submission Standards
 
 Every form must use React Hook Form with Zod validation. The schema must be co-located with the form component.
@@ -2212,6 +2313,7 @@ export function EmployeeBioForm() {
 ```
 
 **Rules**:
+
 - Zod schema co-located with form (not in a separate `types/` file)
 - Server errors mapped to field-level via `setError` (not shown as generic toast)
 - Unsaved changes warning via `beforeunload` when `isDirty`
@@ -2227,18 +2329,18 @@ export function EmployeeBioForm() {
 
 ### 19.1 Core Principle: Automation Over Manual Review
 
-No rule is valuable if it relies on humans remembering to check it. Every standard in this document must have automated enforcement. 
+No rule is valuable if it relies on humans remembering to check it. Every standard in this document must have automated enforcement.
 
 **Note on Package Managers**: While developers are free to use any package manager (npm, yarn, bun) for local development, all automated enforcement and CI/CD pipelines are optimized for **pnpm**. Ensure `pnpm-lock.yaml` is kept up to date.
 
 **Mandatory Enforcement Layers**:
 
-| Layer | Tool | When | Purpose |
-|-------|------|------|---------|
-| L1: Editor                         | ESLint + Prettier          | Every save              | Immediate feedback while coding |
-| L2: Pre-commit Hook               | Husky + lint-staged        | Every `git commit`      | Block bad code before it enters history |
-| L3: CI Pipeline                   | GitHub Actions             | Every PR / push          | Enforce before merge, across all contributors |
-| L4: Code Review                   | Human review               | Every PR                 | Architecture, logic, edge cases automation cannot catch |
+| Layer               | Tool                | When               | Purpose                                                 |
+| ------------------- | ------------------- | ------------------ | ------------------------------------------------------- |
+| L1: Editor          | ESLint + Prettier   | Every save         | Immediate feedback while coding                         |
+| L2: Pre-commit Hook | Husky + lint-staged | Every `git commit` | Block bad code before it enters history                 |
+| L3: CI Pipeline     | GitHub Actions      | Every PR / push    | Enforce before merge, across all contributors           |
+| L4: Code Review     | Human review        | Every PR           | Architecture, logic, edge cases automation cannot catch |
 
 ### 19.2 Required Husky + lint-staged Setup
 
@@ -2302,10 +2404,7 @@ The `check-modularization` script (see Step 7) validates folder structure and ba
 // package.json
 {
   "lint-staged": {
-    "src/**/*.{ts,tsx}": [
-      "eslint --fix --max-warnings 0",
-      "prettier --write"
-    ],
+    "src/**/*.{ts,tsx}": ["eslint --fix --max-warnings 0", "prettier --write"],
     "src/**/*.{css,scss}": ["prettier --write"],
     "*.{json,md,yaml,yml}": ["prettier --write"]
   }
@@ -2378,12 +2477,12 @@ rules: {
 
 **The `--no-verify` policy**:
 
-| Action | Consequence |
-|--------|-------------|
-| `git commit --no-verify` | Commit lands locally, but CI catches all skipped checks on push/PR |
-| `git push --no-verify` | Push succeeds, but CI pre-push checks run anyway; PR blocked if failing |
-| Tampering with `.husky/` files | Caught in code review; `.husky/` is committed and reviewed |
-| Removing hooks from `package.json` | CI `pnpm install` re-installs husky; hooks re-created |
+| Action                             | Consequence                                                             |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `git commit --no-verify`           | Commit lands locally, but CI catches all skipped checks on push/PR      |
+| `git push --no-verify`             | Push succeeds, but CI pre-push checks run anyway; PR blocked if failing |
+| Tampering with `.husky/` files     | Caught in code review; `.husky/` is committed and reviewed              |
+| Removing hooks from `package.json` | CI `pnpm install` re-installs husky; hooks re-created                   |
 
 > **TL;DR**: `--no-verify` delays validation from commit-time to CI-time. The checks still run and the PR still gets blocked. There is no path to merge that bypasses these standards.
 
@@ -2430,12 +2529,22 @@ function logWarning(msg) {
 
 // Helper: check if a path is a directory
 function isDirectory(path) {
-  try { return statSync(path).isDirectory(); } catch { return false; }
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 // Helper: check if a file is a TypeScript file
 function isTsFile(filename) {
-  return /\.(ts|tsx)$/.test(filename) && !filename.endsWith('.test.ts') && !filename.endsWith('.test.tsx') && !filename.endsWith('.spec.ts') && !filename.endsWith('.spec.tsx');
+  return (
+    /\.(ts|tsx)$/.test(filename) &&
+    !filename.endsWith('.test.ts') &&
+    !filename.endsWith('.test.tsx') &&
+    !filename.endsWith('.spec.ts') &&
+    !filename.endsWith('.spec.tsx')
+  );
 }
 
 console.log('\n🔍 Checking modularization compliance...\n');
@@ -2460,9 +2569,11 @@ for (const dirName of MODULARIZED_DIRS) {
       } else {
         // Verify barrel exports at least one member
         const barrelContent = readdirSync(entryPath);
-        const tsFiles = barrelContent.filter(f => isTsFile(f) && f !== BARREL_FILE);
+        const tsFiles = barrelContent.filter((f) => isTsFile(f) && f !== BARREL_FILE);
         if (tsFiles.length === 0) {
-          logWarning(`${dirName}/${entry}/${BARREL_FILE} exists but no implementation files found in this domain`);
+          logWarning(
+            `${dirName}/${entry}/${BARREL_FILE} exists but no implementation files found in this domain`
+          );
         }
       }
 
@@ -2470,8 +2581,15 @@ for (const dirName of MODULARIZED_DIRS) {
       const subEntries = readdirSync(entryPath);
       for (const subEntry of subEntries) {
         const subPath = join(entryPath, subEntry);
-        if (subEntry !== 'test' && subEntry !== '__tests__' && subEntry !== '__mocks__' && isDirectory(subPath)) {
-          logWarning(`${dirName}/${entry}/ should not contain nested subdirectory "${subEntry}/" -- keep domains flat`);
+        if (
+          subEntry !== 'test' &&
+          subEntry !== '__tests__' &&
+          subEntry !== '__mocks__' &&
+          isDirectory(subPath)
+        ) {
+          logWarning(
+            `${dirName}/${entry}/ should not contain nested subdirectory "${subEntry}/" -- keep domains flat`
+          );
         }
       }
     } else if (isTsFile(entry)) {
@@ -2479,8 +2597,8 @@ for (const dirName of MODULARIZED_DIRS) {
       if (!allowedRoot.includes(entry)) {
         logError(
           `Flat file "${dirName}/${entry}" is not allowed at the root level. ` +
-          `Move it to a domain subdirectory (e.g., ${dirName}/${entry.replace(/\.(ts|tsx)$/, '')}/${entry}). ` +
-          `Allowed root files: ${allowedRoot.join(', ') || 'none'}`
+            `Move it to a domain subdirectory (e.g., ${dirName}/${entry.replace(/\.(ts|tsx)$/, '')}/${entry}). ` +
+            `Allowed root files: ${allowedRoot.join(', ') || 'none'}`
         );
       }
     }
@@ -2496,7 +2614,9 @@ try {
   logError('ESLint found violations (may include deep imports bypassing barrel files)');
 }
 
-console.log(`\n${errors === 0 ? '✅' : '❌'} Modularization check complete. Errors: ${errors}, Warnings: ${warnings}\n`);
+console.log(
+  `\n${errors === 0 ? '✅' : '❌'} Modularization check complete. Errors: ${errors}, Warnings: ${warnings}\n`
+);
 
 if (errors > 0) {
   console.error('Fix the errors above and try again.\n');
@@ -2509,6 +2629,7 @@ if (warnings > 0) {
 ```
 
 **What this enforces at commit time**:
+
 - ESLint auto-fixes what it can, then fails hard on remaining errors (`--max-warnings 0`)
 - Prettier formats all staged files
 - Commitlint rejects non-conventional commit messages
@@ -2524,17 +2645,7 @@ export default {
   rules: {
     'type-enum': [
       'error',
-      [
-        'feat',
-        'fix',
-        'security',
-        'perf',
-        'docs',
-        'style',
-        'refactor',
-        'test',
-        'chore',
-      ],
+      ['feat', 'fix', 'security', 'perf', 'docs', 'style', 'refactor', 'test', 'chore'],
     ],
     'subject-max-length': [2, 'always', 100],
     'body-max-line-length': [2, 'always', 100],
@@ -2791,11 +2902,11 @@ console.log(chalk.green('\nAll pre-commit checks passed!'));
 
 ### 19.9 What Each Layer Catches
 
-| Layer | Catches | Cannot Catch |
-|-------|---------|--------------|
-| L1 Editor | Typos, bad names, bad formatting | Logic bugs, architecture flaws |
-| L2 Pre-commit | Same as L1 + blocks commit | Business logic errors |
-| L3 CI Pipeline | Everything automated can check | Business logic correctness |
+| Layer          | Catches                            | Cannot Catch                      |
+| -------------- | ---------------------------------- | --------------------------------- |
+| L1 Editor      | Typos, bad names, bad formatting   | Logic bugs, architecture flaws    |
+| L2 Pre-commit  | Same as L1 + blocks commit         | Business logic errors             |
+| L3 CI Pipeline | Everything automated can check     | Business logic correctness        |
 | L4 Code Review | Architecture, security, edge cases | Naming that already passed ESLint |
 
 ### 19.10 Enforcement Checklist for New Projects
@@ -2826,6 +2937,7 @@ When setting up a new project, verify:
 > **This is a living document.** It should be reviewed and updated quarterly by the frontend chapter lead and architecture team. Any deviation from these standards must be documented in an Architecture Decision Record (ADR).
 
 ---
+
 ## Appendix C. Frontend Cost & Pricing Reference (June 2026)
 
 > Use this to estimate implementation and operational costs when proposing a new project or staffing decisions. Prices are approximations for mid-market commercial engagements and can vary by vendor, region, and contract length.
@@ -2844,39 +2956,39 @@ Use this table to compare partner-inclusive pricing vs. standard list pricing wh
 
 ### C.1 Estimated Annual Costs by Project Size
 
-| Project Size | Frontend Devs | Backend Devs | DevOps | QA | Tools & Licenses | Infrastructure | Total Est. Annual |
-|---|---|---|---|---|---|---|---|
-| Small (MVP/closed beta) | 1 | 1 | 0.25 | 0.5 | ~USD 2,000 | ~USD 1,500 | ~USD 160,000 |
-| Medium (production SaaS) | 2 | 2 | 0.5 | 1 | ~USD 5,000 | ~USD 3,500 | ~USD 350,000 |
-| Large (enterprise/multi-tenant) | 4 | 4 | 1 | 2 | ~USD 12,000 | ~USD 8,000 | ~USD 800,000 |
-| Enterprise (regulated/high-scale) | 6+ | 6+ | 2+ | 3+ | ~USD 25,000+ | ~USD 20,000+ | ~USD 1,600,000+ |
+| Project Size                      | Frontend Devs | Backend Devs | DevOps | QA  | Tools & Licenses | Infrastructure | Total Est. Annual |
+| --------------------------------- | ------------- | ------------ | ------ | --- | ---------------- | -------------- | ----------------- |
+| Small (MVP/closed beta)           | 1             | 1            | 0.25   | 0.5 | ~USD 2,000       | ~USD 1,500     | ~USD 160,000      |
+| Medium (production SaaS)          | 2             | 2            | 0.5    | 1   | ~USD 5,000       | ~USD 3,500     | ~USD 350,000      |
+| Large (enterprise/multi-tenant)   | 4             | 4            | 1      | 2   | ~USD 12,000      | ~USD 8,000     | ~USD 800,000      |
+| Enterprise (regulated/high-scale) | 6+            | 6+           | 2+     | 3+  | ~USD 25,000+     | ~USD 20,000+   | ~USD 1,600,000+   |
 
 ### C.2 Tooling & License Costs (Annual)
 
-| Tool / Service | Purpose | Typical Tier | Est. Cost | Notes |
-|---|---|---|---|---|
-| GitHub Enterprise / Teams | Repo hosting, Actions minutes, GHCR, Environments | Team: USD 4/user/mo; Enterprise: USD 21/user/mo | USD 2,400 – USD 25,000/yr | Public repos have free Actions minutes; private minutes are billed beyond the free tier (2,000 min/mo). |
-| Sentry (Error Tracking) | Frontend & backend error monitoring | Team: ~USD 29/app/mo | USD 350+/app/yr | Volume-based; consider self-hosted at scale. |
-| Datadog / New Relic / Azure Monitor | APM, logs, traces | Host-based or ingestion-based | USD 1,500 – USD 10,000+/yr | Strong for microservices; may overlap with Prometheus/Grafana. |
-| SonarCloud / SonarQube | Static analysis, quality gate | Developer: ~USD 25/dev/mo; Enterprise billed annually | USD 2,000 – USD 15,000/yr | SonarCloud is SaaS; SonarQube can be self-hosted with infra cost. |
-| Snyk / Trivy / Dependabot | Dependency & container vulnerability scanning | Snyk Team: ~USD 19/dev/mo; Trivy is free (OSS) | USD 0 – USD 5,000/yr | Trivy + GitHub Dependabot cover most needs at no extra cost. |
-| Vercel / Netlify / Azure Static Web Apps | Frontend preview deploys and hosting | Pro: ~USD 20/user/mo | USD 2,400 – USD 8,000/yr | GHCR + K8s can replace this; preview environments add cost. |
-| Azure Container Registry (ACR) or AWS ECR | Container image registry | Basic: USD 0.167/day + storage/egress | USD 100 – USD 1,000/yr | Often cheaper than GHCR at high throughput; pay for storage + egress. |
-| Auth0 / WorkOS / Clerk | Managed auth (if not custom) | Free to USD 23+/mo | USD 0 – USD 2,000/yr | Custom NestJS auth saves license cost but needs more engineering time. |
-| Storybook | Component library documentation + review | OSS free; Cloud from USD 20/mo | USD 0 – USD 5,000/yr | Includes collaboration add-ons in paid tiers. |
+| Tool / Service                            | Purpose                                           | Typical Tier                                          | Est. Cost                  | Notes                                                                                                   |
+| ----------------------------------------- | ------------------------------------------------- | ----------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| GitHub Enterprise / Teams                 | Repo hosting, Actions minutes, GHCR, Environments | Team: USD 4/user/mo; Enterprise: USD 21/user/mo       | USD 2,400 – USD 25,000/yr  | Public repos have free Actions minutes; private minutes are billed beyond the free tier (2,000 min/mo). |
+| Sentry (Error Tracking)                   | Frontend & backend error monitoring               | Team: ~USD 29/app/mo                                  | USD 350+/app/yr            | Volume-based; consider self-hosted at scale.                                                            |
+| Datadog / New Relic / Azure Monitor       | APM, logs, traces                                 | Host-based or ingestion-based                         | USD 1,500 – USD 10,000+/yr | Strong for microservices; may overlap with Prometheus/Grafana.                                          |
+| SonarCloud / SonarQube                    | Static analysis, quality gate                     | Developer: ~USD 25/dev/mo; Enterprise billed annually | USD 2,000 – USD 15,000/yr  | SonarCloud is SaaS; SonarQube can be self-hosted with infra cost.                                       |
+| Snyk / Trivy / Dependabot                 | Dependency & container vulnerability scanning     | Snyk Team: ~USD 19/dev/mo; Trivy is free (OSS)        | USD 0 – USD 5,000/yr       | Trivy + GitHub Dependabot cover most needs at no extra cost.                                            |
+| Vercel / Netlify / Azure Static Web Apps  | Frontend preview deploys and hosting              | Pro: ~USD 20/user/mo                                  | USD 2,400 – USD 8,000/yr   | GHCR + K8s can replace this; preview environments add cost.                                             |
+| Azure Container Registry (ACR) or AWS ECR | Container image registry                          | Basic: USD 0.167/day + storage/egress                 | USD 100 – USD 1,000/yr     | Often cheaper than GHCR at high throughput; pay for storage + egress.                                   |
+| Auth0 / WorkOS / Clerk                    | Managed auth (if not custom)                      | Free to USD 23+/mo                                    | USD 0 – USD 2,000/yr       | Custom NestJS auth saves license cost but needs more engineering time.                                  |
+| Storybook                                 | Component library documentation + review          | OSS free; Cloud from USD 20/mo                        | USD 0 – USD 5,000/yr       | Includes collaboration add-ons in paid tiers.                                                           |
 
 ### C.3 Infrastructure Costs (Monthly)
 
-| Environment | Typical Specs | Est. Monthly | Annual Est. |
-|---|---|---|---|
-| Dev (1 replica, no HA) | 1 vCPU / 2 GB RAM | USD 40 – USD 120 | USD 500 – USD 1,500 |
-| Staging (2 replicas) | 2 vCPU / 4 GB RAM each | USD 120 – USD 300 | USD 1,500 – USD 3,600 |
-| Production (min 3 replicas, autoscale) | 2 vCPU / 4 GB RAM each + load balancer | USD 300 – USD 900 | USD 3,600 – USD 10,800 |
-| Managed PostgreSQL (e.g., Azure Database, RDS, Cloud SQL) | 2 vCPU / 8 GB + storage | USD 150 – USD 500 | USD 1,800 – USD 6,000 |
-| Managed Redis / Valkey | 1 vCPU / 2 GB | USD 15 – USD 50 | USD 180 – USD 600 |
-| Object Storage (S3 / Blob) | 1 TB + egress | USD 20 – USD 80 | USD 240 – USD 960 |
-| SSL (managed by ingress or ACM) | -- | Often free | USD 0 |
-| DNS / domain | -- | USD 10 – USD 30 | USD 120 – USD 360 |
+| Environment                                               | Typical Specs                          | Est. Monthly      | Annual Est.            |
+| --------------------------------------------------------- | -------------------------------------- | ----------------- | ---------------------- |
+| Dev (1 replica, no HA)                                    | 1 vCPU / 2 GB RAM                      | USD 40 – USD 120  | USD 500 – USD 1,500    |
+| Staging (2 replicas)                                      | 2 vCPU / 4 GB RAM each                 | USD 120 – USD 300 | USD 1,500 – USD 3,600  |
+| Production (min 3 replicas, autoscale)                    | 2 vCPU / 4 GB RAM each + load balancer | USD 300 – USD 900 | USD 3,600 – USD 10,800 |
+| Managed PostgreSQL (e.g., Azure Database, RDS, Cloud SQL) | 2 vCPU / 8 GB + storage                | USD 150 – USD 500 | USD 1,800 – USD 6,000  |
+| Managed Redis / Valkey                                    | 1 vCPU / 2 GB                          | USD 15 – USD 50   | USD 180 – USD 600      |
+| Object Storage (S3 / Blob)                                | 1 TB + egress                          | USD 20 – USD 80   | USD 240 – USD 960      |
+| SSL (managed by ingress or ACM)                           | --                                     | Often free        | USD 0                  |
+| DNS / domain                                              | --                                     | USD 10 – USD 30   | USD 120 – USD 360      |
 
 > These are mid-2026 market reference prices. Cloud providers frequently discount reserved/commitment terms.
 
@@ -2889,28 +3001,28 @@ Use this table to compare partner-inclusive pricing vs. standard list pricing wh
 
 ### C.5 Open-Source vs Commercial Alternatives (2026)
 
-| Need | Commercial Option | OSS Alternative | Est. Savings | Trade-offs / Notes |
-|---|---|---|---|---|
-| CI/CD | GitHub Actions (private) | **Woodpecker**, **Gitea Actions**, Jenkins, GitLab CI (self-hosted runners) | Up to ~USD 10,000/yr on high volume | Self-hosted runners need infra + maintenance. Woodpecker/Gitea are easiest to adopt if you want to stay off cloud minutes. |
-| Error Tracking | Sentry Team | **Sentry Self-Hosted**, GlitchTip | ~USD 350 – USD 3,000+/yr saved | Self-hosted Sentry needs ~1–2 vCPU + 2–4 GB RAM per app. GlitchTip is lighter. |
-| Monitoring/APM | Datadog / New Relic | **Prometheus + Grafana**, SigNoz, Uptime Kuma | ~USD 1,500 – USD 10,000+/yr saved | OSS has higher setup cost. Best for teams with in-house SRE knowledge. |
-| Static Analysis | SonarCloud | **SonarQube Community**, ESLint + TypeScript strict + Coverage, CodeQL | ~USD 2,000 – USD 15,000/yr saved | SonarQube CE is capable. GitHub CodeQL is free for public and private repos. |
-| Dependency Scanning | Snyk | **Trivy**, OWASP Dependency-Check, GitHub Dependabot, Renovate | ~USD 0 – USD 5,000/yr saved | Dependabot + Trivy cover the majority of needs at zero license cost. |
-| Auth (if not custom) | Auth0 / Clerk | **Keycloak**, Authentik, SuperTokens | ~USD 0 – USD 2,000/yr saved | Keycloak is the most mature but heavier. SuperTokens is lighter and developer-friendly. |
-| Component Review | Storybook Cloud | **Storybook OSS**, Chromatic (paid) | ~USD 0 – USD 5,000/yr saved | Storybook OSS is fully free. Chromatic adds hosted review at ~USD 20/app/mo. |
-| Frontend Hosting | Vercel / Netlify / SWA | **Nginx + Cloudflare**, Caddy, self-hosted K8s + GHCR | ~USD 2,400 – USD 8,000/yr saved | GHCR + K8s is usually cheaper at scale; preview environments cost more effort. |
-| Container Registry | ACR / ECR | **GHCR**, Harbor (self-hosted) | ~USD 100 – USD 1,000/yr saved | GHCR is free for public/private with GitHub Actions. Harbor is good for air-gapped/on-prem. |
+| Need                 | Commercial Option        | OSS Alternative                                                             | Est. Savings                        | Trade-offs / Notes                                                                                                         |
+| -------------------- | ------------------------ | --------------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| CI/CD                | GitHub Actions (private) | **Woodpecker**, **Gitea Actions**, Jenkins, GitLab CI (self-hosted runners) | Up to ~USD 10,000/yr on high volume | Self-hosted runners need infra + maintenance. Woodpecker/Gitea are easiest to adopt if you want to stay off cloud minutes. |
+| Error Tracking       | Sentry Team              | **Sentry Self-Hosted**, GlitchTip                                           | ~USD 350 – USD 3,000+/yr saved      | Self-hosted Sentry needs ~1–2 vCPU + 2–4 GB RAM per app. GlitchTip is lighter.                                             |
+| Monitoring/APM       | Datadog / New Relic      | **Prometheus + Grafana**, SigNoz, Uptime Kuma                               | ~USD 1,500 – USD 10,000+/yr saved   | OSS has higher setup cost. Best for teams with in-house SRE knowledge.                                                     |
+| Static Analysis      | SonarCloud               | **SonarQube Community**, ESLint + TypeScript strict + Coverage, CodeQL      | ~USD 2,000 – USD 15,000/yr saved    | SonarQube CE is capable. GitHub CodeQL is free for public and private repos.                                               |
+| Dependency Scanning  | Snyk                     | **Trivy**, OWASP Dependency-Check, GitHub Dependabot, Renovate              | ~USD 0 – USD 5,000/yr saved         | Dependabot + Trivy cover the majority of needs at zero license cost.                                                       |
+| Auth (if not custom) | Auth0 / Clerk            | **Keycloak**, Authentik, SuperTokens                                        | ~USD 0 – USD 2,000/yr saved         | Keycloak is the most mature but heavier. SuperTokens is lighter and developer-friendly.                                    |
+| Component Review     | Storybook Cloud          | **Storybook OSS**, Chromatic (paid)                                         | ~USD 0 – USD 5,000/yr saved         | Storybook OSS is fully free. Chromatic adds hosted review at ~USD 20/app/mo.                                               |
+| Frontend Hosting     | Vercel / Netlify / SWA   | **Nginx + Cloudflare**, Caddy, self-hosted K8s + GHCR                       | ~USD 2,400 – USD 8,000/yr saved     | GHCR + K8s is usually cheaper at scale; preview environments cost more effort.                                             |
+| Container Registry   | ACR / ECR                | **GHCR**, Harbor (self-hosted)                                              | ~USD 100 – USD 1,000/yr saved       | GHCR is free for public/private with GitHub Actions. Harbor is good for air-gapped/on-prem.                                |
 
 ### C.6 OSS Cost-Scoring Cheat Sheet
 
-| Solution | Setup Effort | Maintenance | When It Wins | When to Buy Commercial |
-|---|---|---|---|---|
-| Prometheus + Grafana | Medium | Medium | Metrics-heavy infra, in-house SRE skill | When you want hosted dashboards, alerting, and support SLAs |
-| Sentry Self-Hosted | Medium | Medium | Apps with many errors and sensitive logs | When uptime and incident response are more important than license cost |
-| Keycloak | High | High | Enterprise SSO, internal identity, B2B | When identity is not your core competency |
-| Woodpecker / Gitea | Medium | Medium | Heavy CI usage, private repo cost control | When you want zero per-minute billing and full data control |
-| Jenkins | High | High | Legacy enterprise estates, Windows workloads | When your team already knows Jenkins and plugin ecosystem |
-| Harbor | Medium | Medium | Air-gapped/on-prem registries, large images | When egress or compliance prevents cloud registries |
+| Solution             | Setup Effort | Maintenance | When It Wins                                 | When to Buy Commercial                                                 |
+| -------------------- | ------------ | ----------- | -------------------------------------------- | ---------------------------------------------------------------------- |
+| Prometheus + Grafana | Medium       | Medium      | Metrics-heavy infra, in-house SRE skill      | When you want hosted dashboards, alerting, and support SLAs            |
+| Sentry Self-Hosted   | Medium       | Medium      | Apps with many errors and sensitive logs     | When uptime and incident response are more important than license cost |
+| Keycloak             | High         | High        | Enterprise SSO, internal identity, B2B       | When identity is not your core competency                              |
+| Woodpecker / Gitea   | Medium       | Medium      | Heavy CI usage, private repo cost control    | When you want zero per-minute billing and full data control            |
+| Jenkins              | High         | High        | Legacy enterprise estates, Windows workloads | When your team already knows Jenkins and plugin ecosystem              |
+| Harbor               | Medium       | Medium      | Air-gapped/on-prem registries, large images  | When egress or compliance prevents cloud registries                    |
 
 ### C.7 Backend-Oriented Cost Notes (Frontend Impact)
 
@@ -2938,5 +3050,5 @@ Use this table to compare partner-inclusive pricing vs. standard list pricing wh
   - Azure Hybrid Benefit: https://azure.microsoft.com/en-us/pricing/benefits/azure-hybrid-benefit/
   - Visual Studio subscriptions: https://visualstudio.microsoft.com/subscriptions/
   - FastTrack: https://azure.microsoft.com/en-us/programs/azure-fasttrack/
-  Actual entitlement depends on partner tier, agreement, and region; treat these as **items to explore** with your account team.
+    Actual entitlement depends on partner tier, agreement, and region; treat these as **items to explore** with your account team.
 - Cloud infrastructure ranges are derived from standard managed VM, DB, and storage pricing pages; costs can be lower with reserved instances, savings plans, or partner credits.