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.

---

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

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

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