@flusys/nestjs-storage 3.0.0-rc → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Storage Package Guide
 
 > **Package:** `@flusys/nestjs-storage`
+> **Version:** 3.0.0
 > **Type:** File storage system with pluggable providers and multi-tenant support
 
 This comprehensive guide covers the storage package - flexible file storage with multiple provider support.
@@ -18,8 +19,13 @@ This comprehensive guide covers the storage package - flexible file storage with
 - [File Manager](#file-manager)
 - [Folder Management](#folder-management)
 - [Upload Service](#upload-service)
+- [File Validation & Security](#file-validation--security)
+- [Image Compression](#image-compression)
 - [REST API Endpoints](#rest-api-endpoints)
+- [File Serve Middleware](#file-serve-middleware)
+- [DataSource Provider Pattern](#datasource-provider-pattern)
 - [Multi-Tenant Support](#multi-tenant-support)
+- [Swagger Configuration](#swagger-configuration)
 - [Best Practices](#best-practices)
 - [API Reference](#api-reference)
 
@@ -30,10 +36,11 @@ This comprehensive guide covers the storage package - flexible file storage with
 `@flusys/nestjs-storage` provides a comprehensive file storage system:
 
 - **Multiple Providers** - Local, AWS S3, Azure Blob, SFTP
-- **Provider Connection Reuse** - Efficient connection management
-- **File Validation** - Size and type validation
-- **Folder Hierarchy** - Nested folder structure
-- **Presigned URLs** - Secure time-limited access
+- **Provider Connection Reuse** - Efficient connection management with caching
+- **File Validation** - Size, type, and magic bytes validation
+- **Image Compression** - Automatic optimization with format conversion
+- **Folder Organization** - Simple folder-based file organization
+- **Presigned URLs** - Secure time-limited access for cloud providers
 - **Multi-Tenant Support** - Company/branch file isolation
 - **Storage Configuration** - Per-company storage settings
 
@@ -56,10 +63,13 @@ This comprehensive guide covers the storage package - flexible file storage with
 ```bash
 npm install @flusys/nestjs-storage @flusys/nestjs-shared @flusys/nestjs-core
 
+# Required dependencies
+npm install sharp mime-types uuid
+
 # Optional: Install provider-specific packages
-npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner  # For AWS S3
-npm install @azure/storage-blob                                 # For Azure Blob
-npm install ssh2-sftp-client                                    # For SFTP
+npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner  # For AWS S3
+npm install @azure/storage-blob                                                     # For Azure Blob
+npm install ssh2-sftp-client                                                        # For SFTP
 ```
 
 ---
@@ -83,54 +93,51 @@ export const DEFAULT_ALLOWED_FILE_TYPES = ['*/*']; // All file types
 nestjs-storage/
 ├── src/
 │   ├── modules/
-│   │   └── storage.module.ts        # Main module
+│   │   └── storage.module.ts         # Main module with provider registration
 │   │
 │   ├── config/
-│   │   ├── storage-config.service.ts  # Configuration service
-│   │   ├── storage.constants.ts       # Constants
+│   │   ├── storage.constants.ts      # Module constants
 │   │   └── index.ts
 │   │
 │   ├── providers/
-│   │   ├── local-provider.ts          # Local filesystem
-│   │   ├── s3-provider.optional.ts    # AWS S3
-│   │   ├── azure-provider.optional.ts # Azure Blob
-│   │   ├── sftp-provider.optional.ts  # SFTP
-│   │   ├── storage-factory.service.ts # Provider factory
-│   │   ├── storage-provider.registry.ts
+│   │   ├── local-provider.ts           # Local filesystem (built-in)
+│   │   ├── s3-provider.optional.ts     # AWS S3 (requires @aws-sdk/client-s3)
+│   │   ├── azure-provider.optional.ts  # Azure Blob (requires @azure/storage-blob)
+│   │   ├── sftp-provider.optional.ts   # SFTP (requires ssh2-sftp-client)
+│   │   ├── storage-factory.service.ts  # Provider factory with caching
+│   │   ├── storage-provider.registry.ts # Provider class registry
 │   │   └── index.ts
 │   │
 │   ├── services/
-│   │   ├── upload.service.ts           # Upload operations
-│   │   ├── file-manager.service.ts     # File metadata CRUD
-│   │   ├── folder.service.ts           # Folder CRUD
-│   │   ├── storage-provider-config.service.ts
-│   │   ├── storage-datasource.provider.ts  # Dynamic entity loading
+│   │   ├── upload.service.ts              # Upload/delete operations
+│   │   ├── file-manager.service.ts        # File metadata CRUD
+│   │   ├── folder.service.ts              # Folder CRUD
+│   │   ├── storage-config.service.ts      # Module configuration
+│   │   ├── storage-provider-config.service.ts # Storage config CRUD
+│   │   ├── storage-datasource.provider.ts # Dynamic entity loading
 │   │   └── index.ts
 │   │
 │   ├── controllers/
-│   │   ├── upload.controller.ts
-│   │   ├── file-manager.controller.ts
-│   │   ├── folder.controller.ts
-│   │   ├── storage-config.controller.ts
+│   │   ├── upload.controller.ts        # /storage/upload/*
+│   │   ├── file-manager.controller.ts  # /storage/file-manager/*
+│   │   ├── folder.controller.ts        # /storage/folder/*
+│   │   ├── storage-config.controller.ts # /storage/storage-config/*
 │   │   └── index.ts
 │   │
 │   ├── entities/
-│   │   ├── file-manager-base.entity.ts
-│   │   ├── file-manager.entity.ts
+│   │   ├── file-manager.entity.ts        # FileManager base
 │   │   ├── file-manager-with-company.entity.ts
-│   │   ├── folder-base.entity.ts
-│   │   ├── folder.entity.ts
+│   │   ├── folder.entity.ts              # Folder base
 │   │   ├── folder-with-company.entity.ts
-│   │   ├── storage-config-base.entity.ts
-│   │   ├── storage-config.entity.ts
+│   │   ├── storage-config.entity.ts      # StorageConfig base
 │   │   ├── storage-config-with-company.entity.ts
 │   │   └── index.ts
 │   │
 │   ├── dtos/
-│   │   ├── upload.dto.ts
-│   │   ├── file-manager.dto.ts
-│   │   ├── folder.dto.ts
-│   │   ├── storage-config.dto.ts
+│   │   ├── upload.dto.ts           # Upload options, delete DTOs
+│   │   ├── file-manager.dto.ts     # File manager DTOs
+│   │   ├── folder.dto.ts           # Folder DTOs
+│   │   ├── storage-config.dto.ts   # Storage config DTOs
 │   │   └── index.ts
 │   │
 │   ├── interfaces/
@@ -142,11 +149,20 @@ nestjs-storage/
 │   │   └── index.ts
 │   │
 │   ├── enums/
-│   │   ├── file-location.enum.ts
+│   │   ├── file-location.enum.ts   # Provider type enum
+│   │   └── index.ts
+│   │
+│   ├── middlewares/
+│   │   ├── file-serve.middleware.ts # File serving with fallback strategies
+│   │   └── index.ts
+│   │
+│   ├── docs/
+│   │   ├── storage-swagger.config.ts # Swagger configuration
 │   │   └── index.ts
 │   │
 │   └── utils/
-│       ├── image-compressor.util.ts
+│       ├── file-validator.util.ts    # Magic bytes validation
+│       ├── image-compressor.util.ts  # Sharp-based compression
 │       └── index.ts
 ```
 
@@ -168,22 +184,21 @@ import { StorageModule } from '@flusys/nestjs-storage';
       bootstrapAppConfig: {
         databaseMode: 'single',
         enableCompanyFeature: false,
-        permissionMode: 'RBAC', // IAM permission mode
+        permissionMode: 'RBAC',
       },
       config: {
         defaultDatabaseConfig: {
-          type: 'mysql',
+          type: 'postgres',
           host: 'localhost',
-          port: 3306,
-          username: 'root',
+          port: 5432,
+          username: 'postgres',
           password: 'password',
           database: 'myapp',
         },
-        // File validation
         maxFileSize: 10 * 1024 * 1024, // 10MB
         allowedFileTypes: ['image/*', 'application/pdf', 'text/*'],
-        // URL generation (optional - falls back to APP_URL env or PORT)
-        appUrl: process.env.APP_URL || `http://localhost:${process.env.PORT || 3000}`,
+        localStoragePath: './uploads',
+        appUrl: process.env.APP_URL || 'http://localhost:3000',
       },
     }),
   ],
@@ -199,20 +214,15 @@ StorageModule.forRoot({
   includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
-    enableCompanyFeature: true, // Enable company/branch isolation
-    permissionMode: 'FULL', // Use both roles and direct permissions
+    enableCompanyFeature: true,
+    permissionMode: 'FULL',
   },
   config: {
-    defaultDatabaseConfig: {
-      type: 'mysql',
-      host: 'localhost',
-      port: 3306,
-      username: 'root',
-      password: 'password',
-      database: 'myapp',
-    },
+    defaultDatabaseConfig: { /* ... */ },
     maxFileSize: 10 * 1024 * 1024,
     allowedFileTypes: ['image/*', 'application/pdf'],
+    localStoragePath: './uploads',
+    appUrl: process.env.APP_URL,
   },
 });
 ```
@@ -233,6 +243,8 @@ StorageModule.forRootAsync({
     defaultDatabaseConfig: configService.getDatabaseConfig(),
     maxFileSize: configService.get('MAX_FILE_SIZE'),
     allowedFileTypes: configService.get('ALLOWED_FILE_TYPES'),
+    localStoragePath: configService.get('UPLOAD_PATH'),
+    appUrl: configService.get('APP_URL'),
   }),
   inject: [ConfigService],
 });
@@ -241,28 +253,28 @@ StorageModule.forRootAsync({
 ### Configuration Options
 
 ```typescript
-interface StorageModuleOptions {
-  global?: boolean;
-  includeController?: boolean;
-  bootstrapAppConfig: {
-    databaseMode: 'single' | 'multi-tenant';
-    enableCompanyFeature: boolean;
-    permissionMode?: 'FULL' | 'RBAC' | 'DIRECT'; // IAM permission mode
-  };
-  config: {
-    defaultDatabaseConfig: IDatabaseConfig;
-    maxFileSize?: number; // Max file size in bytes
-    allowedFileTypes?: string[]; // MIME type patterns
-    uploadPath?: string; // Local upload path
-  };
+interface IStorageModuleConfig extends IDataSourceServiceOptions {
+  /** Maximum file size in bytes (default: 100MB) */
+  maxFileSize?: number;
+  /** Allowed MIME types or patterns (default: ['*/*']) */
+  allowedFileTypes?: string[];
+  /** Default storage provider (optional) */
+  defaultStorageProvider?: string;
+  /** Local storage path (default: './uploads') */
+  localStoragePath?: string;
+  /** Application base URL for file URLs */
+  appUrl?: string;
 }
-```
 
-**Note:** `permissionMode` in `bootstrapAppConfig` is used by IAM module for permission checks. Storage module respects these permissions for file access control.
+interface StorageModuleOptions extends IDynamicModuleConfig {
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  config?: IStorageModuleConfig;
+}
+```
 
 ### Swagger Schema Behavior
 
-When `enableCompanyFeature: false`, the following properties are automatically hidden from Swagger documentation:
+When `enableCompanyFeature: false`, the following properties are automatically hidden from Swagger:
 
 | DTO                        | Hidden Fields |
 | -------------------------- | ------------- |
@@ -270,12 +282,21 @@ When `enableCompanyFeature: false`, the following properties are automatically h
 | `FolderResponseDto`        | `companyId`   |
 | `StorageConfigResponseDto` | `companyId`   |
 
-This ensures the API documentation accurately reflects the available fields based on your configuration.
-
 ---
 
 ## Entities
 
+### FileLocationEnum
+
+```typescript
+export enum FileLocationEnum {
+  AWS = 'aws',
+  AZURE = 'azure',
+  SFTP = 'sftp',
+  LOCAL = 'local',
+}
+```
+
 ### Entity Groups
 
 ```typescript
@@ -294,58 +315,201 @@ export function getStorageEntitiesByConfig(enableCompanyFeature: boolean): any[]
   return enableCompanyFeature ? StorageCompanyEntities : StorageCoreEntities;
 }
 
-// Base type aliases for backwards compatibility
+// Base type aliases
 export { FileManager as FileManagerBase } from './file-manager.entity';
 export { Folder as FolderBase } from './folder.entity';
 export { StorageConfig as StorageConfigBase } from './storage-config.entity';
 ```
 
+### FileManager Entity
+
+```typescript
+@Entity({ name: 'file_manager' })
+export class FileManager extends Identity {
+  @Column({ type: 'varchar', length: 255 })
+  name!: string; // Original filename
+
+  @Column({ type: 'varchar', length: 255 })
+  contentType!: string; // MIME type
+
+  @Column({ type: 'varchar', length: 255 })
+  size!: string; // File size as string
+
+  @Column({ type: 'text' })
+  key!: string; // Storage key/path
+
+  @Column({ type: 'text', nullable: true })
+  url!: string | null; // Public/presigned URL
+
+  @Column({ type: 'varchar', length: 50 })
+  location!: string; // Provider type (local, aws, azure, sftp)
+
+  @Column({ type: 'uuid', nullable: true })
+  storageConfigId!: string | null;
+
+  @Column({ type: 'bigint', nullable: true })
+  expiresAt: number | null = null; // URL expiration timestamp
+
+  @Column({ type: 'boolean', default: false })
+  isPrivate!: boolean;
+
+  @ManyToOne('Folder', (folder: any) => folder.fileManager, { nullable: true, onDelete: 'SET NULL' })
+  @JoinColumn({ name: 'folder_id' })
+  folder!: Folder | null;
+}
+
+// With company feature
+@Entity({ name: 'file_manager' })
+export class FileManagerWithCompany extends FileManager {
+  @Column({ type: 'uuid', nullable: true })
+  companyId!: string | null;
+}
+```
+
+### Folder Entity
+
+```typescript
+@Entity({ name: 'folder' })
+export class Folder extends Identity {
+  @Column({ type: 'varchar', length: 255 })
+  name!: string;
+
+  @Column({ type: 'varchar', length: 255 })
+  slug!: string;
+
+  @OneToMany('FileManager', (fileManager: any) => fileManager.folder)
+  fileManager!: any[];
+}
+
+// With company feature
+@Entity({ name: 'folder' })
+export class FolderWithCompany extends Folder {
+  @Column({ type: 'uuid', nullable: true })
+  companyId!: string | null;
+}
+```
+
+### StorageConfig Entity
+
+```typescript
+@Entity({ name: 'storage_config' })
+@Index(['name'])
+@Index(['storage'])
+@Index(['isActive'])
+@Index(['isDefault'])
+export class StorageConfig extends Identity {
+  @Column({ type: 'varchar', length: 255 })
+  name!: string; // e.g., 'default', 'backups', 'media'
+
+  @Column({ type: 'varchar', length: 50 })
+  storage!: string; // Provider type (local, aws, azure, sftp)
+
+  @Column({ type: 'json' })
+  config!: Record<string, any>; // Provider-specific config
+
+  @Column({ type: 'boolean', default: true, name: 'is_active' })
+  isActive!: boolean;
+
+  @Column({ type: 'boolean', default: false, name: 'is_default' })
+  isDefault!: boolean;
+}
+
+// With company feature
+@Entity({ name: 'storage_config' })
+export class StorageConfigWithCompany extends StorageConfig {
+  @Column({ type: 'uuid', nullable: true })
+  companyId!: string | null;
+}
+```
+
 ---
 
 ## Storage Providers
 
-### Provider Types
+### Provider Interface
+
+```typescript
+interface IStorageProvider {
+  uploadFile(file: Express.Multer.File, options: UploadOptionsDto): Promise<IUploadedFileInfo>;
+  uploadMultipleFiles(files: Express.Multer.File[], options: UploadOptionsDto): Promise<IUploadedFileInfo[]>;
+  deleteFile(key: string): Promise<void>;
+  deleteMultipleFiles(keys: string[]): Promise<void>;
+  generatePresignedUrl(key: string, expiresInSeconds?: number): Promise<string>;
+  healthCheck(): Promise<boolean>;
+  initialize?(config: any): Promise<void>;
+}
+
+interface IUploadedFileInfo {
+  key: string;
+  contentType: string;
+  size: number;
+  name: string;
+  location?: string;
+  storageConfigId?: string;
+}
+```
+
+### Provider Registration
+
+Providers are automatically registered when the module loads:
 
 ```typescript
-enum FileLocationEnum {
-  LOCAL = 'LOCAL', // Local filesystem
-  AWS = 'AWS', // AWS S3
-  AZURE = 'AZURE', // Azure Blob Storage
-  SFTP = 'SFTP', // SFTP server
+// storage.module.ts
+StorageProviderRegistry.register(FileLocationEnum.LOCAL, LocalProvider);
+
+// Optional providers loaded dynamically
+const OPTIONAL_PROVIDERS = [
+  { location: FileLocationEnum.AWS, path: '../providers/s3-provider.optional', name: 'S3Provider', dep: '@aws-sdk/client-s3' },
+  { location: FileLocationEnum.AZURE, path: '../providers/azure-provider.optional', name: 'AzureProvider', dep: '@azure/storage-blob' },
+  { location: FileLocationEnum.SFTP, path: '../providers/sftp-provider.optional', name: 'SftpProvider', dep: 'ssh2-sftp-client' },
+];
+
+for (const { location, path, name, dep } of OPTIONAL_PROVIDERS) {
+  try {
+    StorageProviderRegistry.register(location, require(path)[name]);
+    logger.log(`Registered ${name}`);
+  } catch {
+    logger.debug(`${name} not available (install ${dep} to enable)`);
+  }
 }
 ```
 
 ### Local Provider
 
 ```typescript
-// Default provider - always available
-// Stores files in local filesystem
+// Built-in, no external dependencies required
+// Uses Node.js fs module
 
 // Configuration:
 {
-  storage: FileLocationEnum.LOCAL,
+  storage: 'local',
   config: {
-    uploadPath: './uploads',  // Base directory
+    basePath: './uploads',  // Base directory
+    baseUrl: 'http://localhost:3000'  // Optional, for URL generation
   }
 }
 ```
 
+**Features:**
+- Path traversal attack prevention
+- Automatic directory creation
+- UUID-prefixed filenames
+- Image compression support
+
 ### AWS S3 Provider
 
 ```typescript
-// Requires: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+// Requires: npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
 
 // Configuration:
 {
-  storage: FileLocationEnum.AWS,
+  storage: 'aws',
   config: {
     region: 'us-east-1',
     bucket: 'my-bucket',
     accessKeyId: 'AKIA...',
     secretAccessKey: 'secret...',
-    // Optional
-    endpoint: 'https://s3.us-east-1.amazonaws.com',
-    forcePathStyle: false,
+    endpoint: 'https://s3.us-east-1.amazonaws.com'  // Optional
   }
 }
 ```
@@ -357,13 +521,13 @@ enum FileLocationEnum {
 
 // Configuration:
 {
-  storage: FileLocationEnum.AZURE,
+  storage: 'azure',
   config: {
-    connectionString: 'DefaultEndpointsProtocol=https;...',
-    containerName: 'my-container',
-    // Or use SAS token
     accountName: 'myaccount',
-    sasToken: '?sv=...',
+    accountKey: 'key...',
+    containerName: 'my-container',
+    // Or use connection string
+    connectionString: 'DefaultEndpointsProtocol=https;...'
   }
 }
 ```
@@ -375,7 +539,7 @@ enum FileLocationEnum {
 
 // Configuration:
 {
-  storage: FileLocationEnum.SFTP,
+  storage: 'sftp',
   config: {
     host: 'sftp.example.com',
     port: 22,
@@ -383,60 +547,51 @@ enum FileLocationEnum {
     password: 'password',
     // Or use private key
     privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
-    basePath: '/uploads',
+    basePath: '/uploads'
   }
 }
 ```
 
-### Provider Registration
-
-Providers are automatically registered via `UploadService.onModuleInit()`:
-- **Local** - Always available (no external dependencies)
-- **S3/Azure/SFTP** - Registered only if their SDK dependencies are installed
-
-### Provider Connection Reuse
-
-The `StorageFactoryService` caches provider instances:
+### Provider Factory & Caching
 
 ```typescript
-// storage-factory.service.ts
 @Injectable()
 export class StorageFactoryService implements OnModuleDestroy {
-  private providerCache = new Map<string, IStorageProvider>();
-
-  // Generate unique cache key using SHA256 hash
-  private generateCacheKey(config: IStorageProviderConfig): string {
-    const configString = JSON.stringify(config.config, Object.keys(config.config || {}).sort());
-    const configHash = crypto
-      .createHash('sha256')
-      .update(configString)
-      .digest('hex')
-      .substring(0, 16);
-    return `${config.provider}-${configHash}`;
-  }
+  private readonly cache = new Map<string, IStorageProvider>();
 
   async createProvider(config: IStorageProviderConfig): Promise<IStorageProvider> {
     const cacheKey = this.generateCacheKey(config);
 
-    // Return cached provider if exists
-    if (this.providerCache.has(cacheKey)) {
-      return this.providerCache.get(cacheKey)!;
+    const cached = this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    const ProviderClass = StorageProviderRegistry.get(config.provider);
+    if (!ProviderClass) {
+      throw new NotFoundException(`Storage provider '${config.provider}' not registered`);
     }
 
-    // Create new provider
-    const provider = await StorageProviderRegistry.create(config);
-    this.providerCache.set(cacheKey, provider);
-    return provider;
+    const instance = new ProviderClass();
+    await this.initializeProvider(instance, config);
+    this.cache.set(cacheKey, instance);
+    return instance;
+  }
+
+  // Generate cache key using SHA256 hash of config
+  private generateCacheKey(config: IStorageProviderConfig): string {
+    const hash = crypto.createHash('sha256')
+      .update(JSON.stringify(config.config, Object.keys(config.config || {}).sort()))
+      .digest('hex').substring(0, 16);
+    return `${config.provider}-${hash}`;
   }
 
   // Cleanup on module destroy
   async onModuleDestroy(): Promise<void> {
-    for (const [key, provider] of this.providerCache.entries()) {
+    for (const [key, provider] of this.cache.entries()) {
       if ('close' in provider && typeof (provider as any).close === 'function') {
         await (provider as any).close();
       }
     }
-    this.providerCache.clear();
+    this.cache.clear();
   }
 }
 ```
@@ -445,30 +600,53 @@ export class StorageFactoryService implements OnModuleDestroy {
 
 ## Storage Configuration
 
-### StorageConfig Entity
-
-Each company can have multiple storage configurations:
+### StorageProviderConfigService
 
 ```typescript
-@Entity('storage_configs')
-export class StorageConfig extends Identity {
-  @Column({ length: 100 })
-  name: string; // e.g., 'default', 'backups', 'media'
+@Injectable({ scope: Scope.REQUEST })
+export class StorageProviderConfigService extends RequestScopedApiService<...> {
 
-  @Column({ type: 'enum', enum: FileLocationEnum })
-  storage: FileLocationEnum;
+  /** Direct lookup by ID (bypasses company filtering) */
+  async findByIdDirect(id: string): Promise<StorageConfigBase | null>;
 
-  @Column({ type: 'json' })
-  config: Record<string, any>; // Provider-specific config
+  /** Get default config for user's company */
+  async getDefaultConfig(user?: ILoggedUserInfo): Promise<StorageConfigBase | null>;
+
+  /** Get configs by storage type */
+  async getConfigByType(storage: string, user?: ILoggedUserInfo): Promise<StorageConfigBase[]>;
+}
+```
 
-  @Column({ default: true })
-  isActive: boolean; // Whether config is active and usable
+### Default Configuration Resolution
 
-  @Column({ default: false })
-  isDefault: boolean; // Set as default configuration
+When `storageConfigId` is not provided for uploads:
 
-  @Column({ nullable: true })
-  companyId: string; // Company scope (when enabled)
+1. **Priority 1:** Find config with `isDefault: true` and `isActive: true`
+2. **Priority 2:** Fall back to oldest active config
+
+```typescript
+async getDefaultConfig(user?: ILoggedUserInfo): Promise<StorageConfigBase | null> {
+  await this.ensureRepositoryInitialized();
+
+  const baseWhere = buildCompanyWhereCondition(
+    { isActive: true },
+    this.storageConfig.isCompanyFeatureEnabled(),
+    user,
+  );
+
+  // First try to find config marked as default
+  const defaultConfig = await this.repository.findOne({
+    where: { ...baseWhere, isDefault: true },
+    order: { createdAt: 'ASC' },
+  });
+
+  if (defaultConfig) return defaultConfig;
+
+  // Fall back to oldest active config
+  return await this.repository.findOne({
+    where: baseWhere,
+    order: { createdAt: 'ASC' },
+  });
 }
 ```
 
@@ -483,737 +661,646 @@ export class SetupService {
 
   async setupStorageConfigs(user: ILoggedUserInfo) {
     // Create default S3 config
-    await this.storageConfigService.insert(
-      {
-        name: 'default',
-        storage: FileLocationEnum.AWS,
-        config: {
-          region: 'us-east-1',
-          bucket: 'company-files',
-          accessKeyId: process.env.AWS_ACCESS_KEY,
-          secretAccessKey: process.env.AWS_SECRET_KEY,
-        },
-        isActive: true,
-        isDefault: true,  // Set as default configuration
+    await this.storageConfigService.insert({
+      name: 'default',
+      storage: 'aws',
+      config: {
+        region: 'us-east-1',
+        bucket: 'company-files',
+        accessKeyId: process.env.AWS_ACCESS_KEY,
+        secretAccessKey: process.env.AWS_SECRET_KEY,
       },
-      user,
-    );
-
-    // Create backup storage config
-    await this.storageConfigService.insert(
-      {
-        name: 'backups',
-        storage: FileLocationEnum.SFTP,
-        config: {
-          host: 'backup.example.com',
-          username: 'backup-user',
-          privateKey: process.env.SFTP_PRIVATE_KEY,
-          basePath: '/backups',
-        },
-        isActive: true,
-        isDefault: false, // Not the default
+      isActive: true,
+      isDefault: true,
+    }, user);
+
+    // Create local backup config
+    await this.storageConfigService.insert({
+      name: 'local-backup',
+      storage: 'local',
+      config: {
+        basePath: './backups',
       },
-      user,
-    );
+      isActive: true,
+      isDefault: false,
+    }, user);
   }
 }
 ```
 
-### Storage Provider Resolution Flow
+---
 
-When performing upload operations, the `UploadService` resolves the storage provider using a multi-level fallback strategy:
+## File Manager
 
-**Resolution Flow Diagram:**
+### FileManagerService
 
-```
-Upload Request (with optional storageConfigId)
-                │
-                ▼
-┌─────────────────────────────────────────────────────────┐
-│ 1. Check if storageConfigId provided                    │
-└─────────────────────────────────────────────────────────┘
-                │
-       provided? ─┴── no ──┐
-         │                 │
-         ▼                 ▼
-┌──────────────────┐  ┌─────────────────────────────────────┐
-│ 2. Lookup config │  │ 3. Get default config for company   │
-│    by ID         │  │    - Priority 1: isDefault=true     │
-└────────┬─────────┘  │    - Priority 2: oldest active      │
-         │            └─────────────────────────────────────┘
-         │                 │
-         ▼                 ▼
-┌─────────────────────────────────────────────────────────┐
-│ 4. Validate company ownership (if company feature)     │
-│    - Throws BadRequestException if wrong company       │
-└─────────────────────────────────────────────────────────┘
-                │
-                ▼
-┌─────────────────────────────────────────────────────────┐
-│ 5. Create/reuse storage provider instance              │
-│    - Check provider cache by config hash               │
-│    - Create new if not cached                          │
-└─────────────────────────────────────────────────────────┘
-                │
-                ▼
-           [Perform Upload]
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class FileManagerService extends RequestScopedApiService<...> {
+
+  /** Enrich files with provider names */
+  async enrichWithProviderNames<T extends { storageConfigId?: string | null }>(
+    items: T[]
+  ): Promise<(T & { providerName?: string })[]>;
+
+  /** Get multiple files with refreshed URLs */
+  async getFiles(
+    dtos: GetFilesRequestDto[],
+    protocol: string,
+    host: string,
+    user?: ILoggedUserInfo
+  ): Promise<FilesResponseDto[]>;
+}
 ```
 
-**Code Implementation:**
+### URL Generation & Refresh
 
-```typescript
-// UploadService
-private async getStorageProvider(
-  storageConfigId?: string,
-  user?: ILoggedUserInfo,
-): Promise<{ provider: IStorageProvider; config: StorageConfigBase }> {
-  let config: StorageConfigBase | null = null;
-
-  // Step 1: Try to get by ID or fallback to default
-  if (storageConfigId) {
-    config = await this.storageProviderConfigService.findByIdDirect(storageConfigId);
-  }
+Files automatically get presigned URLs when needed:
 
-  if (!config) {
-    config = await this.storageProviderConfigService.getDefaultConfig(user);
-  }
+```typescript
+async getFiles(dtos: GetFilesRequestDto[], protocol: string, host: string, user?: ILoggedUserInfo): Promise<FilesResponseDto[]> {
+  const files = await this.repository.findBy({ id: In(ids) });
+  const now = Date.now();
+  const updatedFiles: FileManagerBase[] = [];
 
-  if (!config) {
-    throw new BadRequestException('No storage configuration available');
-  }
+  const responses = await Promise.all(
+    files.map(async (file) => {
+      const updated = await this.refreshFileUrl(file, protocol, host, now, user);
+      if (updated) updatedFiles.push(file);
+      return this.toFileResponse(file);
+    }),
+  );
 
-  // Step 2: Validate company ownership
-  if (this.storageConfigService.isCompanyFeatureEnabled() && user?.companyId) {
-    const configWithCompany = config as StorageConfigWithCompany;
-    if (configWithCompany.companyId && configWithCompany.companyId !== user.companyId) {
-      throw new BadRequestException('Storage configuration belongs to another company');
-    }
+  if (updatedFiles.length) {
+    await this.repository.save(updatedFiles);
   }
 
-  // Step 3: Get or create provider instance
-  const provider = await this.storageFactory.createProvider({
-    provider: config.storage,
-    config: config.config,
-  });
-
-  return { provider, config };
+  return responses;
 }
-```
-
-**Key Points:**
-- Always specify `storageConfigId` for deterministic behavior
-- Without `storageConfigId`, system uses company's default config
-- Company ownership is always validated when company feature is enabled
-- Provider instances are cached for connection reuse
-
-### Default Configuration Resolution
-
-When `storageConfigId` is not provided for uploads, the system automatically resolves the default config:
-
-1. **Priority 1:** Find config with `isDefault: true` and `isActive: true`
-2. **Priority 2:** Fall back to oldest active config
-
-```typescript
-// StorageProviderConfigService
-async getDefaultConfig(user?: ILoggedUserInfo): Promise<StorageConfigBase | null> {
-  await this.ensureRepositoryInitialized();
 
-  const baseWhere: any = { isActive: true };
+private async refreshFileUrl(file, protocol, host, now, user): Promise<boolean> {
+  const isCloudProvider = file.location === 'aws' || file.location === 'azure';
+  const needsNewUrl = !file.url || (isCloudProvider && now >= file.expiresAt);
 
-  // Filter by company if enabled
-  if (this.storageConfig.isCompanyFeatureEnabled() && user?.companyId) {
-    baseWhere.companyId = user.companyId;
+  if (needsNewUrl && file.storageConfigId) {
+    file.url = await this.uploadService.makeFileUrl(file.key, file.storageConfigId, 3600, user);
+    file.expiresAt = now + 3600 * 1000;
+    return true;
   }
 
-  // First try to find config marked as default
-  const defaultConfig = await this.repository.findOne({
-    where: { ...baseWhere, isDefault: true },
-    order: { createdAt: 'ASC' },
-  });
-
-  if (defaultConfig) return defaultConfig;
+  // For local/SFTP, generate serving URL
+  if (file.location === 'sftp' || file.location === 'local') {
+    const baseUrl = this.getFileBaseUrl(protocol, host);
+    file.url = `${baseUrl}/storage/upload/file/${file.key}`;
+    return true;
+  }
 
-  // Fall back to oldest active config
-  return await this.repository.findOne({
-    where: baseWhere,
-    order: { createdAt: 'ASC' },
-  });
+  return false;
 }
 ```
 
 ---
 
-## File Manager
+## Folder Management
 
-### FileManager Entity
+### FolderService
 
 ```typescript
-@Entity('file_manager')
-export class FileManager extends Identity {
-  @Column({ length: 255 })
-  name: string; // Original filename
+@Injectable({ scope: Scope.REQUEST })
+export class FolderService extends RequestScopedApiService<
+  CreateFolderDto,
+  UpdateFolderDto,
+  IFolder,
+  FolderBase,
+  Repository<FolderBase>
+> {
+  // Standard CRUD operations inherited from RequestScopedApiService
+  // Company filtering applied automatically when enabled
+}
+```
 
-  @Column({ length: 100 })
-  contentType: string; // MIME type
+### Folder DTOs
 
-  @Column()
-  size: number; // File size in bytes
+```typescript
+export class CreateFolderDto {
+  @IsNotEmpty()
+  @IsString()
+  name!: string;
+}
 
-  @Column({ length: 500 })
-  key: string; // Storage key/path
+export class UpdateFolderDto extends PartialType(CreateFolderDto) {
+  @IsUUID()
+  @IsNotEmpty()
+  id!: string;
+}
 
-  @Column({ length: 1000, nullable: true })
-  url: string; // Public/presigned URL
+export class FolderResponseDto {
+  id!: string;
+  name!: string;
+  slug!: string;
+}
+```
 
-  @Column({ type: 'enum', enum: FileLocationEnum })
-  location: FileLocationEnum;
+---
 
-  @Column({ default: false })
-  isPrivate: boolean;
+## Upload Service
 
-  @Column({ nullable: true })
-  folderId: string;
+### UploadService
 
-  @ManyToOne(() => Folder)
-  folder: Folder;
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class UploadService {
+
+  /** Upload single file with validation */
+  async uploadSingleFile(
+    file: Express.Multer.File,
+    options: UploadOptionsDto,
+    user?: ILoggedUserInfo
+  ): Promise<IUploadedFileInfo>;
+
+  /** Upload multiple files */
+  async uploadMultipleFiles(
+    files: Express.Multer.File[],
+    options: UploadOptionsDto,
+    user?: ILoggedUserInfo
+  ): Promise<IUploadedFileInfo[]>;
+
+  /** Delete single file */
+  async deleteSingleFile(
+    key: string,
+    storageConfigId?: string,
+    user?: ILoggedUserInfo,
+    locationHint?: string
+  ): Promise<boolean>;
+
+  /** Delete multiple files */
+  async deleteMultipleFile(
+    keys: string[],
+    storageConfigId?: string,
+    user?: ILoggedUserInfo,
+    locationHint?: string
+  ): Promise<boolean>;
+
+  /** Generate presigned URL */
+  async makeFileUrl(
+    key: string,
+    storageConfigId: string,
+    expiresIn?: number,
+    user?: ILoggedUserInfo
+  ): Promise<string>;
+
+  /** Get local storage base path from DB config */
+  async getLocalStorageBasePath(): Promise<string | null>;
+}
+```
 
-  @Column({ nullable: true })
-  storageConfigId: string;
+### Upload Options DTO
 
-  @Column({ type: 'bigint', nullable: true })
-  expiresAt: number; // URL expiration timestamp
+```typescript
+export enum ImageFormat {
+  ORIGINAL = 'original',
+  JPEG = 'jpeg',
+  PNG = 'png',
+  WEBP = 'webp',
+}
 
-  @Column({ nullable: true })
-  companyId: string; // When company feature enabled
+export class UploadOptionsDto {
+  @IsOptional()
+  @IsUUID()
+  storageConfigId?: string;
+
+  @IsOptional()
+  @Matches(/^[a-zA-Z0-9-_/]*$/)
+  folderPath?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(100)
+  @Max(10000)
+  maxWidth?: number = 1280;
+
+  @IsOptional()
+  @IsInt()
+  @Min(100)
+  @Max(10000)
+  maxHeight?: number = 1280;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  quality?: number = 85;
+
+  @IsOptional()
+  @IsEnum(ImageFormat)
+  format?: ImageFormat = ImageFormat.ORIGINAL;
+
+  @IsOptional()
+  @IsBoolean()
+  compress?: boolean = true;
 }
 ```
 
-### FileManagerService
+---
 
-```typescript
-import { FileManagerService } from '@flusys/nestjs-storage';
+## File Validation & Security
 
-@Injectable()
-export class MyService {
-  constructor(private readonly fileManagerService: FileManagerService) {}
-
-  async manageFiles(user: ILoggedUserInfo) {
-    // Create file record
-    const file = await this.fileManagerService.insert(
-      {
-        name: 'document.pdf',
-        contentType: 'application/pdf',
-        size: 1024000,
-        key: 'documents/doc-123.pdf',
-        location: FileLocationEnum.AWS,
-        storageConfigId: 'config-id',
-        folderId: 'folder-id',
-      },
-      user,
-    );
+### FileValidator Utility
 
-    // Get file by ID
-    const fileData = await this.fileManagerService.getById(file.id, user);
+The `FileValidator` class provides security features to prevent file upload attacks:
 
-    // Get files with pagination
-    const files = await this.fileManagerService.getAll(
-      {
-        filter: { contentType: 'application/pdf' },
-        pagination: { page: 1, limit: 10 },
-      },
-      user,
-    );
+```typescript
+export class FileValidator {
+  /** Detect file type from buffer using magic bytes */
+  static detectFileType(buffer: Buffer): string | null;
 
-    // Get multiple files with valid URLs
-    const filesWithUrls = await this.fileManagerService.getFiles(
-      [{ id: 'file-1' }, { id: 'file-2' }],
-      'https',
-      'example.com',
-      user,
-    );
+  /** Check if MIME type is text-based (no magic bytes) */
+  static isTextBasedType(mimeType: string): boolean;
 
-    // Delete file
-    await this.fileManagerService.delete(
-      {
-        id: file.id,
-        type: 'permanent', // Also deletes from storage
-      },
-      user,
-    );
-  }
-}
-```
+  /** Check if MIME type is dangerous (HTML, JS, SVG) */
+  static isDangerousTextType(mimeType: string): boolean;
 
-### URL Generation
+  /** Check if two MIME types are compatible */
+  static mimeTypesMatch(detected: string, declared: string): boolean;
 
-Files automatically get presigned URLs when needed:
+  /** Check if MIME type is in allowed list */
+  static isTypeAllowed(mimeType: string, allowedTypes: string[]): boolean;
 
-```typescript
-// FileManagerService.getFiles()
-async getFiles(
-  dtos: GetFilesRequestDto[],
-  protocol: string,
-  host: string,
-  user?: ILoggedUserInfo,
-): Promise<FilesResponseDto[]> {
-  const files = await this.repository.findBy({ id: In(ids) });
-  const now = Date.now();
+  /** Validate file content matches declared MIME type */
+  static validateFileContent(
+    buffer: Buffer,
+    declaredMimeType: string,
+    allowedTypes?: string[]
+  ): FileValidationResult;
 
-  return Promise.all(files.map(async (file) => {
-    // Check if URL needs regeneration
-    const needsNewUrl =
-      !file.url ||
-      (file.location === FileLocationEnum.AWS && now >= file.expiresAt) ||
-      (file.location === FileLocationEnum.AZURE && now >= file.expiresAt);
-
-    if (needsNewUrl && file.storageConfigId) {
-      // Generate presigned URL (1 hour expiry)
-      file.url = await this.uploadService.makeFileUrl(
-        file.key,
-        file.storageConfigId,
-        3600,  // seconds
-        user,
-      );
-      file.expiresAt = now + 3600 * 1000;
-      await this.repository.save(file);
-    }
+  /** Sanitize filename to prevent path traversal */
+  static sanitizeFilename(filename: string): string;
+}
 
-    return {
-      id: file.id,
-      name: file.name,
-      contentType: file.contentType,
-      url: file.url,
-    };
-  }));
+interface FileValidationResult {
+  valid: boolean;
+  detectedType?: string;
+  declaredType?: string;
+  message?: string;
 }
 ```
 
----
+### Supported Magic Bytes
 
-## Folder Management
+| Category | Formats |
+|----------|---------|
+| Images | JPEG, PNG, GIF, BMP, WebP, ICO |
+| Documents | PDF, ZIP (includes DOCX, XLSX, PPTX) |
+| Audio | MP3, OGG, FLAC |
+| Video | MP4, WebM, AVI |
+| Archives | GZIP, 7Z, RAR |
 
-### Folder Entity
+### Dangerous File Types
 
-```typescript
-@Entity('folders')
-export class Folder extends Identity {
-  @Column({ length: 100 })
-  name: string;
+These types bypass magic-bytes validation but require **explicit allowlisting**:
 
-  @Column({ nullable: true })
-  parentId: string;
+- `text/html`
+- `application/javascript`, `text/javascript`
+- `image/svg+xml`
+- `application/xhtml+xml`
 
-  @TreeParent()
-  parent: Folder;
+### Safe Text-Based Types
 
-  @TreeChildren()
-  children: Folder[];
+These are allowed without magic bytes:
 
-  @Column({ nullable: true })
-  companyId: string; // When company feature enabled
-}
-```
+- `text/plain`, `text/csv`, `text/markdown`
+- `application/json`, `application/xml`
+- `application/typescript`, `text/css`
 
-### FolderService
+### Filename Sanitization
 
 ```typescript
-import { FolderService } from '@flusys/nestjs-storage';
-
-@Injectable()
-export class MyService {
-  constructor(private readonly folderService: FolderService) {}
-
-  async manageFolders(user: ILoggedUserInfo) {
-    // Create root folder
-    const documents = await this.folderService.insert(
-      {
-        name: 'Documents',
-      },
-      user,
-    );
-
-    // Create subfolder
-    const reports = await this.folderService.insert(
-      {
-        name: 'Reports',
-        parentId: documents.id,
-      },
-      user,
-    );
-
-    // Get folder tree
-    const tree = await this.folderService.getTree(user);
-
-    // Get folder with children
-    const folder = await this.folderService.getById(documents.id, user);
-
-    // Delete folder
-    await this.folderService.delete(
-      {
-        id: reports.id,
-        type: 'soft',
-      },
-      user,
-    );
-  }
+static sanitizeFilename(filename: string): string {
+  return filename
+    .replace(/^.*[\\\/]/, '')           // Remove path components
+    .replace(/\0/g, '')                   // Remove null bytes
+    .replace(/\.{2,}/g, '.')              // Replace multiple dots
+    .replace(/[^a-zA-Z0-9._-]/g, '_')     // Remove special characters
+    .substring(0, 255);                   // Limit length
 }
 ```
 
 ---
 
-## Upload Service
-
-### UploadService
-
-```typescript
-import { UploadService } from '@flusys/nestjs-storage';
+## Image Compression
 
-@Injectable()
-export class MyService {
-  constructor(private readonly uploadService: UploadService) {}
-
-  async uploadFiles(files: Express.Multer.File[], user: ILoggedUserInfo) {
-    // Upload single file
-    const result = await this.uploadService.uploadSingleFile(
-      files[0],
-      {
-        folderPath: 'documents/reports',
-        storageConfigId: 'my-s3-config', // Optional - uses default if not provided
-      },
-      user,
-    );
-    // Returns: { name, key, size, contentType, url }
-
-    // Upload multiple files
-    const results = await this.uploadService.uploadMultipleFiles(
-      files,
-      {
-        folderPath: 'images',
-        storageConfigId: 'my-azure-config',
-      },
-      user,
-    );
+### ImageCompressor Utility
 
-    // Delete file
-    await this.uploadService.deleteSingleFile('documents/reports/report.pdf', 'my-s3-config', user);
+Uses Sharp for image processing:
 
-    // Delete multiple files
-    await this.uploadService.deleteMultipleFile(['file1.pdf', 'file2.pdf'], 'my-s3-config', user);
+```typescript
+export class ImageCompressor {
+  static async compress(
+    buffer: Buffer,
+    mimetype: string,
+    options?: CompressionOptions
+  ): Promise<{ buffer: Buffer; format: string }>;
+}
 
-    // Generate presigned URL
-    const url = await this.uploadService.makeFileUrl(
-      'documents/report.pdf',
-      'my-s3-config',
-      3600, // expiry in seconds
-      user,
-    );
-  }
+interface CompressionOptions {
+  maxWidth?: number;   // Default: 1280
+  maxHeight?: number;  // Default: 1280
+  quality?: number;    // Default: 85
+  format?: ImageFormat; // Default: 'original'
 }
 ```
 
-### File Validation
-
-```typescript
-// StorageConfigService
-validateFileSize(size: number): { valid: boolean; message?: string } {
-  const maxSize = this.config.maxFileSize || 10 * 1024 * 1024; // 10MB default
-  if (size > maxSize) {
-    return {
-      valid: false,
-      message: `File size exceeds maximum allowed size of ${maxSize / 1024 / 1024}MB`,
-    };
-  }
-  return { valid: true };
-}
+### Supported Output Formats
 
-validateFileType(mimeType: string): { valid: boolean; message?: string } {
-  const allowed = this.config.allowedFileTypes || ['*/*'];
+| Format | Quality Options |
+|--------|-----------------|
+| JPEG | MozJPEG optimization, 4:4:4 chroma |
+| PNG | Compression level 9, adaptive filtering, palette |
+| WebP | Smart subsample, effort 6, lossless at 100% |
+| AVIF | Effort 6, 4:4:4 chroma |
+| TIFF | LZW compression, pyramid |
+| GIF | 256 colors, effort 10, dithering |
+| JP2 | JPEG 2000, lossless at 100% |
 
-  const isAllowed = allowed.some(pattern => {
-    if (pattern === '*/*') return true;
-    if (pattern.endsWith('/*')) {
-      const type = pattern.replace('/*', '');
-      return mimeType.startsWith(type);
-    }
-    return mimeType === pattern;
-  });
+### Usage
 
-  if (!isAllowed) {
-    return {
-      valid: false,
-      message: `File type ${mimeType} is not allowed`,
-    };
-  }
-  return { valid: true };
-}
+```typescript
+// Automatic compression during upload
+await uploadService.uploadSingleFile(file, {
+  compress: true,
+  maxWidth: 1920,
+  maxHeight: 1080,
+  quality: 80,
+  format: 'webp',
+}, user);
 ```
 
 ---
 
 ## REST API Endpoints
 
+All storage endpoints are prefixed with `/storage`.
+
 ### Upload Endpoints
 
-| Endpoint                       | Method | Description                        |
-| ------------------------------ | ------ | ---------------------------------- |
-| `/upload/single-file`          | POST   | Upload single file                 |
-| `/upload/multiple-file`        | POST   | Upload multiple files (max 50)     |
-| `/upload/delete-single-file`   | POST   | Delete single file from storage    |
-| `/upload/delete-multiple-file` | POST   | Delete multiple files              |
-| `/upload/file/*filePath`       | GET    | Serve file by path (local storage) |
+| Endpoint | Method | Description | Permission |
+|----------|--------|-------------|------------|
+| `/storage/upload/single-file` | POST | Upload single file | `file.upload` |
+| `/storage/upload/multiple-file` | POST | Upload multiple files (max 50) | `file.upload` |
+| `/storage/upload/delete-single-file` | POST | Delete single file | `file.delete` |
+| `/storage/upload/delete-multiple-file` | POST | Delete multiple files | `file.delete` |
+| `/storage/upload/file/*filePath` | GET | Serve file (local storage) | Public |
 
 ### File Manager Endpoints
 
-| Endpoint                  | Method | Description                        |
-| ------------------------- | ------ | ---------------------------------- |
-| `/file-manager/insert`    | POST   | Create file record                 |
-| `/file-manager/get/:id`   | POST   | Get file by ID                     |
-| `/file-manager/get-all`   | POST   | Get files (paginated)              |
-| `/file-manager/update`    | POST   | Update file metadata               |
-| `/file-manager/delete`    | POST   | Delete file                        |
-| `/file-manager/get-files` | POST   | Get multiple files with valid URLs |
+| Endpoint | Method | Permission |
+|----------|--------|------------|
+| `/storage/file-manager/insert` | POST | `file.create` |
+| `/storage/file-manager/get/:id` | POST | `file.read` |
+| `/storage/file-manager/get-all` | POST | `file.read` |
+| `/storage/file-manager/update` | POST | `file.update` |
+| `/storage/file-manager/delete` | POST | `file.delete` |
+| `/storage/file-manager/get-files` | POST | JWT Auth |
 
 ### Folder Endpoints
 
-| Endpoint          | Method | Description             |
-| ----------------- | ------ | ----------------------- |
-| `/folder/insert`  | POST   | Create folder           |
-| `/folder/get/:id` | POST   | Get folder by ID        |
-| `/folder/get-all` | POST   | Get folders (paginated) |
-| `/folder/tree`    | GET    | Get folder tree         |
-| `/folder/update`  | POST   | Update folder           |
-| `/folder/delete`  | POST   | Delete folder           |
+| Endpoint | Method | Permission |
+|----------|--------|------------|
+| `/storage/folder/insert` | POST | `folder.create` |
+| `/storage/folder/get/:id` | POST | `folder.read` |
+| `/storage/folder/get-all` | POST | `folder.read` |
+| `/storage/folder/update` | POST | `folder.update` |
+| `/storage/folder/delete` | POST | `folder.delete` |
 
 ### Storage Config Endpoints
 
-| Endpoint                  | Method | Description                  |
-| ------------------------- | ------ | ---------------------------- |
-| `/storage-config/insert`  | POST   | Create storage configuration |
-| `/storage-config/get/:id` | POST   | Get config by ID             |
-| `/storage-config/get-all` | POST   | Get configs (paginated)      |
-| `/storage-config/update`  | POST   | Update configuration         |
-| `/storage-config/delete`  | POST   | Delete configuration         |
+| Endpoint | Method | Permission |
+|----------|--------|------------|
+| `/storage/storage-config/insert` | POST | `storageConfig.create` |
+| `/storage/storage-config/get/:id` | POST | `storageConfig.read` |
+| `/storage/storage-config/get-all` | POST | `storageConfig.read` |
+| `/storage/storage-config/update` | POST | `storageConfig.update` |
+| `/storage/storage-config/delete` | POST | `storageConfig.delete` |
 
 ### Upload Request Example
 
 ```bash
 # Upload single file
-curl -X POST http://localhost:3000/upload/single-file \
+curl -X POST http://localhost:3000/storage/upload/single-file \
   -H "Authorization: Bearer <token>" \
   -H "Content-Type: multipart/form-data" \
   -F "file=@document.pdf" \
-  -F "folderPath=documents"
+  -F "folderPath=documents" \
+  -F "compress=true"
 
 # Response:
 {
-  "name": "document.pdf",
-  "key": "documents/abc123-document.pdf",
-  "size": 102.4,
-  "contentType": "application/pdf"
+  "success": true,
+  "message": "File uploaded successfully",
+  "data": {
+    "name": "abc123-document.pdf",
+    "key": "uploads/documents/abc123-document.pdf",
+    "size": 102.4,
+    "contentType": "application/pdf",
+    "location": "local",
+    "storageConfigId": "123e4567-e89b-12d3-a456-426614174000"
+  }
 }
 ```
 
 ---
 
-## DataSource Provider Pattern
-
-### Overview
+## File Serve Middleware
 
-All Storage services now use the **DataSource Provider pattern** for dynamic entity loading. This ensures correct entity selection based on runtime configuration (`enableCompanyFeature`) and supports both single-database and multi-tenant modes.
+The `FileServeMiddleware` handles file serving for local storage with multiple fallback strategies:
 
-### Architecture
-
-```
-┌─────────────────────────────┐
-│   Configuration             │
-│   enableCompanyFeature      │
-└──────────┬──────────────────┘
-           │
-           ▼
-┌──────────────────────────────┐
-│  StorageDataSourceProvider   │
-│  (REQUEST-scoped)            │
-│  • Extends MultiTenant...    │
-│  • Dynamic entity loading    │
-└──────────┬───────────────────┘
-           │
-           ▼
-┌─────────────────────────────────┐
-│  Services (REQUEST-scoped)      │
-│  • FileManagerService           │
-│  • FolderService                │
-│  • StorageProviderConfigService │
-└─────────────────────────────────┘
-```
-
-### Key Changes
-
-#### Before (Static Entity Injection)
 ```typescript
 @Injectable()
-export class FileManagerService {
-  constructor(
-    @InjectRepository(FileManager) repository: Repository<FileManagerBase>,
-  ) {
-    // Static injection - doesn't work with multi-tenant
-  }
-}
-```
-
-#### After (Dynamic Entity Loading)
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class FileManagerService {
-  constructor(
-    private readonly storageConfig: StorageConfigService,
-    private readonly dataSourceProvider: StorageDataSourceProvider,
-  ) {
-    super('file_manager', null as any, ...);
+export class FileServeMiddleware implements NestMiddleware {
+  async use(req: Request, res: Response, next: NextFunction) {
+    const normalizedPath = this.extractFilePath(req);
+    const fullPath = await this.resolveFilePath(normalizedPath);
+    // Stream file with proper headers
   }
 
-  async onModuleInit() {
-    // Get repository dynamically based on configuration
-    const enableCompanyFeature = this.storageConfig.isCompanyFeatureEnabled();
-    const entity = enableCompanyFeature ? FileManagerWithCompany : FileManager;
-    this.repository = await this.dataSourceProvider.getRepository(entity);
+  private async resolveFilePath(normalizedPath: string): Promise<string> {
+    // Strategy 1: Path relative to CWD (new format)
+    // Strategy 2: basePath + remaining path
+    // Strategy 3: Old format - prepend basePath
   }
 }
 ```
 
-### Benefits
+### MIME Types for Inline Display
 
-1. **Dynamic Entity Selection**: Entities are chosen at runtime based on `enableCompanyFeature`
-2. **Multi-Tenant Support**: Works correctly in both single and multi-tenant modes
-3. **No TypeORM Conflicts**: Avoids "No metadata for entity" errors
-4. **Consistent Pattern**: All services follow the same approach
-5. **REQUEST-scoped**: Ensures correct entity per request in multi-tenant scenarios
+```typescript
+const VIEWABLE_TYPE_PREFIXES = [
+  'image/',
+  'video/',
+  'audio/',
+  'text/',
+  'application/pdf',
+  'application/json',
+  'application/xml',
+];
+```
 
-### Affected Services
+### Response Headers
 
-All Storage services now use this pattern:
+```typescript
+res.set({
+  'Content-Type': mimeType,
+  'Content-Length': size,
+  'Content-Disposition': isViewable ? 'inline' : 'attachment',
+  'Cache-Control': 'public, max-age=3600',
+  'Accept-Ranges': 'bytes',
+  'Cross-Origin-Resource-Policy': 'cross-origin',
+  'Access-Control-Allow-Origin': '*',
+  'X-Content-Type-Options': 'nosniff',
+});
+```
 
-- **FileManagerService** - Uses `FileManager` or `FileManagerWithCompany`
-- **FolderService** - Uses `Folder` or `FolderWithCompany`
-- **StorageProviderConfigService** - Uses `StorageConfig` or `StorageConfigWithCompany`
+---
 
-### Module Configuration
+## DataSource Provider Pattern
 
-Repository providers have been removed from `StorageModule`:
+### StorageDataSourceProvider
 
 ```typescript
-// OLD: Static repository providers (removed)
-getRepositoryProviders() {
-  return entities.map(entity => ({
-    provide: getRepositoryToken(entity),
-    useFactory: ...
-  }));
-}
+@Injectable({ scope: Scope.REQUEST })
+export class StorageDataSourceProvider extends MultiTenantDataSourceService {
+  // Storage-specific static cache (isolated from Auth/IAM)
+  protected static override readonly tenantConnections = new Map<string, DataSource>();
+  protected static override singleDataSource: DataSource | null = null;
 
-// NEW: Services get repositories dynamically at runtime
-providers: [
-  StorageConfigService,
-  StorageDataSourceProvider,
-  FileManagerService,
-  FolderService,
-  StorageProviderConfigService,
-  ...
-]
+  /** Get storage entities based on company feature flag */
+  async getStorageEntities(enableCompanyFeature?: boolean): Promise<any[]>;
+
+  /** Get company feature for current tenant */
+  getEnableCompanyFeatureForCurrentTenant(): boolean;
+}
 ```
 
-### Isolated DataSource Cache
+### Dynamic Entity Selection
 
-Each module (Auth, IAM, Storage) maintains isolated datasource caches by overriding both static properties AND methods (`getSingleDataSource`, `getOrCreateTenantConnection`) in `StorageDataSourceProvider`. This prevents "No metadata for entity" errors regardless of module initialization order.
+Services select entities at runtime:
 
-**Key Points:**
-- Isolated cache per module - no shared state between Auth/IAM/Storage
-- Must override methods that access static properties, not just the properties
-- Use explicit subclass reference (e.g., `StorageDataSourceProvider.singleDataSource`)
-- Required when module has entity variants based on `enableCompanyFeature`
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class FileManagerService extends RequestScopedApiService<...> {
+  protected resolveEntity(): EntityTarget<FileManagerBase> {
+    return this.storageConfig.isCompanyFeatureEnabled()
+      ? FileManagerWithCompany
+      : FileManager;
+  }
 
-See [storage-datasource.provider.ts](../projects/nestjs-storage/src/services/storage-datasource.provider.ts) for implementation.
+  protected getDataSourceProvider() {
+    return this.dataSourceProvider;
+  }
+}
+```
 
 ---
 
 ## Multi-Tenant Support
 
-### Company Isolation
+### Company Filtering
 
 When company feature is enabled:
 
-1. **Storage Configs** - Each company has its own storage configurations
-2. **Files** - Files are tagged with companyId
-3. **Folders** - Folders are company-scoped
-4. **Access Control** - Users can only access their company's files
+```typescript
+protected override async getExtraManipulateQuery(query, filterDto, user) {
+  const result = await super.getExtraManipulateQuery(query, filterDto, user);
+
+  applyCompanyFilter(query, {
+    isCompanyFeatureEnabled: this.storageConfig.isCompanyFeatureEnabled(),
+    entityAlias: 'file_manager',
+  }, user);
 
-### Company Filtering
+  await this.applyPrivateFileFilter(query, user);
+
+  return result;
+}
+```
+
+### Private File Access
 
 ```typescript
-// FileManagerService
-override async getExtraManipulateQuery(
-  query: SelectQueryBuilder<FileManager>,
-  dto: FilterAndPaginationDto,
-  user: ILoggedUserInfo,
-) {
-  // Filter by company
-  if (this.storageConfig.isCompanyFeatureEnabled() && user.companyId) {
-    query.andWhere(`file_manager.companyId = :companyId`, {
-      companyId: user.companyId,
-    });
+private async applyPrivateFileFilter(query, user): Promise<void> {
+  if (!user) {
+    query.andWhere('file_manager.isPrivate = :isPrivate', { isPrivate: false });
+    return;
   }
 
-  // Filter private files by permission
-  const userActions = await this.cacheManager.get(
-    `user_action_permission_${user.id}_${user.companyId}`
-  );
+  const cacheKey = `user_action_permission_${user.id}_${user.companyId}`;
+  const actions = await this.cacheManager.get(cacheKey);
+  const canViewPrivate = actions?.some((a) => a.url === 'storage.file.viewPrivate');
 
-  if (!userActions?.includes('storage.file.viewPrivate')) {
+  if (!canViewPrivate) {
     query.andWhere('file_manager.isPrivate = :isPrivate', { isPrivate: false });
   }
-
-  return { query, isRaw: false };
 }
 ```
 
-### Company-Scoped Storage Config
+### Storage Config Validation
 
 ```typescript
-// StorageProviderConfigService
-async getDefaultConfig(user?: ILoggedUserInfo): Promise<StorageConfigBase | null> {
-  const where: any = {};
+private async getStorageProviderWithConfig(storageConfigId?: string, user?: ILoggedUserInfo) {
+  let storageConfig: StorageConfigBase;
+
+  if (storageConfigId) {
+    const config = await this.storageProviderConfigService.findByIdDirect(storageConfigId);
+    if (!config) throw new NotFoundException('Storage configuration not found');
+
+    // Validate company ownership
+    validateCompanyOwnership(
+      config,
+      user,
+      this.storageConfigService.isCompanyFeatureEnabled(),
+      'Storage configuration',
+    );
 
-  // Filter by company
-  if (this.storageConfig.isCompanyFeatureEnabled() && user?.companyId) {
-    where.companyId = user.companyId;
+    storageConfig = config;
+  } else {
+    const defaultConfig = await this.storageProviderConfigService.getDefaultConfig(user);
+    if (!defaultConfig) {
+      throw new NotFoundException('No default storage configuration found');
+    }
+    storageConfig = defaultConfig;
   }
 
-  return await this.repository.findOne({
-    where: { ...where, name: 'default' },
-  });
+  return {
+    provider: await this.createProviderFromConfig(storageConfig),
+    location: storageConfig.storage,
+    configId: storageConfig.id,
+  };
 }
 ```
 
-### Storage Config Validation
+---
+
+## Swagger Configuration
+
+### Using storageSwaggerConfig
 
 ```typescript
-// UploadService.getStorageProvider()
-private async getStorageProvider(
-  storageConfigId?: string,
-  user?: ILoggedUserInfo,
-): Promise<IStorageProvider> {
-  const config = await this.storageProviderConfigService.findById(storageConfigId, user);
-
-  // Validate company ownership
-  if (this.storageConfigService.isCompanyFeatureEnabled() && user?.companyId) {
-    if (config.companyId && config.companyId !== user.companyId) {
-      throw new BadRequestException('Storage configuration belongs to another company');
-    }
-  }
+import { storageSwaggerConfig } from '@flusys/nestjs-storage/docs';
 
-  return await this.storageFactory.createProvider({
-    provider: config.storage,
-    config: config.config,
-  });
-}
+// In your main.ts or app module
+const swaggerOptions = storageSwaggerConfig({
+  enableCompanyFeature: true,
+  databaseMode: 'single',
+});
+
+// Returns:
+// {
+//   title: 'Storage API',
+//   description: '... dynamic description based on config ...',
+//   version: '1.0',
+//   path: 'api/docs/storage',
+//   bearerAuth: true,
+//   excludeSchemaProperties: enableCompanyFeature ? undefined : COMPANY_SCHEMA_EXCLUSIONS,
+// }
 ```
 
 ---
@@ -1226,20 +1313,15 @@ private async getStorageProvider(
 // ✅ Create meaningful config names
 await storageConfigService.insert({
   name: 'default',       // Primary storage
-  storage: FileLocationEnum.AWS,
-  config: { bucket: 'main-files', ... }
+  storage: 'aws',
+  config: { bucket: 'main-files', ... },
+  isDefault: true,
 }, user);
 
 await storageConfigService.insert({
   name: 'media',         // Images/videos
-  storage: FileLocationEnum.AWS,
-  config: { bucket: 'media-files', ... }
-}, user);
-
-await storageConfigService.insert({
-  name: 'backups',       // Backup storage
-  storage: FileLocationEnum.SFTP,
-  config: { host: 'backup.server.com', ... }
+  storage: 'aws',
+  config: { bucket: 'media-files', ... },
 }, user);
 
 // ❌ Don't use generic names
@@ -1249,76 +1331,34 @@ await storageConfigService.insert({
 });
 ```
 
-### 2. Organize Files in Folders
-
-```typescript
-// ✅ Create logical folder structure
-const docs = await folderService.insert({ name: 'Documents' }, user);
-const reports = await folderService.insert({ name: 'Reports', parentId: docs.id }, user);
-const invoices = await folderService.insert({ name: 'Invoices', parentId: docs.id }, user);
-
-// Upload with folder association
-await uploadService.uploadSingleFile(
-  file,
-  {
-    folderPath: 'Documents/Reports',
-    // Files will be stored in organized structure
-  },
-  user,
-);
-
-// ❌ Don't dump all files in root
-```
-
-### 3. Set Appropriate File Validation
+### 2. Configure File Validation
 
 ```typescript
-// ✅ Configure validation per use case
+// ✅ Restrict file types in production
 StorageModule.forRoot({
   config: {
     maxFileSize: 10 * 1024 * 1024, // 10MB
     allowedFileTypes: [
       'image/jpeg',
       'image/png',
-      'image/gif',
+      'image/webp',
       'application/pdf',
-      'text/plain',
-      'text/csv',
     ],
   },
 });
 
-// ❌ Don't allow all file types in production
+// ❌ Don't allow all file types
 allowedFileTypes: ['*/*'];
 ```
 
-### 4. Use @CurrentUser Decorator
-
-```typescript
-// ✅ Use decorator for user context
-@Post('upload')
-async upload(
-  @UploadedFile() file: Express.Multer.File,
-  @CurrentUser() user: ILoggedUserInfo,
-) {
-  return this.uploadService.uploadSingleFile(file, {}, user);
-}
-
-// ❌ Don't extract user manually
-@Post('upload')
-async upload(@Req() req: Request) {
-  const user = req.user; // Not type-safe
-}
-```
-
-### 5. Handle Presigned URL Expiration
+### 3. Use Presigned URLs Properly
 
 ```typescript
 // ✅ Always use getFiles() for URL access
 const files = await fileManagerService.getFiles(
   [{ id: 'file-1' }, { id: 'file-2' }],
-  protocol,
-  host,
+  req.protocol,
+  req.get('host'),
   user,
 );
 // URLs are automatically refreshed if expired
@@ -1328,26 +1368,33 @@ const file = await fileManagerService.getById(id, user);
 return file.url; // May be expired!
 ```
 
-### 6. Clean Up on File Deletion
+### 4. Handle File Deletion Properly
 
 ```typescript
 // ✅ Use permanent delete to remove from storage
-await fileManagerService.delete(
-  {
-    id: fileId,
-    type: 'permanent', // Deletes file from storage provider
-  },
-  user,
-);
+await fileManagerService.delete({
+  id: fileId,
+  type: 'permanent', // Deletes from storage provider
+}, user);
 
-// Soft delete keeps file in storage (useful for recovery)
-await fileManagerService.delete(
-  {
-    id: fileId,
-    type: 'soft', // Only marks as deleted in database
-  },
-  user,
-);
+// Soft delete keeps file in storage (for recovery)
+await fileManagerService.delete({
+  id: fileId,
+  type: 'soft', // Only marks as deleted in DB
+}, user);
+```
+
+### 5. Optimize Image Uploads
+
+```typescript
+// ✅ Enable compression for images
+await uploadService.uploadSingleFile(file, {
+  compress: true,
+  maxWidth: 1920,
+  maxHeight: 1080,
+  quality: 80,
+  format: 'webp', // Best compression/quality ratio
+}, user);
 ```
 
 ---
@@ -1366,6 +1413,7 @@ import {
   FileManagerService,
   FolderService,
   StorageProviderConfigService,
+  StorageConfigService,
   StorageDataSourceProvider,
 } from '@flusys/nestjs-storage/services';
 
@@ -1380,19 +1428,29 @@ import {
   StorageConfig,
   StorageConfigBase,
   StorageConfigWithCompany,
+  StorageCoreEntities,
+  StorageCompanyEntities,
+  getStorageEntitiesByConfig,
 } from '@flusys/nestjs-storage/entities';
 
 // DTOs
 import {
   UploadOptionsDto,
+  DeleteSingleFileDto,
+  DeleteMultipleFileDto,
+  FileUploadResponsePayloadDto,
   CreateFileManagerDto,
   UpdateFileManagerDto,
+  FileManagerResponseDto,
   GetFilesRequestDto,
   FilesResponseDto,
   CreateFolderDto,
   UpdateFolderDto,
+  FolderResponseDto,
   CreateStorageConfigDto,
   UpdateStorageConfigDto,
+  StorageConfigResponseDto,
+  ImageFormat,
 } from '@flusys/nestjs-storage/dtos';
 
 // Interfaces
@@ -1406,6 +1464,7 @@ import {
   IUploadedFileInfo,
   StorageModuleOptions,
   StorageModuleAsyncOptions,
+  StorageOptionsFactory,
 } from '@flusys/nestjs-storage/interfaces';
 
 // Enums
@@ -1418,8 +1477,21 @@ import {
   LocalProvider,
 } from '@flusys/nestjs-storage/providers';
 
-// Config
-import { StorageConfigService } from '@flusys/nestjs-storage/config';
+// Utils
+import { FileValidator, ImageCompressor } from '@flusys/nestjs-storage/utils';
+
+// Docs
+import { storageSwaggerConfig } from '@flusys/nestjs-storage/docs';
+
+// Middleware
+import { FileServeMiddleware } from '@flusys/nestjs-storage/middlewares';
+
+// Constants
+import {
+  STORAGE_MODULE_OPTIONS,
+  DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_ALLOWED_FILE_TYPES,
+} from '@flusys/nestjs-storage/config';
 ```
 
 ---
@@ -1429,15 +1501,17 @@ import { StorageConfigService } from '@flusys/nestjs-storage/config';
 The `@flusys/nestjs-storage` package provides:
 
 - **Multiple Providers** - Local, AWS S3, Azure Blob, SFTP
-- **Connection Reuse** - Efficient provider instance caching
-- **File Validation** - Size and type validation
-- **Folder Hierarchy** - Nested folder structure
-- **Presigned URLs** - Secure time-limited access
+- **Connection Reuse** - SHA256-based provider caching
+- **Security** - Magic bytes validation, path traversal prevention, filename sanitization
+- **Image Compression** - Sharp-based optimization with multiple formats
+- **File Validation** - Size, type, and content validation
+- **Folder Organization** - Simple folder-based file organization
+- **Presigned URLs** - Automatic URL refresh for cloud providers
 - **Multi-Tenant** - Company/branch file isolation
 - **Per-Company Storage** - Different providers per company
-- **REST API** - Complete CRUD endpoints
-- **Auto URL Refresh** - Automatic presigned URL regeneration
+- **REST API** - Complete CRUD endpoints with POST-only RPC
+- **Middleware** - File serving with multiple fallback strategies
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25