@synergyerp/frontend-standards 1.0.2 → 1.1.0

package/FRONTEND_STANDARDS.md

@@ -0,0 +1,2942 @@
+# Frontend Standardization & Deployment Guide
+
+> **Purpose**: Company-wide standards for frontend project architecture, code quality, CI/CD, and code reviews.
+> **Target Audience**: All frontend engineers, QA engineers, and DevOps teams.
+> **Date**: June 2026
+> **Status**: v1.0 -- Standard
+
+---
+
+## Table of Contents
+
+1. [Philosophy & Guiding Principles](#1-philosophy--guiding-principles)
+2. [Recommended Tech Stack](#2-recommended-tech-stack)
+3. [Project Scaffolding & Directory Structure](#3-project-scaffolding--directory-structure)
+4. [TypeScript Configuration Standards](#4-typescript-configuration-standards)
+5. [Code Quality & Linting Standards](#5-code-quality--linting-standards)
+6. [Formatting Standards](#6-formatting-standards)
+7. [UI Component Standards (Lovable Integration)](#7-ui-component-standards-lovable-integration)
+8. [Testing Standards](#8-testing-standards)
+9. [Git Workflow & Commit Standards](#9-git-workflow--commit-standards)
+10. [Code Review Standards](#10-code-review-standards)
+11. [CI/CD Pipeline Standards](#11-cicd-pipeline-standards)
+12. [Deployment Standards](#12-deployment-standards)
+13. [Security Standards](#13-security-standards)
+14. [Monitoring & Observability](#14-monitoring--observability)
+15. [Documentation Standards](#15-documentation-standards)
+16. [Appendix: Quick References](#16-appendix-quick-references)
+17. [API Service Layer Standards](#17-api-service-layer-standards)
+18. [React Hooks Best Practices](#18-react-hooks-best-practices)
+19. [Enforcement: Husky, Git Hooks & Automated Validation](#19-enforcement-husky-git-hooks--automated-validation)
+
+---
+
+## 1. Philosophy & Guiding Principles
+
+### 1.1 Core Tenets
+
+1. **Consistency Over Configuration**: Every project should look, feel, and behave the same way so engineers can move between projects seamlessly.
+2. **Automation Over Manual Processes**: Linting, formatting, testing, and deployments must be automated. Human judgement is reserved for architecture and code reviews.
+3. **Security By Default**: Security checks, input validation, and dependency auditing are non-negotiable gates in every pipeline.
+4. **Documentation As Code**: Key decisions live as close to the code as possible (READMEs, ADRs, inline JSDoc).
+5. **Accessibility First**: Every UI component must be accessible (WCAG 2.1 AA minimum).
+
+### 1.2 Separation Of Concerns
+
+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 |
+| **CI/CD & Deployment** (Sections 10-14) | Pipelines, code review, deployment, monitoring, security | DevOps, QA, Tech Leads |
+
+---
+
+## 2. Recommended Tech Stack
+
+### 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. |
+
+### 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. |
+
+### 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. |
+
+### 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. |
+
+---
+
+## 3. Project Scaffolding & Directory Structure
+
+### 3.1 Standard Project Layout
+
+```
+project-name/
+  src/
+    app/                    # Pages / Routes
+      pages/                # Pages
+      routes/               # Route definitions
+      layouts/              # Layout components
+    components/             # All components
+      ui/                   # Base UI primitives (Lovable/Shadcn)
+      forms/                # Form-specific components
+      layout/               # App layout components
+      shared/               # Shared business components
+    hooks/                  # Custom React hooks
+    lib/                    # Utilities, API clients, helpers
+    store/                  # Zustand stores
+    types/                  # TypeScript type definitions
+    services/               # API service calls (domain-modularized)
+      employee/             # Employee domain services
+        employee-bio-detail.service.ts
+        employee-bank-detail.service.ts
+      auth/                 # Auth domain services
+        auth.service.ts
+      users/                # User domain services
+        users.service.ts
+      api-client.ts         # Shared API client (ONLY shared file at this level)
+    styles/                 # Global styles (Tailwind entry)
+    test/                   # Test setup, mocks, fixtures
+  public/                   # Static assets
+  scripts/                  # Build & automation scripts
+  .github/workflows/        # CI/CD pipeline definitions
+  .husky/                   # Git hooks
+  docs/                     # Project documentation
+  -- root config files --
+```
+
+### 3.2 Monorepo Layout (For Multiple Projects)
+
+```
+project-name/
+  apps/
+    admin/                  # Admin dashboard
+    web/                    # Public website
+  packages/
+    config/eslint/          # Shared ESLint config
+    config/prettier/        # Shared Prettier config
+    config/tsconfig/        # Shared TypeScript config
+    ui/                     # Shared component library
+    utils/                  # Shared utilities
+    types/                  # Shared type definitions
+  scripts/
+  -- root config files --
+```
+
+### 3.3 Standards
+
+- Every project must have a README.md at the root
+- Environment files: .env.example (committed), .env (gitignored)
+- Config files: Use flat config where possible
+- Directory naming: kebab-case for all directories
+- File naming: kebab-case for all files, except PascalCase for React components (e.g., `UserProfile.tsx`)
+
+#### 3.3.1 Domain-Based Modularization (Strictly Enforced)
+
+All domain-specific files across **every** directory (`services/`, `hooks/`, `store/`, `components/`, `lib/`) must be organized into feature subdirectories. Flat/orphaned files at the root of any modularized directory are **prohibited** unless they are truly shared across all domains.
+
+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 |
+
+**Barrel File (`index.ts`) Convention**:
+
+Every domain subdirectory must contain an `index.ts` that re-exports all public members. Parent-level code imports exclusively from the barrel:
+
+```
+services/employee/
+  index.ts                              # Barrel: re-exports everything
+  employee-bio-detail.service.ts           # Implementation file
+  employee-bank-detail.service.ts          # Implementation file
+  employee-emergency-contact.service.ts    # Implementation file
+```
+
+```typescript
+// services/employee/index.ts (BARREL FILE -- REQUIRED)
+export { getEmployeeBio } from './employee-bio-detail.service';
+export { getEmployeeBankDetails, updateEmployeeBankDetails } from './employee-bank-detail.service';
+export { getEmergencyContacts } from './employee-emergency-contact.service';
+```
+
+```typescript
+// pages/EmployeeDashboard.tsx (PARENT CONSUMER -- imports from barrel only)
+import { getEmployeeBio, getEmployeeBankDetails } from '@/services/employee';
+// NOT: import { getEmployeeBio } from '@/services/employee/employee-bio-detail.service'; // BLOCKED
+```
+
+**Violation examples** (these will be blocked by ESLint and CI):
+
+```
+# BAD -- Flat files at directory root (BLOCKED)
+services/employee-bio-detail.service.ts
+hooks/useEmployeeLeave.ts
+store/employeeLeaveStore.ts
+
+# BAD -- Missing barrel file (BLOCKED)
+services/employee/employee-bio-detail.service.ts    # No index.ts in employee/
+
+# BAD -- Deep import bypassing barrel (BLOCKED)
+import { getEmployeeBio } from '@/services/employee/employee-bio-detail.service';
+
+# GOOD -- Domain-modularized with barrel (REQUIRED)
+services/employee/index.ts                       # Barrel exports
+services/employee/employee-bio-detail.service.ts
+services/employee/employee-bank-detail.service.ts
+import { getEmployeeBio } from '@/services/employee';
+```
+
+This rule is enforced via `eslint-plugin-boundaries` combined with `eslint-plugin-import` (see Section 5.2.1 for configuration).
+
+---
+
+## 4. TypeScript Configuration Standards
+
+### 4.1 Required Compiler Options
+
+These options ensure a modern, strict, and performant TypeScript environment:
+
+- **target: ES2022**: Specifies the JavaScript language version for the emitted output.
+- **module: ESNext**: Sets the module system for the program to the latest ECMAScript standard.
+- **moduleResolution: bundler**: Optimized module resolution for modern bundlers like Vite.
+- **strict: true**: Enables all strict type-checking options for maximum safety.
+- **esModuleInterop: true**: Ensures compatibility when importing CommonJS modules.
+- **skipLibCheck: true**: Skips type checking of declaration files to speed up builds.
+- **forceConsistentCasingInFileNames: true**: Prevents issues between case-sensitive and case-insensitive filesystems.
+- **resolveJsonModule: true**: Allows importing .json files as modules.
+- **isolatedModules: true**: Ensures each file can be safely transpiled independently.
+- **allowJs: false**: Disallows plain JavaScript to enforce TypeScript usage.
+- **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.
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowJs": false,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  }
+}
+```
+
+### 4.2 Strict Mode Checklist
+
+- strict: true (enables all strict flags)
+- noUncheckedIndexedAccess: true (prevent undefined access)
+- exactOptionalPropertyTypes: true
+- noPropertyAccessFromIndexSignature: true
+
+---
+
+## 5. Code Quality & Linting Standards
+
+### 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 |
+
+### 5.2 Naming Conventions -- Complete Reference
+
+#### Core Principle: Names Must Be Self-Documenting
+
+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
+- 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 |
+
+#### 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() |
+
+#### 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
+```
+
+#### ESLint Enforcement Rules
+
+```javascript
+rules: {
+  // Ban single-letter variables (minimum 2 characters)
+  'id-length': ['error', {
+    min: 2, max: 50,
+    exceptions: ['i', 'j', 'k', '_', 'x', 'y', 'z'],
+    properties: 'never',
+  }],
+  // Enforce camelCase
+  camelcase: ['error', { properties: 'never', ignoreDestructuring: false, allow: ['^UNSAFE_'] }],
+  // Enforce kebab-case file names, except for PascalCase React components
+  'unicorn/filename-case': ['error', {
+    case: 'kebabCase',
+    ignore: ['^[A-Z].*\\.tsx$'],
+  }],
+  // Enforce PascalCase for React components
+  'react/jsx-pascal-case': ['error', { allowAllCaps: true }],
+}
+```
+
+#### 5.2.1 Domain-Based Modularization Enforcement (eslint-plugin-boundaries + eslint-plugin-import)
+
+Install the required plugins:
+
+```bash
+pnpm add -D eslint-plugin-boundaries eslint-plugin-import
+```
+
+Configuration for enforcing domain-based folder modularization across **all** directories
+(`services/`, `hooks/`, `store/`, `components/`, `lib/`, `types/`), including barrel file (`index.ts`) enforcement:
+
+```javascript
+// eslint.config.js (flat config)
+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": [
+        // Shared/global files (can be imported by any domain)
+        {
+          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",
+          ],
+        },
+        // Employee domain -- all directories
+        {
+          mode: "full",
+          type: "employee",
+          pattern: [
+            "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",
+          pattern: [
+            "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",
+          pattern: [
+            "src/services/users/**",
+            "src/hooks/users/**",
+            "src/store/users/**",
+            "src/components/users/**",
+            "src/lib/users/**",
+            "src/types/users/**",
+          ],
+        },
+      ],
+    },
+    rules: {
+      // === BOUNDARIES RULES ===
+
+      // BLOCK: flat/orphaned domain files at directory roots (enforces subdirectory pattern)
+      "boundaries/entry-point": [
+        "error",
+        {
+          default: "disallow",
+          rules: [
+            // Allow ONLY api-client.ts at the services/ root level
+            {
+              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/",
+            },
+            // No domain-specific files at store/ root
+            {
+              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",
+        {
+          default: "disallow",
+          rules: [
+            // Shared files can be imported by any domain
+            { 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"] },
+            // Shared can import from shared
+            { from: ["shared"], allow: ["shared"] },
+          ],
+        },
+      ],
+
+      // === IMPORT RULES: BLOCK deep imports bypassing barrel files ===
+
+      // BLOCK: importing from a non-index file inside a domain subdirectory
+      "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",
+            // Allow shared/utility files
+            "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/**",
+          ],
+        },
+      ],
+
+      // BLOCK: importing from index files across domain boundaries (backup for boundaries plugin)
+      "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/**/users/**",
+              message: "Employee domain must not import from Users domain. Use shared interfaces instead.",
+            },
+            // (repeat for each domain pair)
+          ],
+        },
+      ],
+    },
+  },
+];
+```
+
+**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` |
+
+**Barrel File Enforcement Flow**:
+
+```
+✅ ALLOWED:  import { getBio } from '@/services/employee';
+             // Resolves to services/employee/index.ts (barrel)
+
+❌ BLOCKED: import { getBio } from '@/services/employee/employee-bio-detail.service';
+             // Deep import bypassing barrel -- `import/no-internal-modules` catches this
+
+✅ ALLOWED:  import { useEmployeeBio } from '@/hooks/employee';
+             // Resolves to hooks/employee/index.ts (barrel)
+
+❌ BLOCKED: import { useEmployeeBio } from '@/hooks/employee/useEmployeeBio';
+             // Deep import bypassing barrel
+```
+
+**Adding a New Domain**:
+1. Create the domain subdirectories across all folders:
+   ```
+   services/<domain>/
+   hooks/<domain>/
+   store/<domain>/
+   components/<domain>/
+   lib/<domain>/
+   types/<domain>/
+   ```
+2. Create an `index.ts` barrel file in each subdirectory
+3. Add the domain element type to `boundaries/elements`
+4. Add the `from`/`disallow` rules to `boundaries/element-types`
+5. Add the domain barrel paths to `import/no-internal-modules` allow list
+6. Add cross-domain restrictions to `import/no-restricted-paths`
+7. The domain starts isolated; update rules if cross-domain communication is needed (via shared interfaces only)
+
+#### Naming Decision Tree
+
+```
+Is it a boolean?    --> is/has/can/should/did/was prefix
+Is it a count?      --> count/total/num/index suffix
+Is it a list?       --> Plural noun or List suffix
+Is it an entity?    --> Specific singular noun
+Is it a getter?     --> get/fetch prefix
+Is it a transformer?--> format/convert prefix
+```
+
+#### Good vs Bad Examples
+
+```typescript
+// BAD -- Would fail code review
+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() { }
+
+// 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() { }
+```
+
+### 5.3 Import Order Standard
+
+```typescript
+// 1. Built-in Node modules
+import fs from 'fs';
+// 2. External dependencies
+import { useState } from 'react';
+// 3. Internal modules (using @/ alias)
+import { Button } from '@/components/ui/button';
+// 4. Parent imports
+import { formatDate } from '../utils/date';
+// 5. Sibling imports
+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.
+4. Ensure generated components pass accessibility checks.
+5. Add JSDoc comments to any complex generated logic.
+
+---
+
+## 6. Formatting Standards
+
+### 6.1 Prettier Configuration
+
+```javascript
+// .prettierrc.js
+export default {
+  semi: true,
+  singleQuote: true,
+  tabWidth: 2,
+  useTabs: false,
+  trailingComma: 'es5',
+  printWidth: 100,
+  bracketSpacing: true,
+  arrowParens: 'always',
+  endOfLine: 'lf',
+  plugins: ['prettier-plugin-organize-imports'],
+};
+```
+
+### 6.2 Format-On-Save (VS Code)
+
+Every project must have .vscode/settings.json:
+```json
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
+}
+```
+
+---
+
+## 7. UI Component Standards (Lovable Integration)
+
+### 7.1 Lovable Workflow
+
+1. **Design in Lovable**: Product designer creates UI mockups/templates.
+2. **Export clean components**: Export generated React components with Tailwind styling.
+3. **Integrate into project**: Place components in src/components/ui/ or shared/.
+4. **Add business logic**: Connect components to stores, API calls, and routing.
+5. **Test**: Write unit tests for logic, visual regression for UI.
+6. **Review**: Code review must verify generated code meets project standards.
+
+### 7.2 Component Architecture
+
+```
+src/components/
+  ui/                    # Base UI primitives (from Lovable/Shadcn)
+    Button.tsx
+    Input.tsx
+    Dialog.tsx
+    Table.tsx
+  forms/                 # Form-specific compositions
+    LoginForm.tsx
+    SignupForm.tsx
+  layout/                # Layout components
+    Header.tsx
+    Sidebar.tsx
+  shared/                # Domain-specific shared components
+    UserAvatar.tsx
+    DataTable.tsx
+```
+
+### 7.3 Component Best Practices
+
+- One component per file (except small utility components)
+- Props interface defined and exported
+- Default export for pages, named export for reusable components
+- Composition over configuration: prefer children and slots over boolean props
+- Lovable components should be presentational -- business logic in hooks and stores
+
+### 7.3.1 Error Boundaries (Required)
+
+Every route-level component must be wrapped in an Error Boundary. Implement a standard `<ErrorBoundary>` component:
+
+```tsx
+import { Component, type ReactNode } from 'react';
+import { logger } from '@/lib/logger';
+
+interface ErrorBoundaryProps {
+  fallback?: ReactNode;
+  children: ReactNode;
+  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error: Error | null;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void {
+    logger.error('ErrorBoundary caught an error', { error, componentStack: errorInfo.componentStack });
+    this.props.onError?.(error, errorInfo);
+  }
+
+  handleReset = () => this.setState({ hasError: false, error: null });
+
+  render() {
+    if (this.state.hasError) {
+      if (this.props.fallback) return this.props.fallback;
+      return (
+        <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">
+            Try Again
+          </button>
+        </div>
+      );
+    }
+    return this.props.children;
+  }
+}
+```
+
+**Usage**:
+```tsx
+// Route-level wrapping
+<ErrorBoundary onError={(err) => captureException(err)}>
+  <EmployeeDashboard />
+</ErrorBoundary>
+```
+
+**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
+- Fallback UI must include a "Try Again" reset action
+
+### 7.3.2 Code Splitting & Lazy Loading (Required for Routes)
+
+All page-level components must be lazy-loaded to reduce initial bundle size.
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { ErrorBoundary } from '@/components/shared/error-boundary';
+import { PageSkeleton } from '@/components/ui/page-skeleton';
+
+const EmployeeDashboard = lazy(() => import('@/pages/employee/employee-dashboard'));
+const EmployeeProfile = lazy(() => import('@/pages/employee/employee-profile'));
+
+export function EmployeeRoutes() {
+  return (
+    <ErrorBoundary>
+      <Suspense fallback={<PageSkeleton />}>
+        <Routes>
+          <Route path="dashboard" element={<EmployeeDashboard />} />
+          <Route path="profile/:id" element={<EmployeeProfile />} />
+        </Routes>
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+**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
+- Named exports are required for lazy-loaded modules: `export function EmployeeDashboard()`
+- Chunk naming: use `webpackChunkName: 'employee'` comment for Vite/webpack
+
+### 7.4.1 Loading & Error State Patterns
+
+**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 |
+
+Debounce loader appearance: do not show any loading indicator for fetches that resolve in < 300ms (avoid flash).
+
+```tsx
+// Standard page pattern
+function EmployeePage() {
+  const { data, isLoading, isError, error, refetch } = useEmployee(id);
+
+  if (isLoading) return <PageSkeleton />;
+  if (isError) return <ErrorState error={error} onRetry={refetch} />;
+  if (!data) return <EmptyState message="No employee data found" action={<CreateEmployeeButton />} />;
+
+  return <EmployeeProfile employee={data} />;
+}
+```
+
+**Error States** — use a standard `<ErrorState>` component:
+
+```tsx
+interface ErrorStateProps {
+  error?: Error | string;
+  onRetry?: () => void;
+  title?: string;
+}
+
+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">
+      <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.'}
+      </p>
+      {onRetry && (
+        <button onClick={onRetry} className="px-4 py-2 bg-primary text-primary-foreground rounded-md">
+          Try Again
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+### 7.4.2 Accessibility Standards (WCAG 2.1 AA — Mandatory)
+
+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>`. |
+
+**Required tools**: axe DevTools browser extension, eslint-plugin-jsx-a11y (already enforced via ESLint).
+
+---
+
+### 7.5 Table, Navigation, and Branding Standards
+
+#### Filterable and Sortable Tables (Required)
+
+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
+- Row selection with selected count and bulk actions
+- Server-side pagination with page numbers, prev/next, and page size selector
+- Empty state with friendly text and a primary action
+- Loading state using table skeleton or row spinners
+- Error state with retry button
+
+#### 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
+- Accessible: keyboard navigable with aria-label
+- Use an up chevron or arrow icon
+
+#### 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
+
+#### 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
+- Consistent spacing: 4px base unit, standard page padding, consistent gaps
+- Approved loading and empty states using corporate colors
+- 404 and error pages with corporate logo, friendly message, and primary action
+
+---
+
+
+---
+
+## 8. Testing Standards
+
+### 8.1 Testing Pyramid
+
+```
+       /\
+      /E2E\          Playwright (critical user flows)
+     /------\
+    /Integr.\        API + Component integration tests
+   /----------\
+  / Unit Tests \     Vitest + Testing Library (fast, isolated)
+ /--------------\
+```
+
+### 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 |
+
+### 8.3 Test Structure
+
+```typescript
+describe('UserProfile', () => {
+  describe('rendering', () => {
+    it('should display user name when data is loaded', () => {
+      const user = { name: 'John Doe', email: 'john@example.com' };
+      render(<UserProfile user={user} />);
+      expect(screen.getByText('John Doe')).toBeInTheDocument();
+    });
+
+    it('should show loading state when data is fetching', () => {
+      render(<UserProfile isLoading={true} />);
+      expect(screen.getByRole('status')).toBeInTheDocument();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should display error message when API fails', () => {
+      render(<UserProfile error="Failed to load" />);
+      expect(screen.getByText(/failed/i)).toBeInTheDocument();
+    });
+  });
+});
+```
+
+### 8.4 E2E Standards (Playwright)
+
+- One spec file per critical user journey
+- Use data-testid attributes (not CSS classes) for selectors
+- Run against production-like environment (staging)
+- Include: login flow, CRUD operations, error states
+
+---
+
+## 9. Git Workflow & Commit Standards
+
+### 9.1 Branch Strategy
+
+```
+main              # Production-ready code
+  develop         # Integration branch
+    feature/*     # New features (branch from develop)
+    bugfix/*      # Bug fixes (branch from develop)
+    hotfix/*      # Critical fixes (branch from main, merge back)
+```
+
+### 9.2 Commit Message Format
+
+```
+<type>(<scope>): <description>
+[optional body]
+```
+
+**Types**: feat, fix, security, perf, docs, style, refactor, test, chore
+
+**Examples**:
+```
+feat(auth): add JWT refresh token flow
+fix(profile): resolve avatar upload timeout
+security(api): implement rate limiting on login
+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 |
+
+**lint-staged config**:
+```json
+{
+  "src/**/*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{json,md,yaml,yml}": ["prettier --write"]
+}
+```
+
+---
+
+## 10. Code Review Standards
+
+### 10.1 PR Pre-Submission Checklist
+
+> **PR Template Required**: Every repository must contain `.github/PULL_REQUEST_TEMPLATE.md`. The canonical templates are provided by `@aoholdings/frontend-standards` (frontend) and `@aoholdings/backend-standards` (backend). They are auto-copied into `.github/` on `pnpm install`. All PRs must follow the template structure. CI validates this via the PR checklist gates.
+
+- [ ] Code compiles without errors (tsc --noEmit)
+- [ ] All lint rules pass
+- [ ] All tests pass
+- [ ] New code has >=90% test coverage
+- [ ] No .only in test files
+- [ ] No console.log or debugger statements
+- [ ] No hardcoded secrets, API keys, or URLs
+- [ ] Branch is up to date with develop/main
+- [ ] PR description follows the template (`.github/PULL_REQUEST_TEMPLATE.md`)
+
+### 10.2 PR Description Template
+
+> **Enforcement**: Every repository must contain `.github/PULL_REQUEST_TEMPLATE.md`. The canonical PR template is provided by `@aoholdings/frontend-standards` and auto-copied on `pnpm install`. CI will flag PRs that do not follow the template structure. See [Section 19.10](#1910-enforcement-checklist-for-new-projects) for the enforcement checklist.
+
+```markdown
+## Description
+[Brief description of the change]
+
+## Type of Change
+- [ ] feat: New feature
+- [ ] fix: Bug fix
+- [ ] refactor: Code restructure
+- [ ] test: Test changes
+- [ ] docs: Documentation
+- [ ] chore: Build/tooling
+
+## Testing Done
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+- [ ] E2E tests (if applicable)
+
+## Screenshots (if UI change)
+
+## Checklist
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] No breaking changes (or documented)
+- [ ] Security implications considered
+- [ ] Accessibility checked (if UI change)
+```
+
+### 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?
+
+### 10.4 Review Process Flow
+
+```
+PR Created
+    |
+Auto Checks (CI): Lint, Types, Tests, Coverage
+    |
+    |-- FAIL --> Author fixes --> PR updated
+    |
+    v PASS
+Peer Review (at least 1 senior dev)
+    |
+    |-- CHANGES REQUESTED --> Author addresses --> Re-review
+    |
+    v APPROVED
+Second Approval (for main branch)
+    |
+    v
+Merge (Squash commit to maintain clean history)
+    |
+    v
+Auto-deploy to staging (if main/develop)
+```
+
+---
+
+## 11. CI/CD Pipeline Standards
+
+### 11.1 Pipeline Stages
+
+```
+CI PIPELINE (Runs on every PR and push to develop/main):
+  1. Checkout + Setup Node.js + pnpm
+  2. Cache dependencies
+  3. pnpm install --frozen-lockfile
+  4. pnpm lint (must pass)
+  5. pnpm check-types (must pass)
+  6. pnpm test:ci (>=80% coverage)
+  7. Security audit (pnpm audit / npm audit)
+  8. Build application
+  9. Upload test results + coverage
+
+CD PIPELINE (Push to develop):
+  1. Build Docker image
+  2. Push to container registry
+  3. Deploy to Dev (auto)
+  4. Run smoke tests
+
+CD PIPELINE (Push to main + manual approval):
+  1. Build Docker image
+  2. Push to container registry
+  3. Deploy to Staging (auto)
+  4. E2E tests
+  5. Manual approval gate
+  6. Deploy to Production (rolling update)
+  7. Health check + smoke tests
+```
+
+### 11.2 CI Configuration (GitHub Actions Example)
+
+```yaml
+name: CI Pipeline
+on:
+  push: { branches: [main, develop] }
+  pull_request: { branches: [main, develop] }
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: "20" }
+      - uses: pnpm/action-setup@v2
+        with: { version: 9 }
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm check-types
+      - run: pnpm test:ci
+      - run: pnpm audit --audit-level=high
+      - run: pnpm build
+
+      - uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/cobertura-coverage.xml
+```
+
+### 11.3 Non-Negotiables
+
+1. Lockfile must be committed: Reproducible builds depend on it. **pnpm-lock.yaml** is the standard for CI/CD.
+2. Pipeline must fail on lint or test failures. No continueOnError.
+3. Security scanning required: npm audit or Snyk/Trivy.
+4. Docker images must be tagged with commit SHA.
+5. Production deployment requires manual approval.
+6. Database migrations must run before the app starts (if applicable).
+
+---
+
+## 12. Deployment Standards
+
+### 12.1 Multi-Stage Dockerfile
+
+```dockerfile
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN pnpm build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 appuser
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/node_modules ./node_modules
+USER appuser
+EXPOSE 3000
+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) |
+
+### 12.3 Deployment Checklist
+
+- [ ] Environment variables configured in secret manager (not committed)
+- [ ] Health check endpoint implemented (/health)
+- [ ] Readiness probe configured (Kubernetes)
+- [ ] Resource limits set (CPU/Memory)
+- [ ] Database migration plan prepared (if applicable)
+- [ ] Rollback plan documented
+- [ ] Monitoring alerts configured
+- [ ] Smoke tests passing
+
+---
+
+## 13. Security Standards
+
+### 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 |
+
+### 13.2 Secrets NEVER Committed
+
+- API keys, tokens, passwords
+- JWT signing secrets
+- Database connection strings
+- Cloud provider credentials
+- SSL/TLS private keys
+- Any .pem file
+
+### 13.3 .env.example Template
+
+```bash
+# App
+VITE_APP_TITLE=My App
+VITE_API_URL=http://localhost:3000/api/v1
+
+# Auth (if applicable)
+VITE_AUTH_DOMAIN=your-domain.auth0.com
+VITE_AUTH_CLIENT_ID=your-client-id
+
+# Monitoring
+VITE_SENTRY_DSN=https://xxx@sentry.io/xxx
+
+# Feature Flags
+VITE_ENABLE_DARK_MODE=true
+VITE_ENABLE_NEW_DASHBOARD=false
+```
+
+---
+
+### 13.4 Console.Log & Debugger Enforcement
+
+Console and debugger rules: `console.log`, `console.debug`, `console.info`, `console.trace`, `console.table`, and `debugger` are banned in committed code.
+
+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); },
+  warn: (...args: unknown[]) => console.warn('[WARN]', ...args),
+  error: (...args: unknown[]) => console.error('[ERROR]', ...args),
+};
+```
+
+Production stripping (Vite/Terser):
+```typescript
+build: {
+  minify: 'terser',
+  terserOptions: {
+    compress: {
+      drop_console: true,
+      drop_debugger: true,
+    },
+  },
+}
+```
+
+---
+
+---
+
+### 13.5 API Response Masking (Network Tab Security)
+
+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)
+- Financial data (card numbers, salaries)
+- Internal IDs (database IDs, internal references)
+- API keys, secrets, private keys
+
+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',
+  ];
+
+  constructor() {
+    this.client.interceptors.response.use((response) => ({
+      ...response,
+      data: this.maskSensitiveData(response.data),
+    }));
+  }
+
+  private maskSensitiveData(data: unknown): unknown {
+    if (typeof data !== 'object' || data === null) return data;
+    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))) {
+        masked[key] = '[REDACTED]';
+      } else if (typeof value === 'object' && value !== null) {
+        masked[key] = this.maskSensitiveData(value);
+      } else {
+        masked[key] = value;
+      }
+    }
+    return masked;
+  }
+}
+```
+
+Strategy 3: Disable caching for sensitive endpoints.
+```typescript
+export const sensitiveService = {
+  getFinancialData: () =>
+    apiClient.get('/reports/financial', {
+      headers: { 'Cache-Control': 'no-store', Pragma: 'no-cache' },
+    }),
+};
+```
+
+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',
+  TENANT_ADMIN = 'tenant_admin',
+  MANAGER = 'manager',
+  ANALYST = 'analyst',
+}
+
+export enum Permission {
+  USERS_READ = 'users:read',
+  USERS_WRITE = 'users:write',
+  USERS_DELETE = 'users:delete',
+  REPORTS_READ = 'reports:read',
+  BILLING_READ = 'billing:read',
+  BILLING_WRITE = 'billing:write',
+  SETTINGS_WRITE = 'settings:write',
+}
+```
+
+ABAC structure:
+```tsx
+export type AbacContext = {
+  role: Role;
+  tenantId: string;
+  userId: string;
+  ownershipIds: string[];
+  region: string;
+  clearanceLevel: number;
+  isImpersonating: boolean;
+};
+
+export type AbacPolicy = (
+  ctx: AbacContext,
+  action: string,
+  resource: { type: string; id?: string; ownerId?: string; tenantId?: string }
+) => boolean;
+
+export const canAccessResource: AbacPolicy = (ctx, action, resource) => {
+  if (ctx.isImpersonating) return false;
+  if (resource.tenantId && resource.tenantId !== ctx.tenantId) return false;
+  if (resource.ownerId && !ctx.ownershipIds.includes(resource.ownerId)) return false;
+  if (action.startsWith('admin:') && ctx.role !== Role.SUPER_ADMIN) return false;
+  return true;
+};
+```
+
+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 />;
+  const hasRole = roles ? roles.includes(auth.role) : 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}</>;
+}
+```
+
+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 abacPass = abacCheck ? abacCheck(auth.abacContext) : true;
+  if (!hasRole || !hasPermission || !abacPass) return <>{fallback}</>;
+  return <>{children}</>;
+}
+```
+
+Data guards:
+```tsx
+export function useAuthorizedUser(id: string) {
+  const auth = useAuth();
+  return useQuery({
+    queryKey: ['user', id],
+    queryFn: async () => {
+      const data = await usersService.getById(id);
+      if (!canAccessResource(auth.abacContext, 'users:read', { type: 'user', id, tenantId: data.tenantId })) {
+        throw new Error('Forbidden');
+      }
+      return data;
+    },
+  });
+}
+```
+
+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']",
+  message: 'Use <Can> or useAuthorized* guards instead of inline role checks.',
+}]
+```
+
+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 |
+
+### 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 |
+
+---
+
+## 15. Documentation Standards
+
+### 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 |
+
+### 15.2 README Template
+
+```markdown
+# Project Name
+[Brief description]
+
+## Quick Start
+```bash
+git clone <repo>
+cd project
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+## Available Scripts
+| Command | Description |
+| pnpm dev | Start development server |
+| pnpm build | Build for production |
+| pnpm test | Run tests |
+| pnpm lint | Lint code |
+
+## Environment Variables
+[Table of required env vars]
+```
+
+---
+
+## 16. Appendix: Quick References
+
+### 16.1 Essential Scripts
+
+```bash
+pnpm dev              # Start dev server with HMR
+pnpm build            # Production build
+pnpm test             # Run unit tests
+pnpm test:e2e         # Run E2E tests
+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
+
+```
+UserProfile.tsx           # React component (PascalCase)
+use-user-data.ts          # Custom hook (kebab-case)
+user-service.ts           # Service/utility (kebab-case)
+UserProfile.test.tsx      # Test file (matches component)
+UserProfile.stories.tsx   # Storybook file (matches component)
+types/user.ts             # Type definitions
+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 |
+
+### 16.4 Package.json Scripts Template
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "lint": "eslint src/ --ext .ts,.tsx --max-warnings 0",
+    "format": "prettier --write src/**/*.{ts,tsx,css,json}",
+    "format:check": "prettier --check src/**/*.{ts,tsx,css,json}",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky",
+    "audit": "pnpm audit --audit-level=high"
+  }
+}
+```
+
+---
+
+---
+
+## 17. API Service Layer Standards
+
+### 17.1 Why a Services Layer?
+
+A dedicated **API service layer** separates all backend communication from UI components. This is critical for:
+
+- **Consistency**: All API calls go through the same error handling, auth headers, and response parsing
+- **Testability**: Service functions can be mocked independently of components
+- **Caching**: Centralized caching and deduplication of requests
+- **Performance**: Request batching, debouncing, and cancellation handled in one place
+- **Maintainability**: Backend URL changes require one file change, not hundreds
+
+### 17.2 Recommended Architecture
+
+```
+src/
+  services/                       # API service layer (domain-modularized)
+    api-client.ts                 # Axios/fetch instance with interceptors (ONLY file at root)
+    auth/                         # Auth domain
+      index.ts                    # Barrel: re-exports all auth services
+      auth.service.ts             # Auth-related API calls
+    users/                        # Users domain
+      index.ts                    # Barrel: re-exports all user services
+      users.service.ts            # User-related API calls
+    employee/                     # Employee domain
+      index.ts                    # Barrel: re-exports all employee services
+      employee-bio-detail.service.ts # Bio detail API calls
+      employee-bank-detail.service.ts# Bank detail API calls
+      employee-leave.service.ts     # Leave management API calls
+  hooks/                          # React hooks that consume services
+    use-debounce.ts               # Utility hook (shared, allowed at root)
+    users/                        # User domain hooks
+      index.ts                    # Barrel
+      use-users.ts                # User data hook using React Query + service
+    employee/                     # Employee domain hooks
+      index.ts                    # Barrel
+      use-employee-bio.ts         # Employee bio hook
+  components/                     # UI components (no direct API calls)
+```
+
+### 17.3 API Client Template
+
+```typescript
+import axios, { AxiosError, AxiosInstance } from 'axios';
+
+const API_BASE_URL = import.meta.env.VITE_API_URL || '/api/v1';
+
+class ApiClient {
+  private client: AxiosInstance;
+
+  constructor() {
+    this.client = axios.create({
+      baseURL: API_BASE_URL,
+      timeout: 30000,
+      headers: { 'Content-Type': 'application/json' },
+    });
+    this.setupInterceptors();
+  }
+
+  private setupInterceptors() {
+    this.client.interceptors.request.use((config) => {
+      const token = getAccessToken();
+      if (token) config.headers.Authorization = `Bearer ${token}`;
+      return config;
+    });
+
+    this.client.interceptors.response.use(
+      (res) => res,
+      (error: AxiosError) => {
+        if (error.response?.status === 401) window.location.href = '/login';
+        return Promise.reject(this.normalizeError(error));
+      }
+    );
+  }
+
+  private normalizeError(error: AxiosError) {
+    return {
+      message: error.response?.data?.message || error.message,
+      status: error.response?.status || 500,
+      code: error.response?.data?.code || 'UNKNOWN_ERROR',
+    };
+  }
+
+  async get<T>(url: string): Promise<T> {
+    const res = await this.client.get<T>(url);
+    return res.data;
+  }
+  async post<T>(url: string, data?: unknown): Promise<T> {
+    const res = await this.client.post<T>(url, data);
+    return res.data;
+  }
+  async put<T>(url: string, data?: unknown): Promise<T> {
+    const res = await this.client.put<T>(url, data);
+    return res.data;
+  }
+  async delete<T>(url: string): Promise<T> {
+    const res = await this.client.delete<T>(url);
+    return res.data;
+  }
+}
+
+export const apiClient = new ApiClient();
+```
+
+### 17.4 Service Module Template (Domain-Modularized with Barrel Export)
+
+Each service file lives inside its domain subdirectory and is re-exported via the barrel `index.ts`.
+
+```typescript
+// src/services/users/users.service.ts
+import { apiClient } from '@/services/api-client';
+import type { User, PaginatedResponse } from '@/types';
+
+const ENDPOINT = '/users';
+
+export const usersService = {
+  getAll: (page = 1, limit = 20) =>
+    apiClient.get<PaginatedResponse<User>>(`${ENDPOINT}?page=${page}&limit=${limit}`),
+  getById: (id: string) => apiClient.get<User>(`${ENDPOINT}/${id}`),
+  create: (data: Partial<User>) => apiClient.post<User>(ENDPOINT, data),
+  update: (id: string, data: Partial<User>) => apiClient.put<User>(`${ENDPOINT}/${id}`, data),
+  delete: (id: string) => apiClient.delete<void>(`${ENDPOINT}/${id}`),
+};
+```
+
+```typescript
+// src/services/users/index.ts (BARREL FILE -- REQUIRED)
+export { usersService } from './users.service';
+```
+
+```typescript
+// src/services/employee/employee-bio-detail.service.ts
+import { apiClient } from '@/services/api-client';
+import type { EmployeeBio } from '@/types';
+
+const ENDPOINT = '/employees';
+
+export const employeeBioDetailService = {
+  getBio: (employeeId: string) =>
+    apiClient.get<EmployeeBio>(`${ENDPOINT}/${employeeId}/bio`),
+  updateBio: (employeeId: string, data: Partial<EmployeeBio>) =>
+    apiClient.put<EmployeeBio>(`${ENDPOINT}/${employeeId}/bio`, data),
+};
+```
+
+```typescript
+// src/services/employee/index.ts (BARREL FILE -- REQUIRED)
+export { employeeBioDetailService } from './employee-bio-detail.service';
+export { employeeBankDetailService } from './employee-bank-detail.service';
+export { employeeLeaveService } from './employee-leave.service';
+```
+
+**Consumer imports** (pages/components import from the barrel only):
+
+```typescript
+// pages/EmployeeProfile.tsx -- GOOD (barrel import)
+import { employeeBioDetailService } from '@/services/employee';
+import { usersService } from '@/services/users';
+
+// pages/EmployeeProfile.tsx -- BAD (deep import -- BLOCKED by ESLint)
+import { employeeBioDetailService } from '@/services/employee/employee-bio-detail.service';
+```
+
+### 17.5 Hook That Consumes a Service (With React Query + Barrel Imports)
+
+```typescript
+// src/hooks/users/use-users.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { usersService } from '@/services/users';
+// NOT: import { usersService } from '@/services/users/users.service'; // BLOCKED
+
+// Query key factory for consistent cache management
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: object) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};
+
+// Fetch paginated users (auto-cached + stale-while-revalidate)
+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
+    refetchOnWindowFocus: true,
+    retry: 3,
+  });
+}
+
+// Create user with automatic cache invalidation
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: usersService.create,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: userKeys.lists() }),
+  });
+}
+```
+
+### 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 |
+
+**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)
+- Prefer React Query over manual fetch + useState for server data
+- Use React Query staleTime to control refetch frequency, not arbitrary timers
+
+---
+
+## 18. React Hooks Best Practices
+
+### 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
+> - Performance optimization (useMemo, useCallback)
+
+### 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
+- Computed values --> Use useMemo or inline computation
+
+```typescript
+// GOOD: Clean subscription with cleanup
+useEffect(() => {
+  const socket = new WebSocket(url);
+  socket.onmessage = (event) => setMessages((prev) => [...prev, JSON.parse(event.data)]);
+  return () => socket.close(); // Cleanup on unmount
+}, [url]);
+
+// BAD: Fetching data manually (use React Query instead)
+useEffect(() => { fetch('/api/users').then(r => r.json()).then(setUsers); }, []);
+
+// BAD: Deriving state from props
+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
+
+```typescript
+// GOOD: Expensive computation memoized
+const filteredUsers = useMemo(() => {
+  return users
+    .filter((u) => u.role === selectedRole)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}, [users, selectedRole]);
+
+// GOOD: Stable object reference for child
+const config = useMemo(() => ({ pageSize: 20, enableSorting: true }), []);
+
+// BAD: Simple operation -- adds overhead
+const greeting = useMemo(() => `Hello, ${name}!`, [name]);
+// Just write: const greeting = `Hello, ${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
+
+```typescript
+// GOOD: Stable callback for memoized child
+const Table = React.memo(({ onRowClick, data }) => { ... });
+function Parent() {
+  const onRowClick = useCallback((id: string) => handleSelect(id), [handleSelect]);
+  return <Table onRowClick={onRowClick} data={data} />;
+}
+
+// BAD: Unnecessary -- native elements don't check prop equality
+const handleClick = useCallback(() => setCount((c) => c + 1), []);
+// <button onClick={handleClick}> -- NO BENEFIT
+
+// BAD: useCallback + inline function = same as no memo
+const handleSubmit = useCallback(() => { submit(data); }, [data]);
+// Same as: const handleSubmit = () => { submit(data); };
+```
+
+### 18.5 useTransition & useDeferredValue -- For Responsive UIs
+
+These hooks prevent the UI from freezing during expensive state updates.
+
+```typescript
+// useTransition: Mark a state update as non-urgent
+function SearchPage() {
+  const [isPending, startTransition] = useTransition();
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState([]);
+
+  const handleChange = (e) => {
+    const value = e.target.value;
+    setQuery(value);  // Urgent: input must feel responsive
+    startTransition(() => {
+      setResults(filterHugeList(value));  // Deferred: can wait
+    });
+  };
+
+  return (
+    <div>
+      <input value={query} onChange={handleChange} />
+      {isPending ? <Spinner /> : <List items={results} />}
+    </div>
+  );
+}
+
+// useDeferredValue: Defer re-render of non-critical content
+function Dashboard() {
+  const [input, setInput] = useState('');
+  const deferredInput = useDeferredValue(input);
+  const isStale = input !== deferredInput;
+
+  return (
+    <div>
+      <input value={input} onChange={(e) => setInput(e.target.value)} />
+      <SlowList text={deferredInput} />  {/* Re-renders less often */}
+      {isStale && <div>Updating...</div>}
+    </div>
+  );
+}
+```
+
+**When to use**:
+- Search fields with large result sets
+- Tab switching with heavy content
+- Chart/table rendering blocking the UI thread
+- Filtering/sorting lists >10,000 items
+
+### 18.6 Custom Hooks for Performance
+
+```typescript
+// hooks/use-debounce.ts -- Debounce rapidly changing values
+export function useDebounce<T>(value: T, delay = 300): T {
+  const [debouncedValue, setDebouncedValue] = useState<T>(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debouncedValue;
+}
+
+// Usage: Reduces API calls during rapid typing
+function SearchUsers() {
+  const [search, setSearch] = useState('');
+  const debouncedSearch = useDebounce(search, 400);  // Wait 400ms after last keystroke
+
+  const { data, isLoading } = useQuery({
+    queryKey: ['users', 'search', debouncedSearch],
+    queryFn: () => usersService.search(debouncedSearch),
+    enabled: debouncedSearch.length >= 2,  // Only search when 2+ chars
+  });
+
+  return (
+    <div>
+      <input value={search} onChange={(e) => setSearch(e.target.value)} />
+      {isLoading ? <Spinner /> : <UserList users={data} />}
+    </div>
+  );
+}
+```
+
+### 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 |
+
+### 18.8 Common Anti-Patterns to Avoid
+
+```typescript
+// ANTI-PATTERN: State + useEffect for derived data
+const [fullName, setFullName] = useState('');
+useEffect(() => { setFullName(`${user.firstName} ${user.lastName}`); }, [user]);
+// FIX: const fullName = `${user.firstName} ${user.lastName}`;
+
+// ANTI-PATTERN: Fetching in useEffect without cleanup
+useEffect(() => { fetch(url).then(setData); }, [url]);
+// FIX: Use React Query or AbortController
+
+// ANTI-PATTERN: Object/array in useEffect deps (causes infinite loop)
+useEffect(() => { doSomething(); }, [{ id: user.id }]);
+// FIX: Use primitive deps: [user.id]
+
+// ANTI-PATTERN: useCallback everywhere
+const handleChange = useCallback((e) => setValue(e.target.value), []);
+// FIX: const handleChange = (e) => setValue(e.target.value);
+
+// ANTI-PATTERN: Nested ternaries in JSX
+return (<div>{isLoading ? <Spin/> : isError ? <Error/> : data.length === 0 ? <Empty/> : <List data={data}/>}</div>);
+// FIX: Extract into variables or early returns
+
+// ANTI-PATTERN: Giant useEffect doing everything
+useEffect(() => {
+  fetchUsers(); setupWebSocket(); initAnalytics(); setInterval(poll, 5000);
+  return () => { cleanupAll(); };
+}, []);
+// FIX: Split into multiple focused useEffect calls
+```
+
+### 18.9 Decision Flowchart
+
+```
+Is this server data (API call)?
+  |-- YES --> React Query (useQuery / useMutation)
+  NO
+  |
+Is this a computed/derived value?
+  |-- YES --> Is it expensive (>1ms)?
+  |             |-- YES --> useMemo
+  |             |-- NO  --> Compute at render
+  NO
+  |
+Is this a function passed as prop to memoized child?
+  |-- YES --> useCallback
+  |-- NO  --> Regular function
+  NO
+  |
+Is this a side effect (subscription, browser API)?
+  |-- YES --> useEffect + cleanup
+  NO
+  |
+Is the UI freezing during state updates?
+  |-- YES --> Is it urgent (input, button)?
+  |             |-- YES --> Keep urgent update, useTransition for non-urgent
+  |             |-- NO  --> useDeferredValue
+  NO
+  |
+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.
+
+```typescript
+// pages/employee/employee-bio-form.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const employeeBioSchema = z.object({
+  firstName: z.string().min(1, 'First name is required').max(100),
+  lastName: z.string().min(1, 'Last name is required').max(100),
+  email: z.string().email('Invalid email format'),
+  phone: z.string().regex(/^\+?[\d\s-]{7,15}$/, 'Invalid phone number').optional(),
+  departmentId: z.string().uuid('Invalid department'),
+});
+
+type EmployeeBioFormData = z.infer<typeof employeeBioSchema>;
+
+export function EmployeeBioForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting, isDirty }, setError, reset } = useForm<EmployeeBioFormData>({
+    resolver: zodResolver(employeeBioSchema),
+    defaultValues: { firstName: '', lastName: '', email: '', phone: '', departmentId: '' },
+  });
+
+  const mutation = useUpdateEmployeeBio();
+
+  const onSubmit = async (data: EmployeeBioFormData) => {
+    try {
+      await mutation.mutateAsync(data);
+      reset(data); // Reset dirty state after successful save
+      toast.success('Bio updated successfully');
+    } catch (err) {
+      // Map server errors to form fields
+      if (err.response?.data?.errors) {
+        for (const { field, message } of err.response.data.errors) {
+          setError(field as keyof EmployeeBioFormData, { message });
+        }
+      } else {
+        toast.error('Failed to update bio. Please try again.');
+      }
+    }
+  };
+
+  // Ensure required: unsaved changes warning
+  useEffect(() => {
+    const handler = (e: BeforeUnloadEvent) => { if (isDirty) e.preventDefault(); };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [isDirty]);
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
+      <div>
+        <label htmlFor="firstName">First Name</label>
+        <input id="firstName" {...register('firstName')} aria-describedby="firstName-error" />
+        {errors.firstName && <p id="firstName-error" role="alert">{errors.firstName.message}</p>}
+      </div>
+      {/* ... other fields ... */}
+      <button type="submit" disabled={isSubmitting || !isDirty}>
+        {isSubmitting ? <Spinner /> : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+**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`
+- Submit button disabled when `isSubmitting` (loading spinner) or `!isDirty`
+- All inputs have `<label>` with `htmlFor` matching input `id`
+- Error messages linked via `aria-describedby`
+- Multi-step forms: each step is a separate form section with shared `useForm` + `watch`
+- Optimistic updates preferred over form submission where applicable
+
+---
+
+## 19. Enforcement: Husky, Git Hooks & Automated Validation
+
+### 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. 
+
+**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 |
+
+### 19.2 Required Husky + lint-staged Setup
+
+#### Step 1: Install dependencies
+
+```bash
+pnpm add -D husky lint-staged
+```
+
+#### Step 2: Enable Husky
+
+```json
+// package.json
+{
+  "scripts": {
+    "prepare": "husky"
+  }
+}
+```
+
+Run: `pnpm prepare` -- this creates the `.husky/` directory.
+
+#### Step 3: Create Pre-commit Hook
+
+```bash
+# .husky/pre-commit
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "Running lint-staged..."
+pnpm exec lint-staged
+```
+
+#### Step 4: Create Commit-msg Hook
+
+```bash
+# .husky/commit-msg
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "Validating commit message..."
+pnpm exec commitlint --edit "$1"
+```
+
+#### Step 5: Create Pre-push Hook
+
+```bash
+# .husky/pre-push
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+echo "Running quality checks..."
+pnpm lint && pnpm check-modularization && pnpm check-types && pnpm test:ci
+```
+
+The `check-modularization` script (see Step 7) validates folder structure and barrel file compliance before code reaches CI.
+
+#### Step 6: Configure lint-staged
+
+```json
+// package.json
+{
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix --max-warnings 0",
+      "prettier --write"
+    ],
+    "src/**/*.{css,scss}": ["prettier --write"],
+    "*.{json,md,yaml,yml}": ["prettier --write"]
+  }
+}
+```
+
+#### Step 7: Add Modularization Validation Script
+
+Add a `check-modularization` script to `package.json` that validates domain-folder structure and barrel file compliance:
+
+```json
+// package.json
+{
+  "scripts": {
+    "check-modularization": "node scripts/check-modularization.mjs",
+    "lint": "eslint --ext .ts,.tsx --max-warnings 0 .",
+    "lint:fix": "eslint --ext .ts,.tsx . --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,css,md}\"",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky",
+    "validate": "pnpm lint && pnpm check-modularization && pnpm check-types",
+    "test:validate": "pnpm test:ci --coverage"
+  }
+}
+```
+
+#### Step 8: Anti-Bypass Enforcement (`--no-verify` Protection)
+
+The `git commit --no-verify` (or `-n`) flag skips pre-commit and commit-msg hooks locally. This is a **policy violation** and must be caught in CI. To ensure checks persist regardless:
+
+**1. Commit Message Validation in CI** — since `--no-verify` can skip `commitlint` locally, CI validates all PR commit messages:
+
+```yaml
+# .github/workflows/ci.yml (add this step BEFORE the lint step)
+- name: Validate Commit Messages (anti-bypass for --no-verify)
+  run: |
+    echo "Checking all commit messages in this PR for conventional commit format..."
+    pnpm exec commitlint --from origin/${{ github.base_ref }} --to HEAD
+    # Fails if ANY commit message in the PR violates conventional commit format
+```
+
+**2. Pre-commit Checks Duplicated in CI** — every check that pre-commit runs locally also runs in CI with zero tolerance:
+
+```yaml
+- name: Lint (catches --no-verify bypass)
+  run: pnpm lint
+  # Runs regardless of whether developer skipped hooks locally
+
+- name: Check Modularization (catches --no-verify bypass)
+  run: pnpm check-modularization
+  # Runs regardless of whether developer skipped hooks locally
+```
+
+**3. ESLint Rule to Detect `--no-verify` Usage Pattern** — add a `no-restricted-syntax` rule that flags common bypass patterns in CI scripts or husky config tampering:
+
+```javascript
+// eslint.config.js
+rules: {
+  // Flag any attempted husky bypass or hook removal
+  'no-restricted-properties': ['error', {
+    object: 'process',
+    property: 'exit',
+    message: 'Do not use process.exit to bypass validation hooks.',
+  }],
+}
+```
+
+**4. Branch Protection Rule** — require all PR status checks to pass before merge. Even if a developer uses `--no-verify` locally, the PR cannot be merged because CI will fail on lint/modularization/commit-message checks.
+
+**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 |
+
+> **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.
+
+Create the validation script at `scripts/check-modularization.mjs`:
+
+```javascript
+// scripts/check-modularization.mjs
+import { readdirSync, existsSync, statSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = join(__dirname, '..');
+const SRC = join(PROJECT_ROOT, 'src');
+
+// Modularized directories that require subdirectory organization
+const MODULARIZED_DIRS = ['services', 'hooks', 'store', 'components', 'lib', 'types'];
+
+// Files allowed at the root of each directory (everything else must be in subdirs)
+const ALLOWED_ROOT_FILES = {
+  services: ['api-client.ts', 'api-client.tsx'],
+  hooks: ['use-debounce.ts', 'use-media-query.ts', 'index.ts'],
+  store: ['index.ts'],
+  components: ['index.ts'],
+  lib: ['index.ts'],
+  types: ['index.ts'],
+};
+
+// Required barrel file name
+const BARREL_FILE = 'index.ts';
+
+let errors = 0;
+let warnings = 0;
+
+function logError(msg) {
+  console.error(`  ❌ ERROR: ${msg}`);
+  errors++;
+}
+
+function logWarning(msg) {
+  console.warn(`  ⚠️  WARNING: ${msg}`);
+  warnings++;
+}
+
+// Helper: check if a path is a directory
+function isDirectory(path) {
+  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');
+}
+
+console.log('\n🔍 Checking modularization compliance...\n');
+
+for (const dirName of MODULARIZED_DIRS) {
+  const dirPath = join(SRC, dirName);
+  if (!existsSync(dirPath) || !isDirectory(dirPath)) continue;
+
+  const allowedRoot = ALLOWED_ROOT_FILES[dirName] || [];
+  const entries = readdirSync(dirPath);
+
+  for (const entry of entries) {
+    const entryPath = join(dirPath, entry);
+
+    if (isDirectory(entryPath)) {
+      // This is a domain subdirectory -- check it has a barrel file
+      console.log(`  📁 ${dirName}/${entry}/`);
+
+      const barrelPath = join(entryPath, BARREL_FILE);
+      if (!existsSync(barrelPath)) {
+        logError(`${dirName}/${entry}/ is missing required ${BARREL_FILE} barrel file`);
+      } else {
+        // Verify barrel exports at least one member
+        const barrelContent = readdirSync(entryPath);
+        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`);
+        }
+      }
+
+      // Check no nested subdirectories (domains should be flat)
+      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`);
+        }
+      }
+    } else if (isTsFile(entry)) {
+      // This is a flat file at the directory root
+      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'}`
+        );
+      }
+    }
+  }
+}
+
+// Also run the ESLint check (catches deep imports bypassing barrels)
+try {
+  const { execSync } = await import('child_process');
+  console.log('\n  🔍 Verifying no deep imports bypass barrels...');
+  execSync('pnpm lint', { cwd: PROJECT_ROOT, stdio: 'inherit' });
+} catch {
+  logError('ESLint found violations (may include deep imports bypassing barrel files)');
+}
+
+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');
+  process.exit(1);
+}
+
+if (warnings > 0) {
+  console.warn('Warnings found. Consider addressing them.\n');
+}
+```
+
+**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
+- Pre-push runs the full quality suite (lint, modularization, types, tests)
+- Modularization script validates folder structure AND barrel file compliance
+
+### 19.3 Commitlint Configuration
+
+```javascript
+// commitlint.config.js
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      'error',
+      [
+        'feat',
+        'fix',
+        'security',
+        'perf',
+        'docs',
+        'style',
+        'refactor',
+        'test',
+        'chore',
+      ],
+    ],
+    'subject-max-length': [2, 'always', 100],
+    'body-max-line-length': [2, 'always', 100],
+  },
+};
+```
+
+### 19.4 ESLint Rules That Must Be Enforced (with Error Severity)
+
+These rules translate the standards in Section 5 into machine-enforceable lint rules:
+
+```javascript
+// packages/config/eslint/base.mjs (add these to the rules block)
+rules: {
+  // === NAMING (Section 5.2) ===
+  'id-length': ['error', {
+    min: 2,
+    max: 50,
+    exceptions: ['i', 'j', 'k', '_', 'x', 'y', 'z'],
+    properties: 'never',
+  }],
+
+  camelcase: ['error', {
+    properties: 'never',
+    ignoreDestructuring: false,
+    allow: ['^UNSAFE_'],
+  }],
+
+  'unicorn/filename-case': ['error', {
+    case: 'kebabCase',
+    ignore: ['^[A-Z].*\\.tsx$'],  // PascalCase for component files
+  }],
+
+  'react/jsx-pascal-case': ['error', {
+    allowAllCaps: true,  // Allow HOCs like withAuth()
+  }],
+
+  // === IMPORTS (Section 5.3) ===
+  'import/order': ['error', {
+    groups: ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
+    'newlines-between': 'always',
+    alphabetize: { order: 'asc', caseInsensitive: true },
+  }],
+
+  // === FUNCTIONS (Section 5.2) ===
+  'prefer-arrow-callback': 'error',
+  'func-style': ['error', 'expression'],
+  'require-await': 'error',
+
+  // === NULL SAFETY ===
+  'unicorn/no-null': 'error',
+
+  // === REACT HOOKS (Section 18) ===
+  'react-hooks/rules-of-hooks': 'error',
+  'react-hooks/exhaustive-deps': 'warn',
+
+  // === LOVABLE GENERATED CODE (Section 5.4) ===
+  'no-unused-vars': ['error', {
+    varsIgnorePattern: '^_',
+    argsIgnorePattern: '^_',
+  }],
+
+  '@typescript-eslint/no-explicit-any': 'error',
+  '@typescript-eslint/no-unsafe-assignment': 'error',
+  '@typescript-eslint/no-unsafe-call': 'error',
+  '@typescript-eslint/no-unsafe-member-access': 'error',
+
+  // === PRETTIER ===
+  'prettier/prettier': ['error', {
+    semi: true,
+    singleQuote: true,
+    tabWidth: 2,
+    trailingComma: 'es5',
+    printWidth: 100,
+  }],
+
+  // === CONSOLE & DEBUGGER (Section 13.4) ===
+  'no-console': ['error', { allow: ['warn', 'error'] }],
+  'no-debugger': 'error',
+
+  // === MODULARIZATION & BARREL FILE ENFORCEMENT (Section 3.3.1, 5.2.1) ===
+  'boundaries/entry-point': ['error', {
+    default: 'disallow',
+    rules: [
+      { target: ['src/services/**/*.ts'], allow: 'src/services/api-client.ts' },
+      { target: ['src/hooks/use-employee*.ts', 'src/hooks/use-auth*.ts', 'src/hooks/use-user*.ts'], disallow: 'src/hooks/' },
+      { target: ['src/store/**/*.ts'], allow: 'src/store/index.ts' },
+    ],
+  }],
+
+  'boundaries/element-types': ['error', {
+    default: 'disallow',
+    rules: [
+      { from: ['employee', 'auth', 'users'], allow: ['shared'] },
+      { from: ['employee'], disallow: ['auth', 'users'] },
+      { from: ['auth'], disallow: ['employee', 'users'] },
+      { from: ['users'], disallow: ['employee', 'auth'] },
+      { from: ['shared'], allow: ['shared'] },
+    ],
+  }],
+
+  // BLOCK: deep imports bypassing barrel files (imports must go through index.ts)
+  'import/no-internal-modules': ['error', {
+    allow: [
+      'src/services/*/index',
+      'src/hooks/*/index',
+      'src/store/*/index',
+      'src/components/*/index',
+      'src/lib/*/index',
+      'src/types/*/index',
+      'src/services/api-client',
+      'src/hooks/use-debounce',
+      'src/hooks/use-media-query',
+      'src/components/ui/**',
+      'src/lib/*',
+      'src/types/*',
+      'src/app/**',
+      'src/styles/**',
+      'src/test/**',
+    ],
+  }],
+}
+```
+
+### 19.5 CI Validation Scripts (package.json)
+
+Create a `scripts/` directory with reusable validation:
+
+```json
+// package.json
+{
+  "scripts": {
+    "lint": "eslint --ext .ts,.tsx --max-warnings 0 .",
+    "lint:fix": "eslint --ext .ts,.tsx . --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx,json,css,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx,json,css,md}\"",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky",
+    "validate": "pnpm lint && pnpm check-types",
+    "test:validate": "pnpm test:ci --coverage"
+  }
+}
+```
+
+### 19.6 CI Pipeline Enforcement (GitHub Actions)
+
+Every CI run must check these in order. Any failure blocks the PR:
+
+```yaml
+# .github/workflows/ci.yml (excerpt)
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+      - uses: pnpm/action-setup@v2
+      - run: pnpm install --frozen-lockfile
+
+      # LAYER 3: Automated enforcement
+      - name: Validate Commit Messages (anti-bypass for --no-verify)
+        if: github.event_name == 'pull_request'
+        run: pnpm exec commitlint --from origin/${{ github.base_ref }} --to HEAD
+
+      - name: Lint ( ESLint + naming rules + modularization )
+        run: pnpm lint
+        # Fails on: naming, imports, types, prettier, no-unused-vars, cross-domain imports
+
+      - name: Check Modularization ( domain structure + barrels )
+        run: pnpm check-modularization
+        # Fails on: flat files at directory roots, missing barrel files, deep imports
+
+      - name: Type Check ( TypeScript strict )
+        run: pnpm check-types
+        # Fails on: any TS type error, missing types, implicit any
+
+      - name: Format Check ( Prettier )
+        run: pnpm format:check
+        # Fails on: any formatting deviation
+
+      - name: Test with Coverage ( Vitest )
+        run: pnpm test:validate
+        # Fails on: test failures OR coverage < 80%
+
+      - name: Security Audit ( pnpm audit )
+        run: pnpm audit --audit-level=high
+        # Fails on: high/critical vulnerabilities
+
+      - name: Build
+        run: pnpm build
+        # Fails on: TS errors missed by tsc, bundler errors
+```
+
+### 19.7 Coverage Threshold Enforcement
+
+> **Note**: Vitest v3 deprecated the top-level `lines`/`branches`/`functions`/`statements` shorthand in the `coverage` block. Use `thresholds` exclusively.
+
+```javascript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'cobertura'],
+      thresholds: {
+        lines: 80,
+        branches: 75,
+        functions: 80,
+        statements: 80,
+        // Each new file must have at least 90%
+        perFile: true,
+      },
+    },
+  },
+});
+```
+
+### 19.8 Pre-commit Validation Script Template
+
+```javascript
+// scripts/validate-pre-commit.js
+import { execSync } from 'child_process';
+import chalk from 'chalk';
+
+const checks = [
+  { name: 'Lint', command: 'pnpm lint' },
+  { name: 'Type Check', command: 'pnpm check-types' },
+];
+
+let failed = false;
+
+for (const check of checks) {
+  try {
+    console.log(chalk.blue(`Running ${check.name}...`));
+    execSync(check.command, { stdio: 'inherit' });
+    console.log(chalk.green(`${check.name} passed`));
+  } catch (err) {
+    console.error(chalk.red(`${check.name} FAILED`));
+    failed = true;
+  }
+}
+
+if (failed) {
+  console.error(chalk.red('\nPre-commit validation failed. Fix the above errors and try again.'));
+  process.exit(1);
+}
+
+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 |
+| L4 Code Review | Architecture, security, edge cases | Naming that already passed ESLint |
+
+### 19.10 Enforcement Checklist for New Projects
+
+When setting up a new project, verify:
+
+- [ ] Husky installed: `pnpm prepare` creates `.husky/`
+- [ ] Pre-commit hook exists and runs: `git commit --dry-run`
+- [ ] Commit-msg hook exists: Bad message is rejected
+- [ ] Pre-push hook exists: Tests run on `git push`
+- [ ] lint-staged config in package.json (not in separate config file)
+- [ ] `pnpm lint` exits non-zero on any ESLint error (including boundaries + `no-internal-modules`)
+- [ ] `pnpm check-modularization` exits non-zero on folder structure / barrel violations
+- [ ] `pnpm check-types` exits non-zero on any TS error
+- [ ] `pnpm format:check` exits non-zero on unformatted files
+- [ ] `pnpm test:ci` enforces coverage thresholds (80% lines, 75% branches)
+- [ ] `pnpm audit --audit-level=high` runs in CI
+- [ ] GitHub Actions CI blocked on lint/modularization/type/test failures (not `continue-on-error`)
+- [ ] Branch protection requires CI to pass before merge
+- [ ] Every domain subdirectory has an `index.ts` barrel file
+- [ ] No flat domain files at `services/`, `hooks/`, `store/`, `components/`, `lib/` roots
+- [ ] `.github/PULL_REQUEST_TEMPLATE.md` exists (copied from `@aoholdings/frontend-standards`)
+- [ ] All PRs follow the template format
+- [ ] Reviewer knows the standards in this document
+
+---
+
+> **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.
+
+### Partner Benefits & Azure Cost Relief
+
+As a **Microsoft Partner**, your organization may qualify for:
+
+- **Microsoft Action Pack / Solutions Partner** benefits: included Azure credits, free/dev CI-CD minutes, and co-selling/support access.
+- **Azure Hybrid Benefit / Reserved Instances**: reduces VM and managed-service compute cost by **20%–40%**.
+- **Visual Studio Enterprise / GitHub Enterprise** bundled licensing: avoids duplicate license spend and typically lowers total cost of ownership.
+- **Azure for Startups / ISV Pied Piper**: early-stage credits and advisory hours to reduce ramp-up cost.
+- **FastTrack / Partner Support**: faster migrations and production-readiness reviews reduce delivery risk and project overruns.
+
+Use this table to compare partner-inclusive pricing vs. standard list pricing when planning workloads.
+
+### 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+ |
+
+### 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. |
+
+### 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 |
+
+> These are mid-2026 market reference prices. Cloud providers frequently discount reserved/commitment terms.
+
+### C.4 CDN & Hosting Notes
+
+- For multi-region low-latency asset delivery, expect an additional USD 10 – USD 80/month depending on cache hit ratio.
+- Pre-rendering, caching strategies, and service workers reduce bandwidth and infrastructure cost more than most premature optimizations.
+
+---
+
+### 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. |
+
+### 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 |
+
+### C.7 Backend-Oriented Cost Notes (Frontend Impact)
+
+- **Serverless / Edge**: If the backend is serverless (Lambda/Cloud Functions), frontend should aim for fewer, batched API calls to reduce invocation costs.
+- **Caching**: Client-side caching (React Query, SW) and CDN caching reduce backend and bandwidth spend.
+- **Monitoring**: OSS frontend monitoring stack (Sentry self-hosted + Grafana) can replace Datadog RUM for ~USD 1,500 – USD 3,000/yr with some ops effort.
+- **Rate Limiting**: Implemented correctly in the frontend (debounce/cancel stale requests), it reduces backend compute and queuing costs.
+
+### C.8 Sources & Methodology
+
+- Pricing is based on **public list prices** from vendor pricing pages:
+  - Azure pricing: https://azure.microsoft.com/en-us/pricing/
+  - Azure Static Web Apps: https://azure.microsoft.com/en-us/pricing/details/app-service/static/
+  - GitHub: https://github.com/pricing
+  - Sentry: https://sentry.io/pricing/
+  - Datadog: https://www.datadoghq.com/pricing/
+  - SonarCloud: https://www.sonarsource.com/pricing/
+  - Snyk: https://snyk.io/pricing/
+  - Vercel: https://vercel.com/pricing
+  - Netlify: https://www.netlify.com/pricing/
+  - Storybook: https://storybook.js.org/docs/configure/overview#tooling-options
+- Microsoft Partner benefits sourced from:
+  - Microsoft Partner Network: https://partner.microsoft.com/
+  - Microsoft for Startups / ISV Pied Piper: https://startups.microsoft.com/
+  - 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.
+- 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.