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:

### Task: Refactor Series Addition and Folder Creation Logic

**Priority:** High  
**Status:** ✅ Complete

#### Overview

Refactored the series addition workflow to defer folder creation until download time and ensure proper series scanning on addition. This improves the separation of concerns and ensures a cleaner workflow.

#### Completed Changes

1. **Folder Creation Removed from Series Addition**
   - Modified [src/server/api/anime.py](../src/server/api/anime.py) to remove folder creation on series add
   - Series are now only added to the database and in-memory structures
   - Folder creation is deferred to download time

2. **Folder Creation Added to Download Start**
   - Updated [src/core/SeriesApp.py](../src/core/SeriesApp.py) `download()` method
   - Added folder existence check before download
   - Creates folder if it doesn't exist using the series folder name
   - Includes proper error handling and logging

3. **Database Persistence Maintained**
   - Series are still properly saved to the database on addition
   - No regression in database entry creation

4. **Targeted Scanning Works**
   - Scan logic continues to work correctly
   - Only the added series is scanned (not full library rescan)
   - Works correctly even when folder doesn't exist yet

#### Test Results

- All add_series endpoint tests passing (9/9)
- All SeriesApp download tests passing (4/4)
- Total: 1132 tests passing (up from 1123 before changes)
- Remaining failures are unrelated to these changes (scan_service, download_service issues)

#### Note on Year Attribute

Year information is not currently available in the Serie class or search results. The folder naming currently uses just the series name without the year suffix. This can be enhanced in a future task when year metadata is added to the system.

---