nfoguard/SUMMARY.md

NFOGuard Development Summary

Current Status: v1.3.2 - Path Mapping Fix & Database Migration

Latest Updates (v1.3.2)

• 🐛 CRITICAL: Fixed path mapping bug converting movies6 to movies/6
• 🔧 DATABASE: Added automatic migration for has_video_file columns
• 🎯 PATH CONFIG: Removed all hardcoded paths - fully configurable via environment
• 📝 VALIDATION: Enhanced path validation in webhook processing
• 🔍 DEBUG: Added debug logging to path mapper for troubleshooting

Path Mapping Logic (Fixed)

Radarr webhook: /mnt/unionfs/Media/Movies/movies6/Annabelle...
↓ Match RADARR_ROOT_FOLDERS[1]: /mnt/unionfs/Media/Movies/movies6
↓ Map to MOVIE_PATHS[1]: /media/Movies/movies6  
✅ Result: /media/Movies/movies6/Annabelle...

Environment Configuration Required

• MOVIE_PATHS=/media/Movies/movies,/media/Movies/movies6
• TV_PATHS=/media/TV/tv,/media/TV/tv6
• RADARR_ROOT_FOLDERS=/mnt/unionfs/Media/Movies/movies,/mnt/unionfs/Media/Movies/movies6
• SONARR_ROOT_FOLDERS=/mnt/unionfs/Media/TV/tv,/mnt/unionfs/Media/TV/tv6

Previous Updates (v1.3.1)

• 🐛 FIXED: 'container_path' undefined variable error in Radarr webhook handler
• 🔧 ENHANCED: Webhook now properly handles both 'folderPath' and 'path' fields
• ✅ VALIDATION: Added mandatory path validation before processing
• 🎯 BATCH: Enhanced batch processing with IMDb ID validation to prevent cross-processing

Zero Hardcoded Paths

• ✅ No default fallback paths in configuration
• ✅ Application fails with clear error if paths not configured
• ✅ Works with any folder structure
• ✅ Completely portable between environments

Database Migration Support

• ✅ Automatic schema updates for existing databases
• ✅ Graceful handling of missing columns
• ✅ Backward compatibility maintained

Webhook Processing Flow

1. Reception: Webhook received and parsed
2. Path Resolution: External path mapped to container path using environment mappings
3. Validation: Verify mapped path exists and IMDb ID matches
4. Batching: Add to processing queue with anti-storm protection
5. Processing: Date resolution, NFO creation, file timestamp updates
6. Database: Record processing history and results

Technical Architecture

• Path Mapper: Environment-configurable path translation
• NFO Manager: Creates metadata files with proper date attribution
• Database Manager: SQLite with automatic migration support
• Webhook Batcher: Intelligent batching with validation
• Client Managers: API access for external services

Debug Features

• Path Mapping Debug: Detailed logging of path translation process
• Health Endpoint: Database and external service status
• Statistics API: Comprehensive media library statistics
• Debug Endpoints: Movie import analysis, TMDB lookup testing

Configuration Requirements

Critical Environment Variables

# Required - Application will fail without these
MOVIE_PATHS=/your/container/movie/paths
TV_PATHS=/your/container/tv/paths
RADARR_ROOT_FOLDERS=/host/radarr/paths
SONARR_ROOT_FOLDERS=/host/sonarr/paths

# Database and logging
DB_PATH=/app/data/media_dates.db
LOG_DIR=/app/data/logs

Known Issues

• Path mapping must exactly match your container and host configurations
• Database requires migration for existing installations
• Debug logging may be verbose during path mapping troubleshooting