# 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 ## How you work 1. Task the next task 2. Process the task 3. Make Tests. 4. Remove task from instructions.md 5. Commit in git 6. goto 1. ## 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 ## Core Tasks ### 1. Project Structure Setup #### [] Create main FastAPI application structure - Create `src/server/main.py` - Configure FastAPI app with CORS, middleware - Set up static file serving for existing frontend assets - Configure Jinja2 templates - Add health check endpoint #### [] 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.