- Use folder name as fallback when series name is empty
- Skip series with both empty name and folder
- Add try/catch for individual series to prevent one failure
from stopping the entire sync
- Moved _sync_series_to_database from fastapi_app.py to anime_service.py
- Renamed to sync_series_from_data_files for better clarity
- Updated all imports and test references
- Removed completed TODO tasks from instructions.md
- Add get_all_series_from_data_files() to SeriesApp
- Sync series from data files to DB on startup
- Add unit tests for new SeriesApp method
- Add integration tests for sync functionality
- Update documentation
- Updated infrastructure.md with queue database schema and storage details
- Updated instructions.md to mark migration task as completed
- No deprecated JSON code remains in codebase
- 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
