# Requirements Document

## Introduction

The VFX Project Management System currently stores absolute file paths in the database for submissions, attachments, and thumbnails. When deploying to Linux environments, these absolute paths become invalid, causing thumbnail URLs and file serving to fail. The system needs to store relative file paths and resolve them dynamically at runtime to ensure cross-platform compatibility.

## Glossary

- **File_Handler**: The utility class responsible for file upload, storage, and path management
- **Submission**: User-uploaded work files (videos, images) with version control
- **Attachment**: Supporting files attached to tasks (documents, references)
- **Thumbnail**: Generated preview images for visual files
- **Avatar**: User profile image stored in the system
- **Backend_Directory**: The root directory of the backend application
- **Relative_Path**: File path stored relative to the backend directory
- **Absolute_Path**: Complete file system path resolved at runtime

## Requirements

### Requirement 1

**User Story:** As a system administrator, I want to migrate existing database records with absolute file paths to relative paths, so that thumbnail URLs work correctly on Linux deployments.

#### Acceptance Criteria

1. WHEN the migration script processes the submissions table THEN it SHALL convert all file_path values from absolute to relative paths
2. WHEN the migration script processes the task_attachments table THEN it SHALL convert all file_path values from absolute to relative paths  
3. WHEN the migration script processes the projects table THEN it SHALL convert all thumbnail_path values from absolute to relative paths
4. WHEN the migration script processes the users table THEN it SHALL convert all avatar_url values from absolute to relative paths
5. WHEN the migration encounters a path that cannot be converted THEN it SHALL log the error and continue processing
6. WHEN the migration is complete THEN all file paths in the database SHALL be relative to the backend directory

### Requirement 2

**User Story:** As a system administrator, I want file paths to be stored relative to the backend directory, so that the application works correctly when deployed across different environments.

#### Acceptance Criteria

1. WHEN the system saves any file THEN the File_Handler SHALL store the file path relative to the Backend_Directory in the database
2. WHEN the system serves any file THEN the File_Handler SHALL resolve the relative path to an absolute path at runtime
3. WHEN the system creates any thumbnails THEN the thumbnail paths SHALL be stored relative to the Backend_Directory
4. WHEN the system migrates existing data THEN all absolute paths SHALL be converted to relative paths
5. WHEN the system validates file existence THEN it SHALL resolve relative paths to absolute paths for filesystem operations

### Requirement 2

**User Story:** As a developer, I want the FileHandler to only use relative path logic, so that the system is simplified and works consistently across all environments.

#### Acceptance Criteria

1. WHEN the system saves any file THEN it SHALL store only relative paths in the database
2. WHEN the system serves any file THEN it SHALL resolve relative paths to absolute paths for filesystem access
3. WHEN the system creates thumbnails THEN it SHALL store only relative paths for thumbnail locations
4. WHEN the system saves user avatars THEN it SHALL store only relative paths for avatar locations
5. WHEN the FileHandler validates file existence THEN it SHALL resolve relative paths to absolute paths
6. WHEN the system encounters any file path THEN it SHALL assume the path is relative to the backend directory

### Requirement 3

**User Story:** As a user, I want all thumbnail URLs (submissions, attachments, projects, and generated thumbnails) to work correctly on Linux deployments, so that I can preview uploaded files regardless of the deployment environment.

#### Acceptance Criteria

1. WHEN a user uploads any image file THEN the system SHALL generate a thumbnail with a relative path
2. WHEN a user uploads an avatar image THEN the system SHALL store the avatar with a relative path
3. WHEN the API returns any data with thumbnails or avatars THEN the URLs SHALL be accessible via the file serving endpoints
4. WHEN the file serving endpoint receives any thumbnail or avatar request THEN it SHALL resolve the relative path and serve the correct file
5. WHEN any thumbnail or avatar file is missing THEN the system SHALL return a 404 error with appropriate messaging

### Requirement 4

**User Story:** As a system administrator, I want to migrate existing database records to use relative paths only, so that the system is simplified and works consistently across all deployments.

#### Acceptance Criteria

1. WHEN the migration script runs THEN it SHALL convert all absolute paths in the database to relative paths
2. WHEN the migration is complete THEN the system SHALL only use relative path logic for all file operations
3. WHEN the system processes any file path THEN it SHALL assume the path is relative to the Backend_Directory
4. WHEN the migration encounters invalid paths THEN it SHALL log errors but continue processing other records
5. WHEN the migration is complete THEN all file serving endpoints SHALL work with the converted relative paths
6. WHEN the migration processes avatar URLs THEN it SHALL convert them to relative paths and ensure avatar serving works correctly