# 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 ## Implementation Order The tasks should be completed in the following order to ensure proper dependencies and logical progression: 1. **Project Structure Setup** - Foundation and dependencies 2. **Authentication System** - Security layer implementation 3. **Configuration Management** - Settings and config handling 4. **Anime Management Integration** - Core functionality wrapper 5. **Download Queue Management** - Queue handling and persistence 6. **WebSocket Real-time Updates** - Real-time communication 7. **Frontend Integration** - Integrate existing frontend assets 8. **Core Logic Integration** - Enhance existing core functionality 9. **Database Layer** - Data persistence and management 10. **Testing** - Comprehensive test coverage 11. **Deployment and Configuration** - Production setup 12. **Documentation and Error Handling** - Final documentation and error handling # make the following steps for each task or subtask. make sure you do not miss one 1. Task the next task 2. Process the task 3. Make Tests. 4. Remove task from instructions.md. 5. Update infrastructure.md 6. Commit in git ## Core Tasks ### 1. Project Structure Setup #### [] Set up dependency injection system - []Create `src/server/utils/dependencies.py` - []Implement SeriesApp dependency injection - []Add database session dependency - []Create authentication dependency #### [] Configure logging system - []Create `src/server/utils/logging.py` - []Set up structured logging with multiple handlers - []Configure log rotation and cleanup - []Add request/response logging middleware ### 2. Authentication System #### [] Implement authentication models - []Create `src/server/models/auth.py` - []Define LoginRequest, LoginResponse models - []Add SetupRequest, AuthStatus models - []Include session management models #### [] Create authentication service - []Create `src/server/services/auth_service.py` - []Implement master password setup/validation - []Add session management with JWT tokens - []Include failed attempt tracking and lockout - []Add password strength validation #### [] Implement authentication API endpoints - []Create `src/server/api/auth.py` - []Add POST `/api/auth/setup` - initial setup - []Add POST `/api/auth/login` - login endpoint - []Add POST `/api/auth/logout` - logout endpoint - []Add GET `/api/auth/status` - authentication status #### [] Create authentication middleware - []Create `src/server/middleware/auth.py` - []Implement JWT token validation - []Add request authentication checking - []Include rate limiting for auth endpoints ### 3. Configuration Management #### [] Implement configuration models - []Create `src/server/models/config.py` - []Define ConfigResponse, ConfigUpdate models - []Add SchedulerConfig, LoggingConfig models - []Include ValidationResult model #### [] Create configuration service - []Create `src/server/services/config_service.py` - []Implement configuration loading/saving - []Add configuration validation - []Include backup/restore functionality - []Add scheduler configuration management #### [] Implement configuration API endpoints - []Create `src/server/api/config.py` - []Add GET `/api/config` - get configuration - []Add PUT `/api/config` - update configuration - []Add POST `/api/config/validate` - validate config - []Add GET/POST `/api/config/backup` - backup management ### 4. Anime Management Integration #### [] Implement anime models - []Create `src/server/models/anime.py` - []Define AnimeSeriesResponse, EpisodeInfo models - []Add SearchRequest, SearchResult models - []Include MissingEpisodeInfo model #### [] Create anime service wrapper - []Create `src/server/services/anime_service.py` - []Wrap SeriesApp functionality for web layer - []Implement async wrappers for blocking operations - []Add caching for frequently accessed data - []Include error handling and logging #### [] Implement anime API endpoints - []Create `src/server/api/anime.py` - []Add GET `/api/v1/anime` - list series with missing episodes - []Add POST `/api/v1/anime/rescan` - trigger rescan - []Add POST `/api/v1/anime/search` - search for new anime - []Add GET `/api/v1/anime/{id}` - get series details ### 5. Download Queue Management #### [] Implement download queue models - []Create `src/server/models/download.py` - []Define DownloadItem, QueueStatus models - []Add DownloadProgress, QueueStats models - []Include DownloadRequest model #### [] Create download queue service - []Create `src/server/services/download_service.py` - []Implement queue management (add, remove, reorder) - []Add download progress tracking - []Include queue persistence and recovery - []Add concurrent download management #### [] Implement download API endpoints - []Create `src/server/api/download.py` - []Add GET `/api/queue/status` - get queue status - []Add POST `/api/queue/add` - add to queue - []Add DELETE `/api/queue/{id}` - remove from queue - []Add POST `/api/queue/start` - start downloads - []Add POST `/api/queue/stop` - stop downloads ### 6. WebSocket Real-time Updates #### [] Implement WebSocket manager - []Create `src/server/services/websocket_service.py` - []Add connection management - []Implement broadcast functionality - []Include room-based messaging - []Add connection cleanup #### [] Add real-time progress updates - []Create `src/server/services/progress_service.py` - []Implement download progress broadcasting - []Add scan progress updates - []Include queue status changes - []Add error notifications #### [] Integrate WebSocket with core services - []Update download service to emit progress - []Add scan progress notifications - []Include queue change broadcasts - []Add error/completion notifications ### 7. Frontend Integration #### [] Integrate existing HTML templates - []Review and integrate existing HTML templates in `src/server/web/templates/` - []Ensure templates work with FastAPI Jinja2 setup - []Update template paths and static file references if needed - []Maintain existing responsive layout and theme switching #### [] Integrate existing JavaScript functionality - []Review existing JavaScript files in `src/server/web/static/js/` - []Update API endpoint URLs to match FastAPI routes - []Ensure WebSocket connections work with new backend - []Maintain existing functionality for app.js and queue.js #### [] Integrate existing CSS styling - []Review and integrate existing CSS files in `src/server/web/static/css/` - []Ensure styling works with FastAPI static file serving - []Maintain existing responsive design and theme support - []Update any hardcoded paths if necessary #### [] Update frontend-backend integration - []Ensure existing JavaScript calls match new API endpoints - []Update authentication flow to work with new auth system - []Verify WebSocket events match new service implementations - []Test all existing UI functionality with new backend ### 8. Core Logic Integration #### [] Enhance SeriesApp for web integration - []Update `src/core/SeriesApp.py` - []Add async callback support - []Implement progress reporting - []Include better error handling - []Add cancellation support #### [] Create progress callback system - []Add progress callback interface - []Implement scan progress reporting - []Add download progress tracking - []Include error/completion callbacks #### [] Add configuration persistence - []Implement configuration file management - []Add settings validation - []Include backup/restore functionality - []Add migration support for config updates ### 9. Database Layer #### [] Implement database models - []Create `src/server/database/models.py` - []Add SQLAlchemy models for anime series - []Implement download queue persistence - []Include user session storage #### [] Create database service - []Create `src/server/database/service.py` - []Add CRUD operations for anime data - []Implement queue persistence - []Include database migration support #### [] Add database initialization - []Create `src/server/database/init.py` - []Implement database setup - []Add initial data migration - []Include schema validation ### 10. Testing #### [] Create unit tests for services - []Create `tests/unit/test_auth_service.py` - []Create `tests/unit/test_anime_service.py` - []Create `tests/unit/test_download_service.py` - []Create `tests/unit/test_config_service.py` #### [] Create API endpoint tests - []Create `tests/api/test_auth_endpoints.py` - []Create `tests/api/test_anime_endpoints.py` - []Create `tests/api/test_download_endpoints.py` - []Create `tests/api/test_config_endpoints.py` #### [] Create integration tests - []Create `tests/integration/test_download_flow.py` - []Create `tests/integration/test_auth_flow.py` - []Create `tests/integration/test_websocket.py` #### [] Create frontend integration tests - []Create `tests/frontend/test_existing_ui_integration.py` - []Test existing JavaScript functionality with new backend - []Verify WebSocket connections and real-time updates - []Test authentication flow with existing frontend ### 11. Deployment and Configuration #### [] Create Docker configuration - []Create `Dockerfile` - []Create `docker-compose.yml` - []Add environment configuration - []Include volume mappings for existing web assets #### [] Create production configuration - []Create `src/server/config/production.py` - []Add environment variable handling - []Include security settings - []Add performance optimizations #### [] Create startup scripts - []Create `scripts/start.sh` - []Create `scripts/setup.py` - []Add dependency installation - []Include database initialization ### 12. Documentation and Error Handling #### [] Create API documentation - []Add OpenAPI/Swagger documentation - []Include endpoint descriptions - []Add request/response examples - []Include authentication details #### [] Implement comprehensive error handling - []Create custom exception classes - []Add error logging and tracking - []Implement user-friendly error messages - []Include error recovery mechanisms #### [] Create user documentation - []Create `docs/user_guide.md` - []Add installation instructions - []Include configuration guide - []Add troubleshooting section ## 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.