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

```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
```

---

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

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