2025-10-19 19:57:42 +02:00

16 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

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

Implementation Order

The tasks should be completed in the following order to ensure proper dependencies and logical progression:

Project Structure Setup - Foundation and dependencies
Authentication System - Security layer implementation
Configuration Management - Settings and config handling
Anime Management Integration - Core functionality wrapper
Download Queue Management - Queue handling and persistence
WebSocket Real-time Updates - Real-time communication
Frontend Integration - Integrate existing frontend assets
Core Logic Integration - Enhance existing core functionality
Database Layer - Data persistence and management
Testing - Comprehensive test coverage
Deployment and Configuration - Production setup
Documentation and Error Handling - Final documentation and error handling

Final Implementation Notes

Incremental Development: Implement features incrementally, testing each component thoroughly before moving to the next
Code Review: Review all generated code for adherence to project standards
Documentation: Document all public APIs and complex logic
Testing: Maintain test coverage above 80% for all new code
Performance: Profile and optimize critical paths, especially download and streaming operations
Security: Regular security audits and dependency updates
Monitoring: Implement comprehensive monitoring and alerting
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.

Core Tasks

10. Tests

[]make sure all tests are passing. Check logic and fix code or test.

11. Deployment and Configuration

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

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

# 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

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

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

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

Incremental Development: Implement features incrementally, testing each component thoroughly before moving to the next
Code Review: Review all generated code for adherence to project standards
Documentation: Document all public APIs and complex logic
Testing: Maintain test coverage above 80% for all new code
Performance: Profile and optimize critical paths, especially download and streaming operations
Security: Regular security audits and dependency updates
Monitoring: Implement comprehensive monitoring and alerting
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.

16 KiB Raw Blame History

Aniworld Web Application Development Instructions

Project Overview

Architecture Principles

Additional Implementation Guidelines

Code Style and Standards

Implementation Order

Final Implementation Notes

Task Completion Checklist

Core Tasks

10. Tests

11. Deployment and Configuration

[] Create production configuration

[] Create startup scripts

12. Documentation and Error Handling

[] Create API documentation

[] Implement comprehensive error handling

[] Create user documentation

File Size Guidelines

Existing Frontend Assets

Quality Assurance

[] Code quality checks

[] Performance testing

[] Security validation

Monitoring and Health Checks

[] Implement health check endpoints

[] Create monitoring service

[] Add metrics collection

Advanced Features

[] Implement backup and restore

[] Create notification system

[] Add analytics and reporting

Maintenance and Operations

[] Create maintenance endpoints

[] Implement log management

[] Create system utilities

Security Enhancements

[] Implement rate limiting

[] Add security headers

[] Create audit logging

Data Management

[] Implement data validation

[] Create data migration tools

[] Add caching layer

Integration Enhancements

[] Extend provider system

[] Create plugin system

[] Add external API integrations

Advanced Testing

[] Performance testing

[] Security testing

[] End-to-end testing

Deployment Strategies

[] Environment management

Implementation Best Practices

Error Handling Patterns

Logging Standards

API Response Patterns

Dependency Injection Patterns

Final Implementation Notes

Task Completion Checklist

16 KiB

Raw Blame History