Aniworld/docs/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

#Run app
conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
```

---

## 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 and other docs
-   [ ] Changes committed to git; keep your messages in git short and clear
-   [ ] Take the next task

---

## TODO List:

### Completed Tasks:

1. **✅ Fixed copy issue to folder /mnt/server/serien/Serien/** (Completed: 2026-01-09)

    **Issue**: PermissionError when copying downloaded files to target directory

    ```
    PermissionError: [Errno 13] Permission denied: '/mnt/server/serien/Serien/Gachiakuta (2025)/Season 1/Gachiakuta - S01E023 - (German Dub).mp4'
    ```

    **Root Cause**:

    - `shutil.copy2()` and `shutil.copy()` attempt to preserve file metadata (permissions, timestamps, ownership)
    - Preserving metadata requires special permissions on the target directory
    - The mounted network directory `/mnt/server/serien/Serien/` has restricted metadata permissions

    **Solution**:

    - Replaced `shutil.copy2()` with `shutil.copyfile()` in [enhanced_provider.py](../src/core/providers/enhanced_provider.py#L558)
    - Replaced `shutil.copy()` with `shutil.copyfile()` in [aniworld_provider.py](../src/core/providers/aniworld_provider.py#L329)
    - `shutil.copyfile()` only copies file content without attempting to preserve metadata

    **Verification**:

    - Created comprehensive tests confirming the fix works
    - Download process can now successfully copy files to `/mnt/server/serien/Serien/`
    - Both providers (aniworld and enhanced) updated

### Active Tasks:

_No active tasks at the moment._