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

```bash
# 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.

---

## Pending Tasks

### High Priority

#### [] Input Validation Tests (11 failing)

-   [] Implement file upload validation endpoints
-   [] Add pagination parameter validation
-   [] Implement email validation
-   [] Add null byte injection handling
-   [] Implement oversized input validation
-   [] Add path traversal protection
-   [] Implement array/object injection validation

#### [] Performance Test Infrastructure (14 errors)

-   [] Fix async fixture issues
-   [] Add missing mocks for download queue
-   [] Configure event loop for stress tests
-   [] Update test setup/teardown patterns

### Integration Enhancements

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

### 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

#### [] Environment management

-   [] Create environment-specific configurations
-   [] Add secrets management
-   [] Implement feature flags
-   [] Include environment validation
-   [] Add rollback mechanisms

## Implementation Best Practices

### Error Handling Patterns

```python
# 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

```python
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

```python
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

```python
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.