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

---

## <20> Credentials

**Admin Login:**

- Username: `admin`
- Password: `Hallo123!`

---

## <20>📚 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:

fix:
Failed to load NFO/images for the-dreaming-boy-is-a-realist: No results found for: The Dreaming Boy is a Realist (2023)
╭─────────────────────────────── Traceback (most recent call last) ────────────────────────────────╮
│ /home/lukas/Volume/repo/Aniworld/src/server/services/background_loader_service.py:399 in │
│ \_load_nfo_and_images │
│ │
│ 396 │ │ │ │
│ 397 │ │ │ # Use existing NFOService to create NFO with all images │
│ 398 │ │ │ # This reuses all existing TMDB API logic and image downloading │
│ ❱ 399 │ │ │ nfo_path = await self.series_app.nfo_service.create_tvshow_nfo( │
│ 400 │ │ │ │ serie_name=task.name, │
│ 401 │ │ │ │ serie_folder=task.folder, │
│ 402 │ │ │ │ year=task.year, │
│ │
│ ╭─────────────────────────────────────────── locals ───────────────────────────────────────────╮ │
│ │ db = <sqlalchemy.ext.asyncio.session.AsyncSession object at 0x736aa1e0b770> │ │
│ │ e = TMDBAPIError('No results found for: The Dreaming Boy is a Realist (2023)') │ │
│ │ self = <src.server.services.background_loader_service.BackgroundLoaderService object at │ │
│ │ 0x736aa27556a0> │ │
│ │ task = SeriesLoadingTask( │ │
│ │ │ key='the-dreaming-boy-is-a-realist', │ │
│ │ │ folder='The Dreaming Boy is a Realist (2023)', │ │
│ │ │ name='The Dreaming Boy is a Realist (2023)', │ │
│ │ │ year=None, │ │
│ │ │ status=<LoadingStatus.LOADING_NFO: 'loading_nfo'>, │ │
│ │ │ progress={'episodes': True, 'nfo': False, 'logo': False, 'images': False}, │ │
│ │ │ started_at=datetime.datetime(2026, 1, 19, 19, 37, 20, 540721, │ │
│ │ tzinfo=datetime.timezone.utc), │ │
│ │ │ completed_at=None, │ │
│ │ │ error=None │ │
│ │ ) │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │
│ /home/lukas/Volume/repo/Aniworld/src/core/services/nfo_service.py:112 in create_tvshow_nfo │
│ │
│ 109 │ │ │ search_results = await self.tmdb_client.search_tv_show(serie_name) │
│ 110 │ │ │ │
│ 111 │ │ │ if not search_results.get("results"): │
│ ❱ 112 │ │ │ │ raise TMDBAPIError(f"No results found for: {serie_name}") │
│ 113 │ │ │ │
│ 114 │ │ │ # Find best match (consider year if provided) │
│ 115 │ │ │ tv_show = self.\_find_best_match(search_results["results"], serie_name, year) │
│ │
│ ╭─────────────────────────────────────────── locals ───────────────────────────────────────────╮ │
│ │ download_fanart = True │ │
│ │ download_logo = True │ │
│ │ download_poster = True │ │
│ │ folder_path = PosixPath('/mnt/server/serien/Serien/The Dreaming Boy is a Realist │ │
│ │ (2023)') │ │
│ │ search_results = {'page': 1, 'results': [], 'total_pages': 1, 'total_results': 0} │ │
│ │ self = <src.core.services.nfo_service.NFOService object at 0x736aa273ce10> │ │
│ │ serie_folder = 'The Dreaming Boy is a Realist (2023)' │ │
│ │ serie_name = 'The Dreaming Boy is a Realist (2023)' │ │
│ │ year = None │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
TMDBAPIError: No results found for: The Dreaming Boy is a Realist (2023)

2026-01-19 20:37:37 [debug ] Message broadcast failed_count=0 message_type=series_loading_update recipient_count=0
2026-01-19 20:37:37 [info ] Successfully loaded all data for series: the-dreaming-boy-is-a-realist
2026-01-19 20:37:37 [info ] Processing loading task for series: bel-blatt
2026-01-19 20:37:37 [debug ] Message broadcast failed_count=0 message_type=series_loading_update recipient_count=0
INFO: Creating NFO for Übel Blatt (2025) (year: None)