109 lines
3.7 KiB
Markdown
109 lines
3.7 KiB
Markdown
# 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 |