# NFOGuard Project Summary

## 📋 Current Status: v0.6.1 (Latest Improvements)

### 🎯 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

**🎯 Configurable Release Date Priority System (v0.6.0)**  
- **Three-Tier Priority System**: Digital → Physical → Theatrical (fully configurable)
- **Smart Fallbacks**: "The Craft (1996)" gets 1996 theatrical, "Top Gun Maverick (2022)" gets digital
- **Per-Movie Intelligence**: Automatically adapts to movie era and available release data
- **Source Tracking**: NFO files annotated with chosen date source (tmdb:theatrical, tmdb:digital, etc.)
- **Quality Control**: Prevents unrealistic dates through smart comparison logic

### 🏗 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_RELEASE_DATES_OVER_FILE_DATES=true` - Smart fallback for manual imports
- `RELEASE_DATE_PRIORITY=digital,physical,theatrical` - Configurable fallback order
- 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 **intelligent release date selection**:
  - "The Craft (1996)" → 1996 theatrical date (not 2025 file date)
  - "Top Gun Maverick (2022)" → digital release date per user preference
- ✅ Zero API timeout issues with database-only approach
- ✅ Complete webhook-based operation (no manual CLI required)
- ✅ NFO source annotations for full transparency

### 🚧 Current Development Focus

**Completed (v0.6.0):**
- ✅ **Revolutionary Priority System**: Configurable digital/physical/theatrical fallbacks
- ✅ **Per-Movie Intelligence**: Adapts to movie era and available release data
- ✅ **Complete Documentation**: README, testing guides, troubleshooting
- ✅ **Source Transparency**: NFO annotations show exactly which source was used

**Next Priorities:**
- TV series processing optimization
- Additional external API integrations (OMDb, Jellyseerr)
- Advanced configuration options
- Community feedback integration

### 📈 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

---

### 🆕 v0.6.1 Recent Improvements (September 2025)

**🔧 Enhanced Radarr History Detection:**
- **Smart Upgrade Detection**: Detects movies where first event is `movieFileRenamed` (upgrade scenarios)
- **Improved Logic**: For movies like The Matrix (1999), prefer digital release dates over recent upgrade dates
- **True Import Preservation**: Still honors actual import dates when they exist - only enhances edge cases

**🎯 Improved IMDb ID Extraction:**  
- **Flexible Regex**: Now supports both `[imdb-tt123]` and `[tt123]` formats
- **NFO Fallback**: Scans `.nfo` files when path extraction fails (handles Radarr auto-generated files)
- **Broader Compatibility**: Works with various folder naming conventions

**🧠 Enhanced Priority Logic:**
- Movies with rename→upgrade history now get better chronological dates
- True import dates always take precedence (no regression)
- Smart fallbacks only engage when appropriate

---

**Last Updated:** September 9, 2025  
**Version:** v0.6.1-dev  
**Status:** Enhanced Production Ready