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.

---

<EFBFBD> Credentials

Admin Login:

• Username: admin
• Password: Hallo123!

---

<EFBFBD>📚 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:

High Priority - Test Failures (136 total)

1. TMDB API Resilience Tests (26 failures)

Location: tests/integration/test_tmdb_resilience.py, tests/unit/test_tmdb_rate_limiting.py Issue: TypeError: 'coroutine' object does not support the asynchronous context manager protocol Root cause: Mock session.get() returns coroutine instead of async context manager Impact: All TMDB API resilience and timeout tests failing

• Fix mock setup in TMDB resilience tests
• Fix mock setup in TMDB rate limiting tests
• Ensure AsyncMock context managers are properly configured

2. Config Backup/Restore Tests (18 failures)

Location: tests/integration/test_config_backup_restore.py Issue: Authentication failures (401 Unauthorized) Root cause: authenticated_client fixture not properly authenticating Affected tests:

• test_create_backup_with_default_name
• test_multiple_backups_can_be_created
• test_list_backups_returns_array
• test_list_backups_contains_metadata
• test_list_backups_shows_recently_created
• test_restore_nonexistent_backup_fails
• test_restore_backup_with_valid_backup
• test_restore_creates_backup_before_restoring
• test_restored_config_matches_backup
• test_delete_existing_backup
• test_delete_removes_backup_from_list
• test_delete_removes_backup_file
• test_delete_nonexistent_backup_fails
• test_full_backup_restore_workflow
• test_restore_with_invalid_backup_name
• test_concurrent_backup_operations
• test_backup_with_very_long_custom_name
• test_backup_preserves_all_configuration_sections

3. Background Loader Service Tests (10 failures)

Location: tests/integration/test_async_series_loading.py, tests/unit/test_background_loader_session.py, tests/integration/test_anime_add_nfo_isolation.py Issues: Service initialization, task processing, NFO loading

• test_loader_start_stop - Fix worker_task vs worker_tasks attribute
• test_add_series_loading_task - Tasks not being added to active_tasks
• test_multiple_tasks_concurrent - Active tasks not being tracked
• test_no_duplicate_tasks - No tasks registered
• test_adding_tasks_is_fast - Active tasks empty
• test_load_series_data_loads_missing_episodes - _load_episodes not called
• test_add_anime_loads_nfo_only_for_new_anime - NFO service not called
• test_add_anime_has_nfo_check_is_isolated - has_nfo check not called
• test_multiple_anime_added_each_loads_independently - NFO service call count wrong
• test_nfo_service_receives_correct_parameters - Call args is None

4. Performance Tests (4 failures)

Location: tests/performance/test_large_library.py, tests/performance/test_api_load.py Issues: Missing attributes, database not initialized, service not initialized

• test_scanner_progress_reporting_1000_series - AttributeError: '_SerieClass' missing
• test_database_query_performance_1000_series - Database not initialized
• test_concurrent_scan_prevention - get_anime_service() missing required argument
• test_health_endpoint_load - RPS too low (37.27 < 50 expected)

5. NFO Tracking Tests (4 failures)

Location: tests/unit/test_anime_service.py Issue: TypeError: object MagicMock can't be used in 'await' expression Root cause: Database mocks not properly configured for async

• test_update_nfo_status_success
• test_update_nfo_status_not_found
• test_get_series_without_nfo
• test_get_nfo_statistics

6. Concurrent Anime Add Tests (2 failures)

Location: tests/api/test_concurrent_anime_add.py Issue: RuntimeError: BackgroundLoaderService not initialized Root cause: Service not initialized in test setup

• test_concurrent_anime_add_requests
• test_same_anime_concurrent_add

7. Other Test Failures (3 failures)

• test_get_database_session_handles_http_exception - Database not initialized
• test_anime_endpoint_returns_series_after_loading - Empty response (expects 2, got 0)

Summary

• Total failures: 136 out of 2503 tests
• Pass rate: 94.6%
• Main issues:
  1. AsyncMock configuration for TMDB tests
  2. Authentication in backup/restore tests
  3. Background loader service lifecycle
  4. Database mock configuration for async operations
  5. Service initialization in tests

---