nfoguard/SUMMARY.md

NFOGuard Development Summary

Current Status: v1.3.6 - NFO Preservation Fix

Latest Updates (v1.3.6)

• 🔧 NFO MANAGER: Fixed movie.nfo to preserve existing content instead of overwriting
• ✅ PRESERVATION: Existing movie metadata (title, plot, actors, etc.) now maintained
• 🎯 TARGETED: Only updates NFOGuard-managed fields (dateadded, uniqueid, lockdata)
• 🧹 CLEANUP: Removes old NFOGuard elements before adding new ones to avoid duplicates

NFO Management Behavior (Fixed)

Before (v1.3.5 and earlier):

<!-- Full existing NFO with title, plot, cast, etc. -->
↓ NFOGuard processing
<movie>
  <!-- Only NFOGuard fields - ALL EXISTING CONTENT LOST -->
</movie>

After (v1.3.6):

<!-- Full existing NFO with title, plot, cast, etc. -->
↓ NFOGuard processing  
<movie>
  <!-- NFOGuard comment and fields added -->
  <!-- ALL EXISTING CONTENT PRESERVED -->
  <title>Existing Title</title>
  <plot>Existing Plot</plot>
  <!-- ... existing content ... -->
  <dateadded>2025-09-14T13:37:14-04:00</dateadded>
  <lockdata>true</lockdata>
</movie>
```lopment 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
```bash
# 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