Aniworld/docs/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

---

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

---

🔧 Current Task: Make MP4 Scanning Progress Visible in UI

Problem Statement

When users trigger a library rescan (via the "Rescan Library" button on the anime page), the MP4 file scanning happens silently in the background. Users only see a brief toast message, but there's no visual feedback showing:

1. That scanning is actively happening
2. How many files/directories have been scanned
3. The progress through the scan operation
4. When scanning is complete with results

Currently, the only indication is in server logs:

INFO:     Starting directory rescan
INFO:     Scanning for .mp4 files

Desired Outcome

Users should see real-time progress in the UI during library scanning with:

1. Progress overlay showing scan is active with a spinner animation
2. Live counters showing directories scanned and files found
3. Current directory display showing which folder is being scanned (truncated if too long)
4. Completion summary showing total files found, directories scanned, and elapsed time
5. Auto-dismiss the overlay after showing completion summary

Files to Modify

1. src/server/services/websocket_service.py

Add three new broadcast methods for scan events:

• broadcast_scan_started: Notify clients that a scan has begun, include the root directory path
• broadcast_scan_progress: Send periodic updates with directories scanned count, files found count, and current directory name
• broadcast_scan_completed: Send final summary with total directories, total files, and elapsed time in seconds

Follow the existing pattern used by broadcast_download_progress for message structure consistency.

2. src/server/services/scanner_service.py

Modify the scanning logic to emit progress via WebSocket:

• Inject WebSocketService dependency into the scanner service
• At scan start, call broadcast_scan_started
• During directory traversal, track directories scanned and files found
• Every 10 directories (to avoid WebSocket spam), call broadcast_scan_progress
• Track elapsed time using time.time()
• At scan completion, call broadcast_scan_completed with summary statistics
• Ensure the scan still works correctly even if WebSocket broadcast fails (wrap in try/except)

3. src/server/static/css/style.css

Add styles for the scan progress overlay:

• Full-screen semi-transparent overlay (z-index high enough to be on top)
• Centered container with background matching theme (use CSS variables)
• Spinner animation using CSS keyframes
• Styling for current directory text (truncated with ellipsis)
• Styling for statistics display
• Success state styling for completion
• Ensure it works in both light and dark mode themes

4. src/server/static/js/anime.js

Add WebSocket message handlers and UI functions:

• Handle scan_started message: Create and show progress overlay with spinner
• Handle scan_progress message: Update directory count, file count, and current directory text
• Handle scan_completed message: Show completion summary, then auto-remove overlay after 3 seconds
• Ensure overlay is properly cleaned up if page navigates away
• Update the existing rescan button handler to work with the new progress system

WebSocket Message Types

Define three new message types following the existing project patterns:

1. scan_started: type, directory path, timestamp
2. scan_progress: type, directories_scanned, files_found, current_directory, timestamp
3. scan_completed: type, total_directories, total_files, elapsed_seconds, timestamp

Implementation Steps

1. First modify websocket_service.py to add the three new broadcast methods
2. Add unit tests for the new WebSocket methods
3. Modify scanner_service.py to use the new broadcast methods during scanning
4. Add CSS styles to style.css for the progress overlay
5. Update anime.js to handle the new WebSocket messages and display the UI
6. Test the complete flow manually
7. Verify all existing tests still pass

Testing Requirements

Unit Tests:

• Test each new WebSocket broadcast method
• Test that scanner service calls WebSocket methods at appropriate times
• Mock WebSocket service in scanner tests

Manual Testing:

• Start server and login
• Navigate to anime page
• Click "Rescan Library" button
• Verify overlay appears immediately with spinner
• Verify counters update during scan
• Verify current directory updates
• Verify completion summary appears
• Verify overlay auto-dismisses after 3 seconds
• Test in both light and dark mode
• Verify no JavaScript console errors

Acceptance Criteria

• Progress overlay appears immediately when scan starts
• Spinner animation is visible during scanning
• Directory counter updates periodically (every ~10 directories)
• Files found counter updates as MP4 files are discovered
• Current directory name is displayed (truncated if path is too long)
• Scan completion shows total directories, files, and elapsed time
• Overlay auto-dismisses 3 seconds after completion
• Works correctly in both light and dark mode
• No JavaScript errors in browser console
• All existing tests continue to pass
• New unit tests added and passing
• Code follows project coding standards

Edge Cases to Handle

• Empty directory with no MP4 files
• Very large directory structure (ensure UI remains responsive)
• WebSocket connection lost during scan (scan should still complete)
• User navigates away during scan (cleanup overlay properly)
• Rapid consecutive scan requests (debounce or queue)

Notes

• Keep progress updates throttled to avoid overwhelming the WebSocket connection
• Use existing CSS variables for colors to maintain theme consistency
• Follow existing JavaScript patterns in the codebase
• The scan functionality must continue to work even if WebSocket fails

---