File Management Module

A comprehensive file management system for DBS Portal with cloud storage abstraction, advanced file browser, drag-and-drop upload, multi-format preview, and enterprise-grade file operations.

Features

🗂️ Advanced File Browser

• Multiple View Modes: Grid, list, and tree views with customizable layouts
• Smart Filtering: Search by name, category, type, size, date, and tags
• Bulk Operations: Select multiple files for copy, move, delete, and share operations
• Folder Navigation: Hierarchical folder structure with breadcrumb navigation
• Real-time Updates: Live file list updates with React Query caching

☁️ Cloud Storage Support

• Multi-Provider Support: Local, AWS S3, Azure Blob Storage, and extensible architecture
• Storage Abstraction: Unified API across different storage providers
• Automatic Failover: Seamless switching between storage providers
• Configuration Management: Easy setup and configuration for cloud providers

☁️ Cloud Storage Abstraction

• Multi-Provider Support: Local, AWS S3, Azure Blob, Google Cloud, Cloudinary
• Storage Engine: Pluggable architecture for custom storage providers
• Automatic Failover: Redundancy and backup strategies
• Performance Optimization: Intelligent caching and CDN integration

📤 Drag-and-Drop Upload

• Modern Upload Experience: Drag-and-drop with progress tracking
• Batch Processing: Multiple file uploads with individual progress
• File Validation: Size, type, and security validation
• Auto-categorization: Intelligent file categorization based on MIME types
• Upload Settings: Configurable access levels, tags, and processing options

👁️ Multi-Format File Viewer

• Image Preview: High-quality image viewing with zoom and pan
• Video/Audio Player: Integrated media player with controls
• Document Viewer: PDF and text file preview
• Metadata Display: Comprehensive file information and EXIF data
• Fullscreen Mode: Immersive viewing experience

🔄 Version Control

• File Versioning: Track changes with detailed changelog
• Version Comparison: Compare different versions
• Rollback Support: Restore previous versions
• Active Version Management: Control which version is live

🔗 File Sharing & Permissions

• Granular Access Control: Public, private, restricted, internal levels
• Secure Sharing: Time-limited links with password protection
• Download Limits: Control access frequency and duration
• User/Role Permissions: Fine-grained access management

📊 Analytics & Monitoring

• Usage Statistics: Download counts, view metrics, popularity scores
• Storage Analytics: Space usage, category breakdown, trends
• Performance Monitoring: Upload/download speeds, error rates
• Audit Trail: Complete activity logging

Installation

npm install @dbs-portal/module-file-management

Dependencies

Required

• @tanstack/react-query - Data fetching and caching
• antd - UI components
• react - React framework
• date-fns - Date formatting
• lodash-es - Utility functions
• zod - Schema validation

Optional (Enhanced Features)

• react-dropzone - Enhanced drag-and-drop (fallback available)
• react-image-gallery - Image gallery viewer
• react-pdf - PDF preview support
• react-player - Video/audio player
• file-saver - File download utilities
• mime-types - MIME type detection

Quick Start

1. Complete File Manager

import { FileManager } from '@dbs-portal/module-file-management'

function FileManagementPage() {
  return (
    <FileManager
      viewMode="list"
      selectionMode="multiple"
      showToolbar
      showSidebar
      showPreview
      allowUpload
      allowCreateFolder
      onFileSelect={(file) => console.log('Selected:', file)}
    />
  )
}

2. File Browser Only

import { FileBrowser } from '@dbs-portal/module-file-management'

function FileBrowserPage() {
  const [selectedFiles, setSelectedFiles] = useState([])

  return (
    <FileBrowser
      parentId="folder-123"
      viewMode="grid"
      selectionMode="multiple"
      allowUpload
      allowDelete
      allowShare
      onFileSelect={(file) => console.log('File selected:', file)}
      onSelectionChange={setSelectedFiles}
    />
  )
}

3. File Upload Component

import { FileUploader } from '@dbs-portal/module-file-management'

function UploadPage() {
  return (
    <FileUploader
      parentId="folder-123"
      multiple
      accept="image/*,application/pdf"
      maxSize={50 * 1024 * 1024} // 50MB
      maxFiles={10}
      autoUpload={false}
      showProgress
      onUploadComplete={(files) => {
        console.log('Uploaded files:', files)
      }}
      onUploadError={(error) => {
        console.error('Upload failed:', error)
      }}
    />
  )
}

4. File Viewer

import { FileViewer, useFile } from '@dbs-portal/module-file-management'

function FileViewerPage({ fileId }: { fileId: string }) {
  const { data: file, isLoading } = useFile(fileId)

  if (isLoading || !file) return <div>Loading...</div>

  return (
    <FileViewer
      file={file}
      showMetadata
      showActions
      allowDownload
      allowShare
      allowEdit
      onEdit={(file) => console.log('Edit file:', file)}
      onShare={(file) => console.log('Share file:', file)}
      onDownload={(file) => console.log('Download file:', file)}
    />
  )
}

5. Cloud Storage Configuration

import {
  storageEngine,
  S3StorageProvider,
  AzureBlobStorageProvider
} from '@dbs-portal/module-file-management'

// Configure AWS S3
storageEngine.registerS3Provider({
  provider: 'aws-s3',
  region: 'us-east-1',
  bucket: 'my-app-files',
  accessKey: process.env.AWS_ACCESS_KEY_ID,
  secretKey: process.env.AWS_SECRET_ACCESS_KEY,
  maxFileSize: 100 * 1024 * 1024, // 100MB
  allowedMimeTypes: ['image/*', 'application/pdf', 'text/*'],
  thumbnailSizes: [
    { width: 150, height: 150 },
    { width: 300, height: 300 }
  ],
  previewFormats: ['image/*', 'application/pdf']
})

// Configure Azure Blob Storage
storageEngine.registerAzureProvider({
  provider: 'azure-blob',
  bucket: 'files',
  accessKey: 'account-name:connection-string',
  secretKey: process.env.AZURE_STORAGE_KEY,
  maxFileSize: 100 * 1024 * 1024,
  allowedMimeTypes: ['*/*'],
  thumbnailSizes: [{ width: 150, height: 150 }],
  previewFormats: ['image/*', 'application/pdf']
})

// Set default provider
storageEngine.setDefaultProvider('aws-s3')

6. Using Hooks for Custom Components

import {
  useFiles,
  useUploadFile,
  useDeleteFile,
  useStorageUsage
} from '@dbs-portal/module-file-management'

function CustomFileComponent() {
  const { data: filesResponse, isLoading } = useFiles(1, 20, {
    category: 'image',
    sortBy: 'createdAt',
    sortOrder: 'desc'
  })

  const uploadMutation = useUploadFile()
  const deleteMutation = useDeleteFile()
  const { data: storageUsage } = useStorageUsage()

  const handleUpload = async (file: File) => {
    try {
      const uploadedFile = await uploadMutation.mutateAsync({
        request: {
          file,
          category: 'image',
          accessLevel: 'private',
          generateThumbnail: true
        }
      })
      console.log('File uploaded:', uploadedFile)
    } catch (error) {
      console.error('Upload failed:', error)
    }
  }

  const handleDelete = async (fileId: string) => {
    try {
      await deleteMutation.mutateAsync(fileId)
      console.log('File deleted')
    } catch (error) {
      console.error('Delete failed:', error)
    }
  }

  return (
    <div>
      <div>Storage Used: {storageUsage?.usedSpace} bytes</div>
      <div>Total Files: {filesResponse?.meta?.total}</div>
      
      {filesResponse?.data?.map(file => (
        <div key={file.id}>
          <span>{file.name}</span>
          <button onClick={() => handleDelete(file.id)}>Delete</button>
        </div>
      ))}
      
      <input
        type="file"
        onChange={(e) => {
          const file = e.target.files?.[0]
          if (file) handleUpload(file)
        }}
      />
    </div>
  )
}

API Reference

Components

FileManager

Complete file management interface with sidebar, toolbar, and preview.

interface FileManagerProps {
  initialParentId?: string
  viewMode?: 'grid' | 'list' | 'tree'
  selectionMode?: 'single' | 'multiple' | 'none'
  showToolbar?: boolean
  showSidebar?: boolean
  showPreview?: boolean
  allowUpload?: boolean
  allowCreateFolder?: boolean
  onFileSelect?: (file: FileEntity) => void
  className?: string
}

FileBrowser

Advanced file browser with filtering and bulk operations.

interface FileBrowserProps {
  parentId?: string
  viewMode?: 'grid' | 'list' | 'tree'
  selectionMode?: 'single' | 'multiple' | 'none'
  allowUpload?: boolean
  allowCreateFolder?: boolean
  allowDelete?: boolean
  allowRename?: boolean
  allowMove?: boolean
  allowShare?: boolean
  filters?: Partial<FileSearchFilters>
  onFileSelect?: (file: FileEntity) => void
  onFileDoubleClick?: (file: FileEntity) => void
  onFolderSelect?: (folder: FolderEntity) => void
  onSelectionChange?: (selectedFiles: FileEntity[]) => void
  className?: string
}

FileUploader

Drag-and-drop file uploader with progress tracking.

interface FileUploaderProps {
  parentId?: string
  multiple?: boolean
  accept?: string
  maxSize?: number
  maxFiles?: number
  autoUpload?: boolean
  showProgress?: boolean
  showPreview?: boolean
  onUploadStart?: (files: File[]) => void
  onUploadProgress?: (progress: FileUploadProgress[]) => void
  onUploadComplete?: (files: FileEntity[]) => void
  onUploadError?: (error: string, file?: File) => void
  className?: string
}

FileViewer

Multi-format file viewer with metadata and actions.

interface FileViewerProps {
  file: FileEntity
  showMetadata?: boolean
  showActions?: boolean
  allowDownload?: boolean
  allowShare?: boolean
  allowEdit?: boolean
  onClose?: () => void
  onEdit?: (file: FileEntity) => void
  onShare?: (file: FileEntity) => void
  onDownload?: (file: FileEntity) => void
  className?: string
}

Hooks

File CRUD Operations

• useFiles(page, pageSize, filters) - Fetch paginated files with filtering
• useFile(id) - Fetch single file by ID
• useUploadFile() - Upload single file with progress
• useUploadFiles() - Upload multiple files with batch progress
• useUpdateFile() - Update file metadata
• useDeleteFile() - Delete file
• useDownloadFile() - Download file as blob
• useGetDownloadUrl() - Get secure download URL

File Operations

• useCopyFile() - Copy file to another location
• useMoveFile() - Move file to another folder
• useRenameFile() - Rename file
• useBulkFileOperation() - Perform bulk operations on multiple files

File Sharing

• useShareFile() - Configure file sharing settings
• useFileSharing(id) - Get file sharing configuration
• useRemoveFileSharing() - Remove file sharing

Version Management

• useFileVersions(id) - Get file version history
• useCreateFileVersion() - Create new file version
• useSetActiveFileVersion() - Set active version

File Processing

• useFileProcessingJobs(id) - Get processing job status
• useStartProcessingJob() - Start processing job (thumbnail, preview, etc.)

Search & Discovery

• useSearchFiles(query, filters) - Search files with advanced filters
• useRecentFiles(limit) - Get recently accessed files
• usePopularFiles(limit) - Get most popular files
• useFilesByCategory(category) - Get files by category

Analytics

• useFileStatistics(id) - Get file usage statistics
• useStorageUsage() - Get storage usage analytics

Folder Operations

• useFolders(parentId) - Get folders in parent
• useCreateFolder() - Create new folder
• useUpdateFolder() - Update folder metadata
• useDeleteFolder() - Delete folder (with recursive option)
• useFolderTree(rootId) - Get hierarchical folder tree

Storage Engine

Built-in Providers

// Local storage (development)
const localProvider = new LocalStorageProvider({
  baseUrl: '/api/files',
  uploadEndpoint: '/api/files/upload'
})

// AWS S3 (production)
const s3Provider = new S3StorageProvider({
  provider: 'aws-s3',
  region: 'us-east-1',
  bucket: 'my-bucket',
  accessKey: 'ACCESS_KEY',
  secretKey: 'SECRET_KEY'
})

// Register providers
storageEngine.registerProvider('local', localProvider)
storageEngine.registerProvider('aws-s3', s3Provider)
storageEngine.setDefaultProvider('aws-s3')

Custom Storage Provider

class CustomStorageProvider implements IStorageProvider {
  async upload(file: File, path: string): Promise<StorageOperationResult> {
    // Custom upload logic
    return { success: true, url: 'https://example.com/file', path }
  }

  async download(path: string): Promise<Blob> {
    // Custom download logic
    return new Blob()
  }

  async delete(path: string): Promise<boolean> {
    // Custom delete logic
    return true
  }

  // Implement other required methods...
}

storageEngine.registerProvider('custom', new CustomStorageProvider())

File Types and Categories

type FileCategory = 
  | 'document'  // PDF, DOC, TXT, etc.
  | 'image'     // JPG, PNG, GIF, etc.
  | 'video'     // MP4, AVI, MOV, etc.
  | 'audio'     // MP3, WAV, FLAC, etc.
  | 'archive'   // ZIP, RAR, TAR, etc.
  | 'code'      // JS, TS, PY, etc.
  | 'data'      // JSON, XML, CSV, etc.
  | 'other'     // Unknown types

type FileAccessLevel = 'public' | 'private' | 'restricted' | 'internal'
type FileStatus = 'uploading' | 'processing' | 'ready' | 'failed' | 'archived' | 'deleted'

Advanced Usage

Custom File Processing

import { useStartProcessingJob } from '@dbs-portal/module-file-management'

function ProcessingExample({ fileId }: { fileId: string }) {
  const processingMutation = useStartProcessingJob()

  const generateThumbnail = async () => {
    try {
      await processingMutation.mutateAsync({
        id: fileId,
        type: 'thumbnail',
        options: {
          width: 200,
          height: 200,
          quality: 80
        }
      })
    } catch (error) {
      console.error('Processing failed:', error)
    }
  }

  return (
    <button onClick={generateThumbnail}>
      Generate Thumbnail
    </button>
  )
}

Bulk File Operations

import { useBulkFileOperation } from '@dbs-portal/module-file-management'

function BulkOperationsExample() {
  const bulkMutation = useBulkFileOperation()

  const moveFiles = async (fileIds: string[], targetFolderId: string) => {
    try {
      const result = await bulkMutation.mutateAsync({
        operation: 'move',
        fileIds,
        targetId: targetFolderId
      })
      
      console.log(`Moved ${result.processedCount} files`)
      if (result.failedCount > 0) {
        console.error('Failed operations:', result.errors)
      }
    } catch (error) {
      console.error('Bulk operation failed:', error)
    }
  }

  return (
    <button onClick={() => moveFiles(['file1', 'file2'], 'folder1')}>
      Move Selected Files
    </button>
  )
}

File Sharing Configuration

import { useShareFile } from '@dbs-portal/module-file-management'

function SharingExample({ fileId }: { fileId: string }) {
  const shareMutation = useShareFile()

  const shareFile = async () => {
    try {
      await shareMutation.mutateAsync({
        id: fileId,
        sharing: {
          isEnabled: true,
          accessLevel: 'view',
          expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
          password: 'optional-password',
          downloadLimit: 10,
          allowedUsers: ['user1', 'user2']
        }
      })
    } catch (error) {
      console.error('Sharing failed:', error)
    }
  }

  return (
    <button onClick={shareFile}>
      Share File
    </button>
  )
}

Configuration

Environment Variables

# Storage settings
VITE_FILE_MAX_SIZE=104857600
VITE_FILE_ALLOWED_TYPES=image/*,application/pdf,text/*
VITE_FILE_STORAGE_PROVIDER=local

# AWS S3 settings (if using S3)
VITE_AWS_REGION=us-east-1
VITE_AWS_BUCKET=my-file-bucket
VITE_AWS_ACCESS_KEY=your-access-key
VITE_AWS_SECRET_KEY=your-secret-key

# Processing settings
VITE_FILE_ENABLE_THUMBNAILS=true
VITE_FILE_ENABLE_PREVIEWS=true
VITE_FILE_THUMBNAIL_SIZES=200x200,400x400

Storage Configuration

import { createStorageEngine } from '@dbs-portal/module-file-management'

const storageEngine = createStorageEngine({
  provider: 'aws-s3',
  region: 'us-east-1',
  bucket: 'my-bucket',
  maxFileSize: 100 * 1024 * 1024, // 100MB
  allowedMimeTypes: [
    'image/*',
    'application/pdf',
    'text/*',
    'video/mp4'
  ],
  thumbnailSizes: [
    { width: 200, height: 200, quality: 80 },
    { width: 400, height: 400, quality: 90 }
  ],
  previewFormats: ['jpg', 'png', 'pdf', 'mp4']
})

Development

Building

npm run build

Testing

npm test

Type Checking

npm run type-check

Linting

npm run lint

Contributing

1. Follow established patterns for components, hooks, and services
2. Ensure all new features have TypeScript types
3. Add comprehensive validation for file operations
4. Update documentation for API changes
5. Test with various file types and sizes

Performance Considerations

Optimization Tips

• Use pagination for large file lists
• Implement virtual scrolling for thousands of files
• Lazy load thumbnails and previews
• Cache frequently accessed files
• Use CDN for file delivery
• Implement progressive image loading

Memory Management

• Clean up blob URLs after use
• Limit concurrent uploads
• Use streaming for large file operations
• Implement proper error boundaries

Security

File Validation

• Server-side MIME type validation
• File size limits
• Virus scanning integration
• Content sanitization
• Path traversal protection

Access Control

• JWT-based authentication
• Role-based permissions
• Audit logging
• Secure file URLs with expiration
• IP-based restrictions

License

MIT License - see LICENSE file for details.