# 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 ```bash # 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 ``` --- # Unified Task Completion Checklist This checklist ensures consistent, high-quality task execution across implementation, testing, debugging, documentation, and version control. --- ## Core Tasks ### 12. Documentation and Error Handling ## Existing Frontend Assets The following frontend assets already exist and should be integrated: - []**Templates**: Located in `src/server/web/templates/` - []**JavaScript**: Located in `src/server/web/static/js/` (app.js, queue.js, etc.) - []**CSS**: Located in `src/server/web/static/css/` - []**Static Assets**: Images and other assets in `src/server/web/static/` When working with these files: - []Review existing functionality before making changes - []Maintain existing UI/UX patterns and design - []Update API calls to match new FastAPI endpoints - []Preserve existing WebSocket event handling - []Keep existing theme and responsive design features ### Data Management #### [] Create data migration tools - []Create `src/server/database/migrations/` - []Add database schema migration scripts - []Implement data transformation tools - []Include rollback mechanisms - []Add migration validation ### Integration Enhancements #### [] Extend provider system - []Enhance `src/core/providers/` for better web integration - []Add provider health monitoring - []Implement provider failover mechanisms - []Include provider performance tracking - []Add dynamic provider configuration #### [] Create plugin system - []Create `src/server/plugins/` - []Add plugin loading and management - []Implement plugin API - []Include plugin configuration - []Add plugin security validation #### [] Add external API integrations - []Create `src/server/integrations/` - []Add anime database API connections - []Implement metadata enrichment services - []Include content recommendation systems - []Add external notification services ### Advanced Testing #### [] Performance testing - []Create `tests/performance/` - []Add load testing for API endpoints - []Implement stress testing for download system - []Include memory leak detection - []Add concurrency testing #### [] Security testing - []Create `tests/security/` - []Add penetration testing scripts - []Implement vulnerability scanning - []Include authentication bypass testing - []Add input validation testing #### [] End-to-end testing - []Create `tests/e2e/` - []Add full workflow testing - []Implement UI automation tests - []Include cross-browser testing - []Add mobile responsiveness testing ### Deployment Strategies #### [] Environment management - []Create environment-specific configurations - []Add secrets management - []Implement feature flags - []Include environment validation - []Add rollback mechanisms ## Implementation Best Practices ### Error Handling Patterns ```python # Custom exception hierarchy class AniWorldException(Exception): """Base exception for AniWorld application""" pass class AuthenticationError(AniWorldException): """Authentication related errors""" pass class DownloadError(AniWorldException): """Download related errors""" pass # Service-level error handling async def download_episode(episode_id: str) -> DownloadResult: try: result = await downloader.download(episode_id) return result except ProviderError as e: logger.error(f"Provider error downloading {episode_id}: {e}") raise DownloadError(f"Failed to download episode: {e}") except Exception as e: logger.exception(f"Unexpected error downloading {episode_id}") raise DownloadError("Unexpected download error") ``` ### Logging Standards ```python import logging import structlog # Configure structured logging structlog.configure( processors=[ structlog.stdlib.add_log_level, structlog.stdlib.add_logger_name, structlog.processors.TimeStamper(fmt="iso"), structlog.processors.JSONRenderer() ], wrapper_class=structlog.stdlib.BoundLogger, logger_factory=structlog.stdlib.LoggerFactory(), cache_logger_on_first_use=True, ) logger = structlog.get_logger(__name__) # Usage examples logger.info("Download started", episode_id=episode_id, user_id=user_id) logger.error("Download failed", episode_id=episode_id, error=str(e)) ``` ### API Response Patterns ```python from pydantic import BaseModel from typing import Optional, List, Any class APIResponse(BaseModel): success: bool message: Optional[str] = None data: Optional[Any] = None errors: Optional[List[str]] = None class PaginatedResponse(APIResponse): total: int page: int per_page: int pages: int # Usage in endpoints @router.get("/anime", response_model=PaginatedResponse) async def list_anime(page: int = 1, per_page: int = 20): try: anime_list, total = await anime_service.list_anime(page, per_page) return PaginatedResponse( success=True, data=anime_list, total=total, page=page, per_page=per_page, pages=(total + per_page - 1) // per_page ) except Exception as e: logger.exception("Failed to list anime") return APIResponse( success=False, message="Failed to retrieve anime list", errors=[str(e)] ) ``` ### Dependency Injection Patterns ```python from fastapi import Depends from typing import Annotated # Service dependencies def get_anime_service() -> AnimeService: return AnimeService() def get_download_service() -> DownloadService: return DownloadService() # Dependency annotations AnimeServiceDep = Annotated[AnimeService, Depends(get_anime_service)] DownloadServiceDep = Annotated[DownloadService, Depends(get_download_service)] # Usage in endpoints @router.post("/download") async def start_download( request: DownloadRequest, download_service: DownloadServiceDep, anime_service: AnimeServiceDep ): # Implementation pass ``` ## Final 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 - [ ] Changes committed to git This comprehensive guide ensures a robust, maintainable, and scalable anime download management system with modern web capabilities.