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

---

## � Credentials

**Admin Login:**

- Username: `admin`
- Password: `Hallo123!`

---

## �📚 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
```

---

## 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 and other docs
- [ ] Changes committed to git; keep your messages in git short and clear
- [ ] Take the next task

---

## TODO List:

### Completed Tasks:

1. ✅ **NFO/Artwork Loading Isolation** (Completed: 2026-01-23)
    - Task: Ensure during anime add, NFO, logo, art, etc. is loaded only for the specific anime being added
    - Status: VERIFIED - Implementation is correct
    - Details: BackgroundLoaderService.\_load_nfo_and_images() correctly passes serie_folder to create_tvshow_nfo(), which only processes that specific series
2. ✅ **Setup Redirect Flow** (Completed: 2026-01-23)
    - Task: Implement redirect flow: setup -> loading -> login when user completes setup
    - Changes:
        - Added /loading to exempt paths in setup_redirect middleware
        - Setup page redirects to loading with initialization in background
        - Loading page connects to WebSocket for real-time progress
        - After completion, loading redirects to login
3. ✅ **Close Setup and Loading Pages** (Completed: 2026-01-23)
    - Task: Make setup and loading pages unavailable after completion to prevent re-access
    - Changes:
        - Check if setup is complete before allowing access to /setup
        - Redirect to login if accessing /setup after completion
        - Check if initialization is complete before allowing access to /loading
        - Redirect to login if accessing /loading after initialization complete
4. ✅ **Fix Loading Page WebSocket Auth** (Completed: 2026-01-23)
    - Task: Fix 403 Forbidden error on WebSocket connection
    - Issue: Loading page was connecting to /ws/progress (doesn't exist)
    - Changes:
        - Changed WebSocket URL from /ws/progress to /ws/connect (correct endpoint)
        - Added /ws/connect to exempt paths in auth middleware
        - Subscribe to 'system' room after connection for progress updates
        - Fixed message data handling to match WebSocket format
5. ✅ **Fix WebSocket Room Subscription Format** (Completed: 2026-01-23)
    - Task: Fix "Invalid room name: ." error
    - Issue: WebSocket message format was incorrect - sending {action: 'join', room: 'system'} instead of {action: 'join', data: {room: 'system'}}
    - Changes: Updated loading.html to send correct message format with nested data object
6. ✅ **Fix Async Generator Exception Handling** (Completed: 2026-01-23)
    - Task: Fix "RuntimeError: generator didn't stop after athrow()" error during anime add
    - Issue: get_optional_database_session() async generator wasn't properly handling exceptions
    - Changes:
        - Simplified exception handling in both get_database_session() and get_optional_database_session()
        - Removed nested try-except inside yield that was causing generator issues
        - Let async context manager handle exceptions naturally
7. ✅ **Initialization Restart Protection** (Completed: 2026-01-23)
    - Task: Ensure initialization doesn't restart on server restart by using database flags
    - Status: VERIFIED - Already implemented correctly
    - Details:
        - SystemSettings.initial_scan_completed flag already prevents re-running initialization
        - initialization_service checks this flag before performing series sync
        - All initialization steps (scan, NFO, media) have individual completion flags
        - Server restart properly skips already-completed steps

### Active Tasks:

(No active tasks - awaiting new requirements)

```

```