directus-task-management/.taskmaster/docs/directus-flow-prd.txt

# Directus Flow Implementation PRD - YouTube Thumbnail Automation

## Project Overview
Implement a comprehensive Directus Flow system to automatically extract and populate YouTube thumbnails when media items are created or updated. This system will enhance the media management capabilities by automatically fetching high-quality thumbnails from YouTube videos.

## Business Requirements

### Primary Goals
1. Automatically extract YouTube video IDs from various URL formats
2. Download high-quality thumbnails from YouTube's CDN
3. Upload thumbnails to Directus file storage
4. Link thumbnails to media items in the database
5. Provide fallback mechanisms for failed downloads
6. Support multiple YouTube URL formats

### Success Criteria
- Flow triggers automatically on media item creation/update
- Thumbnails are successfully downloaded and stored
- Media items are updated with thumbnail references
- System handles various YouTube URL formats
- Error handling and logging are implemented
- Performance is optimized for production use

## Technical Requirements

### Directus Configuration
1. **Field Addition**: Add `youtube_thumbnail` field to `media_items` collection
   - Type: File
   - Interface: File (Image)
   - Required: No
   - Display: Thumbnail preview in layouts

2. **Flow Structure**: Create automated flow with three main operations
   - Trigger: Event Hook on media_items (Create/Update)
   - Filter: Only process items with type = "youtube_video" or "youtube"
   - Operations: Extract ID → Download Thumbnail → Update Record

### YouTube Integration
1. **URL Parsing**: Support multiple YouTube URL formats
   - youtube.com/watch?v=VIDEO_ID
   - youtu.be/VIDEO_ID
   - youtube.com/embed/VIDEO_ID
   - youtube.com/v/VIDEO_ID

2. **Thumbnail Quality**: Implement quality fallback system
   - maxresdefault.jpg (highest quality)
   - hqdefault.jpg (high quality)
   - mqdefault.jpg (medium quality)
   - default.jpg (standard quality)

3. **Download Strategy**: Robust download with retry logic
   - HTTP requests with proper headers
   - Timeout handling (10 seconds)
   - File validation (minimum size check)
   - Error logging and fallback

### File Management
1. **Storage**: Upload to Directus local storage
2. **Naming**: Consistent filename format (youtube_VIDEO_ID.jpg)
3. **Metadata**: Proper file type and title assignment
4. **Cleanup**: Handle duplicate files appropriately

## Implementation Phases

### Phase 1: Directus Setup
- Configure media_items collection with new field
- Set up proper permissions and interfaces
- Test field display in layouts

### Phase 2: Flow Development
- Create the main automation flow
- Implement trigger configuration with filters
- Build the three-operation pipeline
- Add comprehensive error handling

### Phase 3: YouTube Integration
- Develop URL parsing logic
- Implement thumbnail download functionality
- Add quality fallback mechanisms
- Test with various URL formats

### Phase 4: File Management
- Configure file upload to Directus
- Implement proper file naming and metadata
- Set up storage configuration
- Test file linking to media items

### Phase 5: Testing & Optimization
- Comprehensive testing with real YouTube URLs
- Performance optimization
- Error handling validation
- Production deployment

## Technical Specifications

### Flow Operations

#### Operation 1: Extract Video ID
- **Type**: Run Script
- **Purpose**: Parse YouTube URL and extract video ID
- **Input**: media_items.url
- **Output**: video_id, thumbnail_urls array
- **Error Handling**: Invalid URL format detection

#### Operation 2: Download & Upload Thumbnail
- **Type**: Run Script
- **Purpose**: Download thumbnail and upload to Directus
- **Input**: thumbnail_urls, video_id
- **Output**: thumbnail_file_id
- **Error Handling**: Network failures, invalid images, retry logic

#### Operation 3: Update Media Item
- **Type**: Update Data
- **Purpose**: Link thumbnail to media item
- **Input**: thumbnail_file_id
- **Output**: Updated media_items record
- **Error Handling**: Database update failures

### Error Handling Strategy
1. **URL Validation**: Check for valid YouTube URLs before processing
2. **Download Failures**: Try multiple thumbnail qualities
3. **Network Issues**: Implement timeout and retry logic
4. **File Upload**: Handle storage quota and permission issues
5. **Database Updates**: Rollback on failure

### Performance Considerations
1. **Async Processing**: Non-blocking thumbnail downloads
2. **Caching**: Avoid re-downloading existing thumbnails
3. **Rate Limiting**: Respect YouTube's CDN limits
4. **Resource Management**: Efficient memory usage for file handling

## Testing Strategy

### Unit Testing
- URL parsing with various formats
- Thumbnail URL generation
- File upload functionality
- Error handling scenarios

### Integration Testing
- End-to-end flow execution
- Directus API integration
- File storage verification
- Database update validation

### Performance Testing
- Concurrent flow executions
- Large file handling
- Network timeout scenarios
- Memory usage optimization

## Deployment & Monitoring

### Production Setup
1. **Environment Configuration**: Set up production Directus instance
2. **Flow Activation**: Deploy and activate the automation flow
3. **Monitoring**: Set up logging and alerting
4. **Backup**: Ensure data integrity and recovery procedures

### Monitoring & Maintenance
1. **Flow Logs**: Monitor execution success/failure rates
2. **Performance Metrics**: Track processing times and resource usage
3. **Error Tracking**: Monitor and resolve common failure patterns
4. **Regular Updates**: Keep YouTube integration current with API changes

## Success Metrics
- 95%+ successful thumbnail extraction rate
- Average processing time < 30 seconds per item
- Zero data loss during flow execution
- Successful handling of all supported URL formats
- Proper error logging and alerting functionality