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.

---

<EFBFBD> Credentials

Admin Login:

• Username: admin
• Password: Hallo123!

---

<EFBFBD>📚 Helpful Commands

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

All tasks completed! Recent issues have been resolved.

Recently Fixed Issues:

✅ Fixed: NFO Creation 500 Error - Missing Folder (2026-01-18)

Issue: POST http://127.0.0.1:8000/api/nfo/blue-period/create returns 500 (Internal Server Error) with message "Series folder not found: /home/lukas/Volume/serien/Blue Period"

Root Cause: The NFO service was checking if the series folder existed before creating NFO files, and raising a FileNotFoundError if it didn't. This prevented users from creating NFO files for newly added series where no episodes had been downloaded yet.

Solution: Modified create_tvshow_nfo() in nfo_service.py to automatically create the series folder (with mkdir(parents=True, exist_ok=True)) if it doesn't exist, instead of raising an error.

Files Modified:

• src/core/services/nfo_service.py

Tests Added:

• tests/unit/test_nfo_service_folder_creation.py - Unit test verifying folder creation
• tests/integration/test_nfo_folder_creation.py - Integration test for end-to-end verification

Verification:

• Unit and integration tests pass
• NFO files can now be created for series even when the folder doesn't exist
• Folder is automatically created when needed

---

✅ Fixed: NFO Service 503 Error (2026-01-18)

Issue: Failed to load resource: the server responded with a status of 503 (Service Unavailable) when creating NFO files.

Root Cause: The TMDB API key configured in data/config.json was not being loaded into the application settings during startup. The NFO service dependency check was failing because settings.tmdb_api_key was None.

Solution: Updated fastapi_app.py startup code to sync NFO configuration (including TMDB API key) from data/config.json to settings object, similar to how anime_directory was already being synced.

Files Modified:

• src/server/fastapi_app.py

Verification: NFO endpoints now return 200 OK instead of 503, and NFO creation is functional.

---

✅ Fixed: NFO Database Query Error (2026-01-18)

Issue: WARNING: Could not fetch NFO data from database: '_AsyncGeneratorContextManager' object has no attribute 'query'

Root Cause:

1. Synchronous code in anime.py was calling get_db_session() which returns an async context manager, but wasn't using async with.
2. Async methods in anime_service.py were calling get_db_session() without using async with.
3. Incorrect attribute name: used folder_name instead of folder.

Solution:

1. Changed anime.py line ~323 to use get_sync_session() instead of get_db_session() for synchronous database access.
2. Updated three async methods in anime_service.py to properly use async with get_db_session():
   • update_nfo_status()
   • get_series_without_nfo()
   • get_nfo_statistics()
3. Fixed attribute name from db_series.folder_name to db_series.folder in anime.py.

Files Modified:

• src/server/api/anime.py
• src/server/services/anime_service.py

Verification: Server now starts without warnings, and NFO metadata can be fetched from the database correctly.