nfoguard/SUMMARY.md

NFOGuard Development Summary

Current Status: v1.3.7 - NFO XML Parsing Fix

Latest Updates (v1.3.7)

• � FIXED: XML comment parsing error causing NFO creation to fail
• 🔧 XML HANDLING: Improved XML comment insertion and file writing
• ✅ PRESERVATION: Existing movie metadata properly preserved during updates
• 🎯 ROBUST: Better error handling for malformed XML files

NFO Update Process (Fixed)

1. ✅ Load existing movie.nfo (if exists)
2. ✅ Parse and validate XML structure  
3. ✅ Remove old NFOGuard elements to avoid duplicates
4. ✅ Preserve all existing content (title, plot, cast, etc.)
5. ✅ Add/update NFOGuard fields (dateadded, lockdata, uniqueid)
6. ✅ Write properly formatted XML with comment

Error Resolution

• v1.3.6: XML comment handling caused '() error
• v1.3.7: Fixed comment insertion and XML serialization
• Result: NFO files now update correctly while preserving contentlopment Summary

Current Status: v1.3.3 - Database Migration & Path Validation Complete

Latest Updates (v1.3.3)

• � DATABASE: Fixed missing path column migration in movies table
• ✅ MIGRATION: Automatic schema updates with graceful error handling
• 🔍 VALIDATION: Enhanced database migration with column existence checks
• 🎯 COMPATIBILITY: Backward compatibility with existing databases maintained

Path Mapping Success (v1.3.2-v1.3.3)

• 🐛 CRITICAL: Fixed substring matching bug (movies/movies6, tv/tv6)
• 🎯 ALGORITHM: Longest-path-first matching prevents incorrect mappings
• � DEBUG: Comprehensive debug logging for troubleshooting
• ✅ TESTED: Annabelle webhook now processes correctly

Working Path Mapping Example

Radarr webhook: /mnt/unionfs/Media/Movies/movies6/Annabelle...
✅ Sort by length: [movies6, movies] (longest first)
✅ Match movies6: /mnt/unionfs/Media/Movies/movies6
✅ Map to index 1: /media/Movies/movies6
✅ Result: /media/Movies/movies6/Annabelle (2014) [tt3322940]
✅ Path exists: Validation passes
✅ Processing: Movie webhook succeeds

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