@synergyerp/backend-standards 1.0.0 → 1.1.1

package/BACKEND_STANDARDS.md

@@ -0,0 +1,966 @@
+# Backend Standardization & Deployment Guide
+
+> **Purpose**: Company-wide standards for backend project architecture, code quality, security, and deployment.
+> **Target Audience**: All backend engineers, DevOps teams, and QA engineers.
+> **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. [API Service Layer & Database Standards](#7-api-service-layer--database-standards)
+8. [Testing Standards](#8-testing-standards)
+9. [Git Workflow & Commit Standards](#9-git-workflow--commit-standards)
+10. [Security Standards](#10-security-standards)
+11. [Enforcement: Husky, Git Hooks & CI/CD Validation](#11-enforcement-husky-git-hooks--cicd-validation)
+12. [CI/CD & Deployment Standards](#12-cicd--deployment-standards)
+13. [Monitoring & Observability](#13-monitoring--observability)
+14. [Logging & Error Handling](#14-logging--error-handling)
+15. [Documentation Standards](#15-documentation-standards)
+16. [Appendix: Quick References](#16-appendix-quick-references)
+
+---
+
+## 1. Philosophy & Guiding Principles
+
+### 1.1 Core Tenets
+
+1. **Consistency Over Configuration**: Every backend project should follow the same architectural patterns.
+2. **Type Safety Everywhere**: Use TypeScript strictly to catch errors at compile time.
+3. **Security By Design**: Authentication, authorization, and input validation are first-class citizens.
+4. **Performance & Scalability**: Modular architecture ensures we can scale features independently.
+5. **Separation of Concerns**: Controllers handle requests, Services handle logic, Repositories handle data.
+
+---
+
+## 2. Recommended Tech Stack
+
+### 2.1 Framework & Runtime
+
+| Layer | Recommended | Alternative | Notes |
+|-------|------------|-------------|-------|
+| **Runtime** | Node.js 20+ (LTS) | -- | Standard runtime. |
+| **Framework** | Express.js | NestJS | Use Express for lightweight services, NestJS for enterprise-grade apps. |
+| **Language** | TypeScript 5.5+ | -- | Non-negotiable. Strict mode required. |
+| **Package Manager**| pnpm 9+ | npm / yarn | Developers may use any manager locally, but **pnpm** is preferred for CI/CD. |
+
+### 2.2 Database & Storage
+
+| Layer | Recommendation | Notes |
+|-------|---------------|-------|
+| **Database** | PostgreSQL | Primary relational database. |
+| **ORM / Query Builder** | Prisma or TypeORM | Schema-driven or Decorator-based. |
+| **Caching** | Redis | For session management and high-performance caching. |
+| **Migrations** | Built-in ORM Migrations | Version-controlled database changes. |
+
+---
+
+## 3. Project Scaffolding & Directory Structure
+
+### 3.1 Modular Feature-Based Architecture
+
+Projects must adopt a feature-based structure where each business domain owns its logic.
+
+```
+src/
+  modules/                  # Business logic split by domain
+    auth/
+      auth.controller.ts
+      auth.service.ts
+      auth.repository.ts
+      auth.validation.ts
+      auth.routes.ts
+    users/
+      user.controller.ts
+      user.service.ts
+      ...
+  shared/                   # Shared logic across modules
+    middlewares/
+    utils/
+    constants/
+  config/                   # Configuration files (db, environment)
+  routes/                   # Centralized route registration
+  app.ts                    # Express app definition
+  server.ts                 # Server entry point
+```
+
+### 3.2 Standards
+
+- **File naming**: `kebab-case.extension.ts` (e.g., `user.controller.ts`). Use dot notation for role separation.
+- **Directory naming**: `kebab-case` (e.g., `user-profile/`).
+- **Module isolation**: Modules should ideally only interact with other modules via their Services, not Repositories.
+- **.nvmrc**: Every project must include a `.nvmrc` file pinning the Node.js version (e.g., `20`). This ensures consistent runtime across all environments.
+
+#### 3.2.1 Module Isolation & Barrel File Enforcement (Strict)
+
+Every module subdirectory **must** expose its public surface via an `index.ts` barrel file. Cross-module imports **must** go through the barrel — deep imports into another module's internals are **prohibited**.
+
+```
+src/modules/
+  auth/
+    index.ts              # Barrel: exports ONLY auth.service (public API)
+    auth.controller.ts
+    auth.service.ts
+    auth.repository.ts    # INTERNAL -- never imported by other modules
+    auth.validation.ts    # INTERNAL
+    auth.routes.ts
+  users/
+    index.ts              # Barrel: exports ONLY user.service (public API)
+    user.controller.ts
+    user.service.ts
+    user.repository.ts    # INTERNAL
+    ...
+```
+
+**Module Communication Rules**:
+
+| Rule | Enforcement |
+|------|-------------|
+| Module A may import from Module B's barrel (`index.ts`) only | ESLint `import/no-internal-modules` |
+| Module A must NOT import Module B's repository, controller, or validation files | ESLint `boundaries/element-types` |
+| Module A must NOT import flat files from `src/modules/` root | ESLint `boundaries/entry-point` |
+| Every module subdirectory must contain an `index.ts` barrel | `check-modularization` script (CI) |
+| `index.ts` must only re-export the module's public service(s) | Code review |
+
+**Violation examples**:
+
+```typescript
+// ❌ BLOCKED: Deep import into another module's repository
+import { UserRepository } from '@/modules/users/user.repository';
+
+// ❌ BLOCKED: Importing another module's controller
+import { UserController } from '@/modules/users/user.controller';
+
+// ✅ ALLOWED: Import from barrel (public API only)
+import { userService } from '@/modules/users';
+```
+
+**Barrel File Template**:
+
+```typescript
+// src/modules/users/index.ts
+export { userService } from './user.service';
+// NOTE: Do NOT export user.repository, user.controller, or user.validation
+// Those are module-internal -- other modules must go through userService
+```
+
+> For ESLint enforcement configuration, see [Section 5.1.1](#511-module-isolation--barrel-file-eslint-configuration).
+
+### 3.3 Graceful Shutdown (Required)
+
+Every backend service must handle SIGTERM/SIGINT gracefully to support zero-downtime deployments.
+
+```typescript
+// server.ts
+import { createServer } from 'http';
+import { app } from './app';
+import { logger } from './shared/utils/logger';
+
+const server = createServer(app);
+const PORT = process.env.PORT || 3000;
+
+server.listen(PORT, () => {
+  logger.info({ port: PORT }, 'Server started');
+});
+
+const shutdown = async (signal: string) => {
+  logger.info({ signal }, 'Shutdown signal received. Draining connections...');
+  
+  server.close(async (err) => {
+    if (err) {
+      logger.error({ err }, 'Error during graceful shutdown');
+      process.exit(1);
+    }
+    
+    // Close database connections
+    // await prisma.$disconnect();
+    // Close Redis connections
+    // await redis.quit();
+    
+    logger.info('Server shut down gracefully');
+    process.exit(0);
+  });
+
+  // Force shutdown after 30 seconds
+  setTimeout(() => {
+    logger.error('Forced shutdown after 30s timeout');
+    process.exit(1);
+  }, 30_000).unref();
+};
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+---
+
+## 4. TypeScript Configuration Standards
+
+### 4.1 Required Compiler Options
+
+These options ensure a modern, strict, and performant TypeScript environment for Node.js:
+
+- **target: ES2022**: Emits JavaScript compatible with modern Node.js versions.
+- **module: ESNext**: Uses the latest ECMAScript module system.
+- **moduleResolution: bundler**: Optimized for modern toolchains (use `node` if not using a bundler).
+- **strict: true**: Enables all strict type-checking flags.
+- **esModuleInterop: true**: Ensures compatibility with CommonJS imports.
+- **skipLibCheck: true**: Speeds up compilation by skipping type checks on dependencies.
+- **emitDecoratorMetadata**: Required for dependency injection and ORM decorators (NestJS/TypeORM).
+- **experimentalDecorators**: Enables support for decorators.
+- **baseUrl & 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,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "baseUrl": ".",
+    "paths": { "@/*": ["src/*"] }
+  }
+}
+```
+
+### 4.2 Strict Mode Checklist
+
+```jsonc
+// Additional strict flags beyond "strict": true
+{
+  "compilerOptions": {
+    // ... standard config from 4.1 ...
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "allowJs": false
+  }
+}
+```
+
+---
+
+## 5. Code Quality & Linting Standards
+
+### 5.0 Required ESLint Plugins for Backend
+
+| Plugin | Purpose |
+|--------|---------|
+| @eslint/js | ESLint recommended rules |
+| typescript-eslint | TypeScript-specific rules |
+| eslint-plugin-import | Import ordering + internal module restrictions |
+| eslint-plugin-unicorn | Modern JS best practices |
+| eslint-plugin-prettier | Prettier as ESLint rule |
+| eslint-plugin-boundaries | Enforce module isolation and folder dependency rules |
+
+Install:
+
+```bash
+pnpm add -D eslint @eslint/js typescript-eslint eslint-plugin-import eslint-plugin-unicorn eslint-plugin-prettier eslint-plugin-boundaries
+```
+
+### 5.1 Naming Conventions -- Complete Reference
+
+#### Core Principle: Names Must Be Self-Documenting
+
+**Single-letter variables are strictly prohibited** except loop indices `i, j, k` and unused parameters `_`.
+
+| Entity | Convention | Good Example | Bad Example |
+|--------|-----------|-------------|-------------|
+| Files (General) | kebab-case.dot-role.ts | user.controller.ts | UserService.ts |
+| Directories | kebab-case | user-profile/ | UserProfile/ |
+| Variables | camelCase | userCount, isLoading | uc, data |
+| Booleans | camelCase + prefix (is/has/can/should/was) | isActive, hasPermission, canSubmit | active, permission |
+| Functions | camelCase (verb+noun) | createUser(), getById() | create(), handle() |
+| Classes | PascalCase | UserRepository, UserService | userRepository |
+| Interfaces/Types| PascalCase | CreateUserDto, UserProfile | user_profile |
+| Enums | PascalCase name, UPPER_SNAKE_CASE members | Role.ADMIN | role.admin |
+| Constants | UPPER_SNAKE_CASE | MAX_RETRY_COUNT | maxRetryCount |
+| Database Tables | snake_case (singular) | user, role, permission<br/>*(Prisma: PascalCase model with `@@map()`)* | users, RoleTable |
+| Database Columns| snake_case | user_id, first_name | userId, firstName |
+| Env variables | UPPER_SNAKE + prefix | DATABASE_URL | db_url |
+
+#### Banned Variable Names
+
+| Banned | Why | Use Instead |
+|--------|-----|-------------|
+| const data | Too vague | const users, const response |
+| const temp | Temporary to whom? | const formattedDate |
+| const arr | Hungarian notation | const permissions |
+| const obj | Everything is an object | const config |
+| const result | Everything is a result | const validationResult |
+
+#### Boolean Naming
+
+Booleans must use a prefix that makes true/false obvious:
+`GOOD: isActive, hasPermission, canSubmit, shouldRetry, wasProcessed`
+`BAD:  active, permission, submit, retry, processed`
+
+#### 5.1.1 Module Isolation & Barrel File ESLint Configuration
+
+```javascript
+// eslint.config.js (flat config -- backend)
+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": [
+        {
+          mode: "full",
+          type: "modules",
+          pattern: "src/modules/*/**",
+        },
+        {
+          mode: "full",
+          type: "shared",
+          pattern: [
+            "src/shared/**",
+            "src/config/**",
+            "src/routes/**",
+            "src/app.ts",
+            "src/server.ts",
+          ],
+        },
+      ],
+    },
+    rules: {
+      // BLOCK: flat files at modules/ root (all modules must be in subdirectories)
+      "boundaries/entry-point": [
+        "error",
+        {
+          default: "disallow",
+          rules: [
+            {
+              target: ["src/modules/**/*.ts"],
+              allow: "src/modules/**/index.ts",
+            },
+          ],
+        },
+      ],
+
+      // BLOCK: deep imports bypassing barrel files (imports must go through index.ts)
+      "import/no-internal-modules": [
+        "error",
+        {
+          allow: [
+            // Only allow importing the barrel (index.ts) from each module
+            "src/modules/*/index",
+            // Allow shared utilities
+            "src/shared/**",
+            "src/config/**",
+            "src/routes/**",
+            "src/app",
+            "src/server",
+          ],
+        },
+      ],
+
+      // BLOCK: importing repositories or controllers from other modules
+      "import/no-restricted-paths": [
+        "error",
+        {
+          zones: [
+            {
+              target: "./src/modules/*/",
+              from: "./src/modules/*/",
+              except: ["./index.ts"],
+              message:
+                "Cross-module imports must go through the barrel (index.ts). " +
+                "Do not import another module's repository, controller, or validation files directly.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+];
+```
+
+**Enforcement Summary**:
+
+| Rule | What It Catches | Severity |
+|------|----------------|----------|
+| `boundaries/entry-point` | Flat files at `modules/` root | `error` |
+| `import/no-internal-modules` | Deep imports bypassing barrel files (e.g., importing `user.repository.ts` directly) | `error` |
+| `import/no-restricted-paths` | Cross-module imports of non-barrel files (repositories, controllers, etc.) | `error` |
+
+**Adding a New Module**:
+1. Create `src/modules/<module-name>/`
+2. Create the standard files: `*.controller.ts`, `*.service.ts`, `*.repository.ts`, `*.validation.ts`, `*.routes.ts`
+3. Create `index.ts` barrel that exports **only** the public service
+4. Add the new module to the `import/no-internal-modules` allow list: `"src/modules/<module-name>/index"`
+5. Update `import/no-restricted-paths` if the module needs cross-module access patterns
+
+---
+
+## 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'],
+};
+```
+
+---
+
+## 7. API Service Layer & Database Standards
+
+### 7.1 API Endpoint Standards
+
+- Use versioned REST endpoints: `GET /api/v1.0/users`
+- For multi-tenant applications: `GET /api/v1.0/:tenant_id/users`
+- Use plural nouns for resources, but singular for database tables.
+
+### 7.2 Standard Response Envelopes
+
+**Success (200/201)**:
+```json
+{
+  "statusCode": 200,
+  "success": true,
+  "message": "User retrieved successfully",
+  "data": [],
+  "pagination": { "page": 1, "limit": 10, "totalRecords": 100, "totalPages": 10 }
+}
+```
+
+**Error (400/500)**:
+```json
+{
+  "statusCode": 400,
+  "success": false,
+  "message": "Validation failed",
+  "errors": [ { "field": "email", "message": "Email is required" } ]
+}
+```
+
+### 7.2.1 Pagination Standard
+
+| Parameter | Type | Default | Max | Description |
+|-----------|------|---------|-----|-------------|
+| `page` | number | 1 | — | Current page number |
+| `limit` | number | 10 | 100 | Items per page |
+| `sortBy` | string | `createdAt` | — | Field to sort by |
+| `order` | `asc` \| `desc` | `desc` | — | Sort direction |
+
+Example: `GET /api/v1.0/users?page=1&limit=20&sortBy=name&order=asc`
+
+---
+
+## 8. Testing Standards
+
+- **Unit Testing**: Vitest or Jest. Aim for 80% line coverage, 75% branch coverage, 80% function coverage, and 80% statement coverage. Enforcement via CI.
+- **Integration Testing**: Test API endpoints with a test database (e.g., using Supertest).
+- **Mocks**: Mock external services (Email, S3, etc.) but use real databases (via TestContainers) if possible for integration tests.
+
+---
+
+## 9. Git Workflow & Commit Standards
+
+Follow the Git workflow and commit standards defined in the **CI/CD Standardization & DevOps Guide** (Section 2) and **Frontend Standardization & Deployment Guide** (Section 9).
+
+### 9.1 PR Template Enforcement
+
+Every repository must contain `.github/PULL_REQUEST_TEMPLATE.md`. The canonical backend PR template is provided by **`@aoholdings/backend-standards`** and is auto-copied into the consumer repo's `.github/` directory on `pnpm install`.
+
+```bash
+# Install the standards package (includes PR template)
+pnpm add -D @aoholdings/backend-standards
+
+# The PR template is automatically placed at .github/PULL_REQUEST_TEMPLATE.md
+```
+
+CI validates that all PRs follow the template structure. Module isolation compliance is a mandatory section in the template (see BACKEND_STANDARDS.md Section 3.2.1).
+
+---
+
+## 10. Security Standards
+
+### 10.1 Authentication & Authorization
+- **JWT**: Stateless authentication with short-lived access tokens and refresh tokens.
+- **Password Hashing**: Use `bcrypt` with 12 salt rounds.
+- **RBAC (Role-Based Access Control)**: Assign users to roles (Admin, Manager, User).
+- **ABAC (Attribute-Based Access Control)**: Fine-grained permissions based on attributes (Tenant ID, Owner ID).
+
+### 10.2 API Response Masking (Critical)
+Sensitive fields must NEVER be returned to the client. Use public DTOs in the service layer to ensure only safe fields are returned.
+
+**Global Response Interceptor Example**:
+```typescript
+class ResponseInterceptor {
+  private SENSITIVE_FIELDS = ['password', 'password_hash', 'salt', 'ssn', 'api_key', 'token'];
+
+  public mask(data: any): any {
+    if (typeof data !== 'object' || data === null) return data;
+    if (Array.isArray(data)) return data.map(item => this.mask(item));
+    
+    const masked: Record<string, any> = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (this.SENSITIVE_FIELDS.includes(key.toLowerCase())) {
+        masked[key] = '[REDACTED]';
+      } else {
+        masked[key] = this.mask(value);
+      }
+    }
+    return masked;
+  }
+}
+```
+
+### 10.3 Input Validation & Sanitization
+- Validate all incoming data using Zod or Class-Validator.
+- Sanitize HTML to prevent XSS if your application processes user-generated content.
+- Whitelist allowed request fields to prevent mass-assignment vulnerabilities.
+
+### 10.4 Rate Limiting
+
+All API endpoints must be protected by rate limiting to prevent abuse and ensure fair resource usage.
+
+| Endpoint Type | Window | Max Requests | Notes |
+|---------------|--------|-------------|-------|
+| General API | 15 min | 100 per IP | Default for all endpoints |
+| Auth endpoints (login, register, MFA) | 15 min | 5 per IP | Prevents brute-force |
+| Password reset / email verification | 1 hour | 3 per IP | Prevents spam |
+
+```typescript
+import rateLimit from 'express-rate-limit';
+
+export const generalLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,  // 15 minutes
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { statusCode: 429, success: false, message: 'Too many requests. Please try again later.' },
+});
+
+export const authLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 5,
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+```
+
+### 10.5 CORS Configuration
+
+All backend services must configure CORS with an explicit origin whitelist. Never use wildcard (`*`) origins in production.
+
+```typescript
+import cors from 'cors';
+
+const ALLOWED_ORIGINS = process.env.CORS_ORIGINS?.split(',') || ['http://localhost:5173'];
+
+export const corsMiddleware = cors({
+  origin: (origin, callback) => {
+    if (!origin || ALLOWED_ORIGINS.includes(origin)) {
+      callback(null, true);
+    } else {
+      callback(new Error('Not allowed by CORS'));
+    }
+  },
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
+  exposedHeaders: ['X-Request-ID', 'X-RateLimit-Remaining'],
+  maxAge: 86400,
+});
+```
+
+### 10.6 Security Headers
+
+Use `helmet` middleware to set standard security headers on all responses.
+
+```typescript
+import helmet from 'helmet';
+
+app.use(helmet({
+  contentSecurityPolicy: false,  // Configured separately per application
+  crossOriginEmbedderPolicy: true,
+  crossOriginOpenerPolicy: { policy: 'same-origin' },
+  crossOriginResourcePolicy: { policy: 'same-origin' },
+  dnsPrefetchControl: { allow: false },
+  frameguard: { action: 'deny' },
+  hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
+  referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+  xssFilter: true,
+}));
+```
+
+---
+
+## 11. Enforcement: Husky, Git Hooks & CI/CD Validation
+
+### 11.1 Core Principle: Automation Over Manual Review
+
+Every standard must be machine-enforced to be effective.
+
+| Layer | Tool | When | Purpose |
+|-------|------|------|---------|
+| L1: Editor | ESLint + Prettier | Every save | Immediate developer feedback |
+| L2: Pre-commit | Husky + lint-staged | Every commit | Block bad code locally |
+| L3: CI Pipeline | GitHub Actions | Every PR | Enforce standards before merge |
+| L4: CD Pipeline | Smoke Tests | Every deploy | Verify runtime integrity |
+
+### 11.2 Required Git Hooks (Husky)
+
+- **pre-commit**: Runs `lint-staged` (ESLint + Prettier).
+- **commit-msg**: Validates commit messages using `commitlint`.
+- **pre-push**: Runs linting, full test suite, type checking, **and modularization validation**.
+
+### 11.3 Pre-push Hook with Modularization Check
+
+```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
+```
+
+### 11.4 Modularization Validation Script
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "check-modularization": "node scripts/check-modularization.mjs",
+    "lint": "eslint --ext .ts --max-warnings 0 .",
+    "lint:fix": "eslint --ext .ts . --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "check-types": "tsc --noEmit",
+    "prepare": "husky"
+  }
+}
+```
+
+Create `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 ROOT = join(__dirname, '..');
+const MODULES_DIR = join(ROOT, 'src', 'modules');
+
+const BARREL_FILE = 'index.ts';
+let errors = 0;
+
+function isDir(p) { try { return statSync(p).isDirectory(); } catch { return false; } }
+
+console.log('\n🔍 Checking backend module modularization...\n');
+
+if (!existsSync(MODULES_DIR)) {
+  console.log('  No src/modules/ directory found. Skipping.');
+} else {
+  const entries = readdirSync(MODULES_DIR);
+
+  for (const entry of entries) {
+    const entryPath = join(MODULES_DIR, entry);
+
+    if (isDir(entryPath)) {
+      console.log(`  📁 modules/${entry}/`);
+      const barrelPath = join(entryPath, BARREL_FILE);
+
+      if (!existsSync(barrelPath)) {
+        console.error(`    ❌ ERROR: Missing required ${BARREL_FILE} barrel file`);
+        errors++;
+        continue;
+      }
+
+      // Verify barrel only exports service (not repository, controller, etc.)
+      const barrelContent = readdirSync(entryPath);
+      const hasRepo = barrelContent.some(f => f.includes('repository'));
+      const hasCtrl = barrelContent.some(f => f.includes('controller'));
+      const hasValidation = barrelContent.some(f => f.includes('validation'));
+
+      if (hasRepo) console.log(`    ⚠️  WARNING: Repository file detected -- ensure it is NOT exported from ${BARREL_FILE}`);
+      if (hasCtrl) console.log(`    ⚠️  WARNING: Controller file detected -- ensure it is NOT exported from ${BARREL_FILE}`);
+      if (hasValidation) console.log(`    ⚠️  WARNING: Validation file detected -- ensure it is NOT exported from ${BARREL_FILE}`);
+    } else if (entry.endsWith('.ts')) {
+      console.error(`    ❌ ERROR: Flat file "modules/${entry}" at root -- move into a module subdirectory`);
+      errors++;
+    }
+  }
+}
+
+console.log(`\n${errors === 0 ? '✅' : '❌'} Backend modularization check complete. Errors: ${errors}\n`);
+if (errors > 0) process.exit(1);
+```
+
+### 11.5 Anti-Bypass (`--no-verify`) Protection
+
+The `git commit --no-verify` flag skips local hooks. Since CI runs the same checks independently, `--no-verify` only delays validation — it never bypasses it.
+
+**CI duplicates ALL pre-commit checks**:
+
+```yaml
+# .github/workflows/ci.yml (backend)
+- name: Lint (catches --no-verify bypass)
+  run: pnpm lint
+
+- name: Check Modularization (catches --no-verify bypass)
+  run: pnpm check-modularization
+
+- name: Validate Commit Messages (catches --no-verify bypass)
+  run: pnpm exec commitlint --from origin/${{ github.base_ref }} --to HEAD
+```
+
+**The `--no-verify` policy**:
+
+| Action | Consequence |
+|--------|-------------|
+| `git commit --no-verify` | Commit lands locally; CI blocks PR if checks fail |
+| Tampering with `.husky/` | Caught in code review; `.husky/` is committed |
+| Disabling husky in `package.json` | CI re-installs hooks via `pnpm prepare` |
+
+> **There is no merge path that bypasses these standards.** Even if hooks are skipped locally, CI enforces the same checks before merge.
+
+---
+
+## 12. CI/CD & Deployment Standards
+
+Refer to the **CI/CD Standardization & DevOps Guide** for full details.
+- **Docker**: Every project must have a multi-stage Dockerfile.
+- **Migrations**: Migrations must run automatically in dev and staging CD pipelines. Production migrations require manual approval per the **CI/CD Standardization & DevOps Guide** (Section 10).
+- **Health Checks**: Implement `/health` endpoint for K8s liveness/readiness probes.
+
+---
+
+## 13. Monitoring & Observability
+
+- **Sentry**: Capture runtime exceptions.
+- **Prometheus/Grafana**: Track API latency, request counts, and error rates.
+- **Structured Logging**: Log in JSON format to stdout for log aggregation (ELK/Loki).
+
+---
+
+## 14. Logging & Error Handling
+
+### 14.1 Structured Logging
+
+All applications must use structured JSON logging to stdout. This allows for easy parsing by log aggregators (ELK, Loki, Datadog).
+
+**Recommended Logger (Pino)**:
+```typescript
+import pino from 'pino';
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  formatters: {
+    level: (label) => ({ level: label.toUpperCase() }),
+  },
+  timestamp: pino.stdTimeFunctions.isoTime,
+});
+```
+
+### 14.1.1 Request ID Middleware
+
+Every request must carry a unique `X-Request-ID` header for distributed tracing.
+
+```typescript
+import { v4 as uuidv4 } from 'uuid';
+import type { Request, Response, NextFunction } from 'express';
+
+export const requestIdMiddleware = (req: Request, res: Response, next: NextFunction) => {
+  const requestId = (req.headers['x-request-id'] as string) || uuidv4();
+  req.headers['x-request-id'] = requestId;
+  res.setHeader('X-Request-ID', requestId);
+  next();
+};
+
+// In logger: include requestId in every log entry
+logger.child({ requestId: req.headers['x-request-id'] });
+```
+
+### 14.2 Centralized Error Handling
+
+> **CRITICAL**: Import `express-async-errors` at the top of `app.ts` to ensure async route handler rejections are caught by the error handler middleware. Without this, unhandled promise rejections in async routes will crash the process.
+>
+> ```typescript
+> import 'express-async-errors';
+> ```
+
+Use a global error middleware to catch all unhandled exceptions and return a standardized response.
+
+```typescript
+export const errorHandler = (err: Error, req: Request, res: Response, next: NextFunction) => {
+  const statusCode = (err as any).statusCode || 500;
+  logger.error({ err, path: req.path }, 'Unhandled exception');
+
+  res.status(statusCode).json({
+    statusCode,
+    success: false,
+    message: process.env.NODE_ENV === 'production' ? 'Internal server error' : err.message,
+    stack: process.env.NODE_ENV === 'production' ? undefined : err.stack,
+  });
+};
+```
+
+---
+
+## 15. Documentation Standards
+
+- **Swagger**: Every API must expose a Swagger UI at `/docs`.
+- **README**: Clear setup instructions, environment variables, and script definitions.
+
+---
+
+## 16. Appendix: Quick References
+
+Standard `package.json` scripts:
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js",
+    "test": "vitest",
+    "lint": "eslint .",
+    "check-modularization": "node scripts/check-modularization.mjs",
+    "db:migrate": "prisma migrate deploy"
+  }
+}
+```
+
+---
+
+> **This is a living document.** It should be reviewed and updated quarterly by the line manager and architecture team.
+---
+## Appendix A. Backend Cost & Pricing Reference (June 2026)
+
+> Use these estimates for staffing, infrastructure budgeting, and vendor selection. Amounts are mid-2026 commercial market approximations; actual costs vary by geography, vendor, and contract terms.
+
+### 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.
+
+### A.1 Estimated Annual Costs by Project Size
+
+| Project Size | Backend Devs | Frontend Devs | DevOps | QA / Security | Tools & Licenses | Infrastructure | Total Est. Annual |
+|---|---|---|---|---|---|---|---|
+| Small (MVP / closed beta) | 1 | 1 | 0.25 | 0.25 | ~USD 2,000 | ~USD 2,000 | ~USD 170,000 |
+| Medium (production SaaS) | 2 | 2 | 0.5 | 0.5 | ~USD 5,000 | ~USD 4,000 | ~USD 380,000 |
+| Large (enterprise / multi-tenant) | 4 | 4 | 1 | 1 | ~USD 12,000 | ~USD 10,000 | ~USD 900,000 |
+| Enterprise (regulated / high scale) | 6+ | 6+ | 2+ | 2+ | ~USD 25,000+ | ~USD 25,000+ | ~USD 1,800,000+ |
+
+### A.2 Tooling & License Costs (Annual)
+
+| Tool / Service | Purpose | Typical Tier | Est. Cost | Notes |
+|---|---|---|---|---|
+| GitHub Enterprise / Teams | Repo hosting, Actions, GHCR, Environments | Team: USD 4/user/mo; Enterprise: USD 21/user/mo | USD 2,400 – USD 25,000/yr | Private repo Actions minutes are billed past 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; self-hosted option at scale. |
+| Datadog / New Relic / Azure Monitor | APM, logs, traces | Host/ingestion based | USD 1,500 – USD 10,000+/yr | Strong for microservice backends. |
+| SonarCloud / SonarQube | Static analysis, quality gate | Developer: ~USD 25/dev/mo; Enterprise: annually | USD 2,000 – USD 15,000/yr | SonarCloud SaaS vs self-hosted with infra cost. |
+| Snyk / Trivy / Dependabot | Dependency & container vulnerability scanning | Snyk Team: ~USD 19/dev/mo; Trivy: free | USD 0 – USD 5,000/yr | Trivy + GitHub Dependabot often cover needs at zero extra cost. |
+| Auth0 / WorkOS / Clerk | Managed auth (optional if custom NestJS auth) | Free to USD 23+/mo | USD 0 – USD 2,000/yr | Custom auth saves license cost but needs more engineering time. |
+| Redis Cloud (optional) | Managed Redis / Valkey | 1 GB – 50 GB | USD 100 – USD 1,000/yr | Useful for cache-heavy workloads; not strictly required. |
+| Managed Postgres (Azure/RDS/Cloud SQL) | 2 vCPU / 8 GB + storage | USD 150 – USD 500/mo | USD 1,800 – USD 6,000/yr | Preferred for regulated backends due to backups and HA options. |
+| Azure Key Vault / AWS Secrets Manager | Secret storage & rotation | Per-secret / per-operation pricing | USD 200 – USD 1,500/yr | Prevents expensive breach remediation. |
+| Object Storage (S3 / Blob) | File uploads, media, exports | 1 TB + egress | USD 240 – USD 960/yr | Backend-controlled uploads/downloads. |
+
+### A.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 + LB | USD 300 – USD 900 | USD 3,600 – USD 10,800 |
+| Managed PostgreSQL | 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 | 1 TB + egress | USD 20 – USD 80 | USD 240 – USD 960 |
+| SSL / ingress certs | Managed | Often free | USD 0 |
+| DNS / domain | -- | USD 10 – USD 30 | USD 120 – USD 360 |
+
+> These are mid-2026 reference prices. Reserved/commitment terms generally reduce compute cost by 20%–40%.
+
+---
+
+### A.4 Open-Source vs Commercial Alternatives (2026)
+
+| Need | Commercial Option | OSS Alternative | Est. Savings | Trade-offs / Notes |
+|---|---|---|---|---|
+| CI/CD Platform | GitHub Actions / Azure DevOps / GitLab.com | **Woodpecker**, **Gitea Actions**, **Jenkins**, **Drone CI** | Up to ~USD 10,000+/yr | OSS needs self-hosted runners/infra and more ops. Best when private-minute costs dominate. |
+| Auth (optional) | Auth0 / WorkOS / Clerk | **Keycloak**, **Authentik**, **SuperTokens** | ~USD 0 – USD 2,000/yr | Keycloak is the most mature. SuperTokens is lighter and DX-friendly. Custom NestJS auth has highest eng cost. |
+| Managed Redis | Redis Cloud | **Valkey** (Linux Foundation fork) / self-hosted Redis | ~USD 100 – USD 1,000/yr | Valkey is API/protocol compatible with Redis and avoids license changes. Self-hosted shifts infra cost to ops. |
+| API Gateway / BFF | Kong Enterprise / Zuplo | **Kong OSS**, **APISIX**, **Traefik** | ~USD 1,000 – USD 10,000/yr | OSS APIs/gateways are production-grade; commercial adds support, RBAC, and analytics. |
+| Logging | Datadog / Splunk / New Relic | **Loki + Promtail**, **OpenSearch**, **Vector + ClickHouse** | ~USD 1,000 – USD 8,000/yr | Loki is the easiest OSS drop-in for K8s logging. OpenSearch is heavier but more capable. |
+| Monitoring/APM | Datadog / New Relic / Azure Monitor | **Prometheus + Grafana**, **SigNoz**, **Grafana Cloud** | ~USD 1,500 – USD 10,000+/yr | Grafana Cloud Pro is cheaper than Datadog. Self-hosted Prometheus saves most, but needs SRE skill. |
+| Static Analysis | SonarCloud | **SonarQube Community**, **CodeQL**, **ESLint + TS strict + Coverage** | ~USD 2,000 – USD 15,000/yr | SonarQube CE is capable. CodeQL is free on GitHub. Pre-commit linting is free regardless. |
+| Dependency Scanning | Snyk | **Trivy**, **OWASP Dependency-Check**, **Dependabot**, **Renovate** | ~USD 0 – USD 5,000/yr | Dependabot + Trivy usually cover needs at zero marginal license cost. Renovate is best for automated updates. |
+| Secret Storage | Azure Key Vault premium | **HashiCorp Vault OSS**, **SOPS + age/GPG**, **Doppler CLI (free tier)** | ~USD 200 – USD 1,500/yr | Vault OSS is mature. SOPS is best if secrets are already committed encrypted in Git. |
+| Object / File Storage | Blob / S3 managed | **MinIO**, **SeaweedFS** | ~USD 240 – USD 960/yr | Useful on-prem or when egress is expensive. Managed cloud is simpler for small teams. |
+
+### A.5 Cost Optimization Tips for Backend
+
+- **Cache first**: Redis/Valkey reduces DB load and compute spend.
+- **Connection pooling**: Prevents overprovisioning DB and app replicas.
+- **Queue async work**: Bull/BullMQ smooths spikes without scaling stateless workers.
+- **Batch and debounce**: Fewer API calls reduce downstream costs.
+- **Right-size replicas**: Start small; use HPA before adding more replicas.
+- **Reserved/commitment terms**: 1-year or 3-year reserved compute often saves 20%–40%.
+- **OSS first, buy when support matters**: Choose open-source defaults; move to commercial only when support contracts or compliance features justify it.
+
+### A.6 Sources & Methodology
+
+- Pricing is based on **public list prices** from vendor pricing pages:
+  - Azure pricing: https://azure.microsoft.com/en-us/pricing/
+  - Azure DevOps pricing: https://azure.microsoft.com/en-us/pricing/details/devops/azure-devops-services/
+  - 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/
+  - Redis Cloud: https://redis.io/pricing/
+  - Trivy: https://github.com/aquasecurity/trivy (open source)
+- 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.
+- Infrastructure estimates use managed cloud VM/service pricing without reserved/commitment discounts by default; exact regional pricing is available from cloud provider calculators.