lukas.pupkalipinski/Aniworld
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Aniworld/instructions.md
Lukas 7481a33c15 instruction2
2025-10-12 22:39:51 +02:00

12 KiB
Raw Blame History

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.

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

Implementation Order

  1. Start with project structure and dependencies
  2. Implement authentication system completely
  3. Add configuration management
  4. Create anime service wrapper
  5. Implement download queue management
  6. Add WebSocket real-time updates
  7. Integrate existing frontend assets with new backend
  8. Enhance core logic integration
  9. Implement database layer
  10. Create comprehensive tests
  11. Add deployment configuration
  12. Complete documentation

Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards.