storage

Supabase Storage Architecture

This document outlines our approach to file storage using Supabase Storage. These guidelines ensure consistent, secure, and efficient file handling across the application.

Core Principles

1. Security First: Enforce proper access controls and permissions
2. Structured Organization: Maintain consistent file paths and bucket structures
3. Performance Optimization: Implement efficient upload/download strategies
4. Error Resilience: Handle failures gracefully at all points

Configuration Best Practices

• Use environment variables for all bucket names

  // In .env.local
  NEXT_PUBLIC_SUPABASE_PROFILE_BUCKET="profile-images"
  
  // In code
  const profileBucket = process.env.NEXT_PUBLIC_SUPABASE_PROFILE_BUCKET
  

• Never hardcode bucket names in application code
• Set appropriate file size limits and validate file types
• Use upsert: true only when intentionally replacing files
• Always include proper content-type headers when uploading

Bucket Organization

Naming & Structure

• Use kebab-case for bucket names: profile-images, document-files
• Create purpose-specific buckets rather than general-purpose ones
• Document each bucket's purpose and access pattern

Security Policies

• Make buckets private by default
• Implement Row Level Security (RLS) for user-specific access
• Example RLS policy for user-owned files:

  CREATE POLICY "Users can only access their own files"
  ON storage.objects
  FOR ALL
  USING (auth.uid()::text = (storage.foldername(name))[1]);
  

Note: For production deployment, provide SQL scripts for required RLS policies to your DevOps team.

File Path Conventions

Organize files using consistent path structures:

{bucket}/{userId}/{purpose}/{filename}

Examples:

• User avatars: profile-images/user_123/avatar/profile.jpg
• Documents with versioning: documents/user_123/contracts/2024-02-13-contract.pdf

This structure:

• Enables effective RLS policies
• Simplifies permission management
• Provides natural organization