MovieMapper/PHASE_5_IMPLEMENTATION.md

Phase 5: Advanced Features Implementation Summary

Overview

Phase 5 implements advanced features for the MovieMapper iOS app, focusing on offline-first architecture and enhanced tagging capabilities.

---

1. Offline-First Architecture

LocalCache.swift

Location: Sources/Services/LocalCache.swift

Features:

• Caches show search results in UserDefaults with 7-day expiration
• Supports caching of individual shows and arrays of shows
• Automatic cache expiration handling
• Methods:
  • cacheShows(key:shows:) - Cache an array of shows
  • getCachedShows(key:) - Retrieve cached shows
  • cacheSearchResults(key:shows:) - Cache search results
  • getCachedSearchResults(key:) - Get cached search results
  • cacheShowDetails(key:show:) - Cache individual show details
  • getCachedShowDetails(key:) - Get cached show details
  • clearCache() - Clear all cached data
  • clearCacheEntry(key:) - Clear specific cache entry

Integration:

• Used by TVDBClient to cache search results and show details
• Provides offline access to recently searched shows and show details
• Automatically expires old cache entries

OfflineManager.swift

Location: Sources/Services/OfflineManager.swift

Features:

• Monitors network connectivity using Combine
• Queues operations when offline for later execution
• Automatic retry mechanism (up to 3 attempts)
• Persistent operation queue using UserDefaults
• Methods:
  • queueOperation(description:operation:) - Add operation to queue
  • processQueue() - Process queued operations
  • loadQueue() - Load queue from UserDefaults on app launch
  • clearQueue() - Clear all queued operations
  • getQueuedOperations() - Get current queue

Network Status:

• isOnline: Bool - Current connectivity status
• status: NetworkStatus - .online or .offline

Operation Structure:

• UUID-based operation tracking
• Retry count tracking
• Error logging for failed operations

---

2. Tagging System

TagManager.swift

Location: Sources/Services/TagManager.swift

Features:

• Add/remove tags on files
• Move tagged files to Jellyfin-compatible folders
• Automatic folder creation for target folders
• Audit logging for all tagging operations

Methods:

• addTag(_tag:to:in:) - Add a tag to a file
• removeTag(_tag:from:in:) - Remove a tag from a file
• hasTag(_tag:in:) - Check if file has a tag
• getAllTags(for:) - Get all tags for a file
• moveTaggedFiles(_files:to:in:) - Move tagged files to a folder
• moveFilesWithTags(_files:in:) - Move files to appropriate folders based on their tags
• getTaggedFiles(in:) - Get all tagged files in a directory

Jellyfin Compatible Folders:

• extra → extras/
• behindTheScenes → behind-the-scenes/
• delete → delete/

Result Structure:

public struct MoveTaggedFilesResult {
    let success: Bool
    let movedCount: Int
    let failedCount: Int
    let movedFiles: [MediaFile]
    let failedFiles: [MoveFailure]
}

---

3. UI Integration

FileListView.swift Updates

New Features:

• Toggle tagging mode with floating action button
• Visual tag badges on files showing tag state
• Floating action button for moving all tagged files
• Individual file tag toggling when in tagging mode

Floating Action Button:

• Two buttons stacked vertically:
  1. "Tag Files" - Toggle tagging mode on/off
  2. "Move All Tagged" - Move all tagged files to appropriate folders
• Auto-hides when not needed
• Smooth animation for appearance/disappearance

Tag Badges:

• Shows tag name with first letter capitalized
• Color-coded based on tag type (purple for extra, orange for behind-the-scenes, red for delete)
• Tap to toggle tag when in tagging mode
• Visual feedback with border and shadow

---

4. TVDB Client Updates

TVDBClient.swift

Updates:

• Uses LocalCache for caching search results and show details
• Removed manual UserDefaults caching
• Cleaner separation of concerns
• Offline-capable search and show details

Caching Behavior:

• Search results cached with key search_{query}
• Show details cached with key show_{id}
• Episodes cached with key episodes_{showId}_{seasonNumber}
• Cache expires after 7 days

---

5. Data Model Updates

SharedModels Files (all made public)

Updated to use public access control:

• MediaFile.swift - File structure with tags
• Show.swift - Show structure with caching support
• Season.swift - Season structure
• Episode.swift - Episode structure
• TagType.swift - Tag type enum (extra, behindTheScenes, delete)
• TaggedFile.swift - Tagged file structure

---

6. Package Structure

Package.swift Updates

Structure:

• All source files in Sources/ directory
• SharedModels included in Sources directory
• Proper module structure for Swift Package Manager
• Dependencies: FFmpegKitSwift, Alamofire, ReactiveSwift

---

Integration Summary

File Flow

1. Search:

   • User searches for show → TVDBClient checks cache first
   • If not in cache, fetch from network and cache result
   • Offline: shows cached results

2. File Scanning:

   • FileScanner scans directory (completely offline)
   • Files loaded with metadata (duration, quality, FPS)
   • Files can be tagged locally

3. Tagging:

   • User toggles tagging mode
   • Tags added/removed via TagManager
   • Tags persisted to .metadata file
   • Audit log updated for each action

4. File Movement:

   • User selects "Move All Tagged"
   • TagManager moves files to appropriate folders
   • Audit log entry created
   • Files removed from UI

Offline Capabilities

• File scanning: 100% offline
• Tagging: 100% offline
• File movement: 100% offline
• TVDB search: Cached results available offline
• TVDB show details: Cached results available offline
• Episode data: Cached results available offline

---

Testing Recommendations

1. LocalCache:

   • Cache write/read operations
   • Cache expiration (7-day test)
   • Clear cache functionality

2. OfflineManager:

   • Queue operations while offline
   • Automatic processing when online
   • Retry mechanism (3 attempts)
   • Persistence across app launches

3. TagManager:

   • Add/remove tags
   • Move files to correct folders
   • Folder creation (extras, behind-the-scenes, delete)
   • Audit logging

4. FileListView:

   • Tagging mode toggle
   • Tag badge display
   • Floating action button visibility
   • Move all tagged files

---

Known Limitations

1. FileScanner:

   • Non-recursive scanning (current directory only)
   • No parent directory navigation yet
   • Tag state lost on directory change

2. LocalCache:

   • UserDefaults based (not suitable for large datasets)
   • 7-day expiration
   • No manual cache management UI

3. OfflineManager:

   • No UI feedback for queued operations
   • No priority system for operations
   • Limited retry options

---

Next Steps (Future Phases)

1. Phase 6: Build & Distribution
2. Phase 7: Advanced Features
   • iCloud sync
   • File preview
   • Bulk operations
   • Advanced filtering

---

Files Created/Modified

Created:

• Sources/Services/LocalCache.swift
• Sources/Services/OfflineManager.swift
• Sources/Services/TagManager.swift
• Sources/SharedModels/ (copied from parent directory)

Modified:

• Sources/Services/TVDBClient.swift - Uses LocalCache
• Sources/UI/FileListView.swift - Enhanced tagging UI
• Sources/SharedModels/*.swift - Made public
• Package.swift - Updated targets

---

Summary

Phase 5 successfully implements:

• ✅ Local caching of show search results (7-day expiration)
• ✅ File scanning works completely offline
• ✅ TVDB features optional (internet required for fresh data)
• ✅ TagManager with addTag, removeTag, moveTaggedFiles methods
• ✅ Jellyfin compatible folders (extras/, behind-the-scenes/, delete/)
• ✅ Floating action button for moving all tagged files
• ✅ Tag state persistence
• ✅ Audit logging for tagging operations

The implementation follows the iOS app architecture and integrates seamlessly with existing services.