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)

All API layer tasks completed.

---

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

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

All database layer tasks completed:

• Task 6.1: Verified AnimeSeries.key is unique and indexed, folder is metadata only, updated docstrings
• Task 6.2: Verified all service methods use key for lookups, no folder-based identification

---

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

Task 7.1: Update All Test Fixtures to Use Key ✅

Files: All test files in tests/

Objective: Ensure all test fixtures and mocks use key consistently.

Steps:

1. Search for all test files using folder as identifier
2. Update FakeSerie class in tests/api/test_anime_endpoints.py:
   • Ensure key is the primary identifier
3. Update all test fixtures to use key
4. Update mock data to use realistic key values
5. Ensure tests verify both key and folder are present but only key is used for operations

Success Criteria:

• All test fixtures use key as identifier
• Tests verify key is used for operations
• Tests verify folder is present as metadata
• All tests pass (1006 tests passing)

Test Command:

conda run -n AniWorld python -m pytest tests/ -v

Completion Notes:

• Updated FakeSerie and FakeSeriesApp in test_anime_endpoints.py with realistic keys
• Updated fixtures in test_websocket_integration.py (6+ fixtures)
• Updated fixtures in test_download_progress_integration.py (5 fixtures)
• Updated fixtures in test_download_progress_websocket.py (9 fixtures)
• Updated fixtures in test_download_models.py (10+ fixtures)
• All fixtures now use URL-safe, lowercase, hyphenated key format

---

Task 7.2: Add Integration Tests for Identifier Consistency ✅

File: Created tests/integration/test_identifier_consistency.py

Objective: Create integration tests to verify key is used consistently across all layers.

Steps:

1. Create tests/integration/test_identifier_consistency.py
2. Write test to verify:
   • API endpoint returns key as identifier
   • Download service uses key
   • Database lookups use key
   • WebSocket events include key
3. Write test to verify folder is never used for lookups
4. Write test for end-to-end flow using key

Success Criteria:

• Integration test file created
• Tests verify key usage across all layers
• Tests verify folder not used for identification
• All integration tests pass (10 tests)

Completion Notes:

• Created comprehensive test file with 10 tests:
  • TestAPIIdentifierConsistency: 2 tests for API response validation
  • TestServiceIdentifierConsistency: 2 tests for download service key usage
  • TestWebSocketIdentifierConsistency: 2 tests for WebSocket events
  • TestIdentifierValidation: 2 tests for model validation
  • TestEndToEndIdentifierFlow: 2 tests for full flow verification
• Tests use UUID suffixes for isolation to prevent state leakage

Test Command:

conda run -n AniWorld python -m pytest tests/integration/test_identifier_consistency.py -v

---

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

Task 9.1: Run Full Test Suite

Objective: Verify all changes work together correctly.

Steps:

1. Run complete test suite:

   conda run -n AniWorld python -m pytest tests/ -v --tb=short
   

2. Fix any failing tests
3. Verify test coverage is maintained
4. Run integration tests
5. Run manual UI tests

Success Criteria:

• All unit tests pass
• All integration tests pass
• All API tests pass
• Test coverage >= 80%
• Manual UI testing successful

---

Task 9.2: Manual End-to-End Testing

Objective: Manually verify all features work with the new identifier system.

Steps:

1. Start server: conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
2. Login to web interface
3. Test search functionality (verify results show key)
4. Test adding new series (verify uses key)
5. Test downloading episodes (verify uses key)
6. Test WebSocket events (verify events include key)
7. Verify database contains correct key values
8. Test rescan functionality

Success Criteria:

• Search works correctly
• Adding series works
• Downloads work correctly
• WebSocket events work
• Database entries correct
• Rescan functionality works

---

Task 9.3: Performance and Load Testing

Objective: Ensure identifier changes don't impact performance.

Steps:

1. Run performance tests on key operations:
   • Series lookup by key
   • Database queries using key
   • API response times
2. Compare with baseline if available
3. Identify any performance regressions
4. Optimize if needed

Success Criteria:

• No significant performance regression
• Lookup by key is fast
• Database queries optimized
• API response times acceptable

---

Phase 10: Deployment

Task 10.1: Create Migration Script

Objective: Create script to migrate existing data if needed.

Steps:

1. Create scripts/migrate_identifiers.py
2. Script should:
   • Check all series have valid key values
   • Update any references that incorrectly use folder
   • Validate database integrity
   • Create backup before migration
3. Add rollback capability
4. Test migration on test data

Success Criteria:

• Migration script created
• Script validates data
• Backup functionality works
• Rollback capability tested
• Migration tested on test data

---

Task 10.2: Update Deployment Documentation

File: Update deployment section in instructions.md

Objective: Document deployment steps for identifier changes.

Steps:

1. Add pre-deployment checklist
2. Document migration steps
3. Add rollback procedure
4. Document verification steps
5. Add troubleshooting guide

Success Criteria:

• Deployment steps documented
• Migration procedure clear
• Rollback procedure documented
• Verification steps listed
• Troubleshooting guide added

---

Task 10.3: Deploy to Production

Objective: Deploy changes to production environment.

Steps:

1. Create deployment tag: v2.0.0-identifier-standardization
2. Backup production database
3. Run migration script
4. Deploy new code
5. Monitor logs for errors
6. Verify production functionality
7. Monitor for 24 hours

Success Criteria:

• Deployment tag created
• Database backed up
• Migration successful
• Code deployed
• No errors in logs
• All features working
• 24-hour monitoring completed

---

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
• Phase 10: Deployment