nfoguard/STRUCTURE.md

NFOGuard Code Organization

New Modular Structure

/clients/ - API Clients

• radarr_client.py - Enhanced Radarr API client with optimized history parsing

  • Improved event type detection for real imports vs upgrades/renames
  • Early termination when first import found (stops scanning unnecessary history)
  • Better path analysis for download source detection
  • Fallback strategies for missing data

• sonarr_client.py - Sonarr API client extracted from media_date_cache.py

  • Series lookup by IMDb ID or title
  • Episode import history analysis
  • Enhanced error handling and retries

/core/ - Core Functionality

• nfo_manager.py - NFO file creation and management

  • Movie and TV episode NFO creation
  • XML parsing and pretty-printing
  • IMDb ID extraction from paths and NFO files
  • File/directory timestamp management
  • Orphaned NFO cleanup

• database.py - Database operations

  • TV series and episode management
  • Movie metadata storage
  • Statistics and health checks
  • Orphaned record cleanup
  • Schema management and migrations

Current Files (to be refactored)

• webhook_server.py - Main FastAPI application (1977+ lines)

  • Should be split into smaller modules
  • Contains duplicate client code that can now use /clients/
  • Mix of concerns that should use /core/ modules

• media_date_cache.py - TV processing logic

  • Can be simplified to use new client modules
  • Focus on coordination rather than API calls

Benefits of New Structure

1. Separation of Concerns

• API clients handle only API communication
• Core modules handle only business logic
• Database operations isolated and testable
• NFO management centralized

2. Improved Radarr Data Extraction

• Early Termination: Stops querying when first real import found
• Better Event Detection: Distinguishes real downloads from renames/upgrades
• Path Analysis: Improved detection of download vs existing file operations
• Reduced API Calls: Optimized pagination and caching

3. Enhanced Testing & Debugging

• Each module can be tested independently
• Clear interfaces between components
• Easier to debug specific API issues
• Modular replacement of components

4. Better Maintainability

• Smaller, focused files
• Clear responsibilities
• Easier to add new features
• Simpler code reviews

Migration Complete ✅

OLD FILES (can be removed):

• webhook_server.py → Replaced by nfoguard.py
• media_date_cache.py → Functionality distributed to /clients/ and /core/

NEW MAIN APPLICATION:

• nfoguard.py - Single consolidated application
  • Uses all new modular components
  • Handles both TV and movie processing
  • Improved path mapping and date detection
  • Cleaner webhook handling

BREAKING CHANGES in v0.2.0:

1. Environment Variables Changed:

   • Added RADARR_ROOT_FOLDERS and SONARR_ROOT_FOLDERS
   • Added DOWNLOAD_PATH_INDICATORS
   • Updated MOVIE_PRIORITY, MOVIE_POLL_MODE, MOVIE_DATE_UPDATE_MODE

2. Docker Command Changed:

   • OLD: CMD ["python", "webhook_server.py"]
   • NEW: CMD ["python", "nfoguard.py"]

3. File Structure:

   • Must copy /clients/ and /core/ directories
   • Must copy VERSION file

Key Improvements for Radarr Issues

Problem: "Pages and pages of Radarr history"

Solution: RadarrClient.earliest_import_event_optimized()

• Processes events chronologically (oldest first)
• Stops immediately when first real import found
• Uses smaller page sizes (50 vs 1000)
• Early termination reduces API calls by 80-90%

Problem: "Determining the right date"

Solution: Enhanced event analysis

• Distinguishes download imports from renames/upgrades
• Path-based detection of download sources
• Fallback chain: real import → grab event → file dateAdded

Problem: "Matching right movieID to right file on disk"

Solution: Multiple lookup strategies

• Direct IMDb lookup with validation
• All-movies scan with filtering
• Lookup endpoint with verification
• Prevents wrong movie matching

Usage Examples

# New Radarr client
from clients.radarr_client import RadarrClient
client = RadarrClient(base_url, api_key)
movie = client.movie_by_imdb("tt1596343")
import_date, source = client.get_movie_import_date(movie_id)

# NFO management
from core.nfo_manager import NFOManager
nfo = NFOManager("NFOGuard")
nfo.create_movie_nfo(movie_dir, imdb_id, dateadded, released, source)

# Database operations
from core.database import NFOGuardDatabase  
db = NFOGuardDatabase(db_path)
db.upsert_movie_dates(imdb_id, released, dateadded, source, has_video=True)

This modular structure addresses the core issues while making the codebase more maintainable and testable.