nfoguard/SUMMARY.md

NFOGuard Development Summary

Current Status: v1.3.4 - Complete Database Migration Fix

Latest Updates (v1.3.4)

• 🔧 DATABASE: Fixed comprehensive schema migration for all missing columns
• ✅ MIGRATION: Added automatic detection and addition of path, has_video_file, last_updated columns
• 🎯 ROBUST: Schema introspection ensures all required columns exist
• 🔍 VALIDATION: Comprehensive column checking for both movies and episodes tables

Database Migration Strategy

✅ Check existing schema with PRAGMA table_info()
✅ Add missing columns: path, has_video_file, last_updated
✅ Update existing records with default values
✅ Handle both movies and episodes tables
✅ Graceful migration without data loss

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

• 🐛 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 processes correctly through all stageslopment 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