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

```python
# 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

```javascript
// 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);
```

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

```json
{
  "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