nfoguard/SUMMARY.md

NFOGuard Project Summary

📋 Current Status: v0.6.0 (In Development)

🎯 Project Goal

Preserve movie and TV import dates in Emby/Jellyfin/Plex by preventing upgraded files from appearing as "recently added". NFOGuard listens to Radarr/Sonarr webhooks and manages .nfo files and file timestamps to maintain chronological consistency.

🚀 Major Achievements

Database-Only Architecture (v0.5.0+)

• Performance: 10x faster than API-based approach
• Reliability: Direct PostgreSQL database queries eliminate API limitations
• Scalability: Handles 1500+ movies without pagination issues

Smart Date Detection (v0.6.0)

• Manual Import Handling: Intelligently prefers digital release dates over file dates
• Quality Control: Avoids unrealistic dates (won't use 2000 digital date for 1983 movie)
• Configurable: User can enable/disable smart fallback behavior

🏗 Current Architecture

Core Components:

• nfoguard.py - Main FastAPI webhook server
• clients/radarr_db_client.py - Direct database access client
• clients/external_clients.py - TMDB/OMDb integration
• core/nfo_manager.py - NFO file creation and management
• bulk_update_movies.py - Mass movie processing

Data Flow:

1. Radarr webhook → NFOGuard processes → Database queries for import dates
2. Smart fallback logic for manual imports → TMDB digital release dates
3. NFO file creation with preserved dates → File timestamp updates

🔧 Configuration Management

Environment-Based Setup:

• .env.template - Generic configuration template
• docker-compose.yml - Production deployment configuration
• Supports multiple media paths and database types

Key Settings:

• MOVIE_PRIORITY=import_then_digital - Prioritizes real import history
• PREFER_DIGITAL_OVER_FILE_DATES=true - Smart fallback for manual imports
• Database connection parameters for PostgreSQL/SQLite

📊 Performance Metrics

Before (API-based):

• Took 30+ seconds for complex movies
• Failed on movies with extensive history
• API pagination caused timeouts

After (Database-only):

• Sub-second response times
• Handles any history size
• Reliable July 2025 date detection maintained

🧪 Testing Infrastructure

Comprehensive Test Suite:

• test_bulk_update.py - Database connection validation
• test_movie_scan.py - Directory scanning logic testing
• test_end_to_end.py - Complete workflow validation

Debug Endpoints:

• /debug/movie/{imdb_id} - Import date analysis
• /debug/movie/{imdb_id}/priority - Date selection logic
• /debug/movie/{imdb_id}/history - Complete import history

🎉 Success Metrics

Production Results:

• ✅ Correct July 2025 dates preserved for legitimate imports
• ✅ Manual imports now use TMDB digital dates instead of file dates
• ✅ Zero API timeout issues with database-only approach
• ✅ Complete webhook-based operation (no manual CLI required)

🚧 Current Development Focus

In Progress (v0.6.0):

• Smart digital release date logic for manual imports
• Enhanced documentation and deployment guides
• Bug fixes in debug endpoints

Next Priorities:

• TV series processing optimization
• Additional external API integrations
• Advanced configuration options

📈 Project Maturity

Ready for Production:

• ✅ Stable database architecture
• ✅ Comprehensive error handling
• ✅ Docker deployment ready
• ✅ Extensive testing coverage
• ✅ Complete documentation

Community Ready:

• ✅ Environment-based configuration
• ✅ Portable Docker setup
• ✅ Detailed API documentation
• ✅ Troubleshooting guides

---

Last Updated: September 9, 2025
Version: v0.6.0-dev
Status: Active Development