nfoguard/SUMMARY.md

NFOGuard v1.3.1 - Media Import Date Preservation System

NFOGuard is a sophisticated webhook service that preserves the original import dates of movies and TV shows in media servers (Emby/Jellyfin/Plex). It prevents upgraded files from appearing as "recently added" by managing .nfo files and filesystem timestamps.

🎯 Project Overview

NFOGuard is a comprehensive media management system that:

• Receives webhooks from Radarr/Sonarr when media is imported
• Preserves original import dates even when files are upgraded/renamed
• Creates and manages .nfo files with accurate metadata
• Updates filesystem timestamps to maintain chronological order
• Provides extensive debugging and monitoring capabilities

🏗 Architecture Highlights

Core Components

• nfoguard.py - Main FastAPI application with webhook handlers and debug endpoints
• core/ - Database management, NFO file handling, and path mapping
• clients/ - Radarr/Sonarr API clients and database connectors
• Docker-first deployment with secure configuration management

Smart Date Selection System

Intelligent priority system for determining import dates:

1. Radarr/Sonarr Import History (highest priority - real import dates)
2. TMDB/OMDb Release Dates (digital → physical → theatrical)
3. File modification time (fallback only if enabled)

🚀 Technical Strengths

Performance Optimization

• Database-first approach: Direct PostgreSQL/SQLite queries vs API pagination
• Sub-second response times for complex movie histories
• Bulk processing capabilities for large libraries
• Webhook batching system with 5-second delay to handle rapid events

Robust Error Handling

Comprehensive debug endpoints for troubleshooting:

• /debug/movie/{imdb_id} - Import date analysis and pipeline testing
• /debug/movie/{imdb_id}/priority - Date selection logic explanation
• /debug/tmdb/{imdb_id} - TMDB API debugging and validation
• /batch/status - Real-time webhook queue monitoring

Security & Configuration

Two-file configuration system for production safety:

• .env - Safe to share (paths, preferences, non-sensitive settings)
• .env.secrets - API keys, passwords, database credentials (git-ignored)

📋 Code Quality & Documentation

Excellent Documentation

• Comprehensive README.md with curl examples and configuration guides
• Detailed TESTING.md with validation workflows and test scenarios
• Clear DEPLOYMENT.md for production setup with Docker Compose
• Extensive inline code documentation and type hints

Smart Webhook Processing

Dual-mode TV webhook processing:

• Targeted mode: Process only webhook episodes (efficient for single episodes)
• Series mode: Process entire series (comprehensive for bulk imports)

Version Management

• Detailed changelog tracking with semantic versioning
• Clear release notes with upgrade instructions
• Git-based version detection for development builds

🔧 Recent Improvements & Fixes

v1.3.1 - Webhook Processing Isolation (Current)

Fixed Critical Webhook Bug:

• Issue: Movie webhooks were processing wrong movies due to path mapping failures
• Root Cause: TV path configuration errors corrupted shared batch queue
• Solution: Implemented webhook isolation with prefixed batch keys and validation

Key Changes:

• Added prefixed batch keys (movie:tt123456, tv:tt123456) to prevent cross-contamination
• Implemented path existence validation before processing
• Added IMDb ID validation in batch processing to prevent wrong movie processing
• Enhanced error logging with specific failure reasons
• Removed duplicate webhook handler code

Logging Example (Fixed):

[2025-09-14T12:40:05-04:00] INFO: Received Radarr webhook: Download  
[2025-09-14T12:40:05-04:00] DEBUG: Mapped Radarr path -> /media/Movies/movies6/Annabelle (2014) [tt3322940]
[2025-09-14T12:40:05-04:00] INFO: Batched movie webhook for movie:tt3322940
[2025-09-14T12:40:10-04:00] DEBUG: Batch validation passed: IMDb tt3322940 found in path
[2025-09-14T12:40:10-04:00] INFO: Processing movie: Annabelle (2014) [tt3322940] ✅ CORRECT

Ongoing Potential Improvements

Code Organization

• Status: Identified for future improvement
• Issue: Main nfoguard.py file is large (2000+ lines)
• Proposed Solution: Split into focused modules:

  api/
  ├── endpoints/
  │   ├── debug.py      # Debug endpoints
  │   ├── webhooks.py   # Webhook handlers  
  │   └── health.py     # Health/stats
  └── main.py           # FastAPI app setup
  

Enhanced Exception Handling

• Status: Minor improvement opportunity
• Proposed: More specific exception types for better error categorization
• Benefit: Improved debugging and API response clarity

Metrics & Monitoring

• Status: Future enhancement
• Proposed: Prometheus metrics endpoint for production monitoring
• Metrics: Webhook processing times, success rates, batch queue depths

Configuration Validation

• Status: Future enhancement
• Proposed: Startup validation of path mappings and API connectivity
• Benefit: Earlier detection of configuration issues

🎉 Overall Assessment

NFOGuard is a production-ready, well-architected system with:

• ✅ Comprehensive testing framework with real-world scenarios
• ✅ Excellent documentation covering setup, testing, and troubleshooting
• ✅ Smart fallback mechanisms for robust date detection
• ✅ Performance optimizations for large media libraries
• ✅ Security best practices with secret management
• ✅ Docker deployment ready with health checks
• ✅ Extensive debug capabilities for production support

The webhook-first architecture and database-priority system demonstrate sophisticated understanding of the media management ecosystem. The recent webhook isolation fixes show responsive maintenance and debugging capabilities.

📊 Development Stats

• Lines of Code: ~2000+ (main application)
• Test Coverage: Comprehensive manual and automated testing
• Dependencies: FastAPI, SQLite/PostgreSQL, requests, pathlib
• Deployment: Docker Compose with multi-architecture support
• Documentation: 6 comprehensive markdown files

Recommendation: This codebase is ready for open-source release and community adoption. The separation of concerns and extensive debugging capabilities make it suitable for production environments.