File Management

Complete file management system built with Supabase Storage, featuring entity-based organization, authorization controls, and specialized services for different file types.

Architecture Overview

Data Flow Pattern

Client Components → Server Actions → Service Facades → Services → Repository

Core Technologies

  • Supabase Storage for file hosting and management
  • React Dropzone with drag & drop interface
  • FileUpload Component with ShadCN UI integration
  • Framer Motion for upload animations
  • Zod Validation for file type and size constraints
The boilerplate implements a storage factory pattern supporting multiple providers. Supabase is implemented by default, with S3 adapter ready for production scaling.

Quick Start

1

Configure Supabase Storage

# Required environment variables
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
2

Basic File Upload

import { FileUpload } from '@/components/ui/file-upload'

<FileUpload
  onChange={handleFileUpload}
  onlyimage={true}
  multi={false}
  isUploading={isUploading}
/>
3

Upload via Server Action

const result = await uploadImageForEntityService({
  file,
  entityType: EntityTypeConst.USER,
  entityId: user.id,
  category: FileCategoryConst.PROFILE,
})

File Organization

Entity-Based Structure

Files are automatically organized by entity type with timestamp-based naming: 
users/{userId}/profile-1703123456789.webp
users/{userId}/document-1703123456789.pdf

File Categories

export enum FileCategoryConst {
  PROFILE = 'profile',     // User avatars
  LOGO = 'logo',          // Organization logos
  IMAGE = 'image',        // General images
  DOCUMENT = 'document',  // PDF, docs
  BANNER = 'banner',      // Hero images
}

Environment Separation

# Development files
dev/users/123/profile-1703123456789.webp

# Production files
prod/users/123/profile-1703123456789.webp

Core Services

Image Upload Service

Specialized for images with strict validation: 
export const uploadImageForEntityService = async (
  params: UploadFileForEntity
): Promise<FileResponse>

// Supported types: WebP, JPEG, JPG, PNG
const ALLOWED_IMAGE_MIME_TYPES = [
  'image/webp',
  'image/jpeg',
  'image/jpg',
  'image/png'
] as const
Usage Example: 
const result = await uploadImageForEntityService({
  file,
  entityType: EntityTypeConst.ORGANIZATION,
  entityId: organization.id,
  category: FileCategoryConst.LOGO,
})

// Generated path: "organizations/123/logo-1703123456789.png"
// Returns: { path, url, size, type, name }

General File Upload Service

For all file types with configurable validation: 
export const uploadFileForEntityService = async (
  params: UploadFileForEntity
): Promise<FileResponse>

// Supports documents, images, and other file types
// Automatic path generation with timestamp

Specialized Entity Services

// User profile image upload
export const uploadUserProfileService = async (
  userId: string,
  file: File
): Promise<FileResponse>

// Organization logo upload
export const uploadOrganizationLogoService = async (
  orgId: string,
  file: File
): Promise<FileResponse>

Essential Commands

# Development
pnpm dev                    # Start with file upload testing

# Testing file uploads
pnpm test src/services/file-service.test.ts

# Database operations
pnpm db:studio             # View file records in database
Your file management system is now configured! Continue with the detailed guides for implementation specifics.

Detailed Guides

Explore specific aspects of the file management system:

Implementation

Configuration

Examples

  • Usage Examples - Complete implementation examples for common use cases
This modular approach provides a comprehensive file management system with enterprise-grade security, performance, and developer experience.