Aniworld/instructions.md

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

# 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

• Add OpenAPI/Swagger documentation (FastAPI configured with /api/docs and /api/redoc)
• Include endpoint descriptions (documented in docs/api_reference.md)
• Add request/response examples (included in all endpoint documentation)
• Include authentication details (JWT authentication documented)

[x] Implement comprehensive error handling

• Create custom exception classes (src/server/exceptions/exceptions.py with 12 exception types)
• Add error logging and tracking (src/server/utils/error_tracking.py with ErrorTracker and RequestContextManager)
• Implement user-friendly error messages (structured error responses in error_handler.py)
• Include error recovery mechanisms (planned for future, basic structure in place)

[x] Create user documentation

• Create docs/user_guide.md (comprehensive user guide completed)
• Add installation instructions (included in user guide and deployment guide)
• Include configuration guide (detailed configuration section in both guides)
• Add troubleshooting section (comprehensive troubleshooting guide included)

[x] Create API reference documentation

• Created docs/api_reference.md with complete API documentation
• Documented all REST endpoints with examples
• Documented WebSocket endpoints
• Included error codes and status codes
• Added authentication and authorization details
• Included rate limiting and pagination documentation

[x] Create deployment documentation

• Created docs/deployment.md with production deployment guide
• Included system requirements
• Added pre-deployment checklist
• Included production deployment steps
• Added Docker deployment instructions
• Included Nginx reverse proxy configuration
• Added security considerations
• 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

# 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

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.