# 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 - [ ] 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.