LinkDesk/backend/docs/file_handling.md

File Handling System Documentation

Overview

The VFX Project Management System includes a comprehensive file handling system that provides secure file upload, storage, serving, and access control for task attachments and work submissions.

Features

File Upload System

• Secure file validation with format and size restrictions
• Organized directory structure for efficient file storage
• Unique filename generation to prevent conflicts
• Automatic thumbnail generation for image files
• Version control for submissions

File Serving and Access Control

• Authenticated file serving with role-based permissions
• Thumbnail serving for quick previews
• Video streaming for media playback
• File information API for metadata access

Supported File Formats

Video Formats

• .mov - QuickTime Movie
• .mp4 - MPEG-4 Video
• .avi - Audio Video Interleave
• .mkv - Matroska Video
• .webm - WebM Video

Image Formats

• .exr - OpenEXR (High Dynamic Range)
• .jpg, .jpeg - JPEG Image
• .png - Portable Network Graphics
• .tiff, .tif - Tagged Image File Format
• .dpx - Digital Picture Exchange
• .hdr - High Dynamic Range Image

Document Formats

• .pdf - Portable Document Format
• .txt - Plain Text
• .doc, .docx - Microsoft Word Document

Archive Formats

• .zip - ZIP Archive
• .rar - RAR Archive
• .7z - 7-Zip Archive

File Size Limits

• Task Attachments: 10MB maximum
• Work Submissions: 500MB maximum

API Endpoints

File Upload Endpoints (via Tasks Router)

Upload Task Attachment

POST /tasks/{task_id}/attachments

• Uploads a file attachment to a task
• Creates thumbnail for image files
• Returns attachment metadata with serving URLs

Submit Work

POST /tasks/{task_id}/submit

• Submits work file for review
• Automatically versions submissions
• Updates task status to "submitted"

File Serving Endpoints

Serve Attachment

GET /files/attachments/{attachment_id}
GET /files/attachments/{attachment_id}?thumbnail=true

• Serves attachment files with access control
• Optional thumbnail parameter for image previews

Serve Submission

GET /files/submissions/{submission_id}
GET /files/submissions/{submission_id}?thumbnail=true

• Serves submission files with access control
• Optional thumbnail parameter for image previews

Stream Submission

GET /files/submissions/{submission_id}/stream

• Streams video files for playback
• Supports range requests for efficient streaming

File Information

GET /files/info/attachment/{attachment_id}
GET /files/info/submission/{submission_id}

• Returns file metadata and information
• Includes file type detection and existence status

Directory Structure

backend/uploads/
├── attachments/
│   └── {task_id}/
│       └── {unique_filename}
├── submissions/
│   └── {task_id}/
│       └── {versioned_filename}
└── thumbnails/
    └── {filename}_thumb.jpg

Access Control

Permission Matrix

User Role	Own Tasks	Other Tasks	Review Access
Artist	✓	✗	✗
Coordinator	✓	✓	✓
Director	✓	✓	✓
Admin	✓	✓	✓

Security Features

• Authentication required for all file operations
• Role-based access control for file serving
• File type validation to prevent malicious uploads
• File size limits to prevent abuse
• Unique filename generation to prevent conflicts
• Path traversal protection through controlled directory structure

File Handler Utility

The FileHandler class provides core functionality:

Key Methods

• validate_file() - Validates file format and size
• save_file() - Saves uploaded file with unique naming
• delete_file() - Removes file and associated thumbnail
• create_thumbnail() - Generates image thumbnails
• get_file_info() - Returns file metadata
• is_image_file() / is_video_file() - File type detection

Configuration

# File size limits
MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024  # 10MB
MAX_SUBMISSION_SIZE = 500 * 1024 * 1024  # 500MB

# Thumbnail settings
THUMBNAIL_SIZE = (200, 200)
THUMBNAIL_QUALITY = 85

Usage Examples

Frontend Integration

// Upload attachment
const formData = new FormData();
formData.append('file', file);
formData.append('attachment_type', 'reference');
formData.append('description', 'Reference image');

const response = await fetch(`/tasks/${taskId}/attachments`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const attachment = await response.json();
console.log('Download URL:', attachment.download_url);
console.log('Thumbnail URL:', attachment.thumbnail_url);

// Submit work
const formData = new FormData();
formData.append('file', workFile);
formData.append('notes', 'Final version ready for review');

const response = await fetch(`/tasks/${taskId}/submit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const submission = await response.json();
console.log('Stream URL:', submission.stream_url);

Error Handling

Common Error Responses

• 400 Bad Request - Invalid file format or missing filename
• 403 Forbidden - Insufficient permissions to access file
• 404 Not Found - File or associated task not found
• 413 Payload Too Large - File exceeds size limits

Error Response Format

{
  "detail": "File too large. Maximum size is 10MB"
}

Performance Considerations

• Chunked streaming for large video files
• On-demand thumbnail generation with caching
• Efficient file serving with proper MIME types
• Range request support for video streaming

Maintenance

File Cleanup

The system does not automatically clean up orphaned files. Consider implementing:

• Periodic cleanup of files without database references
• Archive old submissions after project completion
• Monitor disk usage and implement retention policies

Backup Considerations

• Include upload directories in backup procedures
• Consider separate backup strategy for large media files
• Implement file integrity checks for critical submissions