@jmruthers/pace-core 0.5.87 → 0.5.89

package/docs/implementation-guides/file-reference-system.md

@@ -13,10 +13,12 @@ A centralized file management system for PACE Core that provides consistent file
 The File Reference System replaces scattered file URL columns with a centralized `file_references` table that provides:
 
 - **Consistent Storage**: All files stored in organization-first structure
+- **Bucket-Aware Storage**: Automatic selection between `files` (private) and `public-files` (public) buckets
 - **Metadata Tracking**: Rich file metadata including size, type, dimensions, etc.
 - **Access Control**: Row Level Security (RLS) based on organization membership
 - **Audit Trail**: Track who uploaded files and when
 - **Easy Cleanup**: Identify and manage orphaned files
+- **URL Management**: Automatic signed URL generation for private files, public URLs for public files
 
 ## Architecture
 
@@ -44,15 +46,54 @@ CREATE TABLE file_references (
 {bucket}/{orgId}/{category}/{filename}
 
 Examples:
-- files/org-123/profile_photos/timestamp-uuid-photo.jpg
-- files/org-123/id_documents/timestamp-uuid-passport.pdf
-- public-files/org-123/event_logos/timestamp-uuid-logo.png
+- files/org-123/profile_photos/timestamp-uuid-photo.jpg (private)
+- files/org-123/id_documents/timestamp-uuid-passport.pdf (private)
+- public-files/org-123/event_logos/timestamp-uuid-logo.png (public)
+```
+
+### Bucket Selection
+
+The system uses two Supabase storage buckets:
+
+1. **`files` bucket** (Private)
+   - For files that require authentication
+   - Accessible via signed URLs with expiration
+   - Default bucket for new file references
+   - Protected by RLS policies
+
+2. **`public-files` bucket** (Public)
+   - For files accessible without authentication
+   - Accessible via direct public URLs
+   - Used for event logos, public assets, etc.
+   - Defined by `is_public = true` in `file_references`
+
+**Bucket selection is automatic** based on the `is_public` flag when creating file references:
+
+```typescript
+// Private file (files bucket)
+await service.createFileReference({
+  table_name: 'pace_person',
+  record_id: personId,
+  organisation_id: orgId,
+  category: FileCategory.PROFILE_PHOTOS,
+  is_public: false // Uses 'files' bucket
+}, file);
+
+// Public file (public-files bucket)
+await service.createFileReference({
+  table_name: 'event',
+  record_id: eventId,
+  organisation_id: orgId,
+  category: FileCategory.EVENT_LOGOS,
+  is_public: true // Uses 'public-files' bucket
+}, file);
 ```
 
 ### File Categories
 
 ```typescript
 enum FileCategory {
+  // Core categories
   PROFILE_PHOTOS = 'profile_photos',
   ID_DOCUMENTS = 'id_documents',
   QUALIFICATIONS = 'qualifications',
@@ -63,7 +104,16 @@ enum FileCategory {
   IMAGES = 'images',
   AUDIO = 'audio',
   VIDEO = 'video',
-  ARCHIVES = 'archives'
+  ARCHIVES = 'archives',
+  
+  // CAKE-specific categories
+  CAKE_DISH = 'cake_dish',
+  
+  // TRAC-specific categories
+  TRAC_ACCOMMODATION = 'trac_accommodation',
+  TRAC_ACTIVITY = 'trac_activity',
+  TRAC_JOURNAL = 'trac_journal',
+  TRAC_TRANSPORT = 'trac_transport'
 }
 ```
 
@@ -73,6 +123,7 @@ enum FileCategory {
 
 #### FileUpload Component
 
+**Basic Usage:**
 ```tsx
 import { FileUpload, FileCategory } from '@jmruthers/pace-core';
 
@@ -81,12 +132,82 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   table_name="pace_person"
   record_id={personId}
   organisation_id={orgId}
-  app_id="your-app-id"
+  app_id="your-app-id" // Optional - auto-resolved from app name if not provided
   category={FileCategory.PROFILE_PHOTOS}
   accept="image/*"
   maxSize={5 * 1024 * 1024}
-  onUploadSuccess={(result) => console.log('Uploaded:', result.file_path)}
-  onUploadError={(error) => console.error('Upload failed:', error)}
+  onUploadSuccess={(result) => {
+    console.log('Uploaded:', result.file_reference);
+    console.log('URL:', result.file_url);
+  }}
+  onUploadError={(error, file) => {
+    console.error(`Upload failed for ${file?.name}:`, error);
+  }}
+/>
+```
+
+**With Progress Tracking:**
+```tsx
+<FileUpload
+  supabase={supabase}
+  table_name="pace_person"
+  record_id={personId}
+  organisation_id={orgId}
+  // app_id omitted - will be auto-resolved from app name
+  category={FileCategory.PROFILE_PHOTOS}
+  accept="image/*"
+  maxSize={5 * 1024 * 1024}
+  showProgress={true}
+  showPreview={true}
+  multiple={true}
+  disabled={false}
+  className="custom-upload-area"
+  onProgress={(progress) => {
+    console.log(`Uploading ${progress.fileName}: ${progress.percentage}%`);
+  }}
+  onUploadSuccess={(result) => {
+    console.log('Uploaded:', result.file_reference);
+    console.log('URL:', result.file_url);
+  }}
+  onUploadError={(error, file) => {
+    console.error(`Failed to upload ${file?.name}:`, error);
+  }}
+>
+  {/* Custom upload UI */}
+  <div className="border-2 border-dashed border-main-300 rounded-lg p-6 text-center">
+    <p>Drop files here or click to browse</p>
+  </div>
+</FileUpload>
+```
+
+**Public File Upload (Event Logo):**
+```tsx
+<FileUpload
+  supabase={supabase}
+  table_name="event"
+  record_id={eventId}
+  organisation_id={orgId}
+  app_id="your-app-id"
+  category={FileCategory.EVENT_LOGOS}
+  accept="image/*"
+  isPublic={true} // Uploads to public-files bucket
+  showPreview={true}
+  onUploadSuccess={(result) => {
+    // File is now accessible via public URL
+    console.log('Public URL:', result.file_url);
+  }}
+/>
+```
+
+**Custom Upload UI:**
+```tsx
+<FileUpload
+  supabase={supabase}
+  table_name="pace_person"
+  record_id={personId}
+  organisation_id={orgId}
+  app_id="your-app-id"
+  category={FileCategory.PROFILE_PHOTOS}
 >
   <div className="custom-upload-ui">
     <p>Click to upload profile photo</p>
@@ -123,25 +244,112 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
 #### useFileReference Hook
 
 ```tsx
-import { useFileReference } from '@jmruthers/pace-core';
-
-const { uploadFile, getFileUrl, deleteFile, isLoading, error } = useFileReference(supabase);
-
-// Upload a file
+import { useFileReference, FileCategory } from '@jmruthers/pace-core';
+
+const { 
+  uploadFile, 
+  getFileUrl, 
+  getFileReferenceById,
+  getFilesByCategory,
+  deleteFileReference,
+  isLoading, 
+  error 
+} = useFileReference(supabase);
+
+// Upload a private file
 const result = await uploadFile({
   table_name: 'pace_person',
   record_id: personId,
   organisation_id: orgId,
   app_id: 'your-app-id',
   category: FileCategory.PROFILE_PHOTOS,
-  is_public: false
+  is_public: false // Uses 'files' bucket
 }, file);
 
-// Get file URL
+// Upload a public file
+const publicResult = await uploadFile({
+  table_name: 'event',
+  record_id: eventId,
+  organisation_id: orgId,
+  app_id: 'your-app-id',
+  category: FileCategory.EVENT_LOGOS,
+  is_public: true // Uses 'public-files' bucket
+}, logoFile);
+
+// Get file URL (automatically handles bucket selection)
 const fileUrl = await getFileUrl('pace_person', personId, orgId);
+// Returns:
+// - Public URL for public files (from public-files bucket)
+// - Signed URL for private files (from files bucket)
+
+// Get file reference by ID
+const fileRef = await getFileReferenceById(fileRefId, orgId);
+
+// Get files by category
+const eventLogos = await getFilesByCategory(
+  'event',
+  eventId,
+  FileCategory.EVENT_LOGOS,
+  orgId
+);
 
 // Delete file
-const success = await deleteFile('pace_person', personId, orgId, true);
+const success = await deleteFileReference('pace_person', personId, orgId, true);
+```
+
+#### useFileReferenceById Hook
+
+```tsx
+import { useFileReferenceById } from '@jmruthers/pace-core';
+
+const { fileReference, fileUrl, isLoading, error } = useFileReferenceById(
+  supabase,
+  fileReferenceId,
+  organisationId
+);
+
+// Automatically loads file reference and URL when ID changes
+```
+
+#### useFilesByCategory Hook
+
+```tsx
+import { useFilesByCategory, FileCategory } from '@jmruthers/pace-core';
+
+const { fileReferences, fileUrls, isLoading, error } = useFilesByCategory(
+  supabase,
+  'event',
+  eventId,
+  FileCategory.EVENT_LOGOS,
+  organisationId
+);
+
+// fileUrls is a Map<fileId, url> for easy lookup
+fileReferences.forEach(fileRef => {
+  const url = fileUrls.get(fileRef.id);
+  // Use url for display
+});
+```
+
+#### useEventLogo Hook
+
+```tsx
+import { useEventLogo } from '@jmruthers/pace-core';
+
+const { logoUrl, fallbackText, isLoading, error, refetch } = useEventLogo(
+  supabase,
+  eventId,
+  eventName,
+  organisationId,
+  {
+    validateImage: true,
+    enableCache: true,
+    cacheTtl: 30 * 60 * 1000 // 30 minutes
+  }
+);
+
+// Automatically handles both public and private event logos
+// Falls back to event initials if no logo is found
 ```
 
 #### useFileReferenceForRecord Hook
@@ -185,36 +393,82 @@ const files = await service.listFileReferences('pace_person', personId, orgId);
 
 ## Database Functions
 
-### Helper Functions
+### RPC Functions
+
+**All RPCs follow the `<family>_<domain>_<verb>` naming convention:**
 
 ```sql
--- Insert file reference
-SELECT insert_file_reference(
-  'pace_person',           -- table_name
-  'person-uuid',           -- record_id
-  'org-123/profile_photos/file.jpg',  -- file_path
-  'org-uuid',              -- organisation_id
-  'app-uuid',              -- app_id
-  '{"fileName": "photo.jpg"}'::jsonb,  -- file_metadata
-  false                    -- is_public
+-- Create file reference (replaces insert_file_reference)
+SELECT data_file_reference_create(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_file_path := 'org-123/profile_photos/file.jpg',
+  p_organisation_id := 'org-uuid',
+  p_app_id := 'app-uuid',
+  p_file_metadata := '{"fileName": "photo.jpg"}'::jsonb,
+  p_category := 'profile_photos',
+  p_is_public := false
+);
+
+-- Get file URL (returns file_path for public files, NULL for private files)
+SELECT data_file_reference_url_get(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_organisation_id := 'org-uuid'
+);
+-- Note: Client generates public URL from returned file_path
+
+-- Get signed URL path for private files (client generates signed URL)
+SELECT data_file_reference_signed_url_get(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_organisation_id := 'org-uuid',
+  p_expires_in := 3600
 );
+-- Returns file_path - client uses getSignedUrl() helper to generate URL
 
--- Get file URL
-SELECT get_file_url('pace_person', 'person-uuid', 'org-uuid');
+-- Get file reference by ID
+SELECT data_file_reference_get(
+  p_file_reference_id := 'file-ref-uuid',
+  p_organisation_id := 'org-uuid'
+);
 
--- Get signed URL for private files
-SELECT get_file_signed_url('pace_person', 'person-uuid', 'org-uuid', 3600);
+-- Get files by category
+SELECT data_file_reference_by_category_list(
+  p_table_name := 'event',
+  p_record_id := 'event-uuid',
+  p_category := 'event_logos',
+  p_organisation_id := 'org-uuid'
+);
 
 -- Delete file reference
-SELECT delete_file_reference('pace_person', 'person-uuid', 'org-uuid', true);
+SELECT data_file_reference_delete(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_organisation_id := 'org-uuid',
+  p_delete_file := true
+);
 
--- List files for a record
-SELECT * FROM get_record_files('pace_person', 'person-uuid', 'org-uuid');
+-- List files for a record (replaces get_record_files)
+SELECT * FROM data_file_reference_list(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_organisation_id := 'org-uuid'
+);
 
--- Get file count for a record
-SELECT get_record_file_count('pace_person', 'person-uuid', 'org-uuid');
+-- Get file count for a record (replaces get_record_file_count)
+SELECT data_file_reference_count_get(
+  p_table_name := 'pace_person',
+  p_record_id := 'person-uuid',
+  p_organisation_id := 'org-uuid'
+);
 ```
 
+**Important Notes:**
+- RPCs return `file_path` and `is_public` status
+- Client-side helpers (`getPublicUrl`, `getSignedUrl`) generate the actual URLs
+- This architecture separates database operations (access control) from URL generation (client-side)
+
 ## Migration from Old System
 
 ### Before (Old Pattern)
@@ -226,10 +480,10 @@ interface Person {
   profile_photo_url: string; // Direct URL
 }
 
-// Manual file management
+// Manual file management with hardcoded bucket
 const uploadFile = async (file: File) => {
   const { data } = await supabase.storage
-    .from('files')
+    .from('files') // Hardcoded bucket
     .upload(`org-123/profile_photos/${file.name}`, file);
   
   await supabase
@@ -237,18 +491,25 @@ const uploadFile = async (file: File) => {
     .update({ profile_photo_url: data.path })
     .eq('id', personId);
 };
+
+// Manual URL generation
+const getPhotoUrl = async () => {
+  const { data } = await supabase.storage
+    .from('files')
+    .getPublicUrl(photoPath); // Doesn't handle signed URLs
+};
 ```
 
 ### After (New Pattern)
 ```typescript
-// File reference system
+// File reference system - no URL columns needed
 interface Person {
   id: string;
   name: string;
   // profile_photo_url removed - use file_references table
 }
 
-// Centralized file management
+// Centralized file management with bucket selection
 const { uploadFile } = useFileReference(supabase);
 
 const handleUpload = async (file: File) => {
@@ -257,11 +518,32 @@ const handleUpload = async (file: File) => {
     record_id: personId,
     organisation_id: orgId,
     app_id: 'your-app-id',
-    category: FileCategory.PROFILE_PHOTOS
+    category: FileCategory.PROFILE_PHOTOS,
+    is_public: false // Automatically uses 'files' bucket
   }, file);
 };
+
+// Automatic URL generation with bucket selection
+const { fileUrl } = useFileReferenceForRecord(
+  supabase,
+  'pace_person',
+  personId,
+  orgId
+);
+// Automatically uses correct bucket and URL type (public or signed)
 ```
 
+### Key Migration Benefits
+
+1. **Bucket-Aware Storage**: No need to manually select buckets
+2. **Automatic URL Generation**: Client helpers handle public vs signed URLs
+3. **Unified Access Control**: RLS policies apply to all file references
+4. **Consistent Metadata**: All files tracked with rich metadata
+5. **Easy Cleanup**: Identify orphaned files easily
+6. **App ID Auto-Resolution**: No need to hardcode app IDs in components
+7. **Memory Leak Prevention**: Automatic cleanup and cache management
+8. **Enhanced Error Handling**: Comprehensive error messages and recovery
+
 ## Storage Management
 
 ### Audit Orphaned Files
@@ -295,16 +577,36 @@ All file references are protected by RLS policies:
 - Service role has full access for administrative operations
 - File paths are validated to prevent directory traversal
 
-### Access Control
+### Access Control and URL Generation
 
-```typescript
-// Public files - accessible via public URL
-const publicUrl = getPublicUrl(filePath);
+The system automatically handles URL generation based on file visibility:
 
-// Private files - require signed URL
-const signedUrl = await getSignedUrl(supabase, filePath, { expiresIn: 3600 });
+```typescript
+import { getPublicUrl, getSignedUrl, getBucketName } from '@jmruthers/pace-core';
+
+// Public files - accessible via direct public URL
+const publicPath = 'org-123/event_logos/logo.png';
+const publicUrl = getPublicUrl(supabase, publicPath, true);
+// Uses 'public-files' bucket automatically
+
+// Private files - require signed URL with expiration
+const privatePath = 'org-123/profile_photos/photo.jpg';
+const signedUrlResult = await getSignedUrl(supabase, privatePath, {
+  appName: 'pace-core',
+  orgId: 'org-123',
+  expiresIn: 3600 // 1 hour
+});
+// Uses 'files' bucket automatically and generates signed URL
+
+// Bucket selection helper
+const bucket = getBucketName(isPublic); // 'public-files' or 'files'
 ```
 
+**URL Refresh for Signed URLs:**
+- Signed URLs expire after the specified duration (default: 1 hour)
+- The `useFileReferenceForRecord` hook automatically refreshes signed URLs before expiration
+- Refresh happens 5 minutes before expiration (at 55 minutes into the 1-hour expiry)
+
 ## Best Practices
 
 ### 1. Use Appropriate Categories
@@ -351,14 +653,78 @@ useEffect(() => {
 />
 ```
 
+## Recent Improvements
+
+### Performance & Memory Management
+- **Fixed infinite logging loops**: Removed debug logging that was causing performance issues
+- **Memory leak prevention**: Added automatic cleanup in hooks and components
+- **Cache management**: Implemented cache size limits and TTL for event logos
+- **Optimized re-renders**: Fixed infinite re-render loops in FileDisplay component
+
+### Enhanced User Experience
+- **App ID auto-resolution**: FileUpload component now automatically resolves app_id from app name
+- **Better error handling**: More descriptive error messages and graceful failure handling
+- **Progress tracking**: Enhanced upload progress with visual feedback
+- **Event context integration**: Event logos now automatically sync with selected events
+
+### Security & Reliability
+- **RLS policy fixes**: Resolved permission issues for file uploads
+- **Organisation context**: Proper database session context setting
+- **Super admin support**: Enhanced permissions for administrative users
+- **Bucket validation**: Improved bucket selection and validation logic
+
 ## Troubleshooting
 
 ### Common Issues
 
-1. **File not found**: Check if file reference exists in database
-2. **Access denied**: Verify user has access to organization
-3. **Upload fails**: Check file size limits and storage permissions
-4. **Signed URL expired**: Refresh signed URL for private files
+1. **File not found**
+   - Check if file reference exists in `file_references` table
+   - Verify `file_path` is correct in the database
+   - Check if file exists in the correct bucket (`files` vs `public-files`)
+
+2. **Access denied / RLS policy violation**
+   - Verify user has access to organisation (check RLS policies)
+   - Check if file reference `organisation_id` matches user's organisation
+   - Ensure RLS policies are correctly set up
+   - For super admins, verify `rbac_global_roles` table entry
+
+3. **Upload fails**
+   - Check file size limits (default: 10MB, configurable)
+   - Verify storage bucket permissions
+   - Check file type validation (if `accept` prop is specified)
+   - Review browser console for detailed error messages
+   - Ensure organisation context is properly set
+
+4. **App ID resolution failed**
+   - Ensure app name is set via `setRBACAppName()` or provide `app_id` prop
+   - Check that app exists in `rbac_apps` table
+   - Verify app name matches exactly (case-sensitive)
+
+5. **Memory issues / infinite re-renders**
+   - Use `clearEventLogoCache()` when unmounting components
+   - Check for dependency loops in useEffect hooks
+   - Ensure proper cleanup in component unmount effects
+
+6. **Signed URL expired**
+   - Signed URLs expire after 1 hour by default
+   - Use `useFileReferenceForRecord` hook for automatic refresh
+   - Or manually refresh using `getSignedUrl()` helper
+
+7. **Wrong bucket being used**
+   - Check `is_public` flag in file reference
+   - Verify `isPublic` prop in `FileUpload` component
+   - Use `getBucketName()` helper to verify bucket selection
+
+8. **Public files not accessible**
+   - Ensure file is in `public-files` bucket
+   - Verify `is_public = true` in `file_references` table
+   - Check storage bucket public access policies
+
+9. **URL generation fails**
+   - Verify Supabase client is properly configured
+   - Check network connectivity
+   - Review browser console for errors
+   - Ensure file path is correctly formatted
 
 ### Debug Mode
 
@@ -367,6 +733,49 @@ Enable debug logging to troubleshoot issues:
 ```typescript
 // Set debug mode in your app
 localStorage.setItem('pace-core-debug', 'true');
+
+// Or enable in specific components
+<FileUpload
+  // ... other props
+  onUploadError={(error, file) => {
+    console.error('Upload error:', error, file);
+    // Additional error handling
+  }}
+/>
+```
+
+### Checking File Reference Status
+
+```typescript
+// Check file reference in database
+const { data, error } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId)
+  .eq('organisation_id', orgId);
+
+console.log('File references:', data);
+console.log('Is public:', data[0]?.is_public);
+console.log('Bucket:', data[0]?.is_public ? 'public-files' : 'files');
+```
+
+### Verifying Storage Bucket
+
+```typescript
+import { getBucketName } from '@jmruthers/pace-core';
+
+// Check which bucket should be used
+const isPublic = true; // or false
+const bucket = getBucketName(isPublic);
+console.log('Using bucket:', bucket); // 'public-files' or 'files'
+
+// List files in bucket
+const { data, error } = await supabase.storage
+  .from(bucket)
+  .list('org-123/profile_photos');
+
+console.log('Files in bucket:', data);
 ```
 
 ## API Reference
@@ -410,32 +819,157 @@ interface FileMetadata {
 
 ### Step 1: Database Migration
 Run the migration scripts in order:
+
+**Latest Migration (Required for bucket support):**
+1. `20251030124830_refactor_file_reference_rpc_functions.sql`
+   - Renames RPCs to follow `<family>_<domain>_<verb>` convention
+   - Adds bucket-aware functions
+   - Updates security checks
+
+**Previous Migrations (if not already applied):**
 1. `20250202030001_add_file_references_indexes_and_functions.sql`
 2. `20250202030002_migrate_file_columns_to_file_references.sql`
 3. `20250202030003_drop_old_file_columns.sql`
 4. `20250202030004_drop_old_file_columns_final.sql`
 
 ### Step 2: Update Application Code
-Replace direct file URL usage with file reference system:
 
+**Replace Direct File URL Usage:**
 ```typescript
 // Old
 const profilePhoto = person.profile_photo_url;
+<img src={profilePhoto} />
 
 // New
-const { fileUrl } = useFileReferenceForRecord(supabase, 'pace_person', personId, orgId);
+const { fileUrl } = useFileReferenceForRecord(
+  supabase, 
+  'pace_person', 
+  personId, 
+  orgId
+);
+<img src={fileUrl || fallback} />
+```
+
+**Update File Upload Code:**
+```typescript
+// Old - Manual bucket selection
+const { data } = await supabase.storage
+  .from('files')
+  .upload(path, file);
+
+// New - Automatic bucket selection
+const { uploadFile } = useFileReference(supabase);
+await uploadFile({
+  table_name: 'pace_person',
+  record_id: personId,
+  organisation_id: orgId,
+  app_id: appId,
+  category: FileCategory.PROFILE_PHOTOS,
+  is_public: false // Automatically uses correct bucket
+}, file);
 ```
 
-### Step 3: Test and Verify
-1. Test file uploads and downloads
-2. Verify RLS policies work correctly
-3. Run audit script to check for orphaned files
-4. Clean up any issues found
+**Migrate Public Files:**
+```typescript
+// If migrating event logos or other public files
+await uploadFile({
+  // ... other options
+  category: FileCategory.EVENT_LOGOS,
+  is_public: true // Uses 'public-files' bucket
+}, logoFile);
+```
 
-### Step 4: Cleanup
-Run the cleanup migration:
+### Step 3: Update RPC Function Calls
+
+**Old RPC Names (deprecated):**
+- `insert_file_reference` → `data_file_reference_create`
+- `get_file_url` → `data_file_reference_url_get`
+- `get_file_signed_url` → `data_file_reference_signed_url_get`
+- `delete_file_reference` → `data_file_reference_delete`
+- `get_record_files` → `data_file_reference_list`
+- `get_record_file_count` → `data_file_reference_count_get`
+
+**New RPC Names:**
+```typescript
+// Use the service layer instead of direct RPC calls
+const service = createFileReferenceService(supabase);
+
+// Old direct RPC call
+await supabase.rpc('get_file_url', { /* ... */ });
+
+// New service method (recommended)
+const url = await service.getFileUrl(table_name, record_id, org_id);
+```
+
+### Step 4: Verify Bucket Configuration
+
+1. **Check existing file references:**
+   ```sql
+   SELECT 
+     id,
+     file_path,
+     is_public,
+     CASE 
+       WHEN is_public THEN 'public-files'
+       ELSE 'files'
+     END as bucket
+   FROM file_references
+   WHERE organisation_id = 'your-org-id';
+   ```
+
+2. **Ensure files are in correct buckets:**
+   - Files with `is_public = true` should be in `public-files` bucket
+   - Files with `is_public = false` should be in `files` bucket
+
+3. **Migrate files if needed:**
+   ```typescript
+   // If you find files in wrong bucket, use storage helpers to move them
+   import { uploadFile, deleteFile } from '@jmruthers/pace-core';
+   
+   // Read from old bucket and upload to correct bucket
+   const { data: fileBlob } = await supabase.storage
+     .from('wrong-bucket')
+     .download(oldPath);
+   
+   await uploadFile(supabase, fileBlob, {
+     orgId,
+     isPublic: true, // or false
+     customPath: category
+   });
+   ```
+
+### Step 5: Test and Verify
+
+1. **Test file uploads:**
+   - Upload private file (should use `files` bucket)
+   - Upload public file (should use `public-files` bucket)
+   - Verify file reference is created correctly
+
+2. **Test file access:**
+   - Access private file (should generate signed URL)
+   - Access public file (should use public URL)
+   - Verify URLs are correct format
+
+3. **Verify RLS policies:**
+   - Test access from different organizations
+   - Verify access is denied for unauthorized users
+   - Check public files are accessible without auth
+
+4. **Run audit script:**
+   ```bash
+   node scripts/audit-storage-files.js
+   ```
+
+### Step 6: Cleanup
+
+Run the cleanup migration (if applicable):
 - `20250202040001_cleanup_migration_tables.sql`
 
+**Remove old code:**
+- Remove direct storage bucket references
+- Remove manual URL generation code
+- Remove deprecated RPC function calls
+
 ## Support
 
 For issues or questions about the File Reference System: