Aniworld/docs/instructions.md

Aniworld Web Application Development Instructions

This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.

Project Overview

The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in SeriesApp.py while the web layer provides REST API endpoints and a responsive UI.

Architecture Principles

• Single Responsibility: Each file/class has one clear purpose
• Dependency Injection: Use FastAPI's dependency system
• Clean Separation: Web layer calls core logic, never the reverse
• File Size Limit: Maximum 500 lines per file
• Type Hints: Use comprehensive type annotations
• Error Handling: Proper exception handling and logging

Additional Implementation Guidelines

Code Style and Standards

• Type Hints: Use comprehensive type annotations throughout all modules
• Docstrings: Follow PEP 257 for function and class documentation
• Error Handling: Implement custom exception classes with meaningful messages
• Logging: Use structured logging with appropriate log levels
• Security: Validate all inputs and sanitize outputs
• Performance: Use async/await patterns for I/O operations

📞 Escalation

If you encounter:

• Architecture issues requiring design decisions
• Tests that conflict with documented requirements
• Breaking changes needed
• Unclear requirements or expectations

Document the issue and escalate rather than guessing.

---

📚 Helpful Commands

# Run all tests
conda run -n AniWorld python -m pytest tests/ -v --tb=short

# Run specific test file
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v

# Run specific test class
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v

# Run specific test
conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v

# Run with extra verbosity
conda run -n AniWorld python -m pytest tests/ -vv

# Run with full traceback
conda run -n AniWorld python -m pytest tests/ -v --tb=long

# Run and stop at first failure
conda run -n AniWorld python -m pytest tests/ -v -x

# Run tests matching pattern
conda run -n AniWorld python -m pytest tests/ -v -k "auth"

# Show all print statements
conda run -n AniWorld python -m pytest tests/ -v -s

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

---

Implementation Notes

1. Incremental Development: Implement features incrementally, testing each component thoroughly before moving to the next
2. Code Review: Review all generated code for adherence to project standards
3. Documentation: Document all public APIs and complex logic
4. Testing: Maintain test coverage above 80% for all new code
5. Performance: Profile and optimize critical paths, especially download and streaming operations
6. Security: Regular security audits and dependency updates
7. Monitoring: Implement comprehensive monitoring and alerting
8. Maintenance: Plan for regular maintenance and updates

---

Task Completion Checklist

For each task completed:

• Implementation follows coding standards
• Unit tests written and passing
• Integration tests passing
• Documentation updated
• Error handling implemented
• Logging added
• Security considerations addressed
• Performance validated
• Code reviewed
• Task marked as complete in instructions.md
• Infrastructure.md updated and other docs
• Changes committed to git; keep your messages in git short and clear
• Take the next task

---

TODO List:

🎬 NFO Metadata Integration

Task 3: Adapt Scraper Code for NFO Generation ✅ COMPLETE (95%)

Priority: High
Estimated Time: 4-5 hours
Status: Functional implementation complete. See task3_status.md for details.

What Was Completed:

• ✅ TMDB API client with caching and retry logic
• ✅ NFO XML generator for Kodi/XBMC format
• ✅ Image downloader for poster/logo/fanart
• ✅ NFO service orchestration layer
• ✅ SeriesManagerService integration
• ✅ CLI tool (python -m src.cli.nfo_cli)
• ✅ Integration test script
• ✅ Configuration settings

Remaining: Documentation (30 minutes)

Adapt code from /home/lukas/Volume/repo/scraper/ to create tvshow.nfo files using TMDB API.

Implementation Steps:

1. Copy and Adapt Scraper Code

   • Review code structure in /home/lukas/Volume/repo/scraper/src/scraper/
   • Copy relevant modules: api/tmdb_client.py, services/metadata_service.py, utils/xml_utils.py
   • Adapt to fit AniworldMain project structure and coding standards
   • Update requirements.txt with TMDB API dependencies (requests, lxml)
   • Add configuration for TMDB API key

2. Create NFO Service (src/core/services/nfo_service.py)

   class NFOService:
       """Service for creating and managing tvshow.nfo files."""
   
       def __init__(self, tmdb_client, metadata_service):
           # Initialize with scraper components
   
       async def check_nfo_exists(self, serie_folder: str) -> bool:
           """Check if tvshow.nfo exists for a series."""
   
       async def create_tvshow_nfo(
           self,
           serie_name: str,
           serie_folder: str,
           year: Optional[int] = None
       ) -> Path:
           """Create tvshow.nfo by scraping TMDB."""
   
       async def update_tvshow_nfo(self, serie_folder: str) -> Path:
           """Update existing tvshow.nfo with fresh data."""
   

3. Implement TMDB Search and Scraping:

   • Adapt TMDB client code from /home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py
   • Search TMDB for series by name
   • Handle multiple search results (prompt user or use best match)
   • Download series metadata
   • Adapt XML generation code from /home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py
   • Generate tvshow.nfo with proper Kodi/XBMC format
   • Save to series folder

4. Implement Media File Downloads:

   • Download poster.jpg from TMDB poster URL (w500 or original size)
   • Download logo.png from TMDB logo URL (if available)
   • Download fanart.jpg from TMDB backdrop URL (original size)
   • Save files to series folder with standard names:
     • {serie_folder}/poster.jpg
     • {serie_folder}/logo.png
     • {serie_folder}/fanart.jpg
   • Handle missing images gracefully (not all series have logos)
   • Add retry logic for failed downloads
   • Validate downloaded images (check file size, format)
   • Update NFO to reference local files

5. Add Configuration (src/config/settings.py)

   • Add TMDB_API_KEY setting
   • Add NFO_AUTO_CREATE boolean setting
   • Add NFO_UPDATE_ON_SCAN boolean setting
   • Add NFO_DOWNLOAD_POSTER boolean setting (default: true)
   • Add NFO_DOWNLOAD_LOGO boolean setting (default: true)
   • Add NFO_DOWNLOAD_FANART boolean setting (default: true)
   • Add NFO_IMAGE_SIZE setting (w500/original, default: original)

Acceptance Criteria:

• Code adapted from scraper repo and integrated
• NFOService can check for existing tvshow.nfo
• Can create new tvshow.nfo from TMDB data
• Downloads poster.jpg, logo.png, fanart.jpg from TMDB
• Handles missing images gracefully (logo may not exist)
• Saves media files with correct names and locations
• NFO references both remote URLs and local files
• Handles search ambiguity gracefully
• Saves NFO files to correct locations
• Proper error handling and logging
• Configuration settings work
• Follows AniworldMain coding standards
• Unit tests pass with > 85% coverage

Testing Requirements:

• TMDBClient Tests:
  • Mock all API calls with responses
  • Test successful series search
  • Test handling of multiple search results
  • Test series details retrieval
  • Test rate limiting
  • Test API error handling (404, 401, 500)
  • Test network timeout handling
  • Test invalid API key
• NFOService Tests:
  • Mock filesystem operations
  • Mock TMDB client responses
  • Test check_nfo_exists() with existing/missing files
  • Test create_tvshow_nfo() success path
  • Test error handling (no search results, API failures)
  • Test handling of ambiguous search results
  • Test file writing and permissions
  • Test update existing NFO
• NFO Generator Tests:
  • Test XML generation with complete data
  • Test XML generation with minimal data
  • Test XML escaping for special characters
  • Test generated XML validates against Kodi schema
  • Compare output with reference NFO from scraper repo
• Media Download Tests:
  • Mock HTTP requests for image downloads
  • Test successful poster download
  • Test successful logo download (when available)
  • Test successful fanart download
  • Test handling of missing logo (common case)
  • Test handling of 404 errors
  • Test image validation (file size, format)
  • Test retry logic on failures
  • Test file naming and location
  • Test skipping existing files

Files to Create:

• src/core/services/nfo_service.py
• src/core/services/tmdb_client.py (adapted from scraper)
• src/core/utils/nfo_generator.py (adapted from scraper's xml_utils.py)
• src/core/utils/image_downloader.py (for downloading media files)
• tests/unit/test_nfo_service.py
• tests/unit/test_tmdb_client.py
• tests/unit/test_nfo_generator.py
• tests/unit/test_image_downloader.py
• tests/fixtures/tmdb_responses.json (mock API responses)
• tests/fixtures/sample_poster.jpg (test image)
• tests/fixtures/sample_logo.png (test image)
• tests/fixtures/sample_fanart.jpg (test image)

Files to Modify:

• src/config/settings.py
• requirements.txt

Reference Files from Scraper Repo:

• /home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py
• /home/lukas/Volume/repo/scraper/src/scraper/services/metadata_service.py
• /home/lukas/Volume/repo/scraper/src/scraper/services/asset_service.py (for image downloads)
• /home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py
• /home/lukas/Volume/repo/scraper/tvshow.nfo (example output format)

---

Task 4: Add NFO Check to Download Flow

Priority: High
Estimated Time: 2-3 hours

Integrate NFO checking into the download workflow - check for tvshow.nfo before downloading, create if missing.

Implementation Steps:

1. Modify SeriesApp Download Logic (src/core/SeriesApp.py)

   async def download(
       self,
       serie_folder: str,
       season: int,
       episode: int,
       key: str,
       language: str = "German Dub",
       item_id: Optional[str] = None,
   ) -> bool:
       # 1. Check if tvshow.nfo exists
       # 2. Check if media files exist (poster.jpg, logo.png, fanart.jpg)
       # 3. If not and NFO_AUTO_CREATE=true, create NFO and download media
       # 4. Continue with download as normal
   

2. Add Progress Callbacks:

   • Report NFO check progress
   • Report NFO creation progress
   • Update UI with NFO status

3. Add NFO Check to Rescan:

   • During rescan, identify series without tvshow.nfo
   • Optionally batch-create missing NFO files
   • Report statistics

Acceptance Criteria:

• Download checks for tvshow.nfo before proceeding
• Checks for media files (poster.jpg, logo.png, fanart.jpg)
• Creates NFO and downloads media if missing and auto-create enabled
• Progress updates shown to user (NFO + each media file)
• Doesn't break existing download flow
• Rescan identifies missing NFOs and media files
• Proper error handling if NFO/media creation fails
• Missing media doesn't block episode download
• All integration tests pass
• No regression in existing tests

Testing Requirements:

• Integration Tests:
  • Test download with existing NFO and media (should skip creation)
  • Test download without NFO (auto-create enabled, downloads media)
  • Test download without NFO (auto-create disabled)
  • Test download with NFO but missing media files
  • Test NFO creation failure doesn't block download
  • Test media download failure doesn't block download
  • Test progress callbacks are fired for NFO + each media file
  • Test rescan identifies series without NFOs and media
  • Test batch NFO and media creation during rescan
• Unit Tests:
  • Mock NFOService in SeriesApp tests
  • Test NFO check logic isolated
  • Test configuration flag handling
• Regression Tests:
  • Run all existing download tests
  • Verify no performance degradation
  • Test backward compatibility

Files to Modify:

• src/core/SeriesApp.py
• src/core/SerieScanner.py
• tests/integration/test_download_flow.py
• tests/unit/test_series_app.py

---

Task 5: Add NFO Management API Endpoints

Priority: Medium
Estimated Time: 3-4 hours

Create REST API endpoints for NFO management.

Implementation Steps:

1. Create NFO API Router (src/server/api/nfo.py)

   # Endpoints:
   GET  /api/nfo/{serie_id}/check           # Check if NFO and media exist
   POST /api/nfo/{serie_id}/create          # Create new NFO and download media
   PUT  /api/nfo/{serie_id}/update          # Update existing NFO and refresh media
   GET  /api/nfo/{serie_id}/content         # Get NFO content
   GET  /api/nfo/{serie_id}/media/status    # Get media files status
   POST /api/nfo/{serie_id}/media/download  # Download missing media files
   POST /api/nfo/batch/create               # Batch create missing NFOs and media
   GET  /api/nfo/missing                    # List series without NFOs or media
   

2. Create Request/Response Models (src/server/models/nfo.py)

   • NFOCheckResponse (includes media file status)
   • NFOCreateRequest (includes media download options)
   • NFOBatchCreateRequest
   • NFOMissingResponse
   • MediaStatusResponse (has_poster, has_logo, has_fanart)
   • MediaDownloadRequest (specify which files to download)

3. Add to FastAPI App (src/server/fastapi_app.py)

   • Register NFO router
   • Add NFO service to dependencies

Acceptance Criteria:

• All endpoints implemented and working
• Proper authentication/authorization
• Request validation with Pydantic
• Comprehensive error handling
• API documentation updated
• Integration tests pass
• Test coverage > 90% for endpoints

Testing Requirements:

• Endpoint Tests (for each endpoint):
  • Test successful response (200/201)
  • Test authentication required (401)
  • Test authorization (403 if applicable)
  • Test invalid input validation (422)
  • Test not found cases (404)
  • Test server errors (500)
• Specific Endpoint Tests:
  • GET /api/nfo/{serie_id}/check: Test existing/missing NFO
  • POST /api/nfo/{serie_id}/create: Test creation, duplicate, errors
  • PUT /api/nfo/{serie_id}/update: Test update, not found
  • GET /api/nfo/{serie_id}/content: Test content retrieval, XML format
  • POST /api/nfo/batch/create: Test batch processing, partial failures
  • GET /api/nfo/missing: Test filtering, pagination
• Integration Tests:
  • Test with mocked NFOService
  • Test concurrent requests
  • Test rate limiting if applicable
• API Documentation:
  • Verify OpenAPI schema generation
  • Test example requests/responses

Files to Create:

• src/server/api/nfo.py
• src/server/models/nfo.py
• tests/api/test_nfo_endpoints.py
• tests/api/test_nfo_validation.py

Files to Modify:

• src/server/fastapi_app.py

---

Task 6: Add NFO UI Features

Priority: Medium
Estimated Time: 4-5 hours

Add UI components for NFO management in the web interface.

Implementation Steps:

1. Add NFO and Media Status Indicators

   • Show NFO status badge on series cards
   • Show media file status (poster, logo, fanart) with icons
   • Green check if NFO and all media exist
   • Yellow warning if NFO exists but missing media
   • Orange warning if missing NFO
   • Red error if scraping failed
   • Individual icons for each media file (poster, logo, fanart)

2. Add NFO and Media Management Actions

   • "Create NFO" button on series without it (downloads media too)
   • "Download Media" button for missing poster/logo/fanart
   • "View NFO" button to display content
   • "View Media" button to preview poster/logo/fanart
   • "Refresh NFO" button to update from TMDB (re-download media)
   • Batch "Create Missing NFOs" action
   • Batch "Download Missing Media" action

3. Create NFO Status Page (src/server/web/templates/nfo_status.html)

   • List all series with NFO status
   • Filter: All / With NFO / Without NFO
   • Bulk actions
   • Search functionality

4. Add JavaScript Handlers (src/server/web/static/js/nfo-manager.js)

   • API calls for NFO operations
   • Progress tracking during creation
   • Success/error notifications
   • Real-time status updates via WebSocket

Acceptance Criteria:

• NFO status visible on series cards
• Can create NFO from UI
• Can view NFO content in modal
• Batch operations work
• WebSocket updates for progress
• Mobile responsive
• Follows Fluent UI design
• Frontend tests pass
• Manual UI testing documented

Testing Requirements:

• Frontend Integration Tests:
  • Test NFO status badge displays correctly
  • Test "Create NFO" button functionality
  • Test "View NFO" modal opens and displays content
  • Test "Refresh NFO" button
  • Test batch create action
  • Test WebSocket progress updates
  • Mock API responses for all operations
• JavaScript Unit Tests:
  • Test API call functions
  • Test success/error notification handling
  • Test progress update logic
  • Test filtering functionality
• UI/UX Tests:
  • Test responsive design on mobile viewport
  • Test loading states
  • Test error states
  • Test accessibility (keyboard navigation, screen readers)
• Manual Testing Checklist:
  • Create checklist for manual UI testing
  • Test all user flows
  • Test edge cases (slow network, errors)
  • Browser compatibility (Chrome, Firefox, Safari, Edge)

Files to Create:

• src/server/web/templates/nfo_status.html
• src/server/web/static/js/nfo-manager.js
• src/server/web/static/css/components/nfo-status.css
• tests/frontend/test_nfo_ui.py
• docs/NFO_UI_TESTING.md (manual testing guide)

Files to Modify:

• src/server/web/templates/index.html
• src/server/web/static/js/app.js
• src/server/web/static/css/main.css

---

Task 7: Add NFO Configuration Settings

Priority: Low
Estimated Time: 2 hours

Add NFO configuration options to the settings UI.

Implementation Steps:

1. Add NFO Settings Section (src/server/web/templates/settings.html)

   NFO Metadata Settings:
   - TMDB API Key [text input] [required]
   - Auto-create NFO files [checkbox] [default: true]
   - Update NFO on rescan [checkbox] [default: false]
   - Preferred language for metadata [dropdown] [default: German]
   
   Media Download Settings:
   - Download poster.jpg [checkbox] [default: true]
   - Download logo.png [checkbox] [default: true]
   - Download fanart.jpg [checkbox] [default: true]
   - Image quality [dropdown: original/w500] [default: original]
   - Overwrite existing media [checkbox] [default: false]
   

2. Update Config Models (src/server/models/config.py)

   • Add NFOConfig section
   • Add validation

3. Add Config API Support (src/server/api/config.py)

   • Handle NFO config updates
   • Validate TMDB API key on save

Acceptance Criteria:

• Settings UI has NFO section
• Config saves and loads correctly
• TMDB API key validated
• Settings affect NFO creation behavior
• Configuration tests pass

Testing Requirements:

• Config Model Tests:
  • Test NFOConfig validation
  • Test TMDB API key format validation
  • Test required fields
  • Test default values
  • Test serialization/deserialization
• Config API Tests:
  • Test saving NFO config
  • Test loading NFO config
  • Test TMDB API key validation endpoint
  • Test invalid API key rejection
  • Test config update affects service behavior
• Integration Tests:
  • Test config changes are persisted
  • Test config loaded on app startup
  • Test NFO service respects config settings
• UI Tests:
  • Test settings form submission
  • Test validation error display
  • Test success notifications

Files to Modify:

• src/server/web/templates/settings.html
• src/server/models/config.py
• src/server/api/config.py
• tests/unit/test_config_models.py
• tests/api/test_config_endpoints.py

---

Task 8: Add Database Support for NFO Status

Priority: Medium
Estimated Time: 2-3 hours

Track NFO file status in the database.

Implementation Steps:

1. Add NFO Fields to Database Models (src/server/database/models.py)

   class AnimeSeries:
       # Add fields:
       has_nfo: bool = False
       nfo_created_at: Optional[datetime] = None
       nfo_updated_at: Optional[datetime] = None
       tmdb_id: Optional[int] = None
       tvdb_id: Optional[int] = None
   

2. Update Services (src/server/services/anime_service.py)

   • Update NFO status after creation
   • Query series by NFO status
   • Track TMDB/TVDB IDs

Acceptance Criteria:

• Database schema updated (SQLAlchemy will auto-create columns)
• NFO status tracked in DB
• Queries for missing NFOs work
• Backward compatible with existing data
• Database tests pass

Testing Requirements:

• Model Tests:
  • Test new fields default values
  • Test NFO status persistence
  • Test TMDB/TVDB ID storage
  • Test datetime fields
  • Test nullable constraints
• Service Tests:
  • Test updating NFO status after creation
  • Test querying series by NFO status
  • Test querying series without NFO
  • Test TMDB/TVDB ID queries
  • Mock database operations
• Integration Tests:
  • Test database queries return correct results
  • Test filter by has_nfo=True/False
  • Test ordering by nfo_created_at
  • Test join queries if applicable
• Backward Compatibility Tests:
  • Test loading existing series without NFO fields
  • Test default values for existing records
  • Test queries work with mixed data

Files to Modify:

• src/server/database/models.py
• src/server/services/anime_service.py
• tests/unit/test_database_models.py
• tests/unit/test_anime_service.py
• tests/integration/test_nfo_database.py

Note: No manual migration needed - SQLAlchemy will handle new columns automatically.

---

Task 9: Documentation and Testing

Priority: High
Estimated Time: 3-4 hours

Document NFO features and ensure comprehensive test coverage.

Implementation Steps:

1. Update Documentation:

   • Add NFO section to docs/API.md
   • Document NFO endpoints
   • Add configuration guide to docs/CONFIGURATION.md
   • Update README.md with NFO features
   • Add troubleshooting section

2. Create Integration Tests:

   • Test complete NFO creation workflow
   • Test download with NFO check
   • Test batch NFO creation
   • Test UI interactions

3. Add Performance Tests:

   • Test TMDB API rate limiting
   • Test concurrent NFO creation
   • Measure impact on download flow

Acceptance Criteria:

• All documentation updated
• Test coverage > 80%
• Integration tests pass
• Performance benchmarks documented
• Troubleshooting guide complete

Files to Modify:

• docs/API.md
• docs/CONFIGURATION.md
• docs/ARCHITECTURE.md
• README.md

Files to Create:

• tests/integration/test_nfo_workflow.py
• tests/performance/test_nfo_performance.py
• docs/NFO_GUIDE.md

---

📋 NFO Feature Summary

Overview: These tasks integrate tvshow.nfo metadata file creation into the Aniworld download manager using the external scraper library and TMDB API. Before downloading episodes, the system will check if tvshow.nfo exists in the series folder, and if not (and auto-create is enabled), it will scrape TMDB to create the metadata file.

Key Benefits:

• Proper media library metadata for Kodi/Plex/Jellyfin
• Better organization and presentation
• Enhanced search and discovery
• Automatic metadata maintenance

Technical Approach:

1. Copy and adapt code from /home/lukas/Volume/repo/scraper/ repository
2. Integrate TMDB API client (adapted from scraper's tmdb_client.py)
3. Integrate NFO XML generation (adapted from scraper's xml_utils.py)
4. Add NFO checking to download pre-flight checks
5. Use TMDB API to search and fetch series metadata
6. Generate tvshow.nfo with proper Kodi/XBMC format
7. Track NFO status in database
8. Provide UI for manual NFO management

Dependencies:

• Code reference: /home/lukas/Volume/repo/scraper/ (copy and adapt, not as library)
• TMDB API access (requires API key)
• Additional Python packages:
  • requests (for TMDB API and image downloads)
  • lxml (for XML generation)
  • Pillow (for image validation and processing)

Key Files to Reference from Scraper:

• API Client: /home/lukas/Volume/repo/scraper/src/scraper/api/tmdb_client.py
• Metadata Service: /home/lukas/Volume/repo/scraper/src/scraper/services/metadata_service.py
• Asset Service: /home/lukas/Volume/repo/scraper/src/scraper/services/asset_service.py
• XML Utils: /home/lukas/Volume/repo/scraper/src/scraper/utils/xml_utils.py
• Models: /home/lukas/Volume/repo/scraper/src/scraper/models/tvshow.py
• Example NFO: /home/lukas/Volume/repo/scraper/tvshow.nfo
• Example Media: Check existing series folders for poster.jpg, logo.png, fanart.jpg examples

Estimated Total Time: 25-30 hours

Priority Order:

1. Task 1-3: Core NFO support and scraper integration (High)
2. Task 4: Download flow integration (High)
3. Task 8: Database support (Medium)
4. Task 5: API endpoints (Medium)
5. Task 6: UI features (Medium)
6. Task 7: Configuration (Low)
7. Task 9: Documentation and testing (High)

---