feat: profile photo maps to user_document_links, enhanced initial health check for supabase buckets, added smart fallback with force_provider support

docs/DOCUMENT_MANAGEMENT.md

@@ -34,13 +34,19 @@ Return document metadata to user
 
 ## Storage Routing Rules
 
-| File Type | Storage Provider | Folder/Bucket |
-|-----------|-----------------|---------------|
-| `image/*` | Cloudinary | `/swiftops/users/`, `/swiftops/tickets/`, etc. |
-| `video/*` | Cloudinary | `/swiftops/users/`, `/swiftops/tickets/`, etc. |
-| `application/pdf` | Supabase | `documents-users`, `documents-tickets`, etc. |
-| `application/*` | Supabase | `documents-users`, `documents-tickets`, etc. |
-| Other | Supabase | `documents-general` |
+The system automatically routes files based on optimization, not capability:
+
+| File Type | Default Provider | Reason | Alternative |
+|-----------|-----------------|--------|-------------|
+| `image/*` | **Cloudinary** | CDN delivery, auto-optimization, transformations | Supabase can also store images |
+| `video/*` | **Cloudinary** | Streaming, transcoding, adaptive bitrate | Supabase can also store videos |
+| `application/pdf` | **Supabase** | Cost-effective, simple storage | N/A |
+| `application/*` | **Supabase** | General documents (DOCX, XLSX, etc.) | N/A |
+| Other | **Supabase** | Fallback for all other file types | N/A |
+
+**Note**: Both providers can technically store any file type. The routing is based on optimization:
+- **Cloudinary**: Best for media that needs CDN delivery and transformations
+- **Supabase**: Best for documents and general file storage
 
 ## Database Schema
 

src/app/api/v1/documents.py

@@ -10,6 +10,7 @@ from uuid import UUID
 from app.api.deps import get_db, get_current_active_user
 from app.models.user import User
 from app.models.document import Document
+from app.models.user_document_link import UserDocumentLink
 from app.schemas.document import (
     DocumentResponse,
     DocumentListResponse,
@@ -18,6 +19,7 @@ from app.schemas.document import (
 )
 from app.services.media_service import StorageService
 from app.services.audit_service import AuditService
+from datetime import datetime
 import logging
 import json
 
@@ -39,18 +41,25 @@ async def upload_document(
     description: Optional[str] = Form(None),
     tags: Optional[str] = Form("[]"),  # JSON string of array
     is_public: bool = Form(False),
+    force_provider: Optional[str] = Form(None),  # Optional: 'cloudinary' or 'supabase'
     request: Request = None,
     current_user: User = Depends(get_current_active_user),
     db: Session = Depends(get_db)
 ):
     """
-    Universal document upload endpoint
+    Universal document upload endpoint with smart fallback
     
-    Automatically routes to:
-    - Cloudinary for images and videos
-    - Supabase Storage for documents (PDF, DOCX, etc.)
+    Default routing:
+    - Images/videos → Cloudinary (with Supabase fallback)
+    - Documents → Supabase Storage
     
-    Supports all entity types: user, project, ticket, client, contractor, etc.
+    Features:
+    - Automatic fallback if primary provider fails
+    - Optional provider override via force_provider parameter
+    - Supports all entity types: user, project, ticket, client, contractor, etc.
+    
+    Parameters:
+    - force_provider: Optional override ('cloudinary' or 'supabase')
     """
     try:
         # Parse tags from JSON string
@@ -63,6 +72,13 @@ async def upload_document(
                 detail="No file provided"
             )
         
+        # Validate force_provider if provided
+        if force_provider and force_provider not in ['cloudinary', 'supabase']:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="force_provider must be 'cloudinary' or 'supabase'"
+            )
+        
         # Upload file
         document = await StorageService.upload_file(
             file=file,
@@ -74,9 +90,35 @@ async def upload_document(
             tags=tags_list,
             is_public=is_public,
             uploaded_by_user_id=current_user.id,
-            db=db
+            db=db,
+            force_provider=force_provider
         )
         
+        # Create user_document_link for user documents
+        if entity_type == 'user':
+            # Check if link already exists for this document type
+            existing_link = db.query(UserDocumentLink).filter(
+                UserDocumentLink.user_id == entity_id,
+                UserDocumentLink.document_link_type == document_type
+            ).first()
+            
+            if existing_link:
+                # Update existing link to point to new document
+                existing_link.document_id = document.id
+                existing_link.updated_at = datetime.utcnow().isoformat()
+            else:
+                # Create new link
+                doc_link = UserDocumentLink(
+                    user_id=entity_id,
+                    document_id=document.id,
+                    document_link_type=document_type,
+                    notes=description
+                )
+                db.add(doc_link)
+            
+            db.commit()
+            logger.info(f"Created user_document_link for {document_type}")
+        
         # Audit log
         AuditService.log_action(
             db=db,
@@ -322,3 +364,47 @@ async def get_user_documents(
         current_user=current_user,
         db=db
     )
+
+
+@router.get("/users/{user_id}/profile-photo", response_model=Optional[DocumentResponse])
+async def get_user_profile_photo(
+    user_id: UUID,
+    current_user: User = Depends(get_current_active_user),
+    db: Session = Depends(get_db)
+):
+    """
+    Get user's profile photo (convenience endpoint)
+    
+    Uses user_document_links for fast lookup
+    """
+    # Get profile photo link
+    doc_link = db.query(UserDocumentLink).filter(
+        UserDocumentLink.user_id == user_id,
+        UserDocumentLink.document_link_type == 'profile_photo'
+    ).first()
+    
+    if not doc_link:
+        return None
+    
+    # Get document
+    document = db.query(Document).filter(
+        Document.id == doc_link.document_id,
+        Document.deleted_at == None
+    ).first()
+    
+    if not document:
+        return None
+    
+    response = DocumentResponse.from_orm(document)
+    
+    # Add uploader info
+    if document.uploaded_by_user_id:
+        uploader = db.query(User).filter(User.id == document.uploaded_by_user_id).first()
+        if uploader:
+            response.uploader = UploaderInfo(
+                id=uploader.id,
+                name=uploader.name,
+                email=uploader.email
+            )
+    
+    return response

src/app/core/health_checks.py

@@ -113,7 +113,7 @@ def check_supabase_storage() -> Dict[str, Any]:
     Returns:
         dict: Status information
     """
-    if not all([settings.SUPABASE_URL, settings.SUPABASE_KEY]):
+    if not all([settings.SUPABASE_URL, settings.SUPABASE_SERVICE_KEY]):
         return {
             "configured": False,
             "status": "Not configured",
@@ -123,8 +123,8 @@ def check_supabase_storage() -> Dict[str, Any]:
     try:
         from supabase import create_client
         
-        # Create Supabase client
-        supabase = create_client(settings.SUPABASE_URL, settings.SUPABASE_KEY)
+        # Create Supabase client with service role key (has permission to list buckets)
+        supabase = create_client(settings.SUPABASE_URL, settings.SUPABASE_SERVICE_KEY)
         
         # Test by listing buckets (read-only operation)
         buckets = supabase.storage.list_buckets()
@@ -132,14 +132,16 @@ def check_supabase_storage() -> Dict[str, Any]:
         return {
             "configured": True,
             "status": "Connected",
-            "buckets": len(buckets),
-            "message": f"Supabase Storage accessible ({len(buckets)} buckets)"
+            "buckets": len(buckets) if buckets else 0,
+            "bucket_names": [b.get('name') for b in buckets] if buckets else [],
+            "message": f"Supabase Storage accessible ({len(buckets) if buckets else 0} buckets)"
         }
         
     except Exception as e:
         return {
             "configured": True,
             "status": "Failed",
+            "buckets": 0,
             "message": f"Connection failed: {str(e)}"
         }
 

src/app/main.py

@@ -156,7 +156,10 @@ async def startup_event():
         if storage["configured"]:
             logger.info(f"  Supabase Storage: {storage['status']}")
             if storage["status"] == "Connected":
-                logger.info(f"    Buckets: {storage.get('buckets', 0)}")
+                bucket_count = storage.get('buckets', 0)
+                logger.info(f"    Buckets: {bucket_count}")
+                if bucket_count > 0 and storage.get('bucket_names'):
+                    logger.info(f"    Names: {', '.join(storage['bucket_names'])}")
             else:
                 logger.info(f"    Note: {storage['message']}")
         

src/app/services/media_service.py

@@ -17,19 +17,32 @@ logger = logging.getLogger(__name__)
 
 
 class StorageService:
-    """Universal storage service that routes to appropriate provider"""
+    """Universal storage service that routes to appropriate provider with fallback support"""
     
     @staticmethod
-    def determine_provider(file_type: str) -> str:
+    def determine_provider(file_type: str, force_provider: str = None) -> str:
         """
-        Determine storage provider based on file type
+        Determine storage provider based on file type with optional override
         
-        Rules:
-        - Images (image/*) → Cloudinary
-        - Videos (video/*) → Cloudinary
+        Args:
+            file_type: MIME type of the file
+            force_provider: Optional override ('cloudinary' or 'supabase')
+        
+        Rules (when no override):
+        - Images (image/*) → Cloudinary (optimized for media)
+        - Videos (video/*) → Cloudinary (optimized for media)
         - Documents (application/pdf, docx, etc.) → Supabase
         - Everything else → Supabase
+        
+        Returns:
+            'cloudinary' or 'supabase'
         """
+        # Allow manual override
+        if force_provider in ['cloudinary', 'supabase']:
+            logger.info(f"Using forced provider: {force_provider}")
+            return force_provider
+        
+        # Default routing based on file type
         if file_type.startswith('image/') or file_type.startswith('video/'):
             return 'cloudinary'
         return 'supabase'
@@ -45,16 +58,18 @@ class StorageService:
         tags: list,
         is_public: bool,
         uploaded_by_user_id: UUID,
-        db: Session
+        db: Session,
+        force_provider: str = None
     ) -> Document:
         """
-        Universal file upload handler
+        Universal file upload handler with automatic fallback
         
         Workflow:
-        1. Determine storage provider based on file type
-        2. Upload to appropriate provider
-        3. Create document record in database
-        4. Return document object
+        1. Determine storage provider based on file type (or use override)
+        2. Try to upload to primary provider
+        3. If primary fails, automatically fallback to alternative provider
+        4. Create document record in database
+        5. Return document object
         
         Args:
             file: The file to upload
@@ -67,31 +82,70 @@ class StorageService:
             is_public: Whether document is public
             uploaded_by_user_id: ID of user uploading
             db: Database session
+            force_provider: Optional provider override ('cloudinary' or 'supabase')
         
         Returns:
             Document object
         
         Raises:
-            HTTPException: If upload fails
+            HTTPException: If both providers fail
         """
         try:
-            # Determine provider
-            provider = StorageService.determine_provider(file.content_type)
+            # Determine primary provider
+            provider = StorageService.determine_provider(file.content_type, force_provider)
             
             logger.info(f"Uploading {file.filename} ({file.content_type}) to {provider}")
             
-            # Upload to appropriate provider
+            # Try primary provider with fallback
+            upload_result = None
+            file_url = None
+            file_size = None
+            additional_metadata = {}
+            
             if provider == 'cloudinary':
-                upload_result = await CloudinaryService.upload(
-                    file=file,
-                    entity_type=entity_type,
-                    entity_id=str(entity_id),
-                    document_type=document_type
-                )
-                file_url = upload_result['secure_url']
-                file_size = upload_result.get('bytes')
-                additional_metadata = upload_result
+                try:
+                    upload_result = await CloudinaryService.upload(
+                        file=file,
+                        entity_type=entity_type,
+                        entity_id=str(entity_id),
+                        document_type=document_type
+                    )
+                    file_url = upload_result['secure_url']
+                    file_size = upload_result.get('bytes')
+                    additional_metadata = upload_result
+                    
+                except Exception as cloudinary_error:
+                    logger.warning(f"Cloudinary upload failed: {cloudinary_error}")
+                    logger.info("Falling back to Supabase Storage...")
+                    
+                    # Fallback to Supabase
+                    try:
+                        # Reset file pointer for retry
+                        await file.seek(0)
+                        
+                        upload_result = await SupabaseStorageService.upload(
+                            file=file,
+                            entity_type=entity_type,
+                            entity_id=str(entity_id),
+                            document_type=document_type
+                        )
+                        file_url = upload_result['public_url']
+                        file_size = upload_result.get('size')
+                        additional_metadata = upload_result
+                        additional_metadata['fallback'] = True
+                        additional_metadata['primary_provider_error'] = str(cloudinary_error)
+                        provider = 'supabase'  # Update provider to reflect actual storage
+                        
+                        logger.info("Successfully uploaded to Supabase (fallback)")
+                        
+                    except Exception as supabase_error:
+                        logger.error(f"Supabase fallback also failed: {supabase_error}")
+                        raise HTTPException(
+                            status_code=500,
+                            detail=f"Both storage providers failed. Cloudinary: {cloudinary_error}. Supabase: {supabase_error}"
+                        )
             else:
+                # Primary is Supabase
                 upload_result = await SupabaseStorageService.upload(
                     file=file,
                     entity_type=entity_type,

tests/integration/test_document_upload.js

@@ -2,12 +2,13 @@
 
 /**
  * Document Upload Test
- * Tests universal document management system
+ * Tests universal document management system with storage provider selection
  */
 
 const https = require('https');
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
 
 const BASE_URL = 'https://kamau1-swiftops-backend.hf.space';
 const ADMIN_EMAIL = 'lewis.kamau421@gmail.com';
@@ -18,6 +19,7 @@ const TEST_IMAGE_PATH = path.join(__dirname, '../images/lesley.jpg');
 let adminToken = null;
 let lesleyUserId = null;
 let documentId = null;
+let selectedProvider = null;
 
 const colors = {
     reset: '\x1b[0m',
@@ -172,39 +174,126 @@ async function step2_GetLesleyUserId() {
     }
 }
 
-async function step3_UploadProfilePhoto() {
-    log('\n📸 Step 3: Upload Profile Photo', 'blue');
+async function step3_UploadDocument() {
+    const providerName = selectedProvider === '1' ? 'Supabase' : 'Cloudinary';
+    log(`\n📤 Step 3: Upload Document (${providerName})`, 'blue');
 
     try {
-        // Read test image
-        const imageBuffer = fs.readFileSync(TEST_IMAGE_PATH);
+        let fileBuffer, fileName, contentType, documentType, description;
+        
+        if (selectedProvider === '1') {
+            // Supabase - Upload a PDF (create a dummy PDF for testing)
+            log('   Creating test PDF document...', 'cyan');
+            // Simple PDF content (minimal valid PDF)
+            const pdfContent = `%PDF-1.4
+1 0 obj
+<<
+/Type /Catalog
+/Pages 2 0 R
+>>
+endobj
+2 0 obj
+<<
+/Type /Pages
+/Kids [3 0 R]
+/Count 1
+>>
+endobj
+3 0 obj
+<<
+/Type /Page
+/Parent 2 0 R
+/Resources <<
+/Font <<
+/F1 <<
+/Type /Font
+/Subtype /Type1
+/BaseFont /Helvetica
+>>
+>>
+>>
+/MediaBox [0 0 612 792]
+/Contents 4 0 R
+>>
+endobj
+4 0 obj
+<<
+/Length 44
+>>
+stream
+BT
+/F1 12 Tf
+100 700 Td
+(Test Document) Tj
+ET
+endstream
+endobj
+xref
+0 5
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+0000000317 00000 n 
+trailer
+<<
+/Size 5
+/Root 1 0 R
+>>
+startxref
+410
+%%EOF`;
+            fileBuffer = Buffer.from(pdfContent);
+            fileName = 'test_contract.pdf';
+            contentType = 'application/pdf';
+            documentType = 'contract';
+            description = 'Test contract document (Supabase Storage)';
+        } else {
+            // Cloudinary - Upload the image
+            fileBuffer = fs.readFileSync(TEST_IMAGE_PATH);
+            fileName = 'lesley.jpg';
+            contentType = 'image/jpeg';
+            documentType = 'profile_photo';
+            description = 'Lesley profile photo (Cloudinary)';
+        }
         
         // Prepare form data
         const formData = {
             file: {
-                filename: 'lesley.jpg',
-                contentType: 'image/jpeg',
-                content: imageBuffer
+                filename: fileName,
+                contentType: contentType,
+                content: fileBuffer
             },
             entity_type: 'user',
             entity_id: lesleyUserId,
-            document_type: 'profile_photo',
-            document_category: 'personal',
-            description: 'Lesley profile photo',
-            tags: '["profile", "avatar"]',
-            is_public: 'true'
+            document_type: documentType,
+            document_category: selectedProvider === '1' ? 'legal' : 'personal',
+            description: description,
+            tags: selectedProvider === '1' ? '["contract", "legal"]' : '["profile", "avatar"]',
+            is_public: 'false',
+            force_provider: selectedProvider === '1' ? 'supabase' : 'cloudinary'
         };
 
         const response = await makeMultipartRequest('POST', '/api/v1/documents/upload', formData, adminToken);
 
         if (response.status === 201) {
             documentId = response.data.id;
-            log('✅ Profile photo uploaded', 'green');
+            log('✅ Document uploaded successfully', 'green');
             log(`   Document ID: ${documentId}`);
             log(`   File: ${response.data.file_name}`);
-            log(`   Storage: ${response.data.storage_provider}`);
-            log(`   URL: ${response.data.file_url.substring(0, 50)}...`);
+            log(`   Type: ${response.data.document_type}`);
+            log(`   Storage: ${response.data.storage_provider}`, 'magenta');
+            log(`   URL: ${response.data.file_url.substring(0, 60)}...`);
             log(`   Size: ${(response.data.file_size / 1024).toFixed(2)} KB`);
+            
+            // Verify correct storage provider
+            const expectedProvider = selectedProvider === '1' ? 'supabase' : 'cloudinary';
+            if (response.data.storage_provider === expectedProvider) {
+                log(`   ✓ Routed to correct provider: ${expectedProvider}`, 'green');
+            } else {
+                log(`   ✗ Wrong provider! Expected ${expectedProvider}, got ${response.data.storage_provider}`, 'red');
+            }
+            
             return true;
         } else {
             log(`❌ Upload failed: ${response.status}`, 'red');
@@ -291,10 +380,54 @@ async function step6_UpdateDocumentMetadata() {
     }
 }
 
+function promptStorageProvider() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout
+        });
+
+        console.log('\n' + '='.repeat(70));
+        console.log('📦 Storage Provider Selection');
+        console.log('='.repeat(70));
+        console.log('');
+        console.log('Choose storage provider to test:');
+        console.log('');
+        console.log('  1️⃣  Supabase Storage');
+        console.log('      • General-purpose storage (PDFs, images, any file type)');
+        console.log('      • Test with: PDF document');
+        console.log('');
+        console.log('  2️⃣  Cloudinary');
+        console.log('      • Optimized for images/videos (CDN, transformations)');
+        console.log('      • Test with: JPEG image');
+        console.log('');
+        console.log('Note: Both can store images, but Cloudinary is optimized for media.');
+        console.log('');
+
+        rl.question('Enter your choice (1 or 2): ', (answer) => {
+            rl.close();
+            const choice = answer.trim();
+            if (choice === '1' || choice === '2') {
+                resolve(choice);
+            } else {
+                console.log('\n❌ Invalid choice. Please run again and select 1 or 2.');
+                process.exit(1);
+            }
+        });
+    });
+}
+
 async function runTest() {
-    log('='.repeat(70), 'blue');
+    // Prompt for storage provider
+    selectedProvider = await promptStorageProvider();
+    
+    const providerName = selectedProvider === '1' ? 'Supabase Storage' : 'Cloudinary';
+    const fileType = selectedProvider === '1' ? 'PDF document' : 'Image (JPEG)';
+    
+    log('\n' + '='.repeat(70), 'blue');
     log('📁 Document Upload Test', 'blue');
-    log('   Testing: Universal document management system', 'cyan');
+    log(`   Provider: ${providerName}`, 'magenta');
+    log(`   File Type: ${fileType}`, 'cyan');
     log('='.repeat(70), 'blue');
 
     const results = [];
@@ -313,7 +446,7 @@ async function runTest() {
     results.push({ name: 'Get User ID', status: true });
 
     // Document Tests
-    results.push({ name: 'Upload Profile Photo', status: await step3_UploadProfilePhoto() });
+    results.push({ name: 'Upload Document', status: await step3_UploadDocument() });
     results.push({ name: 'Get Documents', status: await step4_GetDocuments() });
     results.push({ name: 'Get Single Document', status: await step5_GetSingleDocument() });
     results.push({ name: 'Update Metadata', status: await step6_UpdateDocumentMetadata() });
@@ -335,13 +468,15 @@ async function runTest() {
     log(`Total: ${results.length} | Passed: ${passed} | Failed: ${failed}`);
 
     if (failed === 0) {
+        const providerName = selectedProvider === '1' ? 'Supabase Storage' : 'Cloudinary';
         log('\n🎉 All tests passed!', 'green');
         log(`\n✨ Document system is working perfectly!`, 'magenta');
+        log(`   Storage Provider: ${providerName}`, 'magenta');
         log(`   User ID: ${lesleyUserId}`, 'magenta');
         if (documentId) {
             log(`   Document ID: ${documentId}`, 'magenta');
         }
-        log(`   Test image: ${TEST_IMAGE_PATH}`, 'magenta');
+        log(`\n💡 Tip: Run the test again and select the other provider!`, 'cyan');
     } else {
         log(`\n⚠️  ${failed} step(s) failed`, 'red');
     }