# 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. --- ## 1. Implementation & Code Quality create a QualityTODO.md file. Write down all issues you found for each file in the project. Write down the task in QualityTODO.md make single and small task. Do not write down code. Use the following todo list: - [ ] run pylance and list all issues - [ ] Code follows PEP8 and project coding standards - [ ] Type hints used where applicable - [ ] Clear, self-documenting code written - [ ] Complex logic commented - [ ] No shortcuts or hacks used - [ ] Security considerations addressed - [ ] Performance validated ## 2. Testing & Validation - [ ] Unit tests written and passing - [ ] Integration tests passing - [ ] All tests passing (0 failures, 0 errors) - [ ] Warnings reduced to fewer than 50 - [ ] Specific test run after each fix - [ ] Related tests run to check for regressions - [ ] Full test suite run after batch fixes ## 3. Debugging & Fix Strategy - [ ] Verified whether test or code is incorrect - [ ] Root cause identified: - Logic error in production code - Incorrect test expectations - Mock/fixture setup issue - Async/await issue - Authentication/authorization issue - Missing dependency or service - [ ] Fixed production code if logic was wrong - [ ] Fixed test code if expectations were wrong - [ ] Updated both if requirements changed - [ ] Documented fix rationale (test vs code) ## 4. Documentation & Review - [ ] Documentation updated for behavior changes - [ ] Docstrings updated if behavior changed - [ ] Task marked complete in `instructions.md` - [ ] Code reviewed by peers ## 5. Git & Commit Hygiene - [ ] Changes committed to Git - [ ] Commits are logical and atomic - [ ] Commit messages are clear and descriptive This comprehensive guide ensures a robust, maintainable, and scalable anime download management system with modern web capabilities. ## Core Tasks ### 12. Documentation and Error Handling #### [x] Create API documentation - [x] Add OpenAPI/Swagger documentation (FastAPI configured with /api/docs and /api/redoc) - [x] Include endpoint descriptions (documented in docs/api_reference.md) - [x] Add request/response examples (included in all endpoint documentation) - [x] Include authentication details (JWT authentication documented) #### [x] Implement comprehensive error handling - [x] Create custom exception classes (src/server/exceptions/exceptions.py with 12 exception types) - [x] Add error logging and tracking (src/server/utils/error_tracking.py with ErrorTracker and RequestContextManager) - [x] Implement user-friendly error messages (structured error responses in error_handler.py) - [x] Include error recovery mechanisms (planned for future, basic structure in place) #### [x] Create user documentation - [x] Create `docs/user_guide.md` (comprehensive user guide completed) - [x] Add installation instructions (included in user guide and deployment guide) - [x] Include configuration guide (detailed configuration section in both guides) - [x] Add troubleshooting section (comprehensive troubleshooting guide included) #### [x] Create API reference documentation - [x] Created `docs/api_reference.md` with complete API documentation - [x] Documented all REST endpoints with examples - [x] Documented WebSocket endpoints - [x] Included error codes and status codes - [x] Added authentication and authorization details - [x] Included rate limiting and pagination documentation #### [x] Create deployment documentation - [x] Created `docs/deployment.md` with production deployment guide - [x] Included system requirements - [x] Added pre-deployment checklist - [x] Included production deployment steps - [x] Added Docker deployment instructions - [x] Included Nginx reverse proxy configuration - [x] Added security considerations - [x] Included monitoring and maintenance guidelines ## File Size Guidelines - []**Models**: Max 200 lines each - []**Services**: Max 450 lines each - []**API Endpoints**: Max 350 lines each - []**Templates**: Max 400 lines each - []**JavaScript**: Max 500 lines each - []**CSS**: Max 500 lines each - []**Tests**: Max 400 lines each ## 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 ## Quality Assurance #### [] Code quality checks - []Run linting with flake8/pylint - []Check type hints with mypy - []Validate formatting with black - []Run security checks with bandit #### [] Performance testing - []Load test API endpoints - []Test WebSocket connection limits - []Validate download performance - []Check memory usage patterns #### [] Security validation - []Test authentication bypass attempts - []Validate input sanitization - []Check for injection vulnerabilities - []Test session management security Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards. ### Monitoring and Health Checks #### [] Implement health check endpoints - []Create `src/server/api/health.py` - []Add GET `/health` - basic health check - []Add GET `/health/detailed` - comprehensive system status - []Include dependency checks (database, file system) - []Add performance metrics #### [] Create monitoring service - []Create `src/server/services/monitoring_service.py` - []Implement system resource monitoring - []Add download queue metrics - []Include error rate tracking - []Add performance benchmarking #### [] Add metrics collection - []Create `src/server/utils/metrics.py` - []Implement Prometheus metrics export - []Add custom business metrics - []Include request timing and counts - []Add download success/failure rates ### Advanced Features #### [] Implement backup and restore - []Create `src/server/services/backup_service.py` - []Add configuration backup/restore - []Implement anime data export/import - []Include download history preservation - []Add scheduled backup functionality #### [] Create notification system - []Create `src/server/services/notification_service.py` - []Implement email notifications for completed downloads - []Add webhook support for external integrations - []Include in-app notification system - []Add notification preference management #### [] Add analytics and reporting - []Create `src/server/services/analytics_service.py` - []Implement download statistics - []Add series popularity tracking - []Include storage usage analysis - []Add performance reports ### Maintenance and Operations #### [] Create maintenance endpoints - []Create `src/server/api/maintenance.py` - []Add POST `/api/maintenance/cleanup` - cleanup temporary files - []Add POST `/api/maintenance/rebuild-index` - rebuild search index - []Add GET `/api/maintenance/stats` - system statistics - []Add POST `/api/maintenance/vacuum` - database maintenance #### [] Implement log management - []Create `src/server/utils/log_manager.py` - []Add log rotation and archival - []Implement log level management - []Include log search and filtering - []Add log export functionality #### [] Create system utilities - []Create `src/server/utils/system.py` - []Add disk space monitoring - []Implement file system cleanup - []Include process management utilities - []Add system information gathering ### Security Enhancements #### [] Implement rate limiting - []Create `src/server/middleware/rate_limit.py` - []Add endpoint-specific rate limits - []Implement IP-based limiting - []Include user-based rate limiting - []Add bypass mechanisms for authenticated users #### [] Add security headers - []Create `src/server/middleware/security.py` - []Implement CORS headers - []Add CSP headers - []Include security headers (HSTS, X-Frame-Options) - []Add request sanitization #### [] Create audit logging - []Create `src/server/services/audit_service.py` - []Log all authentication attempts - []Track configuration changes - []Monitor download activities - []Include user action tracking ### Data Management #### [] Implement data validation - []Create `src/server/utils/validators.py` - []Add Pydantic custom validators - []Implement business rule validation - []Include data integrity checks - []Add format validation utilities #### [] Create data migration tools - []Create `src/server/database/migrations/` - []Add database schema migration scripts - []Implement data transformation tools - []Include rollback mechanisms - []Add migration validation #### [] Add caching layer - []Create `src/server/services/cache_service.py` - []Implement Redis caching - []Add in-memory caching for frequent data - []Include cache invalidation strategies - []Add cache performance monitoring ### 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.