@flusys/nestjs-shared 4.0.2 → 4.1.0

package/README.md

@@ -1,1858 +1,745 @@
-# Shared Package Guide
+# @flusys/nestjs-shared
 
-> **Package:** `@flusys/nestjs-shared`
-> **Version:** 4.0.2
-> **Type:** Shared NestJS utilities, classes, decorators, guards, and modules
+> Shared NestJS infrastructure — generic CRUD base classes, JWT guards, permission system, hybrid caching, structured logging, multi-tenancy, and response standardization for the entire FLUSYS ecosystem.
 
-This comprehensive guide covers the shared package - the shared NestJS infrastructure layer.
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-shared.svg)](https://www.npmjs.com/package/@flusys/nestjs-shared)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
 - [Overview](#overview)
-- [Package Architecture](#package-architecture)
-- [ApiService - Generic CRUD Service](#apiservice---generic-crud-service)
-- [RequestScopedApiService](#requestscopedapiservice)
-- [ApiController - Generic CRUD Controller](#apicontroller---generic-crud-controller)
-- [Decorators](#decorators)
+- [Features](#features)
+- [Architecture Position](#architecture-position)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Base Classes](#base-classes)
+  - [ApiService](#apiservice)
+  - [RequestScopedApiService](#requestscopedapiservice)
+  - [createApiController](#createapicontroller)
+- [Base Entities](#base-entities)
+- [Response DTOs](#response-dtos)
 - [Guards](#guards)
-- [Middleware](#middleware)
+- [Decorators](#decorators)
 - [Interceptors](#interceptors)
-- [Caching System](#caching-system)
-- [Multi-Tenant DataSource](#multi-tenant-datasource)
-- [DTOs](#dtos)
-- [Base Entities](#base-entities)
-- [Utilities](#utilities)
-- [Error Handling](#error-handling)
-- [Constants](#constants)
+- [HybridCache](#hybridcache)
+- [Middlewares](#middlewares)
+- [Exceptions & Filters](#exceptions--filters)
+- [Modules](#modules)
+- [Multi-Tenant DataSource Service](#multi-tenant-datasource-service)
 - [Logger System](#logger-system)
-- [API Reference](#api-reference)
+- [Permission System](#permission-system)
+- [Permission Constants](#permission-constants)
+- [Cross-Module Adapter Interfaces](#cross-module-adapter-interfaces)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## Overview
 
-`@flusys/nestjs-shared` provides shared utilities for building scalable NestJS applications:
+`@flusys/nestjs-shared` is the shared infrastructure layer that all FLUSYS feature modules depend on. It provides the building blocks — generic CRUD, guards, decorators, DTOs, caching — so each feature module only needs to implement business logic.
 
-- **Generic CRUD** - Standardized API controller and service patterns
-- **Permission System** - Role and permission-based access control with complex logic and wildcard matching
-- **Caching** - In-memory + Redis hybrid caching (HybridCache)
-- **Request Correlation** - AsyncLocalStorage-based request tracking with correlation IDs
-- **Middleware** - Logging, correlation, and performance monitoring
-- **Interceptors** - Response metadata, idempotency, auto field setting
-- **Multi-Tenancy** - Dynamic database connection management with connection pooling
-- **Error Handling** - Centralized error handling with sensitive data redaction
-- **Logging** - Winston-based logging with tenant-aware routing and daily rotation
+---
 
-### Package Hierarchy
+## Features
 
-```
-@flusys/nestjs-core     <- Pure TypeScript (foundation)
-     |
-@flusys/nestjs-shared   <- Shared NestJS utilities (THIS PACKAGE)
-     |
-@flusys/nestjs-auth     <- Uses common classes
-     |
-@flusys/nestjs-iam      <- Uses common patterns
-     |
-@flusys/nestjs-storage  <- Uses common patterns
-```
+- **Generic CRUD** — `ApiService` + `createApiController` with 7 standardized POST-only RPC endpoints
+- **Permission System** — AND/OR/nested logic trees with wildcard matching, action-level guards
+- **Hybrid Cache** — In-memory (CacheableMemory) + Redis (`@keyv/redis`) with automatic L1/L2 fallback
+- **Request Correlation** — `AsyncLocalStorage`-based request tracking with correlation IDs
+- **Structured Logging** — Winston + daily-rotate-file with tenant-aware routing
+- **Multi-Tenancy** — Dynamic database connection management with per-tenant DataSource pooling
+- **Response Standardization** — Consistent `SingleResponseDto`, `ListResponseDto`, `BulkResponseDto`, `MessageResponseDto`
+- **Security** — HTML sanitization (XSS prevention), slug generation, path traversal protection
+- **Interceptors** — Response metadata, idempotency, audit fields, slug auto-generation
 
 ---
 
-## Package Architecture
+## Architecture Position
 
 ```
-nestjs-shared/
-├── src/
-│   ├── classes/              # Base classes
-│   │   ├── api-service.class.ts           # Generic CRUD service
-│   │   ├── api-controller.class.ts        # Generic CRUD controller factory (createApiController)
-│   │   ├── request-scoped-api.service.ts  # REQUEST-scoped service base
-│   │   ├── hybrid-cache.class.ts          # Two-tier caching (memory + Redis)
-│   │   ├── winston.logger.class.ts        # Winston logger config with tenant routing
-│   │   └── winston-logger-adapter.class.ts # ILogger adapters
-│   │
-│   ├── constants/            # Injection tokens & constants
-│   │   ├── permissions.ts                 # Permission constants (PERMISSIONS)
-│   │   └── index.ts                       # Metadata keys, injection tokens, headers
-│   │
-│   ├── decorators/           # Custom decorators
-│   │   ├── api-response.decorator.ts      # @ApiResponseDto
-│   │   ├── current-user.decorator.ts      # @CurrentUser
-│   │   ├── public.decorator.ts            # @Public
-│   │   ├── require-permission.decorator.ts # @RequirePermission, @RequireAnyPermission, @RequirePermissionLogic
-│   │   ├── sanitize-html.decorator.ts     # @SanitizeHtml, @SanitizeAndTrim
-│   │   └── index.ts
-│   │
-│   ├── dtos/                 # Shared DTOs
-│   │   ├── delete.dto.ts                  # DeleteDto with soft/restore/permanent
-│   │   ├── filter-and-pagination.dto.ts   # FilterAndPaginationDto, GetByIdBodyDto
-│   │   ├── identity-response.dto.ts       # IdentityResponseDto
-│   │   ├── pagination.dto.ts              # PaginationDto
-│   │   ├── response-payload.dto.ts        # Single/List/Bulk/Message response DTOs
-│   │   └── index.ts
-│   │
-│   ├── entities/             # Base entities
-│   │   ├── identity.ts                    # Base entity with UUID & audit fields
-│   │   ├── user-root.ts                   # Base user entity
-│   │   └── index.ts
-│   │
-│   ├── exceptions/           # Custom exceptions
-│   │   └── permission.exception.ts        # Permission-related exceptions
-│   │
-│   ├── guards/               # Authentication & authorization
-│   │   ├── jwt-auth.guard.ts              # JWT token validation with @Public support
-│   │   └── permission.guard.ts            # Permission checks with wildcard matching
-│   │
-│   ├── interceptors/         # Request/response interceptors
-│   │   ├── delete-empty-id-from-body.interceptor.ts
-│   │   ├── idempotency.interceptor.ts     # Prevents duplicate POST requests
-│   │   ├── query-performance.interceptor.ts
-│   │   ├── response-meta.interceptor.ts   # Adds _meta to responses
-│   │   ├── set-user-field-on-body.interceptor.ts  # Factory + SetCreatedByOnBody, etc.
-│   │   └── slug.interceptor.ts            # Auto-generates slug from name
-│   │
-│   ├── interfaces/           # TypeScript interfaces
-│   │   ├── api.interface.ts               # IService interface
-│   │   ├── datasource.interface.ts        # IDataSourceProvider
-│   │   ├── identity.interface.ts          # IIdentity interface
-│   │   ├── logged-user-info.interface.ts  # ILoggedUserInfo
-│   │   ├── logger.interface.ts            # ILogger interface
-│   │   ├── module-config.interface.ts     # IModuleConfigService
-│   │   └── permission.interface.ts        # ILogicNode, PermissionConfig, PermissionGuardConfig
-│   │
-│   ├── middlewares/          # Middleware
-│   │   └── logger.middleware.ts           # Request correlation with AsyncLocalStorage
-│   │
-│   ├── modules/              # NestJS modules
-│   │   ├── cache/cache.module.ts          # CacheModule.forRoot()
-│   │   ├── datasource/
-│   │   │   ├── datasource.module.ts       # DataSourceModule.forRoot/forRootAsync/forFeature
-│   │   │   └── multi-tenant-datasource.service.ts
-│   │   └── utils/
-│   │       ├── utils.module.ts            # Global UtilsModule
-│   │       └── utils.service.ts           # Cache helpers, string utilities
-│   │
-│   └── utils/                # Utility functions
-│       ├── html-sanitizer.util.ts         # escapeHtml, escapeHtmlVariables
-│       ├── query-helpers.util.ts          # applyCompanyFilter, validateCompanyOwnership
-│       ├── request.util.ts                # isBrowserRequest, buildCookieOptions, parseDurationToMs
-│       └── string.util.ts                 # generateSlug, generateUniqueSlug
+@flusys/nestjs-core
+        ↓
+@flusys/nestjs-shared   ← THIS PACKAGE
+        ↓
+┌───────┴───────────────────────┐
+auth  iam  storage  form-builder  email  event-manager  notification  localization
+(all depend on nestjs-shared, none depend on each other)
 ```
 
 ---
 
-## ApiService - Generic CRUD Service
+## Compatibility
 
-The `ApiService` base class provides standardized CRUD operations with caching, pagination, and transaction support.
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@nestjs/core` | `^11.0.0` |
+| `@nestjs/common` | `^11.0.0` |
+| `@nestjs/passport` | `^10.0.0` |
+| `typeorm` | `^0.3.0` |
+| `winston` | `^3.0.0` |
+| `keyv` | `^5.0.0` |
+| Node.js | `>= 18.x` |
 
-### Basic Usage
+---
 
-```typescript
-import { ApiService, HybridCache } from '@flusys/nestjs-shared';
-import { UtilsService } from '@flusys/nestjs-shared';
-import { Injectable, Inject } from '@nestjs/common';
-import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
-import { CACHE_INSTANCE } from '@flusys/nestjs-shared';
+## Installation
 
-@Injectable()
-export class UserService extends ApiService<
-  CreateUserDto,         // Create DTO
-  UpdateUserDto,         // Update DTO
-  IUser,                 // Interface
-  User,                  // Entity
-  Repository<User>       // Repository type
-> {
-  constructor(
-    @InjectRepository(User)
-    protected override repository: Repository<User>,
-    @Inject(CACHE_INSTANCE)
-    protected override cacheManager: HybridCache,
-    @Inject(UtilsService)
-    protected override utilsService: UtilsService,
-  ) {
-    super(
-      'user',              // Entity name (for query alias)
-      repository,
-      cacheManager,
-      utilsService,
-      'UserService',       // Logger context name
-      true,                // Enable caching
-    );
-  }
-}
+```bash
+npm install @flusys/nestjs-shared @flusys/nestjs-core
 ```
 
-### ApiService Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `insert` | `(dto, user) → Promise<T>` | Create single entity |
-| `insertMany` | `(dtos[], user) → Promise<T[]>` | Create multiple entities |
-| `findById` | `(id, user, select?) → Promise<T>` | Find entity by ID (throws if not found) |
-| `findByIds` | `(ids[], user) → Promise<T[]>` | Find multiple by IDs |
-| `getAll` | `(search, filterDto, user) → Promise<{data, total}>` | Get paginated list with filters |
-| `update` | `(dto, user) → Promise<T>` | Update single entity |
-| `updateMany` | `(dtos[], user) → Promise<T[]>` | Update multiple entities |
-| `delete` | `(deleteDto, user) → Promise<null>` | Soft/permanent delete or restore |
-| `clearCacheForAll` | `() → Promise<void>` | Clear all entity cache |
-| `clearCacheForId` | `(entities[]) → Promise<void>` | Clear cache for specific entities |
-
-### Customization Hooks
-
-```typescript
-@Injectable()
-export class UserService extends ApiService<...> {
-  // Repository initialization (for RequestScopedApiService)
-  protected async ensureRepositoryInitialized(): Promise<void> { }
-
-  // Convert DTO to entity (called for single item)
-  protected async convertSingleDtoToEntity(
-    dto: CreateDtoT | UpdateDtoT,
-    user: ILoggedUserInfo | null
-  ): Promise<EntityT> { }
-
-  // Convert entity to response DTO
-  protected convertEntityToResponseDto(entity: EntityT, isRaw: boolean): InterfaceT { }
-
-  // Convert entity list to response list
-  protected convertEntityListToResponseListDto(entities: EntityT[], isRaw: boolean): InterfaceT[] { }
-
-  // Customize SELECT query (add joins, selections)
-  protected async getSelectQuery(
-    query: SelectQueryBuilder<EntityT>,
-    user: ILoggedUserInfo | null,
-    select?: string[]
-  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
-
-  // Add WHERE filters from filter object
-  protected async getFilterQuery(
-    query: SelectQueryBuilder<EntityT>,
-    filter: Record<string, any>,
-    user: ILoggedUserInfo | null
-  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
-
-  // Add global search conditions (default: searches 'name' field)
-  protected async getGlobalSearchQuery(
-    query: SelectQueryBuilder<EntityT>,
-    search: string,
-    user: ILoggedUserInfo | null
-  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
-
-  // Add sort conditions
-  protected async getSortQuery(
-    query: SelectQueryBuilder<EntityT>,
-    sort: Record<string, 'ASC' | 'DESC'>,
-    user: ILoggedUserInfo | null
-  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
-
-  // Add extra query conditions (e.g., company filtering)
-  protected async getExtraManipulateQuery(
-    query: SelectQueryBuilder<EntityT>,
-    dto: FilterAndPaginationDto,
-    user: ILoggedUserInfo | null
-  ): Promise<{ query: SelectQueryBuilder<EntityT>; isRaw: boolean }> { }
-
-  // Lifecycle hooks
-  protected async beforeInsertOperation(dto, user, queryRunner): Promise<void> { }
-  protected async afterInsertOperation(entities[], user, queryRunner): Promise<void> { }
-  protected async beforeUpdateOperation(dto, user, queryRunner): Promise<void> { }
-  protected async afterUpdateOperation(entities[], user, queryRunner): Promise<void> { }
-  protected async beforeDeleteOperation(dto, user, queryRunner): Promise<void> { }
-  protected async afterDeleteOperation(entities[], user, queryRunner): Promise<void> { }
-}
-
 ---
 
-## RequestScopedApiService
+## Quick Start
 
-For dynamic entity resolution based on runtime configuration (e.g., company feature toggling). Extends `ApiService` with lazy repository initialization.
+### 1. Register Global Modules
 
 ```typescript
-import { RequestScopedApiService, HybridCache, CACHE_INSTANCE } from '@flusys/nestjs-shared';
-import { UtilsService, IDataSourceProvider } from '@flusys/nestjs-shared';
-import { Injectable, Scope, Inject } from '@nestjs/common';
-import { DataSource, EntityTarget, Repository } from 'typeorm';
-
-@Injectable({ scope: Scope.REQUEST })
-export class RoleService extends RequestScopedApiService<
-  CreateRoleDto,
-  UpdateRoleDto,
-  IRole,
-  RoleBase,
-  Repository<RoleBase>
-> {
-  private actionRepository!: Repository<Action>;
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { CacheModule, UtilsModule, LoggerMiddleware } from '@flusys/nestjs-shared';
 
-  constructor(
-    @Inject(CACHE_INSTANCE) protected override cacheManager: HybridCache,
-    @Inject(UtilsService) protected override utilsService: UtilsService,
-    @Inject(ModuleConfigService) private readonly config: ModuleConfigService,
-    @Inject(DataSourceProvider) private readonly provider: DataSourceProvider,
-  ) {
-    // Pass null for repository - will be initialized dynamically
-    super('role', null as any, cacheManager, utilsService, 'RoleService', true);
-  }
-
-  // Required: Resolve which entity class to use based on runtime config
-  protected resolveEntity(): EntityTarget<RoleBase> {
-    return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
-  }
-
-  // Required: Return the DataSource provider for repository creation
-  protected getDataSourceProvider(): IDataSourceProvider {
-    return this.provider;
-  }
-
-  // Override to initialize additional repositories alongside primary
-  protected override async ensureRepositoryInitialized(): Promise<void> {
-    await super.ensureRepositoryInitialized();
-    // Initialize additional repositories if needed
-    const repos = await this.initializeAdditionalRepositories([Action]);
-    this.actionRepository = repos[0];
+@Module({
+  imports: [
+    CacheModule.forRoot(true), // true = global
+    UtilsModule,
+  ],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
   }
 }
 ```
 
-### Key Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `ensureRepositoryInitialized()` | `() → Promise<void>` | Auto-called before operations, initializes repository |
-| `resolveEntity()` | `() → EntityTarget<EntityT>` | **Abstract** - Return entity class based on runtime config |
-| `getDataSourceProvider()` | `() → IDataSourceProvider` | **Abstract** - Return DataSource provider |
-| `initializeAdditionalRepositories()` | `(entities[]) → Promise<Repository[]>` | Initialize extra repositories |
-| `getDataSourceForService()` | `() → Promise<DataSource>` | Get raw DataSource for transactions |
-
-### IDataSourceProvider Interface
+### 2. Register Global Exception Filter & Interceptors
 
 ```typescript
-interface IDataSourceProvider {
-  getRepository<T extends ObjectLiteral>(entity: EntityTarget<T>): Promise<Repository<T>>;
-  getDataSource(): Promise<DataSource>;
+import { GlobalExceptionFilter, ResponseMetaInterceptor } from '@flusys/nestjs-shared';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.useGlobalFilters(new GlobalExceptionFilter());
+  app.useGlobalInterceptors(new ResponseMetaInterceptor());
+  await app.listen(3000);
 }
 ```
 
 ---
 
-## ApiController - Generic CRUD Controller
+## Base Classes
 
-The `createApiController` factory creates standardized POST-only RPC controllers with full Swagger documentation.
+### ApiService
 
-### Basic Usage
+Generic CRUD service for simple, static repositories (no dynamic entity switching):
 
 ```typescript
-import { createApiController } from '@flusys/nestjs-shared';
-import { Controller, Inject } from '@nestjs/common';
-import { ApiTags } from '@nestjs/swagger';
-
-@ApiTags('Users')
-@Controller('users')
-export class UserController extends createApiController<
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  IUser,
-  UserService
->(CreateUserDto, UpdateUserDto, UserResponseDto) {
-  constructor(@Inject(UserService) protected service: UserService) {
-    super(service);
+import { Injectable, Inject } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { ApiService } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { UtilsService } from '@flusys/nestjs-shared/modules';
+
+@Injectable()
+export class ProductService extends ApiService<
+  CreateProductDto,
+  UpdateProductDto,
+  IProduct,
+  Product,
+  Repository<Product>
+> {
+  constructor(
+    @InjectRepository(Product) repo: Repository<Product>,
+    @Inject('CACHE_INSTANCE') cacheManager: HybridCache,
+    @Inject(UtilsService) utilsService: UtilsService,
+  ) {
+    super('product', repo, cacheManager, utilsService, ProductService.name);
   }
 }
 ```
 
-### Generated Endpoints
+**Built-in methods:**
 
-| Endpoint | Method | Description | Interceptors |
-|----------|--------|-------------|--------------|
-| `/insert` | POST | Create entity | Idempotency, SetCreatedByOnBody, Slug |
-| `/insert-many` | POST | Create multiple entities | Idempotency, SetCreatedByOnBody, Slug |
-| `/get/:id` | POST | Get entity by ID | - |
-| `/get-all` | POST | Get paginated list with filters | - |
-| `/update` | POST | Update entity | SetUpdateByOnBody, Slug |
-| `/update-many` | POST | Update multiple entities | SetUpdateByOnBody, Slug |
-| `/delete` | POST | Delete/restore/permanent delete | SetDeletedByOnBody |
+| Method | Description |
+|--------|-------------|
+| `insert(dto, user)` | Create a single record |
+| `insertMany(dtos, user)` | Bulk create records |
+| `update(dto, user)` | Update a record by ID |
+| `updateMany(dtos, user)` | Bulk update records |
+| `delete(dto, user)` | Soft delete by ID |
+| `getAll(filter, user)` | Paginated list with filtering |
+| `getById(id, dto)` | Get single record by ID |
+
+### RequestScopedApiService
 
-### Security Configuration Types
+For services that need **dynamic entity loading** per request (DataSource Provider pattern). Use this for all feature modules that have `WithCompany` entity variants:
 
 ```typescript
-// Security levels
-type SecurityLevel = 'public' | 'jwt' | 'permission';
-
-// Endpoint names
-type ApiEndpoint = 'insert' | 'insertMany' | 'getById' | 'getAll' | 'update' | 'updateMany' | 'delete';
-
-// Endpoint security config
-interface EndpointSecurity {
-  level: SecurityLevel;
-  permissions?: string[];          // Required permissions
-  operator?: 'AND' | 'OR';         // How to combine permissions (default: AND)
-  logic?: IPermissionLogic;        // Complex permission logic tree
-}
+import { Injectable, Scope, Inject } from '@nestjs/common';
+import { RequestScopedApiService } from '@flusys/nestjs-shared/classes';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
+import { UtilsService } from '@flusys/nestjs-shared/modules';
 
-// Per-endpoint or global config
-type ApiSecurityConfig = { [K in ApiEndpoint]?: EndpointSecurity | SecurityLevel };
+@Injectable({ scope: Scope.REQUEST }) // REQUEST scope required
+export class ProductService extends RequestScopedApiService<
+  CreateProductDto,
+  UpdateProductDto,
+  IProduct,
+  ProductBase,
+  Repository<ProductBase>
+> {
+  constructor(
+    @Inject('CACHE_INSTANCE') protected override cacheManager: HybridCache,
+    @Inject(UtilsService) protected override utilsService: UtilsService,
+    @Inject(ModuleConfigService) private readonly moduleConfig: ModuleConfigService,
+    @Inject(DataSourceProvider) private readonly dataSourceProvider: DataSourceProvider,
+  ) {
+    super('product', null as any, cacheManager, utilsService, ProductService.name, true);
+  }
 
-interface ApiControllerOptions {
-  security?: ApiSecurityConfig | EndpointSecurity | SecurityLevel;
+  protected override async ensureRepositoryInitialized(): Promise<void> {
+    if (!this.repositoryInitialized) {
+      const entity = this.moduleConfig.isCompanyFeatureEnabled() ? ProductWithCompany : Product;
+      this.repository = await this.dataSourceProvider.getRepository(entity);
+      this.repositoryInitialized = true;
+    }
+  }
 }
 ```
 
-### Security Configuration Examples
+### createApiController
 
-```typescript
-// Global security - all endpoints require JWT
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  { security: 'jwt' },
-) {}
-
-// Per-endpoint security
-@Controller('users')
-export class UserController extends createApiController(
-  CreateUserDto,
-  UpdateUserDto,
-  UserResponseDto,
-  {
-    security: {
-      getAll: 'public',                                    // No auth required
-      getById: 'jwt',                                      // JWT required
-      insert: { level: 'permission', permissions: ['user.create'] },
-      update: { level: 'permission', permissions: ['user.update'] },
-      delete: { level: 'permission', permissions: ['user.delete'] },
-    },
-  },
-) {}
+Factory function that generates a fully-typed CRUD controller class:
 
-// Permission with OR logic
-{
-  security: {
-    getAll: { level: 'permission', permissions: ['user.read', 'admin'], operator: 'OR' },
-  },
-}
+```typescript
+import { Controller, Inject } from '@nestjs/common';
+import { createApiController } from '@flusys/nestjs-shared/classes';
 
-// Complex permission logic
-{
+@Controller('administration/products')
+export class ProductController extends createApiController<
+  CreateProductDto,
+  UpdateProductDto,
+  ProductResponseDto,
+  IProduct,
+  ProductService
+>(CreateProductDto, UpdateProductDto, ProductResponseDto, {
+  entityName: 'product',
   security: {
-    delete: {
-      level: 'permission',
-      logic: {
-        type: 'group',
-        operator: 'AND',
-        children: [
-          { type: 'action', actionId: 'user.delete' },
-          { type: 'group', operator: 'OR', children: [
-            { type: 'action', actionId: 'admin' },
-            { type: 'action', actionId: 'manager' },
-          ]},
-        ],
-      },
-    },
+    insert:     { level: 'permission', permissions: ['product.create'] },
+    insertMany: { level: 'permission', permissions: ['product.create'] },
+    getById:    { level: 'permission', permissions: ['product.read'] },
+    getAll:     { level: 'permission', permissions: ['product.read'] },
+    update:     { level: 'permission', permissions: ['product.update'] },
+    updateMany: { level: 'permission', permissions: ['product.update'] },
+    delete:     { level: 'permission', permissions: ['product.delete'] },
   },
+}) {
+  constructor(@Inject(ProductService) public override service: ProductService) {
+    super(service);
+  }
 }
 ```
 
-**Important:** When per-endpoint security is specified, unconfigured endpoints default to `'jwt'` (not `'public'`) for security.
+**Generated endpoints:**
 
----
-
-## Decorators
+| Route | Method | Permission |
+|-------|--------|-----------|
+| `POST /products/insert` | `insert` | configurable |
+| `POST /products/insert-many` | `insertMany` | configurable |
+| `POST /products/get-all` | `getAll` | configurable |
+| `POST /products/get/:id` | `getById` | configurable |
+| `POST /products/update` | `update` | configurable |
+| `POST /products/update-many` | `updateMany` | configurable |
+| `POST /products/delete` | `delete` | configurable |
 
-### @CurrentUser
+**Security levels:**
 
-Extract the logged-in user from request:
+| Level | Description |
+|-------|-------------|
+| `'public'` | No authentication required (`@Public()`) |
+| `'authenticated'` | Requires valid JWT only |
+| `'permission'` | Requires JWT + specific action permissions |
 
-```typescript
-import { CurrentUser } from '@flusys/nestjs-shared';
-import { ILoggedUserInfo } from '@flusys/nestjs-shared';
-
-@Controller('profile')
-export class ProfileController {
-  @Post('me')
-  getProfile(@CurrentUser() user: ILoggedUserInfo) {
-    return { userId: user.id, companyId: user.companyId };
-  }
+---
 
-  // Extract specific property
-  @Post('id')
-  getUserId(@CurrentUser('id') userId: string) {
-    return { userId };
-  }
-}
-```
+## Base Entities
 
-### @Public
+### Identity (IdentityEntity)
 
-Mark route as public (skip authentication). **Use sparingly - security risk**.
+Base entity for all FLUSYS entities. All entities must extend this:
 
 ```typescript
-import { Public } from '@flusys/nestjs-shared';
+import { Identity } from '@flusys/nestjs-shared/entities';
 
-@Controller('auth')
-export class AuthController {
-  @Public()
-  @Post('login')
-  login() { }
+@Entity('products')
+export class Product extends Identity {
+  @Column() name: string;
+  // id, createdAt, updatedAt, deletedAt inherited
 }
 ```
 
-### @RequirePermission
+**Fields:**
 
-Require specific permission(s) - **AND logic** by default:
-
-```typescript
-import { RequirePermission } from '@flusys/nestjs-shared';
-
-@Controller('admin')
-export class AdminController {
-  // Requires 'admin.dashboard' permission
-  @RequirePermission('admin.dashboard')
-  @Post('dashboard')
-  getDashboard() { }
-
-  // Requires BOTH permissions
-  @RequirePermission('users.read', 'admin.access')
-  @Post('users')
-  getUsers() { }
-}
-```
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | `uuid` | Primary key, auto-generated |
+| `createdAt` | `timestamp` | Auto-set on insert |
+| `updatedAt` | `timestamp` | Auto-updated on save |
+| `deletedAt` | `timestamp \| null` | Soft delete timestamp |
+| `createdBy` | `uuid \| null` | User ID that created the record |
+| `updatedBy` | `uuid \| null` | User ID that last updated the record |
 
-### @RequireAnyPermission
+### UserRoot
 
-Require any of the listed permissions - **OR logic**:
+Extended base entity for user entities. `@flusys/nestjs-auth`'s `User` extends this:
 
 ```typescript
-import { RequireAnyPermission } from '@flusys/nestjs-shared';
-
-@Controller('reports')
-export class ReportsController {
-  // Requires 'reports.view' OR 'reports.admin'
-  @RequireAnyPermission('reports.view', 'reports.admin')
-  @Post()
-  getReports() { }
-}
-```
-
-### @RequirePermissionLogic
+import { UserRoot } from '@flusys/nestjs-shared/entities';
 
-Build complex permission logic with ILogicNode tree (matches frontend ILogicNode):
-
-```typescript
-import { RequirePermissionLogic } from '@flusys/nestjs-shared';
-
-@Controller('sensitive')
-export class SensitiveController {
-  // Complex: User needs 'users.read' AND ('admin' OR 'manager')
-  @RequirePermissionLogic({
-    type: 'group',
-    operator: 'AND',
-    children: [
-      { type: 'action', actionId: 'users.read' },
-      { type: 'group', operator: 'OR', children: [
-        { type: 'action', actionId: 'admin' },
-        { type: 'action', actionId: 'manager' },
-      ]},
-    ],
-  })
-  @Post('complex')
-  getComplexData() { }
+@Entity('user')
+export class User extends UserRoot {
+  // Inherits: id, email, name, password, phone, avatar,
+  //           isEmailVerified, isPhoneVerified, isActive, isSystemUser,
+  //           lastLoginAt, createdAt, updatedAt, deletedAt
 }
 ```
 
-### @SanitizeHtml / @SanitizeAndTrim
-
-Escape HTML entities for XSS prevention:
-
-```typescript
-import { SanitizeHtml, SanitizeAndTrim } from '@flusys/nestjs-shared';
-
-export class CreateCommentDto {
-  @SanitizeHtml()
-  @IsString()
-  content: string;
-
-  @SanitizeAndTrim()  // Escapes HTML AND trims whitespace
-  @IsString()
-  title: string;
-}
-```
+---
 
-### @LogAction
+## Response DTOs
 
-Method-level logging decorator with automatic correlation context and error handling:
+All responses follow a consistent structure:
 
 ```typescript
-import { LogAction } from '@flusys/nestjs-shared';
-
-@Injectable()
-export class UserService {
-  // Module name for routing logs to module-specific files (production)
-  protected readonly moduleName = 'auth';
-
-  // Basic usage - logs start, success (with duration), and errors
-  @LogAction({ action: 'user.create' })
-  async createUser(dto: CreateUserDto): Promise<User> {
-    return this.repository.save(dto);
-  }
-
-  // With all options
-  @LogAction({
-    action: 'user.update',       // Action name (default: ClassName.methodName)
-    module: 'auth',              // Override module routing
-    includeParams: true,         // Log method parameters (sensitive data redacted)
-    includeResult: true,         // Log result preview
-    logLevel: 'info'             // 'debug' | 'info' | 'warn' (default: 'debug')
-  })
-  async updateUser(dto: UpdateUserDto): Promise<User> {
-    return this.repository.save(dto);
-  }
-}
+import {
+  SingleResponseDto,
+  ListResponseDto,
+  BulkResponseDto,
+  MessageResponseDto,
+} from '@flusys/nestjs-shared/dtos';
 ```
 
-**Features:**
-- Automatic start/end logging with duration
-- Error logging with stack trace (then re-throws)
-- Sensitive data redaction (password, secret, token, apiKey, authorization)
-- Request context (requestId, userId, tenantId, companyId)
-- Module-specific log routing (production mode)
-
-### @ApiResponseDto
-
-Generates Swagger schema for response:
+| DTO | Shape | Used for |
+|-----|-------|---------|
+| `SingleResponseDto<T>` | `{ success, message, messageKey?, data?, _meta? }` | insert, update, getById |
+| `ListResponseDto<T>` | `{ success, message, messageKey?, data?, meta, _meta? }` | getAll |
+| `BulkResponseDto<T>` | `{ success, message, messageKey?, data?, meta, _meta? }` | insertMany, updateMany |
+| `MessageResponseDto` | `{ success, message, messageKey?, _meta? }` | delete, actions |
 
+**PaginationMetaDto:**
 ```typescript
-import { ApiResponseDto } from '@flusys/nestjs-shared';
-
-@Controller('users')
-export class UserController {
-  @Post('get-all')
-  @ApiResponseDto(UserResponseDto, true, 'list')  // Array with PaginationMetaDto
-  getAll() { }
-
-  @Post('insert')
-  @ApiResponseDto(UserResponseDto, false)  // Single item
-  insert() { }
-}
+{ total: number; page: number; pageSize: number; count: number; hasMore?: boolean; totalPages?: number }
 ```
 
+**messageKey:** Every response includes a `messageKey` string (e.g., `'auth.login_success'`) for frontend localization. The frontend can look up this key in its translation dictionary instead of relying on the English message text.
+
 ---
 
 ## Guards
 
 ### JwtAuthGuard
 
-Validates JWT tokens for protected routes. Extends Passport's `AuthGuard('jwt')` and respects `@Public()` decorator.
+Validates Bearer JWT tokens on incoming requests:
 
 ```typescript
-import { JwtAuthGuard } from '@flusys/nestjs-shared';
-import { APP_GUARD } from '@nestjs/core';
+import { JwtAuthGuard } from '@flusys/nestjs-shared/guards';
 
-// Apply globally
-@Module({
-  providers: [{ provide: APP_GUARD, useClass: JwtAuthGuard }],
-})
-export class AppModule {}
+@UseGuards(JwtAuthGuard)
+@Post('protected')
+async protectedEndpoint(@CurrentUser() user: ILoggedUserInfo) { }
 ```
 
-**Important:** Constructor needs `@Inject(Reflector)` for bundled code (this is already handled in the guard).
+Applied globally by default in the FLUSYS app. Use `@Public()` to bypass.
 
 ### PermissionGuard
 
-Checks user permissions from cache with AND/OR/nested logic support and wildcard matching.
+Checks that the authenticated user has the required action permission:
 
 ```typescript
-import { PermissionGuard, PERMISSION_GUARD_CONFIG, CACHE_INSTANCE } from '@flusys/nestjs-shared';
+import { PermissionGuard } from '@flusys/nestjs-shared/guards';
+import { RequirePermission } from '@flusys/nestjs-shared/decorators';
 
-@Module({
-  providers: [
-    { provide: APP_GUARD, useClass: PermissionGuard },
-    {
-      provide: PERMISSION_GUARD_CONFIG,
-      useValue: {
-        enableCompanyFeature: true,
-        userPermissionKeyFormat: 'permissions:user:{userId}',
-        companyPermissionKeyFormat: 'permissions:company:{companyId}:branch:{branchId}:user:{userId}',
-      },
-    },
-  ],
-})
-export class AppModule {}
-```
-
-**PermissionGuardConfig Interface:**
-
-```typescript
-interface PermissionGuardConfig {
-  enableCompanyFeature?: boolean;
-  userPermissionKeyFormat?: string;     // Default: 'permissions:user:{userId}'
-  companyPermissionKeyFormat?: string;  // Default: 'permissions:company:{companyId}:branch:{branchId}:user:{userId}'
-}
-```
-
-**Cache Key Formats:**
-
-```typescript
-// Without company feature (enableCompanyFeature: false)
-'permissions:user:{userId}'
-
-// With company feature (enableCompanyFeature: true && user.companyId exists)
-'permissions:company:{companyId}:branch:{branchId}:user:{userId}'
-```
-
-**Wildcard Permission Matching:**
-
-The guard supports wildcard permissions for flexible access control:
-
-```typescript
-// User has permissions: ['user.*', 'admin']
-
-// These checks will PASS:
-@RequirePermission('user.create')  // Matches 'user.*'
-@RequirePermission('user.read')    // Matches 'user.*'
-@RequirePermission('admin')        // Exact match
-
-// Wildcard patterns:
-'*'           // Matches ALL permissions (super admin)
-'user.*'      // Matches 'user.create', 'user.read', 'user.update', etc.
-'storage.*'   // Matches 'storage.file.create', 'storage.folder.read', etc.
+@UseGuards(JwtAuthGuard, PermissionGuard)
+@RequirePermission('product.create')
+@Post('insert')
+async insert() { }
 ```
 
-### Permission Exceptions
-
-```typescript
-import {
-  InsufficientPermissionsException,     // 403 - Missing required permissions
-  NoPermissionsFoundException,           // 403 - No permissions in cache for user
-  PermissionSystemUnavailableException,  // 500 - Cache not available
-} from '@flusys/nestjs-shared';
-
-// Exception response formats:
-// InsufficientPermissionsException (AND):
-{
-  "success": false,
-  "message": "Missing required permissions: user.create, user.update",
-  "code": "INSUFFICIENT_PERMISSIONS",
-  "missingPermissions": ["user.create", "user.update"],
-  "operator": "AND"
-}
-
-// InsufficientPermissionsException (OR):
-{
-  "success": false,
-  "message": "Requires at least one of: admin, manager",
-  "code": "INSUFFICIENT_PERMISSIONS",
-  "missingPermissions": ["admin", "manager"],
-  "operator": "OR"
-}
-
-// NoPermissionsFoundException:
-{
-  "success": false,
-  "message": "No permissions found. Please contact administrator.",
-  "code": "NO_PERMISSIONS_FOUND"
-}
-
-// PermissionSystemUnavailableException:
-{
-  "success": false,
-  "message": "Permission system temporarily unavailable. Please try again later.",
-  "code": "PERMISSION_SYSTEM_UNAVAILABLE"
-}
-```
+> **Note:** Always use `@Inject(Reflector)` in your guard constructors — esbuild bundling loses TypeScript metadata.
 
 ---
 
-## Middleware
-
-### LoggerMiddleware
-
-Combined middleware for request correlation and HTTP logging using AsyncLocalStorage.
-
-**Features:**
-- Request ID generation/tracking (UUID or from `x-request-id` header)
-- Tenant ID tracking (from `x-tenant-id` header)
-- AsyncLocalStorage context for thread-safe access across async operations
-- Automatic sensitive header redaction (authorization, cookie, x-api-key)
-- Performance monitoring (warns on requests > 3s)
-- Body truncation (max 1000 chars in logs)
-- Excluded paths: `/health`, `/metrics`, `/favicon.ico`
+## Decorators
 
-**Configuration via environment:**
-- `LOG_LEVEL` - Logging level (debug enables verbose logging)
+| Decorator | Import | Description |
+|-----------|--------|-------------|
+| `@CurrentUser()` | `@flusys/nestjs-shared/decorators` | Inject full `ILoggedUserInfo` object |
+| `@CurrentUser('id')` | `@flusys/nestjs-shared/decorators` | Inject a specific field from user info |
+| `@Public()` | `@flusys/nestjs-shared/decorators` | Mark endpoint as public (skip JWT guard) |
+| `@RequirePermission(action)` | `@flusys/nestjs-shared/decorators` | Require a specific action permission |
+| `@RequireAnyPermission(...actions)` | `@flusys/nestjs-shared/decorators` | Require any one of listed permissions |
+| `@SanitizeHtml()` | `@flusys/nestjs-shared/decorators` | Strip HTML tags from string fields |
+| `@SanitizeAndTrim()` | `@flusys/nestjs-shared/decorators` | Strip HTML and trim whitespace |
+| `@LogAction(description)` | `@flusys/nestjs-shared/decorators` | Log method calls for audit |
+| `@ApiResponseDto(type)` | `@flusys/nestjs-shared/decorators` | Swagger response shorthand |
 
-**Usage:**
+### ILoggedUserInfo
 
 ```typescript
-import { LoggerMiddleware } from '@flusys/nestjs-shared';
-
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer.apply(LoggerMiddleware).forRoutes('*');
-  }
-}
-```
-
-**Request Context Interface:**
-
-```typescript
-interface IRequestContext {
-  requestId: string;
-  tenantId?: string;
-  userId?: string;
+interface ILoggedUserInfo {
+  id: string;
+  email: string;
+  name: string;
   companyId?: string;
-  startTime: number;
+  branchId?: string;
+  permissions?: string[];
+  isSystemUser?: boolean;
 }
 ```
 
-**Accessing Request Context (read-only):**
-
-```typescript
-import {
-  getRequestId,
-  getTenantId,
-  getUserId,
-  getCompanyId,
-  requestContext,  // AsyncLocalStorage instance for advanced usage
-} from '@flusys/nestjs-shared';
-
-@Injectable()
-export class MyService {
-  async doSomething() {
-    const requestId = getRequestId();   // Current request's correlation ID
-    const tenantId = getTenantId();     // From x-tenant-id header
-    const userId = getUserId();         // Set by auth guard (if available)
-    const companyId = getCompanyId();   // Set by auth (if available)
-  }
-}
-```
-
-**Note:** The context values (`userId`, `companyId`) are populated by authentication guards after JWT validation. The middleware only initializes `requestId` and `tenantId` from headers.
-
 ---
 
 ## Interceptors
 
-### ResponseMetaInterceptor
-
-Automatically adds `_meta` to all responses with `success` field:
-
-```typescript
-// Response structure:
-{
-  "success": true,
-  "data": [...],
-  "_meta": {
-    "requestId": "req_abc123def456",
-    "timestamp": "2024-01-01T00:00:00.000Z",
-    "responseTime": 45
-  }
-}
-```
-
-### IdempotencyInterceptor
-
-Prevents duplicate POST requests using `X-Idempotency-Key` header.
-
-**How it works:**
-1. If key exists and completed → returns cached response (no reprocessing)
-2. If key exists but processing → throws `ConflictException` (409)
-3. If key is new → processes request and caches response for 24 hours
-
-**Usage:**
-
-```typescript
-// Client includes header:
-// X-Idempotency-Key: unique-order-123
-
-// Controller (auto-applied by createApiController for insert endpoints)
-@UseInterceptors(IdempotencyInterceptor)
-@Post('create-order')
-createOrder(@Body() dto: CreateOrderDto) { }
-```
-
-### SetCreatedByOnBody / SetUpdateByOnBody / SetDeletedByOnBody
-
-Auto-set audit user IDs on request body from authenticated user.
-
-```typescript
-// Factory function for custom field names
-import { createSetUserFieldInterceptor } from '@flusys/nestjs-shared';
-
-// Built-in interceptors:
-export const SetCreatedByOnBody = createSetUserFieldInterceptor('createdById');
-export const SetUpdateByOnBody = createSetUserFieldInterceptor('updatedById');
-export const SetDeletedByOnBody = createSetUserFieldInterceptor('deletedById');
-
-// Usage:
-@UseInterceptors(SetCreatedByOnBody)
-@Post('insert')
-insert(@Body() dto: CreateDto) { }
-
-// Works with arrays too:
-// Input: [{ name: 'A' }, { name: 'B' }]
-// Output: [{ name: 'A', createdById: 'user-123' }, { name: 'B', createdById: 'user-123' }]
-```
-
-### DeleteEmptyIdFromBodyInterceptor
-
-Removes empty/null `id` fields from request body (single objects and arrays).
-
-```typescript
-// Input: { id: '', name: 'Test' }
-// Output: { name: 'Test' }
-
-// Input: [{ id: null, name: 'A' }, { id: '123', name: 'B' }]
-// Output: [{ name: 'A' }, { id: '123', name: 'B' }]
-```
-
-### Slug Interceptor
-
-Auto-generates `slug` from `name` field if not provided.
-
-```typescript
-import { Slug } from '@flusys/nestjs-shared';
-
-@UseInterceptors(Slug)
-@Post('insert')
-insert(@Body() dto: CreateDto) { }
-
-// Input: { name: 'My Product Name' }
-// Output: { name: 'My Product Name', slug: 'my-product-name' }
-
-// If slug already provided, it's preserved:
-// Input: { name: 'My Product', slug: 'custom-slug' }
-// Output: { name: 'My Product', slug: 'custom-slug' }
-```
+| Interceptor | Token | Description |
+|-------------|-------|-------------|
+| `ResponseMetaInterceptor` | class | Adds `_meta` (requestId, timestamp, duration) to all responses |
+| `IdempotencyInterceptor` | class | Prevents duplicate POST requests using `x-idempotency-key` header |
+| `SetCreatedByInterceptor` | class | Auto-sets `createdBy` from JWT user on insert |
+| `SetUpdatedByInterceptor` | class | Auto-sets `updatedBy` from JWT user on update |
+| `DeleteEmptyIdInterceptor` | class | Strips empty `id` fields from request bodies |
+| `SlugInterceptor` | class | Auto-generates URL slugs from `name` fields |
 
 ---
 
-## Caching System
+## HybridCache
 
-### HybridCache
-
-Two-tier caching with in-memory (L1) and Redis (L2):
+Two-tier cache: L1 in-memory (CacheableMemory) → L2 Redis. Automatically falls back to in-memory if Redis is unavailable.
 
 ```typescript
-import { HybridCache } from '@flusys/nestjs-shared';
+import { HybridCache } from '@flusys/nestjs-shared/classes';
 
 @Injectable()
 export class MyService {
   constructor(@Inject('CACHE_INSTANCE') private cache: HybridCache) {}
 
-  async getData(key: string) {
-    // Check cache first
+  async getData(key: string): Promise<any> {
     const cached = await this.cache.get(key);
     if (cached) return cached;
 
     const data = await this.fetchFromDb();
-    await this.cache.set(key, data, 3600);  // TTL in seconds
+    await this.cache.set(key, data, 3600); // TTL in seconds
     return data;
   }
 
-  async invalidate(key: string) {
-    await this.cache.del(key);
+  async invalidate(key: string): Promise<void> {
+    await this.cache.delete(key);
   }
 
-  async invalidateAll() {
-    await this.cache.reset();      // Clear L1
-    await this.cache.resetL2();    // Clear L2 (Redis)
+  async invalidateByPrefix(prefix: string): Promise<void> {
+    await this.cache.deleteByPrefix(prefix);
   }
 }
 ```
 
-### CacheModule Setup
-
-```typescript
-import { CacheModule } from '@flusys/nestjs-shared';
-
-@Module({
-  imports: [
-    CacheModule.forRoot(
-      true,     // isGlobal
-      60_000,   // memoryTtl (ms)
-      5000      // memorySize (LRU max items)
-    ),
-  ],
-})
-export class AppModule {}
-```
-
-**Configuration via `USE_CACHE_LABEL` env:**
-- `'memory'` - L1 only
-- `'redis'` - L2 only
-- `'hybrid'` - Both (default)
-
 ---
 
-## Multi-Tenant DataSource
+## Middlewares
 
-Dynamic database connection management with connection pooling.
+### LoggerMiddleware
 
-### Setup
+HTTP request/response logger with correlation IDs. Attach to all routes:
 
 ```typescript
-import { DataSourceModule } from '@flusys/nestjs-shared';
+import { LoggerMiddleware } from '@flusys/nestjs-shared/middlewares';
 
-@Module({
-  imports: [
-    DataSourceModule.forRoot({
-      bootstrapAppConfig: { databaseMode: 'multi-tenant' },
-      defaultDatabaseConfig: {
-        type: 'mysql',
-        host: 'localhost',
-        port: 3306,
-        username: 'root',
-        password: 'password',
-      },
-      tenants: [
-        { id: 'tenant1', database: 'tenant1_db' },
-        { id: 'tenant2', database: 'tenant2_db', host: 'other-server.com' },
-      ],
-    }),
-  ],
-})
-export class AppModule {}
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer.apply(LoggerMiddleware).forRoutes('*');
+  }
+}
 ```
 
-### MultiTenantDataSourceService
+Logged fields: method, URL, status, duration, requestId, userId (from JWT), IP, user-agent.
 
-| Method | Description |
-|--------|-------------|
-| `getDataSource()` | Get DataSource for current tenant (from header) |
-| `getDataSourceForTenant(id)` | Get DataSource for specific tenant |
-| `getRepository(entity)` | Get repository for current tenant |
-| `withTenant(id, callback)` | Execute callback with specific tenant |
-| `forAllTenants(callback)` | Execute callback for all tenants |
-| `registerTenant(config)` | Register new tenant at runtime |
-| `removeTenant(id)` | Remove tenant and close connection |
-| `getCurrentTenantId()` | Get tenant ID from request header |
+The middleware also sets an `AsyncLocalStorage` context so `requestId` and `userId` are available in any service without passing them through method parameters.
 
 ---
 
-## DTOs
+## Exceptions & Filters
 
-### FilterAndPaginationDto
+### Built-in Exception Classes
 
 ```typescript
-import { FilterAndPaginationDto } from '@flusys/nestjs-shared';
+import {
+  NotFoundException,
+  ConflictException,
+  UnauthorizedException,
+  ForbiddenException,
+  BadRequestException,
+  ValidationException,
+} from '@flusys/nestjs-shared/exceptions';
 
-// Request body
-{
-  "filter": { "status": "active" },
-  "pagination": { "currentPage": 0, "pageSize": 10 },
-  "sort": { "createdAt": "DESC" },
-  "select": ["id", "name", "email"],
-  "withDeleted": false
-}
+// All exceptions accept { message, messageKey } for localization
+throw new NotFoundException({ message: 'User not found', messageKey: 'user.not_found' });
 ```
 
-### DeleteDto
-
-```typescript
-import { DeleteDto } from '@flusys/nestjs-shared';
-
-// Soft delete
-{ "id": "uuid", "type": "delete" }
-
-// Restore
-{ "id": "uuid", "type": "restore" }
-
-// Permanent delete
-{ "id": "uuid", "type": "permanent" }
-
-// Multiple IDs
-{ "id": ["uuid1", "uuid2"], "type": "delete" }
-```
+### GlobalExceptionFilter
 
-### Response DTOs
+Catches all unhandled exceptions and returns a consistent error response:
 
 ```typescript
-// Single item
-class SingleResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T;
-  _meta?: RequestMetaDto;
-}
-
-// Paginated list
-class ListResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: PaginationMetaDto;  // { total, page, pageSize, count, hasMore?, totalPages? }
-  _meta?: RequestMetaDto;
-}
-
-// Bulk operations
-class BulkResponseDto<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: BulkMetaDto;  // { count, failed?, total? }
-  _meta?: RequestMetaDto;
-}
+// Register globally
+app.useGlobalFilters(new GlobalExceptionFilter());
+```
 
-// Message only
-class MessageResponseDto {
-  success: boolean;
-  message: string;
-  _meta?: RequestMetaDto;
+Error response shape:
+```json
+{
+  "success": false,
+  "message": "User not found",
+  "messageKey": "user.not_found",
+  "code": 404,
+  "_meta": { "requestId": "...", "timestamp": "..." }
 }
 ```
 
 ---
 
-## Base Entities
-
-### Identity Entity
+## Modules
 
-Base entity with UUID and timestamps:
+### CacheModule
 
 ```typescript
-import { Identity } from '@flusys/nestjs-shared';
+import { CacheModule } from '@flusys/nestjs-shared/modules';
 
-@Entity()
-export class Product extends Identity {
-  // Inherited: id, createdAt, updatedAt, deletedAt
-  // Inherited: createdById, updatedById, deletedById
+// Global (register once in AppModule)
+CacheModule.forRoot(true)
 
-  @Column()
-  name: string;
-}
+// Local (non-global)
+CacheModule.forRoot(false)
 ```
 
-### UserRoot Entity
+Provides `HybridCache` as `'CACHE_INSTANCE'` injection token. Automatically connects to Redis if `REDIS_URL` is set.
 
-Base user entity with common fields:
+### UtilsModule
 
 ```typescript
-import { UserRoot } from '@flusys/nestjs-shared';
+import { UtilsModule } from '@flusys/nestjs-shared/modules';
 
-@Entity()
-export class User extends UserRoot {
-  // Inherited: id, name, email, phone, profilePictureId
-  // Inherited: isActive, emailVerified, phoneVerified
-  // Inherited: lastLoginAt, additionalFields
-  // Inherited: createdAt, updatedAt, deletedAt
-}
+@Module({ imports: [UtilsModule] })
+export class AppModule {}
 ```
 
----
+Provides `UtilsService` with slug generation, HTML sanitization, and query helper utilities.
 
-## Utilities
-
-### Query Helpers
+### DataSourceModule
 
 ```typescript
-import {
-  applyCompanyFilter,
-  buildCompanyWhereCondition,
-  hasCompanyId,
-  validateCompanyOwnership,
-} from '@flusys/nestjs-shared';
-
-// Add company filter to TypeORM query
-applyCompanyFilter(query, {
-  isCompanyFeatureEnabled: true,
-  entityAlias: 'entity',
-}, user);
-
-// Build where condition for company
-const where = buildCompanyWhereCondition(baseWhere, user, isCompanyFeatureEnabled);
-
-// Validate entity belongs to user's company
-validateCompanyOwnership(entity, user, 'Entity');
-```
-
-### String Utilities
+import { DataSourceModule } from '@flusys/nestjs-shared/modules';
 
-```typescript
-import { generateSlug, generateUniqueSlug } from '@flusys/nestjs-shared';
-
-// Generate URL-friendly slug
-const slug = generateSlug('My Product Name', 100);
-// Returns: 'my-product-name'
-
-// Generate unique slug with collision detection
-const uniqueSlug = await generateUniqueSlug(
-  'My Product',
-  async (pattern) => existingSlugs.filter(s => s.startsWith(pattern)),
-  100
-);
+DataSourceModule.forRoot(dataSourceOptions)
 ```
 
-### Request Utilities
-
-```typescript
-import {
-  isBrowserRequest,
-  buildCookieOptions,
-  parseDurationToMs,
-} from '@flusys/nestjs-shared';
-
-// Detect browser vs API client
-const isBrowser = isBrowserRequest(req);
-
-// Build secure cookie options
-const cookieOpts = buildCookieOptions(req);
-
-// Parse duration string
-const ms = parseDurationToMs('7d');  // 604800000
-```
-
-### HTML Sanitizer
-
-```typescript
-import { escapeHtml, escapeHtmlVariables } from '@flusys/nestjs-shared';
-
-// Escape single string
-const safe = escapeHtml('<script>alert("xss")</script>');
-// Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
-
-// Escape all values in an object
-const safeVars = escapeHtmlVariables({
-  userName: '<script>evil</script>',
-  message: 'Hello, World!',
-});
-```
+Wraps `MultiTenantDataSourceService` for dynamic tenant-based DataSource resolution.
 
 ---
 
-## Error Handling
+## Multi-Tenant DataSource Service
 
-### BaseAppException
-
-Structured exceptions with i18n support and validation errors:
+`MultiTenantDataSourceService` manages separate TypeORM DataSource connections per tenant. Each feature module extends it to create an isolated static connection cache:
 
 ```typescript
-import {
-  BaseAppException,
-  NotFoundException,
-  ValidationException,
-  UnauthorizedException,
-  ForbiddenException,
-  ConflictException,
-  InternalServerException,
-  ServiceUnavailableException,
-  IValidationError,
-} from '@flusys/nestjs-shared';
-
-// Custom exception with all options
-throw new BaseAppException({
-  message: 'User registration failed',
-  code: 'REGISTRATION_FAILED',
-  messageKey: 'error.registration.failed',  // For i18n
-  status: HttpStatus.BAD_REQUEST,
-  errors: [
-    { field: 'email', message: 'Email already exists', code: 'DUPLICATE_EMAIL' }
-  ],
-  metadata: { attemptedEmail: email },
-});
-
-// Pre-built exceptions
-throw new NotFoundException('User', userId);
-// → { message: "User with id 'abc' not found", code: "NOT_FOUND", messageKey: "error.notFound" }
+import { MultiTenantDataSourceService } from '@flusys/nestjs-shared/modules';
 
-throw new ValidationException([
-  { field: 'email', message: 'Invalid format' },
-  { field: 'password', message: 'Too short' },
-]);
-
-throw new UnauthorizedException('Invalid credentials');
-throw new ForbiddenException('Admin access required');
-throw new ConflictException('User', 'email');
-throw new InternalServerException('Database connection failed');
-throw new ServiceUnavailableException('Email Service');
-```
-
-### GlobalExceptionFilter
-
-Unified exception handling with structured responses and logging:
-
-```typescript
-import { GlobalExceptionFilter } from '@flusys/nestjs-shared';
-
-// Register in main.ts
-app.useGlobalFilters(new GlobalExceptionFilter());
-
-// Or in app.module.ts
-@Module({
-  providers: [
-    { provide: APP_FILTER, useClass: GlobalExceptionFilter },
-  ],
-})
-export class AppModule {}
-```
+// Feature module DataSource Provider (extends with isolated cache)
+@Injectable()
+export class ProductDataSourceProvider extends MultiTenantDataSourceService {
+  // Static cache isolated to this module
+  private static moduleDataSource: DataSource | null = null;
+  private static moduleTenantSources: Map<string, DataSource> = new Map();
 
-**Response format (all errors):**
-```json
-{
-  "success": false,
-  "message": "User with id 'abc' not found",
-  "code": "NOT_FOUND",
-  "messageKey": "error.notFound",
-  "errors": [...],
-  "_meta": {
-    "requestId": "uuid",
-    "timestamp": "2024-01-15T10:30:00.000Z",
-    "responseTime": 45
+  protected override getSingleDataSource(): DataSource | null {
+    return ProductDataSourceProvider.moduleDataSource;
   }
+
+  // ... override other cache accessors
 }
 ```
 
-**Features:**
-- Consistent error response format
-- Request correlation (requestId, userId, tenantId)
-- Log level by status (500+ → error, 400+ → warn)
-- Handles BaseAppException, HttpException, and generic errors
-- class-validator error transformation
-
 ---
 
-## Constants
-
-### Metadata Keys
-
-```typescript
-import { IS_PUBLIC_KEY, PERMISSIONS_KEY } from '@flusys/nestjs-shared';
-
-// Used internally by decorators:
-IS_PUBLIC_KEY     // 'isPublic' - marks routes as public
-PERMISSIONS_KEY   // 'permissions' - stores permission requirements
-```
-
-### Injection Tokens
-
-```typescript
-import {
-  CACHE_INSTANCE,
-  PERMISSION_GUARD_CONFIG,
-  LOGGER_INSTANCE,
-} from '@flusys/nestjs-shared';
-
-// Injection tokens:
-CACHE_INSTANCE            // 'CACHE_INSTANCE' - HybridCache provider
-PERMISSION_GUARD_CONFIG   // 'PERMISSION_GUARD_CONFIG' - PermissionGuard config
-LOGGER_INSTANCE           // 'LOGGER_INSTANCE' - ILogger provider
-```
+## Logger System
 
-### Header Names
+Winston-based structured logger with daily file rotation:
 
 ```typescript
-import {
-  IDEMPOTENCY_KEY_HEADER,
-  REQUEST_ID_HEADER,
-  CLIENT_TYPE_HEADER,
-} from '@flusys/nestjs-shared';
-
-// HTTP header names:
-IDEMPOTENCY_KEY_HEADER  // 'x-idempotency-key' - For IdempotencyInterceptor
-REQUEST_ID_HEADER       // 'x-request-id' - For request correlation
-CLIENT_TYPE_HEADER      // 'x-client-type' - For client detection (browser/api)
-```
+import { WinstonLoggerAdapter, NestLoggerAdapter } from '@flusys/nestjs-shared/classes';
 
-### Cache Key Prefixes
-
-```typescript
-import {
-  PERMISSIONS_CACHE_PREFIX,
-  IDEMPOTENCY_CACHE_PREFIX,
-} from '@flusys/nestjs-shared';
-
-// Cache key prefixes:
-PERMISSIONS_CACHE_PREFIX   // 'permissions' - For user permissions cache
-IDEMPOTENCY_CACHE_PREFIX   // 'idempotency' - For idempotency keys
+// Use as NestJS app logger
+const app = await NestFactory.create(AppModule, {
+  logger: new NestLoggerAdapter(),
+});
 ```
 
-### Permission Constants
+Log levels: `error`, `warn`, `info`, `http`, `debug`. Configured via `LOG_LEVEL` env var.
 
-```typescript
-import { PERMISSIONS, PermissionCode } from '@flusys/nestjs-shared';
-
-// Auth Module
-PERMISSIONS.USER.CREATE     // 'user.create'
-PERMISSIONS.USER.READ       // 'user.read'
-PERMISSIONS.USER.UPDATE     // 'user.update'
-PERMISSIONS.USER.DELETE     // 'user.delete'
-
-PERMISSIONS.COMPANY.CREATE  // 'company.create'
-PERMISSIONS.COMPANY.READ    // 'company.read'
-// ...
-
-PERMISSIONS.BRANCH.CREATE   // 'branch.create'
-// ...
-
-// IAM Module
-PERMISSIONS.ACTION.CREATE   // 'action.create'
-PERMISSIONS.ROLE.CREATE     // 'role.create'
-PERMISSIONS.ROLE_ACTION.READ    // 'role-action.read'
-PERMISSIONS.ROLE_ACTION.ASSIGN  // 'role-action.assign'
-PERMISSIONS.USER_ROLE.READ      // 'user-role.read'
-PERMISSIONS.USER_ROLE.ASSIGN    // 'user-role.assign'
-PERMISSIONS.USER_ACTION.READ    // 'user-action.read'
-PERMISSIONS.USER_ACTION.ASSIGN  // 'user-action.assign'
-PERMISSIONS.COMPANY_ACTION.READ    // 'company-action.read'
-PERMISSIONS.COMPANY_ACTION.ASSIGN  // 'company-action.assign'
-
-// Storage Module
-PERMISSIONS.FILE.CREATE     // 'file.create'
-PERMISSIONS.FOLDER.CREATE   // 'folder.create'
-PERMISSIONS.STORAGE_CONFIG.CREATE  // 'storage-config.create'
-
-// Email Module
-PERMISSIONS.EMAIL_CONFIG.CREATE     // 'email-config.create'
-PERMISSIONS.EMAIL_TEMPLATE.CREATE   // 'email-template.create'
-
-// Form Builder Module
-PERMISSIONS.FORM.CREATE        // 'form.create'
-PERMISSIONS.FORM_RESULT.CREATE // 'form-result.create'
-
-// Type-safe permission code type:
-type PermissionCode = 'user.create' | 'user.read' | ... ; // Union of all permission strings
-```
+Files rotate daily. Configured via `LOG_DIR`, `LOG_MAX_SIZE`, `LOG_MAX_FILES` env vars.
 
 ---
 
-## Logger System
-
-### Winston Logger
-
-Production-ready logging with tenant-aware routing and daily rotation.
-
-**Configuration via environment:**
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `LOG_DIR` | Directory for log files | `logs/` |
-| `LOG_LEVEL` | Minimum log level | `info` (prod), `debug` (dev) |
-| `LOG_MAX_SIZE` | Max file size before rotation | `20m` |
-| `LOG_MAX_FILES` | Max number of log files to keep | `14d` |
-| `USE_TENANT_MODE` | Enable tenant-aware log routing | `false` |
-| `DISABLE_HTTP_LOGGING` | Disable HTTP request/response logs | `false` |
-
-**Disable HTTP Logging:**
-```bash
-# .env - Disable middleware HTTP logs (keep service-level @LogAction logs)
-DISABLE_HTTP_LOGGING=true
-```
-
-When disabled, LoggerMiddleware skips request/response logging but preserves:
-- `@LogAction` decorator logs
-- Manual `logger.log()` calls
-- Error logs from GlobalExceptionFilter
-
-**Log Format (Production):**
-```
-────────────────────────────────────────────────────────────────────────────────
-2024-01-15 10:30:45.123 | Information | [request-uuid]
-Context: HTTP | Endpoint: POST /api/users | Status: 200 | Duration: 45ms
-Request finished "HTTP/1.1" "POST" "/api/users" - 200 534 "application/json" 45.00ms
-Metadata: {"userId":"user-123","tenantId":"tenant-1"}
-```
+## Permission System
 
-**Logger Modes:**
+Permission logic supports complex AND/OR trees with wildcard matching:
 
 ```typescript
-import { instance as winstonLogger } from '@flusys/nestjs-shared';
+import { IPermissionLogic, IActionNode, IGroupNode } from '@flusys/nestjs-shared/interfaces';
 
-// Development: Console output with colors
-// Production: File-based with daily rotation + tenant routing
-```
-
-**Log File Structure:**
+// Single permission
+const simple: IPermissionLogic = { action: 'product.read' };
 
-```
-logs/
-├── combined-2024-01-15.log      # All logs (tenant mode off)
-├── error-2024-01-15.log         # Error logs only
-└── {tenantId}/                  # Tenant-specific folders (tenant mode on)
-    └── combined-2024-01-15.log
-```
-
-### Logger Adapters
-
-```typescript
-import { WinstonLoggerAdapter, NestLoggerAdapter, ILogger } from '@flusys/nestjs-shared';
-import { Logger } from '@nestjs/common';
-
-// ILogger interface
-interface ILogger {
-  log(message: string, context?: string, ...args: any[]): void;
-  error(message: string, trace?: string, context?: string, ...args: any[]): void;
-  warn(message: string, context?: string, ...args: any[]): void;
-  debug(message: string, context?: string, ...args: any[]): void;
-  verbose(message: string, context?: string, ...args: any[]): void;
-}
+// Wildcard
+const wildcard: IPermissionLogic = { action: 'product.*' };
 
-// Winston adapter (recommended for production)
-// Automatically includes correlation context (requestId, userId, tenantId, companyId)
-const logger = new WinstonLoggerAdapter('MyService');
-logger.log('Operation completed', undefined, { orderId: '123' });
-// Output: { requestId: 'uuid', userId: 'user-id', context: 'MyService', message: 'Operation completed', orderId: '123' }
+// AND logic (user needs ALL of these)
+const andLogic: IPermissionLogic = {
+  operator: 'AND',
+  children: [
+    { action: 'product.read' },
+    { action: 'product.update' },
+  ],
+};
+
+// OR logic (user needs ANY of these)
+const orLogic: IPermissionLogic = {
+  operator: 'OR',
+  children: [
+    { action: 'admin.*' },
+    { action: 'product.read' },
+  ],
+};
 
-// NestJS adapter (for testing or simple use cases)
-const nestLogger = new NestLoggerAdapter(new Logger('MyService'));
+// Nested
+const nested: IPermissionLogic = {
+  operator: 'AND',
+  children: [
+    { action: 'product.read' },
+    {
+      operator: 'OR',
+      children: [{ action: 'admin.manage' }, { action: 'product.update' }],
+    },
+  ],
+};
 ```
 
 ---
 
-## API Reference
-
-### Main Exports
+## Permission Constants
 
-All exports are available from the main package entry point:
+All module permission strings are centralized here:
 
 ```typescript
-// Import everything from main entry
 import {
-  // Classes
-  ApiService,
-  RequestScopedApiService,
-  createApiController,
-  HybridCache,
-  WinstonLoggerAdapter,
-  NestLoggerAdapter,
-  instance as winstonLogger,
-
-  // Controller Types
-  ApiEndpoint,
-  SecurityLevel,
-  EndpointSecurity,
-  ApiSecurityConfig,
-  ApiControllerOptions,
-
-  // Decorators
-  CurrentUser,
-  Public,
-  RequirePermission,
-  RequireAnyPermission,
-  RequirePermissionLogic,
-  RequirePermissionCondition,  // @deprecated - use RequirePermissionLogic
-  SanitizeHtml,
-  SanitizeAndTrim,
-  ApiResponseDto,
-  ArrayResponseType,
-  LogAction,
-  ILogActionOptions,
-
-  // Guards
-  JwtAuthGuard,
-  PermissionGuard,
-
-  // Interceptors
-  ResponseMetaInterceptor,
-  IdempotencyInterceptor,
-  SetCreatedByOnBody,
-  SetUpdateByOnBody,
-  SetDeletedByOnBody,
-  createSetUserFieldInterceptor,  // Factory function
-  DeleteEmptyIdFromBodyInterceptor,
-  Slug,
-
-  // Modules
-  CacheModule,
-  DataSourceModule,
-  DataSourceModuleOptions,
-  DataSourceOptionsFactory,
-  DataSourceModuleAsyncOptions,
-  UtilsModule,
-  UtilsService,
-  MultiTenantDataSourceService,
-
-  // DTOs
-  FilterAndPaginationDto,
-  GetByIdBodyDto,
-  PaginationDto,
-  DeleteDto,
-  SingleResponseDto,
-  ListResponseDto,
-  BulkResponseDto,
-  MessageResponseDto,
-  IdentityResponseDto,
-  PaginationMetaDto,
-  BulkMetaDto,
-  RequestMetaDto,
-
-  // Entities
-  Identity,
-  UserRoot,
-
-  // Interfaces
-  ILoggedUserInfo,
-  IService,
-  IDataSourceProvider,
-  IModuleConfigService,
-  ILogger,
-  IIdentity,
-  ILogicNode,
-  IActionNode,
-  IGroupNode,
-  IPermissionLogic,
-  SimplePermissionConfig,
-  PermissionConfig,
-  PermissionGuardConfig,
-
-  // Middleware
-  LoggerMiddleware,
-  IRequestContext,
-  requestContext,
-  getRequestId,
-  getTenantId,
-  getUserId,
-  getCompanyId,
-
-  // Filters
-  GlobalExceptionFilter,
-
-  // Exceptions
-  BaseAppException,
-  IBaseAppExceptionOptions,
-  IValidationError,
-  NotFoundException,
-  ValidationException,
-  UnauthorizedException,
-  ForbiddenException,
-  ConflictException,
-  InternalServerException,
-  ServiceUnavailableException,
-  InsufficientPermissionsException,
-  NoPermissionsFoundException,
-  PermissionSystemUnavailableException,
-
-  // Constants
-  IS_PUBLIC_KEY,
-  PERMISSIONS_KEY,
-  CACHE_INSTANCE,
-  PERMISSION_GUARD_CONFIG,
-  LOGGER_INSTANCE,
-  IDEMPOTENCY_KEY_HEADER,
-  REQUEST_ID_HEADER,
-  CLIENT_TYPE_HEADER,
-  PERMISSIONS_CACHE_PREFIX,
-  IDEMPOTENCY_CACHE_PREFIX,
-  PERMISSIONS,
-  PermissionCode,
-  // Individual permission exports
   USER_PERMISSIONS,
   COMPANY_PERMISSIONS,
-  BRANCH_PERMISSIONS,
-  ACTION_PERMISSIONS,
   ROLE_PERMISSIONS,
-  ROLE_ACTION_PERMISSIONS,
-  USER_ROLE_PERMISSIONS,
-  USER_ACTION_PERMISSIONS,
-  COMPANY_ACTION_PERMISSIONS,
+  ACTION_PERMISSIONS,
   FILE_PERMISSIONS,
   FOLDER_PERMISSIONS,
   STORAGE_CONFIG_PERMISSIONS,
-  EMAIL_CONFIG_PERMISSIONS,
-  EMAIL_TEMPLATE_PERMISSIONS,
   FORM_PERMISSIONS,
   FORM_RESULT_PERMISSIONS,
+  EMAIL_TEMPLATE_PERMISSIONS,
+  EMAIL_CONFIG_PERMISSIONS,
+  LANGUAGE_PERMISSIONS,
+  TRANSLATION_PERMISSIONS,
+  NOTIFICATION_PERMISSIONS,
+  EVENT_PERMISSIONS,
+} from '@flusys/nestjs-shared/constants';
 
-  // Utilities
-  escapeHtml,
-  escapeHtmlVariables,
-  applyCompanyFilter,
-  buildCompanyWhereCondition,
-  hasCompanyId,
-  validateCompanyOwnership,
-  ICompanyFilterConfig,
-  ICompanyEnabled,
-  isBrowserRequest,
-  buildCookieOptions,
-  parseDurationToMs,
-  generateSlug,
-  generateUniqueSlug,
-} from '@flusys/nestjs-shared';
+// Example: USER_PERMISSIONS
+// { CREATE: 'user.create', READ: 'user.read', UPDATE: 'user.update', DELETE: 'user.delete' }
 ```
 
 ---
 
-## UtilsService
+## Cross-Module Adapter Interfaces
 
-Global utility service for cache management and string operations.
+These interfaces are defined in `nestjs-shared` so modules can reference the contract without importing each other:
 
 ```typescript
-import { UtilsService, CACHE_INSTANCE, HybridCache } from '@flusys/nestjs-shared';
-
-@Injectable()
-export class MyService {
-  constructor(
-    @Inject(UtilsService) private readonly utilsService: UtilsService,
-    @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
-  ) {}
-
-  // Cache key generation with optional tenant prefix
-  getCacheKey(entityName: string, params: any, entityId?: string, tenantId?: string): string;
-  // Example: this.utilsService.getCacheKey('user', { filter: {} }, 'user-123', 'tenant-1')
-  // Returns: 'tenant_tenant-1_entity_user_id_user-123_select_{"filter":{}}'
-
-  // Track cache keys for invalidation
-  async trackCacheKey(
-    cacheKey: string,
-    entityName: string,
-    cacheManager: HybridCache,
-    entityId?: string,
-    tenantId?: string,
-  ): Promise<void>;
-
-  // Clear all cached entries for an entity
-  async clearCache(
-    entityName: string,
-    cacheManager: HybridCache,
-    entityId?: string,
-    tenantId?: string,
-  ): Promise<void>;
-
-  // Generate URL-friendly slug
-  transformToSlug(value: string, salt?: boolean): string;
-  // Example: this.utilsService.transformToSlug('My Product Name')
-  // Returns: 'my-product-name'
-  // With salt: 'my-product-name-42'
-
-  // Generate random integer
-  getRandomInt(min: number, max: number): number;
-}
+import { INotificationAdapter, NOTIFICATION_ADAPTER } from '@flusys/nestjs-shared/interfaces';
+import { IEventManagerAdapter, EVENT_MANAGER_ADAPTER } from '@flusys/nestjs-shared/interfaces';
 ```
 
+Pattern: Feature module A wants to send a notification (defined in module B). Instead of importing B from A (circular dep), A imports only the interface from `nestjs-shared` and uses `@Optional() @Inject(NOTIFICATION_ADAPTER)`.
+
 ---
 
-## Best Practices
+## Troubleshooting
+
+**`Cannot read properties of undefined` on injected service**
 
-### 1. Use Generic Service Pattern
+All constructor dependencies need `@Inject()` decorators — esbuild bundling loses TypeScript metadata:
 
 ```typescript
-// Extend ApiService for consistent CRUD operations
-@Injectable()
-export class ProductService extends ApiService<
-  CreateProductDto,
-  UpdateProductDto,
-  IProduct,
-  Product,
-  Repository<Product>
-> {
-  // Override hooks for custom business logic
-  protected async beforeInsertOperation(dto, user, qr): Promise<void> {
-    // Validation, transformations, etc.
-  }
-}
+// Wrong
+constructor(private readonly service: MyService) {}
 
-// For dynamic entity resolution, use RequestScopedApiService
-@Injectable({ scope: Scope.REQUEST })
-export class RoleService extends RequestScopedApiService<...> {
-  protected resolveEntity() {
-    return this.config.isCompanyFeatureEnabled() ? RoleWithCompany : Role;
-  }
-}
+// Correct
+constructor(@Inject(MyService) private readonly service: MyService) {}
 ```
 
-### 2. Always Use @Inject() Decorators
+---
 
-Required for esbuild bundled code (NestJS DI metadata may be lost):
+**`No metadata for entity X`**
 
-```typescript
-// CORRECT - explicit injection
-constructor(
-  @Inject(MyService) private readonly myService: MyService,
-  @Inject(CACHE_INSTANCE) private readonly cache: HybridCache,
-  @Inject(UtilsService) private readonly utils: UtilsService,
-) {}
-
-// WRONG - may fail in bundled code
-constructor(private readonly myService: MyService) {}
-```
-
-### 3. Use Decorators Consistently
+You are using `RequestScopedApiService` but forgot to call `ensureRepositoryInitialized()` before accessing `this.repository`. Override the method:
 
 ```typescript
-// Use built-in decorators for type safety
-@CurrentUser() user: ILoggedUserInfo
-@CurrentUser('id') userId: string  // Extract specific property
-
-// Permission decorators
-@RequirePermission('user.create')                    // Single permission (AND)
-@RequirePermission('user.create', 'admin')           // Multiple permissions (AND)
-@RequireAnyPermission('user.read', 'admin')          // Multiple permissions (OR)
-@RequirePermissionLogic({ type: 'group', ... })      // Complex logic
-
-// Mark public routes sparingly - security risk!
-@Public()
-
-// Avoid direct request access - use decorators
-// @Req() req: Request  // Not type-safe, avoid!
+protected override async ensureRepositoryInitialized(): Promise<void> {
+  if (!this.repositoryInitialized) {
+    this.repository = await this.dataSourceProvider.getRepository(MyEntity);
+    this.repositoryInitialized = true;
+  }
+}
 ```
 
-### 4. Configure Security at Controller Level
-
-```typescript
-// GOOD - centralized security config
-export class UserController extends createApiController(
-  CreateUserDto, UpdateUserDto, UserResponseDto,
-  {
-    security: {
-      getAll: 'jwt',
-      insert: { level: 'permission', permissions: ['user.create'] },
-      update: { level: 'permission', permissions: ['user.update'] },
-      delete: { level: 'permission', permissions: ['user.delete'] },
-    },
-  },
-) {}
-
-// AVOID - scattered guards on each endpoint
-@UseGuards(JwtGuard)
-@Post('create')
-create() {}
-```
+---
 
-### 5. Use Permission Constants
+**Cache not connecting to Redis**
 
-```typescript
-import { PERMISSIONS } from '@flusys/nestjs-shared';
+`CacheModule` falls back to in-memory automatically if `REDIS_URL` is not set or Redis is unreachable. Check that `REDIS_URL` is set correctly in your `.env` file.
 
-// GOOD - use constants for type safety and refactoring
-@RequirePermission(PERMISSIONS.USER.CREATE)
+---
 
-// AVOID - hardcoded strings prone to typos
-@RequirePermission('user.create')
-```
+**`instanceof` checks fail after bundling**
 
-### 6. Leverage Company Filtering Utilities
+Use property-based checks instead:
 
 ```typescript
-import { applyCompanyFilter, validateCompanyOwnership } from '@flusys/nestjs-shared';
-
-// In service getExtraManipulateQuery hook
-protected async getExtraManipulateQuery(query, dto, user) {
-  applyCompanyFilter(query, {
-    isCompanyFeatureEnabled: this.config.isCompanyFeatureEnabled(),
-    entityAlias: this.entityName,
-  }, user);
-  return { query, isRaw: false };
-}
+// Wrong (fails after esbuild)
+if (dto instanceof UpdateProductDto) { }
 
-// Validate ownership before operations
-validateCompanyOwnership(entity, user, this.config.isCompanyFeatureEnabled(), 'Product');
+// Correct
+if ('id' in dto && dto.id) { }
 ```
 
-### 7. Error Handling Pattern
+---
 
-```typescript
-import { LogAction } from '@flusys/nestjs-shared';
+## License
 
-// Use @LogAction for consistent logging with sensitive data redaction
-@LogAction({ action: 'user.create', includeParams: false })
-async createUser(dto: CreateUserDto): Promise<User> {
-  return this.repository.save(dto);
-  // Errors automatically logged with stack trace, then re-thrown
-}
-```
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.