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

# 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

---

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; keep your messages in git short and clear
• Take the next task

---

Prerequisites

1. Server is running: conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
2. Password: Hallo123!
3. Login via browser at http://127.0.0.1:8000/login

Notes

• This is a simplification that removes complexity while maintaining core functionality
• Improves user experience with explicit manual control
• Easier to understand, test, and maintain
• Good foundation for future enhancements if needed

---

🎯 CRITICAL: Series Identifier Standardization

Overview

Problem: The codebase currently uses multiple identifiers inconsistently:

• key (provider identifier, e.g., "attack-on-titan")
• folder (filesystem folder name, e.g., "Attack on Titan (2013)")
• serie_id (sometimes key, sometimes folder)
• serie_folder (filesystem path used as identifier)

Solution: Standardize on key as the single source of truth for all series identification.

Benefits:

• Single, consistent identifier throughout the codebase
• key is unique, provider-assigned, URL-safe
• folder becomes metadata only (not used for lookups)
• Clearer separation of concerns
• Easier to maintain and debug

Scope: This affects core logic, services, API endpoints, frontend, WebSocket events, and tests.

---

Task Series: Identifier Standardization

Phase 4: API Layer ✅ (Completed November 28, 2025)

Phase 5: Frontend ✅ (Completed November 28, 2025)

Phase 6: Database Layer ✅ (Completed November 28, 2025)

Phase 7: Testing and Validation ✅ Completed November 28, 2025

Phase 8: Documentation and Cleanup ✅ Completed November 28, 2025

All tasks completed:

• Task 8.1: Updated infrastructure.md with enhanced identifier convention section including table format, key format requirements, migration notes, and code examples
• Task 8.2: Updated docs/README.md with series identifier convention section, updated docs/api_reference.md with key-based API examples
• Task 8.3: Added deprecation warnings with Python's warnings module to:
  • SerieList.get_by_folder() in src/core/entities/SerieList.py
  • Folder fallback lookup in src/server/api/anime.py
  • validate_series_key_or_folder() in src/server/utils/validators.py

All deprecation warnings include removal timeline (v3.0.0) and guidance to use key instead.

---

Phase 9: Final Validation ✅ Completed November 28, 2025

All validation tasks completed:

• Task 9.1: Full test suite passes (1006 tests). Fixed search API key extraction from link slugs.
• Task 9.2: Manual end-to-end testing verified - login, search (returns key), queue status (uses serie_id as key). All APIs work correctly with key identifier.
• Task 9.3: Performance tests pass (19 tests). Key lookup is O(1) at ~0.11μs per lookup.

---

Task Tracking

Completion Status

• Phase 1: Core Models and Data Layer ✅
• Phase 2: Core Application Layer ✅
• Phase 3: Service Layer ✅
• Phase 4: API Layer ✅ Completed November 28, 2025
• Phase 5: Frontend ✅ Completed November 28, 2025
• Phase 6: Database Layer ✅ Completed November 28, 2025
• Phase 7: Testing and Validation ✅ Completed November 28, 2025
• Phase 8: Documentation and Cleanup ✅ Completed November 28, 2025
  • Task 8.1: Update Infrastructure Documentation - Enhanced identifier convention section with table, format requirements, migration notes, and code examples
  • Task 8.2: Update README and Developer Docs - Updated docs/README.md with identifier section, updated api_reference.md with key-based examples
  • Task 8.3: Add Deprecation Warnings - Added warnings to SerieList.get_by_folder(), anime.py folder fallback, and validators.py
• Phase 9: Final Validation ✅ Completed November 28, 2025
  • Task 9.1: Run Full Test Suite - 1006 tests pass, fixed search API key extraction
  • Task 9.2: Manual End-to-End Testing - All APIs verified with key identifier
  • Task 9.3: Performance Testing - 19 tests pass, O(1) key lookup

---

🎉 Series Identifier Standardization Complete!

All phases of the identifier standardization have been successfully completed. The codebase now consistently uses key as the primary identifier for series throughout:

• Core entities and data layer
• Application layer services
• API endpoints and responses
• Frontend integration
• Database operations
• WebSocket events

The folder field remains as metadata only and is no longer used for lookups. Deprecation warnings are in place for any legacy folder-based lookups, scheduled for removal in v3.0.0.