File Management | ShipSaaS Documentation

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

Configure Supabase Storage

bash

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

Basic File Upload

tsx

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

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

Upload via Server Action

tsx

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

typescript

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

bash

# 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:

typescript

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:

typescript

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:

typescript

export const uploadFileForEntityService = async (
  params: UploadFileForEntity
): Promise<FileResponse>

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

Specialized Entity Services

typescript

// 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

bash

# 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

File Upload Component - FileUpload component usage and customization
Server Actions - Server-side upload handling and validation

Configuration

Storage Configuration - Supabase setup and storage factory pattern
Authorization & Security - Access control and validation schemas

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.

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

Configure Supabase Storage

bash

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

Basic File Upload

tsx

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

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

Upload via Server Action

tsx

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

typescript

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

bash

# 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:

typescript

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:

typescript

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:

typescript

export const uploadFileForEntityService = async (
  params: UploadFileForEntity
): Promise<FileResponse>

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

Specialized Entity Services

typescript

// 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

bash

# 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

File Upload Component - FileUpload component usage and customization
Server Actions - Server-side upload handling and validation

Configuration

Storage Configuration - Supabase setup and storage factory pattern
Authorization & Security - Access control and validation schemas

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.