- Created QueueRepository adapter in src/server/services/queue_repository.py
- Refactored DownloadService to use repository pattern instead of JSON
- Updated application startup to initialize download service from database
- Updated all test fixtures to use MockQueueRepository
- All 1104 tests passing
Task 9: Clean up legacy code
- Added deprecation warnings to Serie.save_to_file() and load_from_file()
- Updated infrastructure.md with Data Storage section documenting:
- SQLite database as primary storage
- Legacy file storage as deprecated
- Data migration process
- Added deprecation warning tests for Serie class
- Updated existing tests to handle new warnings
- All 1012 tests pass (872 unit + 55 API + 85 integration)
Task 8: Write integration tests for data file migration
- Added test_migration_on_fresh_start_no_data_files test
- Added test_add_series_saves_to_database test
- Added test_scan_async_saves_to_database test
- Added test_load_series_from_db test
- Added test_search_and_add_workflow test
- All 11 migration integration tests pass
- All 870 tests pass (815 unit + 55 API)
- Added db_session parameter to SeriesApp.__init__()
- Added db_session property and set_db_session() method
- Added init_from_db_async() for async database initialization
- Pass db_session to SerieList and SerieScanner during construction
- Added get_series_app_with_db() dependency for FastAPI endpoints
- All 815 unit tests and 55 API tests pass
Task 6: Update Anime API endpoints to use database
- Modified add_series endpoint to save series to database when available
- Added get_optional_database_session dependency for graceful fallback
- Falls back to file-based storage when database unavailable
- All 55 API tests and 809 unit tests pass
- Enhanced infrastructure.md with identifier convention table, format requirements, migration notes
- Updated docs/README.md with series identifier convention section
- Updated docs/api_reference.md with key-based API examples and notes
- Added deprecation warnings to SerieList.get_by_folder()
- Added deprecation warnings to anime.py folder fallback lookup
- Added deprecation warnings to validate_series_key_or_folder()
- All warnings include v3.0.0 removal timeline
- All 1006 tests pass
- Task 7.1: Update All Test Fixtures to Use Key
- Updated FakeSerie/FakeSeriesApp with realistic keys in test_anime_endpoints.py
- Updated 6+ fixtures in test_websocket_integration.py
- Updated 5 fixtures in test_download_progress_integration.py
- Updated 9 fixtures in test_download_progress_websocket.py
- Updated 10+ fixtures in test_download_models.py
- All fixtures now use URL-safe, lowercase, hyphenated key format
- Task 7.2: Add Integration Tests for Identifier Consistency
- Created tests/integration/test_identifier_consistency.py with 10 tests
- TestAPIIdentifierConsistency: API response validation
- TestServiceIdentifierConsistency: Download service key usage
- TestWebSocketIdentifierConsistency: WebSocket events
- TestIdentifierValidation: Model validation
- TestEndToEndIdentifierFlow: Full flow verification
- Tests use UUID suffixes for isolation
All 1006 tests passing.
- Updated AnimeSeries model docstring to clarify key is primary identifier
- Updated folder field to indicate metadata-only usage
- Updated AnimeSeriesService docstring and get_by_key method
- Updated infrastructure.md with database identifier documentation
- All 996 tests passing
- Updated app.js to use 'key' as primary series identifier
- selectedSeries Set now uses key instead of folder
- createSerieCard() uses data-key attribute for identification
- toggleSerieSelection() uses key for lookups
- downloadSelected() iterates with key values
- updateSelectionUI() and toggleSelectAll() use key
- Updated WebSocket service tests
- Tests now include key and folder in broadcast data
- Verified both fields are included in messages
- No changes needed for queue.js and other JS files
- They use download item IDs correctly, not series identifiers
- No template changes needed
- Series cards rendered dynamically in app.js
All 996 tests passing
- Add series context helpers: prepare_series_context, get_series_by_key, filter_series_by_missing_episodes
- Update module docstring with identifier convention documentation
- Add unit tests for new series context helper functions
- Update infrastructure.md with template helpers documentation
- Mark Phase 4 (API Layer) as complete"
- Add series context helpers: prepare_series_context, get_series_by_key, filter_series_by_missing_episodes
- Update module docstring with identifier convention documentation
- Add unit tests for new series context helper functions
- Update infrastructure.md with template helpers documentation
- Mark Phase 4 (API Layer) as complete
- Add validate_series_key() function that validates URL-safe, lowercase,
hyphen-separated series keys (e.g., 'attack-on-titan')
- Add validate_series_key_or_folder() for backward compatibility during
transition from folder-based to key-based identification
- Create comprehensive test suite with 99 test cases for all validators
- Update infrastructure.md with validation utilities documentation
- Mark Task 4.6 as complete in instructions.md
Test: conda run -n AniWorld python -m pytest tests/unit/test_validators.py -v
All 99 validator tests pass, 718 total unit tests pass
- Updated AnimeSeriesResponse and SearchResult models in anime.py:
- Changed 'id' field to 'key' as the primary series identifier
- Added 'folder' as optional metadata field
- Added field validator to normalize key to lowercase and strip whitespace
- Added comprehensive docstrings explaining identifier usage
- Updated DownloadItem and DownloadRequest models in download.py:
- Added field validator for serie_id normalization (lowercase, stripped)
- Improved documentation for serie_id (primary identifier) vs serie_folder (metadata)
- Updated test_anime_models.py with comprehensive tests:
- Tests for key normalization and whitespace stripping
- Tests for folder as optional metadata
- Reorganized tests into proper class structure
- Updated test_download_models.py with validator tests:
- Tests for serie_id normalization in DownloadItem
- Tests for serie_id normalization in DownloadRequest
All 885 tests pass.
- Updated src/server/api/websocket.py docstrings to document key as primary series identifier
- Updated src/server/models/websocket.py with detailed docstrings explaining key and folder fields in message payloads
- Updated src/server/services/websocket_service.py broadcast method docstrings to document key field usage
- Added WebSocket message example with key in infrastructure.md
- All 83 WebSocket tests pass
- Task 4.4 marked as complete in instructions.md
- Verified queue API endpoints already use 'serie_id' (key) as primary identifier
- Updated test fixtures to use explicit key values (e.g., 'test-series-key')
- Added test to verify queue items include serie_id (key) and serie_folder (metadata)
- Fixed test_queue_items_have_required_fields to find correct item by ID
- Added test_queue_item_uses_key_as_identifier for explicit key verification
- Updated instructions.md to mark Task 4.3 as complete
All 870 tests pass.
- Updated DownloadRequest and DownloadItem models with comprehensive
docstrings explaining serie_id (key as primary identifier) vs
serie_folder (filesystem metadata)
- Updated add_to_queue() endpoint docstring to document request parameters
- Updated all test files to include required serie_folder field:
- tests/api/test_download_endpoints.py
- tests/api/test_queue_features.py
- tests/frontend/test_existing_ui_integration.py
- tests/integration/test_download_flow.py
- Updated infrastructure.md with Download Queue request/response models
- All 869 tests pass
This is part of the Series Identifier Standardization effort (Phase 4.2)
to ensure key is used as the primary identifier throughout the codebase.
- Updated AnimeSummary model with enhanced documentation:
- key as primary identifier (unique series identifier)
- folder as metadata only (not used for lookups)
- Added Field descriptions for all attributes
- Updated AnimeDetail model:
- Replaced 'id' field with 'key' field
- Added 'folder' field as metadata
- Enhanced documentation and JSON schema example
- Updated get_anime() endpoint:
- Primary lookup by 'key' (preferred)
- Fallback lookup by 'folder' (backward compatibility)
- Updated docstring to clarify identifier usage
- Updated add_series() endpoint:
- Extracts key from link URL (/anime/stream/{key})
- Returns both key and folder in response
- Enhanced docstring with parameter descriptions
- Updated _perform_search():
- Uses key as primary identifier
- Extracts key from link URL if not present
- Enhanced docstring with return value details
- Updated list_anime() and search endpoint docstrings:
- Clarified key as primary identifier
- Documented folder as metadata only
- Updated instructions.md:
- Marked Task 4.1 as completed
- Updated task tracking section
- Updated infrastructure.md:
- Updated API endpoints documentation
- Added response model details
All anime API tests passing (11/11)
All unit tests passing (604/604)
- Create ScanService class (src/server/services/scan_service.py)
- Use 'key' as primary series identifier throughout
- Include 'folder' as metadata only for display purposes
- Implement scan progress tracking via ProgressService
- Add callback classes for progress, error, and completion
- Support scan event subscription and broadcasting
- Maintain scan history with configurable limit
- Provide cancellation support for in-progress scans
- Create comprehensive unit tests (tests/unit/test_scan_service.py)
- 38 tests covering all functionality
- Test ScanProgress dataclass serialization
- Test callback classes (progress, error, completion)
- Test service lifecycle (start, cancel, status)
- Test event subscription and broadcasting
- Test key-based identification throughout
- Test singleton pattern
- Update infrastructure.md with ScanService documentation
- Document service overview and key features
- Document components and event types
- Document integration points
- Include usage example
- Update instructions.md
- Mark Task 3.4 as complete
- Mark Phase 3 as fully complete
- Remove finished task definition
Task: Phase 3, Task 3.4 - Update ScanService to Use Key
Completion Date: November 27, 2025
- Verified ProgressService correctly uses 'key' as primary series identifier
- ProgressUpdate dataclass has key/folder fields with proper docstrings
- All methods accept and handle key/folder parameters
- to_dict() properly serializes key/folder when present
- 25 unit tests pass including key/folder tests
- Infrastructure documentation already up to date
- Removed completed task details from instructions.md
- Added optional 'key' and 'folder' fields to ProgressUpdate dataclass
- key: Primary series identifier (provider key, e.g., 'attack-on-titan')
- folder: Optional series folder name for display (e.g., 'Attack on Titan (2013)')
- Updated start_progress() and update_progress() methods to accept key/folder parameters
- Enhanced to_dict() serialization to include key/folder when present
- Updated all docstrings to clarify identifier usage
- Added 5 new comprehensive unit tests for key/folder functionality
- All 25 ProgressService tests passing
- Updated infrastructure.md with series identifier documentation
- Maintains backward compatibility - fields are optional
- Completed Phase 3, Task 3.3 of identifier standardization initiative
- Enhanced class and method docstrings to clarify 'key' as primary identifier
- Documented that 'folder' is metadata only (display and filesystem operations)
- Updated event handler documentation to show both key and folder are received
- Modernized type hints to Python 3.9+ style (list[dict] vs List[dict])
- Fixed PEP 8 line length violations
- All 18 anime service tests passing
Implementation follows identifier standardization initiative:
- key: Primary series identifier (provider-assigned, URL-safe)
- folder: Metadata for display and filesystem paths only
Task 3.2 completed November 23, 2025
Documented in infrastructure.md and instructions.md
- Updated DownloadService to use 'serie_id' (provider key) for identification
- Changed 'serie_folder' from Optional to required in models (DownloadItem, DownloadRequest)
- Removed incorrect fallback logic that used serie_id as folder name
- Enhanced docstrings to clarify purpose of each identifier field:
* serie_id: Provider key (e.g., 'attack-on-titan') for lookups
* serie_folder: Filesystem folder name (e.g., 'Attack on Titan (2013)') for file operations
- Updated logging to reference 'serie_key' for clarity
- Fixed all unit tests to include required serie_folder field
- All 25 download service tests passing
- All 47 download model tests passing
- Updated infrastructure.md with detailed documentation
- Marked Task 3.1 as completed in instructions.md
Benefits:
- Clear separation between provider identifier and filesystem path
- Prevents confusion from mixing different identifier types
- Consistent with broader series identifier standardization effort
- Better error messages when required fields are missing
Removed detailed implementation for completed Phase 1 and Task 2.1:
- Task 1.1: Update Serie Class to Enforce Key as Primary Identifier
- Task 1.2: Update SerieList to Use Key for Lookups
- Task 1.3: Update SerieScanner to Use Key Consistently
- Task 1.4: Update Provider Classes to Use Key
- Task 1.5: Update Provider Factory to Use Key
- Task 2.1: Update SeriesApp to Use Key for All Operations
Replaced with completion markers for cleaner task list.
All implementation details are preserved in git history.
Task 2.1 - Update SeriesApp to Use Key for All Operations
Changes:
- Added 'key' field to DownloadStatusEventArgs and ScanStatusEventArgs
- Updated download() method docstrings to clarify key vs folder usage
- Implemented _get_serie_by_key() helper method for series lookups
- Updated all event emissions to include both key (identifier) and folder (metadata)
- Enhanced logging to show both key and folder for better debugging
- Fixed test mocks to include new key and item_id fields
Benefits:
- Consistent series identification throughout core application layer
- Clear separation between identifier (key) and metadata (folder)
- Better debugging with comprehensive log messages
- Type-safe lookups with Optional[Serie] return types
- Single source of truth for series lookups
Test Results:
- All 16 SeriesApp tests pass
- All 562 unit tests pass with no regressions
- No breaking changes to existing functionality
Follows:
- PEP 8 style guidelines (max 79 chars per line)
- PEP 257 docstring standards
- Project coding standards (type hints, error handling, logging)
- Added comprehensive module-level docstring explaining provider vs series keys
- Enhanced Loaders class docstring with purpose and attributes documentation
- Added detailed docstring to GetLoader() method with Args/Returns/Raises sections
- Added type hints: Dict[str, Loader] for self.dict and -> None for __init__
- Clarified distinction between provider keys (e.g., 'aniworld.to') and series keys
- No functional changes - existing implementation already correct
- All 34 provider tests pass
- All 16 SeriesApp tests pass
- Updated instructions.md to mark Task 1.5 as completed
- Follows PEP 8 and PEP 257 standards
- Fixed line length issues (max 79 chars)
- Added UTF-8 encoding to file operations
- Fixed blank line formatting
- Improved code formatting in __str__, to_dict, from_dict methods
- All docstrings now comply with PEP 8
- All 16 Serie class tests pass
- All 5 anime model tests pass
- No functional changes, only style improvements
- Enhanced download() method docstring in aniworld_provider.py
- Enhanced Download() method docstring in enhanced_provider.py
- Clarified that 'key' is the series unique identifier from provider
- Clarified that 'serie_folder'/'serieFolder' is filesystem folder name (metadata only)
- Added comprehensive Args, Returns, and Raises sections to docstrings
- Fixed PEP 8 line length issue in logging statement
- Verified existing code already uses 'key' for identification and logging
- All 34 provider-related tests pass successfully
- No functional changes required, documentation improvements only
Task 1.3: Update SerieScanner to Use Key Consistently
Changes:
- Renamed self.folderDict to self.keyDict for clarity and consistency
- Updated internal storage to use serie.key as dictionary key
- Modified scan() method to store series by key
- Enhanced logging to show both key (identifier) and folder (metadata)
- Added debug logging when storing series
- Updated error contexts to include both key and folder in metadata
- Updated completion statistics to use keyDict
- Enhanced docstrings to clarify identifier vs metadata usage
- Fixed import formatting to comply with PEP 8 line length
Success criteria met:
✅ Scanner stores series by 'key'
✅ Progress callbacks use 'key' for identification
✅ Error messages reference both 'key' and 'folder' appropriately
✅ All 554 unit tests pass
Related to: Series Identifier Standardization (Phase 1, Task 1.3)
