@flusys/nestjs-storage 4.0.1 → 4.1.0

package/README.md

@@ -1,176 +1,106 @@
-# Storage Package Guide
+# @flusys/nestjs-storage
 
-> **Package:** `@flusys/nestjs-storage`
-> **Version:** 4.0.1
-> **Type:** File storage system with pluggable providers and multi-tenant support
+> Multi-provider file storage for NestJS — Local disk, AWS S3, Azure Blob, and SFTP with folder management, image compression, presigned URL generation, and multi-tenant support.
 
-This comprehensive guide covers the storage package - flexible file storage with multiple provider support.
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-storage.svg)](https://www.npmjs.com/package/@flusys/nestjs-storage)
+[![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)
+- [Features](#features)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Constants](#constants)
-- [Package Architecture](#package-architecture)
-- [Module Setup](#module-setup)
-- [Entities](#entities)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+  - [forRoot (Sync)](#forroot-sync)
+  - [forRootAsync (Factory)](#forrootasync-factory)
+- [Configuration Reference](#configuration-reference)
+- [Feature Toggles](#feature-toggles)
 - [Storage Providers](#storage-providers)
-- [Storage Configuration](#storage-configuration)
-- [File Manager](#file-manager)
-- [Folder Management](#folder-management)
-- [Upload Service](#upload-service)
-- [File Validation & Security](#file-validation--security)
+  - [Local](#local-provider)
+  - [AWS S3](#aws-s3)
+  - [Azure Blob Storage](#azure-blob-storage)
+  - [SFTP](#sftp)
+  - [Custom Provider](#custom-provider)
+- [API Endpoints](#api-endpoints)
+- [Entities](#entities)
+- [File Serving (Local)](#file-serving-local)
 - [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)
+- [File Validation](#file-validation)
+- [Exported Services](#exported-services)
+- [Programmatic Usage](#programmatic-usage)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## Overview
 
-`@flusys/nestjs-storage` provides a comprehensive file storage system:
+`@flusys/nestjs-storage` provides a unified API for managing files across multiple storage backends. Provider configurations are stored in the database — switch providers without code changes. Cloud providers (S3, Azure, SFTP) are dynamically imported so you only pay the install cost for what you use.
 
-- **Multiple Providers** - Local, AWS S3, Azure Blob, SFTP
-- **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
+---
 
-### Package Hierarchy
+## Features
 
-```
-@flusys/nestjs-core     ← Foundation
-     ↓
-@flusys/nestjs-shared   ← Shared utilities
-     ↓
-@flusys/nestjs-auth     ← User/Company management
-     ↓
-@flusys/nestjs-storage  ← File storage (THIS PACKAGE)
-```
+- **4 storage backends** — Local disk, AWS S3, Azure Blob Storage, SFTP
+- **Pluggable providers** — Register custom providers via `StorageProviderRegistry`
+- **Folder hierarchy** — Organize files in folders with parent-child relationships
+- **Image compression** — Automatic optimization via `sharp` (JPEG, PNG, WebP, AVIF, TIFF, GIF)
+- **Presigned URLs** — Time-limited signed URLs for S3 and Azure with TTL caching
+- **File validation** — Magic-byte validation prevents file-type spoofing
+- **Path traversal protection** — All file paths sanitized before disk access
+- **Company scoping** — Optional `companyId` filtering on all queries
+- **Multi-tenant** — Per-tenant DataSource isolation
 
 ---
 
-## Installation
-
-```bash
-npm install @flusys/nestjs-storage @flusys/nestjs-shared @flusys/nestjs-core
-
-# Required dependencies
-npm install sharp mime-types uuid
+## Compatibility
 
-# Optional: Install provider-specific packages
-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
-```
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@flusys/nestjs-shared` | `^4.0.0` |
+| `sharp` | `^0.33.0` |
+| `uuid` | `^9.0.0` |
+| `mime-types` | `^2.0.0` |
+| `@aws-sdk/client-s3` | `^3.0.0` *(optional)* |
+| `@azure/storage-blob` | `^12.0.0` *(optional)* |
+| `ssh2-sftp-client` | `^9.0.0` *(optional)* |
+| Node.js | `>= 18.x` |
 
 ---
 
-## Constants
-
-```typescript
-// Injection Token
-export const STORAGE_MODULE_OPTIONS = 'STORAGE_MODULE_OPTIONS';
+## Installation
 
-// Default Configuration
-export const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024; // 100MB
-export const DEFAULT_ALLOWED_FILE_TYPES = ['*/*']; // All file types
+```bash
+npm install @flusys/nestjs-storage @flusys/nestjs-shared @flusys/nestjs-core sharp uuid mime-types
 ```
 
----
+Optional cloud provider SDKs (install only what you need):
 
-## Package Architecture
+```bash
+# AWS S3
+npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
 
-```
-nestjs-storage/
-├── src/
-│   ├── modules/
-│   │   └── storage.module.ts         # Main module with provider registration
-│   │
-│   ├── config/
-│   │   ├── storage.constants.ts      # Module constants
-│   │   └── index.ts
-│   │
-│   ├── providers/
-│   │   ├── 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/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        # /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.entity.ts        # FileManager base
-│   │   ├── file-manager-with-company.entity.ts
-│   │   ├── folder.entity.ts              # Folder base
-│   │   ├── folder-with-company.entity.ts
-│   │   ├── storage-config.entity.ts      # StorageConfig base
-│   │   ├── storage-config-with-company.entity.ts
-│   │   └── index.ts
-│   │
-│   ├── dtos/
-│   │   ├── 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/
-│   │   ├── file-manager.interface.ts
-│   │   ├── folder.interface.ts
-│   │   ├── storage-config.interface.ts
-│   │   ├── storage-module-options.interface.ts
-│   │   ├── storage-provider.interface.ts
-│   │   └── index.ts
-│   │
-│   ├── enums/
-│   │   ├── 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/
-│       ├── file-validator.util.ts    # Magic bytes validation
-│       ├── image-compressor.util.ts  # Sharp-based compression
-│       └── index.ts
+# Azure Blob Storage
+npm install @azure/storage-blob
+
+# SFTP
+npm install ssh2-sftp-client
+npm install -D @types/ssh2-sftp-client
 ```
 
 ---
 
-## Module Setup
+## Quick Start
 
-### Basic Setup
+### Local Storage (Minimal Setup)
 
 ```typescript
 import { Module } from '@nestjs/common';
@@ -184,21 +114,20 @@ import { StorageModule } from '@flusys/nestjs-storage';
       bootstrapAppConfig: {
         databaseMode: 'single',
         enableCompanyFeature: false,
-        permissionMode: 'RBAC',
       },
       config: {
         defaultDatabaseConfig: {
           type: 'postgres',
-          host: 'localhost',
-          port: 5432,
-          username: 'postgres',
-          password: 'password',
-          database: 'myapp',
+          host: process.env.DB_HOST,
+          port: Number(process.env.DB_PORT ?? 5432),
+          username: process.env.DB_USER,
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME,
         },
-        maxFileSize: 10 * 1024 * 1024, // 10MB
-        allowedFileTypes: ['image/*', 'application/pdf', 'text/*'],
+        maxFileSize: 10 * 1024 * 1024,             // 10 MB
+        allowedFileTypes: ['image/*', 'application/pdf'],
         localStoragePath: './uploads',
-        appUrl: process.env.APP_URL || 'http://localhost:3000',
+        appUrl: process.env.APP_URL ?? 'http://localhost:2002',
       },
     }),
   ],
@@ -206,1312 +135,443 @@ import { StorageModule } from '@flusys/nestjs-storage';
 export class AppModule {}
 ```
 
-### With Company Feature
+### Register Local File Serving Middleware
+
+```typescript
+import { FileServeMiddleware } from '@flusys/nestjs-storage';
+
+@Module({})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // Serves GET /storage/upload/file/* from local disk
+    consumer.apply(FileServeMiddleware).forRoutes('storage/upload/file');
+  }
+}
+```
+
+---
+
+## Module Registration
+
+### forRoot (Sync)
 
 ```typescript
 StorageModule.forRoot({
-  global: true,
-  includeController: true,
+  global?: boolean;
+  includeController?: boolean;
   bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: true,
-    permissionMode: 'FULL',
-  },
+    databaseMode: 'single' | 'multi-tenant';
+    enableCompanyFeature: boolean;
+  };
   config: {
-    defaultDatabaseConfig: { /* ... */ },
-    maxFileSize: 10 * 1024 * 1024,
-    allowedFileTypes: ['image/*', 'application/pdf'],
-    localStoragePath: './uploads',
-    appUrl: process.env.APP_URL,
-  },
-});
+    defaultDatabaseConfig: IDatabaseConfig;
+    maxFileSize?: number;          // bytes, default: 100MB
+    allowedFileTypes?: string[];   // MIME types/patterns, default: ['*/*']
+    localStoragePath?: string;     // default: './uploads'
+    appUrl?: string;               // Base URL for local file links
+  };
+})
 ```
 
-### Async Configuration
+### forRootAsync (Factory)
 
 ```typescript
+import { ConfigService } from '@nestjs/config';
+
 StorageModule.forRootAsync({
   global: true,
   includeController: true,
   bootstrapAppConfig: {
     databaseMode: 'single',
     enableCompanyFeature: true,
-    permissionMode: 'FULL',
   },
   imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
-    defaultDatabaseConfig: configService.getDatabaseConfig(),
-    maxFileSize: configService.get('MAX_FILE_SIZE'),
-    allowedFileTypes: configService.get('ALLOWED_FILE_TYPES'),
-    localStoragePath: configService.get('UPLOAD_PATH'),
+  useFactory: (configService: ConfigService) => ({
+    defaultDatabaseConfig: {
+      type: 'postgres',
+      host: configService.get('DB_HOST'),
+      port: configService.get<number>('DB_PORT'),
+      username: configService.get('DB_USER'),
+      password: configService.get('DB_PASSWORD'),
+      database: configService.get('DB_NAME'),
+    },
+    maxFileSize: configService.get<number>('MAX_FILE_SIZE', 10 * 1024 * 1024),
     appUrl: configService.get('APP_URL'),
+    localStoragePath: configService.get('UPLOAD_PATH', './uploads'),
   }),
   inject: [ConfigService],
-});
+})
 ```
 
-### Configuration Options
+---
+
+## Configuration Reference
 
 ```typescript
 interface IStorageModuleConfig extends IDataSourceServiceOptions {
   /** Maximum file size in bytes (default: 100MB) */
   maxFileSize?: number;
-  /** Allowed MIME types or patterns (default: ['*/*']) */
+
+  /** Allowed MIME types. Use '*/*' for all. (default: ['*/*']) */
   allowedFileTypes?: string[];
-  /** Default storage provider (optional) */
-  defaultStorageProvider?: string;
-  /** Local storage path (default: './uploads') */
+
+  /** Local storage base directory (default: './uploads') */
   localStoragePath?: string;
-  /** Application base URL for file URLs */
-  appUrl?: string;
-}
 
-interface StorageModuleOptions extends IDynamicModuleConfig {
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: IStorageModuleConfig;
+  /** Application base URL for building file URLs (local provider) */
+  appUrl?: string;
 }
 ```
 
-### Swagger Schema Behavior
+---
 
-When `enableCompanyFeature: false`, the following properties are automatically hidden from Swagger:
+## Feature Toggles
 
-| DTO                        | Hidden Fields |
-| -------------------------- | ------------- |
-| `FileManagerResponseDto`   | `companyId`   |
-| `FolderResponseDto`        | `companyId`   |
-| `StorageConfigResponseDto` | `companyId`   |
+| Feature | Config | Default | Effect |
+|---------|--------|---------|--------|
+| Company scoping | `enableCompanyFeature: true` | `false` | Uses `*WithCompany` entity variants; filters all queries by `companyId` |
+| Local file serving | Built-in | Always on | Register `FileServeMiddleware` to serve uploaded files from disk |
+| Cloud providers | Install SDK + register | Disabled | S3/Azure/SFTP only activate after provider registration |
 
 ---
 
-## Entities
+## Storage Providers
 
-### FileLocationEnum
+### Local Provider
 
-```typescript
-export enum FileLocationEnum {
-  AWS = 'aws',
-  AZURE = 'azure',
-  SFTP = 'sftp',
-  LOCAL = 'local',
-}
-```
+Built-in, no extra SDK required. Files stored on the server filesystem.
 
-### Entity Groups
+Create a `StorageConfig` record:
 
-```typescript
-// Core entities (no company feature)
-export const StorageCoreEntities = [FileManager, Folder, StorageConfig];
-
-// Company-specific entities
-export const StorageCompanyEntities = [
-  FileManagerWithCompany,
-  FolderWithCompany,
-  StorageConfigWithCompany,
-];
-
-// Helper function
-export function getStorageEntitiesByConfig(enableCompanyFeature: boolean): any[] {
-  return enableCompanyFeature ? StorageCompanyEntities : StorageCoreEntities;
+```json
+POST /storage/storage-config/insert
+{
+  "name": "Local Storage",
+  "storage": "local",
+  "config": {},
+  "isActive": true,
+  "isDefault": true
 }
-
-// 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
+File URLs format: `{appUrl}/storage/upload/file/{path}`
 
-  @Column({ type: 'varchar', length: 255 })
-  contentType!: string; // MIME type
+### AWS S3
 
-  @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;
-}
+**1. Install the SDK:**
+```bash
+npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
 ```
 
-### Folder Entity
-
+**2. Register the provider at startup (before module init):**
 ```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[];
-}
+import { StorageProviderRegistry, FileLocationEnum } from '@flusys/nestjs-storage';
+import { S3Provider } from '@flusys/nestjs-storage/providers/s3-provider.optional';
 
-// With company feature
-@Entity({ name: 'folder' })
-export class FolderWithCompany extends Folder {
-  @Column({ type: 'uuid', nullable: true })
-  companyId!: string | null;
-}
+StorageProviderRegistry.register(FileLocationEnum.AWS, S3Provider);
 ```
 
-### 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;
+**3. Create a StorageConfig:**
+```json
+POST /storage/storage-config/insert
+{
+  "name": "Production S3",
+  "storage": "aws",
+  "config": {
+    "region": "us-east-1",
+    "bucket": "my-app-files",
+    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
+    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+  },
+  "isDefault": true
 }
 ```
 
----
-
-## Storage Providers
-
-### 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>;
-}
+### Azure Blob Storage
 
-interface IUploadedFileInfo {
-  key: string;
-  contentType: string;
-  size: number;
-  name: string;
-  location?: string;
-  storageConfigId?: string;
-}
+**1. Install the SDK:**
+```bash
+npm install @azure/storage-blob
 ```
 
-### Provider Registration
-
-Providers are automatically registered when the module loads:
-
+**2. Register:**
 ```typescript
-// 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)`);
-  }
-}
+import { AzureProvider } from '@flusys/nestjs-storage/providers/azure-provider.optional';
+StorageProviderRegistry.register(FileLocationEnum.AZURE, AzureProvider);
 ```
 
-### Local Provider
-
-```typescript
-// Built-in, no external dependencies required
-// Uses Node.js fs module
-
-// Configuration:
+**3. Create a StorageConfig:**
+```json
+POST /storage/storage-config/insert
 {
-  storage: 'local',
-  config: {
-    basePath: './uploads',  // Base directory
-    baseUrl: 'http://localhost:3000'  // Optional, for URL generation
-  }
+  "name": "Azure Blob",
+  "storage": "azure",
+  "config": {
+    "connectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net",
+    "containerName": "my-files"
+  },
+  "isDefault": true
 }
 ```
 
-**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/lib-storage @aws-sdk/s3-request-presigner
+### SFTP
 
-// Configuration:
-{
-  storage: 'aws',
-  config: {
-    region: 'us-east-1',
-    bucket: 'my-bucket',
-    accessKeyId: 'AKIA...',
-    secretAccessKey: 'secret...',
-    endpoint: 'https://s3.us-east-1.amazonaws.com'  // Optional
-  }
-}
+**1. Install the SDK:**
+```bash
+npm install ssh2-sftp-client
 ```
 
-### Azure Blob Provider
-
+**2. Register:**
 ```typescript
-// Requires: npm install @azure/storage-blob
-
-// Configuration:
-{
-  storage: 'azure',
-  config: {
-    accountName: 'myaccount',
-    accountKey: 'key...',
-    containerName: 'my-container',
-    // Or use connection string
-    connectionString: 'DefaultEndpointsProtocol=https;...'
-  }
-}
+import { SFTPProvider } from '@flusys/nestjs-storage/providers/sftp-provider.optional';
+StorageProviderRegistry.register(FileLocationEnum.SFTP, SFTPProvider);
 ```
 
-### SFTP Provider
-
-```typescript
-// Requires: npm install ssh2-sftp-client
-
-// Configuration:
+**3. Create a StorageConfig:**
+```json
+POST /storage/storage-config/insert
 {
-  storage: 'sftp',
-  config: {
-    host: 'sftp.example.com',
-    port: 22,
-    username: 'user',
-    password: 'password',
-    // Or use private key
-    privateKey: '-----BEGIN RSA PRIVATE KEY-----...',
-    basePath: '/uploads'
+  "name": "Legacy SFTP",
+  "storage": "sftp",
+  "config": {
+    "host": "sftp.example.com",
+    "port": 22,
+    "username": "sftpuser",
+    "password": "secret",
+    "remotePath": "/uploads"
   }
 }
 ```
 
-### Provider Factory & Caching
+### Custom Provider
 
 ```typescript
-@Injectable()
-export class StorageFactoryService implements OnModuleDestroy {
-  private readonly cache = new Map<string, IStorageProvider>();
-
-  async createProvider(config: IStorageProviderConfig): Promise<IStorageProvider> {
-    const cacheKey = this.generateCacheKey(config);
-
-    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`);
-    }
-
-    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}`;
-  }
+import { IStorageProvider, StorageProviderRegistry } from '@flusys/nestjs-storage';
 
-  // Cleanup on module destroy
-  async onModuleDestroy(): Promise<void> {
-    for (const [key, provider] of this.cache.entries()) {
-      if ('close' in provider && typeof (provider as any).close === 'function') {
-        await (provider as any).close();
-      }
-    }
-    this.cache.clear();
-  }
+class MyCloudProvider implements IStorageProvider {
+  async upload(file: IFileUploadOptions): Promise<IUploadedFile> { /* ... */ }
+  async delete(path: string): Promise<void> { /* ... */ }
+  async getUrl(path: string, ttl?: number): Promise<string> { /* ... */ }
 }
-```
-
----
-
-## Storage Configuration
-
-### StorageProviderConfigService
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class StorageProviderConfigService extends RequestScopedApiService<...> {
-
-  /** Direct lookup by ID (bypasses company filtering) */
-  async findByIdDirect(id: string): Promise<StorageConfigBase | null>;
-
-  /** 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[]>;
-}
-```
-
-### Default Configuration Resolution
-
-When `storageConfigId` is not provided for uploads:
-
-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' },
-  });
-}
-```
-
-### Creating Storage Configurations
-
-```typescript
-import { StorageProviderConfigService } from '@flusys/nestjs-storage';
-
-@Injectable()
-export class SetupService {
-  constructor(private readonly storageConfigService: StorageProviderConfigService) {}
-
-  async setupStorageConfigs(user: ILoggedUserInfo) {
-    // Create default S3 config
-    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,
-      },
-      isActive: true,
-      isDefault: true,
-    }, user);
-
-    // Create local backup config
-    await this.storageConfigService.insert({
-      name: 'local-backup',
-      storage: 'local',
-      config: {
-        basePath: './backups',
-      },
-      isActive: true,
-      isDefault: false,
-    }, user);
-  }
-}
+StorageProviderRegistry.register('my-cloud', MyCloudProvider);
 ```
 
 ---
 
-## File Manager
-
-### FileManagerService
-
-```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[]>;
-}
-```
+## API Endpoints
 
-### URL Generation & Refresh
+All endpoints use **POST** and require JWT authentication.
 
-Files automatically get presigned URLs when needed:
+### Storage Config — `POST /storage/storage-config/*`
 
-```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[] = [];
-
-  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);
-    }),
-  );
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /storage/storage-config/insert` | `storage-config.create` | Add provider config |
+| `POST /storage/storage-config/get-all` | `storage-config.read` | List configs |
+| `POST /storage/storage-config/get/:id` | `storage-config.read` | Get config by ID |
+| `POST /storage/storage-config/update` | `storage-config.update` | Update config |
+| `POST /storage/storage-config/delete` | `storage-config.delete` | Delete config |
+| `POST /storage/storage-config/set-default` | `storage-config.update` | Set as default provider |
 
-  if (updatedFiles.length) {
-    await this.repository.save(updatedFiles);
-  }
+### Folders — `POST /storage/folder/*`
 
-  return responses;
-}
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /storage/folder/insert` | `folder.create` | Create folder |
+| `POST /storage/folder/get-all` | `folder.read` | List folders |
+| `POST /storage/folder/get/:id` | `folder.read` | Get folder by ID |
+| `POST /storage/folder/get-tree` | `folder.read` | Get hierarchical folder tree |
+| `POST /storage/folder/update` | `folder.update` | Update folder |
+| `POST /storage/folder/delete` | `folder.delete` | Delete folder (must be empty) |
 
-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);
+### Files — `POST /storage/file/*`
 
-  if (needsNewUrl && file.storageConfigId) {
-    file.url = await this.uploadService.makeFileUrl(file.key, file.storageConfigId, 3600, user);
-    file.expiresAt = now + 3600 * 1000;
-    return true;
-  }
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /storage/file/upload` | `file.create` | Upload a file (multipart/form-data) |
+| `POST /storage/file/get-all` | `file.read` | List files with pagination |
+| `POST /storage/file/get/:id` | `file.read` | Get file metadata by ID |
+| `POST /storage/file/get-url/:id` | `file.read` | Get presigned or direct file URL |
+| `POST /storage/file/update` | `file.update` | Update file metadata |
+| `POST /storage/file/delete` | `file.delete` | Delete file (from storage + DB) |
+| `POST /storage/file/move` | `file.update` | Move file to a different folder |
 
-  // 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;
-  }
+### File Serving (Local)
 
-  return false;
-}
 ```
-
----
-
-## Folder Management
-
-### FolderService
-
-```typescript
-@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
-}
+GET /storage/upload/file/{path}
 ```
 
-### Folder DTOs
-
-```typescript
-export class CreateFolderDto {
-  @IsNotEmpty()
-  @IsString()
-  name!: string;
-}
-
-export class UpdateFolderDto extends PartialType(CreateFolderDto) {
-  @IsUUID()
-  @IsNotEmpty()
-  id!: string;
-}
-
-export class FolderResponseDto {
-  id!: string;
-  name!: string;
-  slug!: string;
-}
-```
+Served directly by `FileServeMiddleware`. No authentication (public file access). Register the middleware in your `AppModule`.
 
 ---
 
-## Upload Service
-
-### UploadService
-
-```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>;
-}
-```
-
-### Upload Options DTO
-
-```typescript
-export enum ImageFormat {
-  ORIGINAL = 'original',
-  JPEG = 'jpeg',
-  PNG = 'png',
-  WEBP = 'webp',
-}
-
-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;
-}
-```
+## Entities
 
----
+### Core Entities (always registered)
 
-## File Validation & Security
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `StorageConfig` | `storage_config` | Provider configuration (credentials, bucket, etc.) |
+| `Folder` | `storage_folder` | Folder hierarchy with `parentId` |
+| `FileManager` | `storage_file` | File metadata (name, path, size, MIME type, provider) |
 
-### FileValidator Utility
+### Company Feature Entities (`enableCompanyFeature: true`)
 
-The `FileValidator` class provides security features to prevent file upload attacks:
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `StorageConfigWithCompany` | `storage_config` | Same + `companyId` |
+| `FolderWithCompany` | `storage_folder` | Same + `companyId` |
+| `FileManagerWithCompany` | `storage_file` | Same + `companyId` |
 
 ```typescript
-export class FileValidator {
-  /** Detect file type from buffer using magic bytes */
-  static detectFileType(buffer: Buffer): string | null;
-
-  /** Check if MIME type is text-based (no magic bytes) */
-  static isTextBasedType(mimeType: string): boolean;
-
-  /** Check if MIME type is dangerous (HTML, JS, SVG) */
-  static isDangerousTextType(mimeType: string): boolean;
-
-  /** Check if two MIME types are compatible */
-  static mimeTypesMatch(detected: string, declared: string): boolean;
-
-  /** Check if MIME type is in allowed list */
-  static isTypeAllowed(mimeType: string, allowedTypes: string[]): boolean;
-
-  /** Validate file content matches declared MIME type */
-  static validateFileContent(
-    buffer: Buffer,
-    declaredMimeType: string,
-    allowedTypes?: string[]
-  ): FileValidationResult;
-
-  /** Sanitize filename to prevent path traversal */
-  static sanitizeFilename(filename: string): string;
-}
-
-interface FileValidationResult {
-  valid: boolean;
-  detectedType?: string;
-  declaredType?: string;
-  message?: string;
-}
-```
-
-### Supported Magic Bytes
-
-| 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 |
-
-### Dangerous File Types
-
-These types bypass magic-bytes validation but require **explicit allowlisting**:
-
-- `text/html`
-- `application/javascript`, `text/javascript`
-- `image/svg+xml`
-- `application/xhtml+xml`
-
-### Safe Text-Based Types
-
-These are allowed without magic bytes:
-
-- `text/plain`, `text/csv`, `text/markdown`
-- `application/json`, `application/xml`
-- `application/typescript`, `text/css`
-
-### Filename Sanitization
+import { StorageModule } from '@flusys/nestjs-storage';
 
-```typescript
-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
-}
+TypeOrmModule.forRoot({
+  entities: [
+    ...StorageModule.getEntities({ enableCompanyFeature: true }),
+  ],
+})
 ```
 
 ---
 
-## Image Compression
-
-### ImageCompressor Utility
+## File Serving (Local)
 
-Uses Sharp for image processing:
+Register `FileServeMiddleware` to serve uploaded local files over HTTP:
 
 ```typescript
-export class ImageCompressor {
-  static async compress(
-    buffer: Buffer,
-    mimetype: string,
-    options?: CompressionOptions
-  ): Promise<{ buffer: Buffer; format: string }>;
-}
+import { FileServeMiddleware } from '@flusys/nestjs-storage';
 
-interface CompressionOptions {
-  maxWidth?: number;   // Default: 1280
-  maxHeight?: number;  // Default: 1280
-  quality?: number;    // Default: 85
-  format?: ImageFormat; // Default: 'original'
+// In AppModule
+configure(consumer: MiddlewareConsumer) {
+  consumer.apply(FileServeMiddleware).forRoutes('storage/upload/file');
 }
 ```
 
-### Supported Output Formats
-
-| 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% |
-
-### Usage
-
-```typescript
-// Automatic compression during upload
-await uploadService.uploadSingleFile(file, {
-  compress: true,
-  maxWidth: 1920,
-  maxHeight: 1080,
-  quality: 80,
-  format: 'webp',
-}, user);
-```
+Files are served from the `localStoragePath` directory. The middleware validates paths to prevent directory traversal attacks.
 
 ---
 
-## REST API Endpoints
-
-All storage endpoints are prefixed with `/storage`.
-
-### Upload Endpoints
-
-| 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 | 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
+## Image Compression
 
-| 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` |
+Automatic compression is applied on upload for supported image types:
 
-### Storage Config Endpoints
+| Format | Compression applied |
+|--------|---------------------|
+| JPEG | Quality 80%, progressive |
+| PNG | Compression level 6 |
+| WebP | Quality 80% |
+| AVIF | Quality 75% |
+| TIFF | Deflate compression |
+| GIF | Passthrough |
 
-| 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` |
+Custom compression options:
 
-### Upload Request Example
+```json
+POST /storage/file/upload
+Content-Type: multipart/form-data
 
-```bash
-# 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 "compress=true"
-
-# Response:
 {
-  "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"
-  }
+  "file": <binary>,
+  "folderId": "uuid",
+  "compress": true,
+  "maxWidth": 1920,
+  "maxHeight": 1080,
+  "quality": 75
 }
 ```
 
 ---
 
-## File Serve Middleware
-
-The `FileServeMiddleware` handles file serving for local storage with multiple fallback strategies:
-
-```typescript
-@Injectable()
-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
-  }
-
-  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
-  }
-}
-```
+## File Validation
 
-### MIME Types for Inline Display
+Files are validated using **magic bytes** (file header inspection), not just the file extension or MIME type header. This prevents users from uploading malicious files with forged extensions.
 
+Allowed types are configured via `allowedFileTypes`:
 ```typescript
-const VIEWABLE_TYPE_PREFIXES = [
-  'image/',
-  'video/',
-  'audio/',
-  'text/',
-  'application/pdf',
-  'application/json',
-  'application/xml',
-];
+allowedFileTypes: ['image/*', 'application/pdf', 'text/plain']
 ```
 
-### Response Headers
-
-```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',
-});
-```
+Wildcard patterns like `image/*` match any subtype (e.g., `image/jpeg`, `image/png`, `image/webp`).
 
 ---
 
-## DataSource Provider Pattern
-
-### StorageDataSourceProvider
+## Exported Services
 
-```typescript
-@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;
-
-  /** Get storage entities based on company feature flag */
-  async getStorageEntities(enableCompanyFeature?: boolean): Promise<any[]>;
-
-  /** Get company feature for current tenant */
-  getEnableCompanyFeatureForCurrentTenant(): boolean;
-}
-```
-
-### Dynamic Entity Selection
-
-Services select entities at runtime:
-
-```typescript
-@Injectable({ scope: Scope.REQUEST })
-export class FileManagerService extends RequestScopedApiService<...> {
-  protected resolveEntity(): EntityTarget<FileManagerBase> {
-    return this.storageConfig.isCompanyFeatureEnabled()
-      ? FileManagerWithCompany
-      : FileManager;
-  }
-
-  protected getDataSourceProvider() {
-    return this.dataSourceProvider;
-  }
-}
-```
+| Service | Description |
+|---------|-------------|
+| `FileManagerService` | File upload, retrieval, deletion, move |
+| `FolderService` | Folder CRUD and tree queries |
+| `StorageConfigService` | Provider config CRUD |
+| `StorageDataSourceProvider` | Dynamic DataSource per request |
 
 ---
 
-## Multi-Tenant Support
-
-### Company Filtering
-
-When company feature is enabled:
-
-```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);
-
-  await this.applyPrivateFileFilter(query, user);
-
-  return result;
-}
-```
-
-### Private File Access
+## Programmatic Usage
 
 ```typescript
-private async applyPrivateFileFilter(query, user): Promise<void> {
-  if (!user) {
-    query.andWhere('file_manager.isPrivate = :isPrivate', { isPrivate: false });
-    return;
-  }
+import { FileManagerService } from '@flusys/nestjs-storage';
 
-  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 (!canViewPrivate) {
-    query.andWhere('file_manager.isPrivate = :isPrivate', { isPrivate: false });
+@Injectable()
+export class ProfileService {
+  constructor(
+    @Inject(FileManagerService) private readonly fileManager: FileManagerService,
+  ) {}
+
+  async uploadAvatar(userId: string, fileBuffer: Buffer, filename: string): Promise<string> {
+    const result = await this.fileManager.uploadFile({
+      buffer: fileBuffer,
+      originalName: filename,
+      mimeType: 'image/jpeg',
+      folderId: 'avatars-folder-id',
+    });
+    return result.id; // Store file ID on user profile
   }
-}
-```
-
-### Storage Config Validation
 
-```typescript
-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',
-    );
-
-    storageConfig = config;
-  } else {
-    const defaultConfig = await this.storageProviderConfigService.getDefaultConfig(user);
-    if (!defaultConfig) {
-      throw new NotFoundException('No default storage configuration found');
-    }
-    storageConfig = defaultConfig;
+  async getAvatarUrl(fileId: string): Promise<string> {
+    return this.fileManager.getFileUrl(fileId);
   }
-
-  return {
-    provider: await this.createProviderFromConfig(storageConfig),
-    location: storageConfig.storage,
-    configId: storageConfig.id,
-  };
 }
 ```
 
 ---
 
-## Swagger Configuration
+## Troubleshooting
 
-### Using storageSwaggerConfig
+**`Provider not registered` error**
 
-```typescript
-import { storageSwaggerConfig } from '@flusys/nestjs-storage/docs';
-
-// 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,
-// }
-```
+You created a StorageConfig with `storage: 'aws'` but forgot to register the S3 provider. Call `StorageProviderRegistry.register()` before the module initializes.
 
 ---
 
-## Best Practices
-
-### 1. Use Named Storage Configs
-
-```typescript
-// ✅ Create meaningful config names
-await storageConfigService.insert({
-  name: 'default',       // Primary storage
-  storage: 'aws',
-  config: { bucket: 'main-files', ... },
-  isDefault: true,
-}, user);
-
-await storageConfigService.insert({
-  name: 'media',         // Images/videos
-  storage: 'aws',
-  config: { bucket: 'media-files', ... },
-}, user);
-
-// ❌ Don't use generic names
-await storageConfigService.insert({
-  name: 'config1',
-  ...
-});
-```
+**Local files return 404**
 
-### 2. Configure File Validation
+Ensure `FileServeMiddleware` is registered and that `localStoragePath` points to an existing directory. The path must be accessible by the Node.js process.
 
-```typescript
-// ✅ Restrict file types in production
-StorageModule.forRoot({
-  config: {
-    maxFileSize: 10 * 1024 * 1024, // 10MB
-    allowedFileTypes: [
-      'image/jpeg',
-      'image/png',
-      'image/webp',
-      'application/pdf',
-    ],
-  },
-});
-
-// ❌ Don't allow all file types
-allowedFileTypes: ['*/*'];
-```
-
-### 3. Use Presigned URLs Properly
-
-```typescript
-// ✅ Always use getFiles() for URL access
-const files = await fileManagerService.getFiles(
-  [{ id: 'file-1' }, { id: 'file-2' }],
-  req.protocol,
-  req.get('host'),
-  user,
-);
-// URLs are automatically refreshed if expired
-
-// ❌ Don't cache URLs without expiration check
-const file = await fileManagerService.getById(id, user);
-return file.url; // May be expired!
-```
-
-### 4. Handle File Deletion Properly
-
-```typescript
-// ✅ Use permanent delete to remove from storage
-await fileManagerService.delete({
-  id: fileId,
-  type: 'permanent', // Deletes from storage provider
-}, 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
+**`File type not allowed` for a valid file**
 
-```typescript
-// ✅ Enable compression for images
-await uploadService.uploadSingleFile(file, {
-  compress: true,
-  maxWidth: 1920,
-  maxHeight: 1080,
-  quality: 80,
-  format: 'webp', // Best compression/quality ratio
-}, user);
-```
+Magic-byte validation is strict. If your file is being rejected incorrectly, check `allowedFileTypes` in your config and ensure the actual file header matches the declared MIME type.
 
 ---
 
-## API Reference
-
-### Main Exports
+**Presigned URL expired immediately**
 
-```typescript
-// Module
-import { StorageModule } from '@flusys/nestjs-storage';
-
-// Services
-import {
-  UploadService,
-  FileManagerService,
-  FolderService,
-  StorageProviderConfigService,
-  StorageConfigService,
-  StorageDataSourceProvider,
-} from '@flusys/nestjs-storage/services';
-
-// Entities
-import {
-  FileManager,
-  FileManagerBase,
-  FileManagerWithCompany,
-  Folder,
-  FolderBase,
-  FolderWithCompany,
-  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
-import {
-  IFileManager,
-  IFolder,
-  IStorageConfig,
-  IStorageModuleConfig,
-  IStorageProvider,
-  IStorageProviderConfig,
-  IUploadedFileInfo,
-  StorageModuleOptions,
-  StorageModuleAsyncOptions,
-  StorageOptionsFactory,
-} from '@flusys/nestjs-storage/interfaces';
-
-// Enums
-import { FileLocationEnum } from '@flusys/nestjs-storage/enums';
-
-// Providers
-import {
-  StorageFactoryService,
-  StorageProviderRegistry,
-  LocalProvider,
-} from '@flusys/nestjs-storage/providers';
-
-// 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';
+S3 and Azure presigned URLs have a TTL. The default TTL is cached per file. Pass a custom TTL in the get-url request body:
+```json
+POST /storage/file/get-url/:id
+{ "ttl": 3600 }
 ```
 
 ---
 
-## Summary
-
-The `@flusys/nestjs-storage` package provides:
+## License
 
-- **Multiple Providers** - Local, AWS S3, Azure Blob, SFTP
-- **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 with POST-only RPC
-- **Middleware** - File serving with multiple fallback strategies
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.