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

```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
```

---

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

---

# Tasks

## Task: Simplify Download Queue Feature

**Status**: ⏳ Not Started

**Objective**: Simplify the download queue management system to use manual start/stop controls with organized status lists.

### Requirements

The queue page (`http://127.0.0.1:8000/queue`) must implement only these features:

1. Items added via `/api/queue/add` are listed in pending queue
2. Start button removes first item from pending list and begins download
3. Successfully completed items move to finished list
4. Failed downloads move to failed list
5. Stop button prevents taking new items from queue (current download continues)

### Phase 1: Backend Service Modifications

#### Task 1.1: Simplify DownloadService

**File**: `src/server/services/download_service.py`

**Objectives**:

-   Remove auto-processing queue system (pause/resume/reorder functionality)
-   Remove priority-based queue management
-   Add manual `start_next_download()` method to process first pending item
-   Add `stop_downloads()` method to prevent new downloads
-   Ensure completion handlers move items to appropriate lists (completed/failed)
-   Maintain WebSocket broadcast for status updates
-   Keep database persistence for queue state

**Dependencies**: None

**Estimated Time**: 4 hours

---

#### Task 1.2: Simplify API Endpoints

**File**: `src/server/api/download.py`

**Objectives**:

-   Remove endpoints: `/pause`, `/resume`, `/reorder`, bulk delete
-   Update `POST /api/queue/start` to start first pending item only
-   Update `POST /api/queue/stop` to stop queue processing
-   Keep endpoints: `/status`, `/add`, `/{item_id}` delete, `/completed` clear, `/failed` clear, `/retry`
-   Proper error handling for edge cases (empty queue, already downloading)
-   Maintain authentication requirements

**Dependencies**: Task 1.1

**Estimated Time**: 2 hours

---

### Phase 2: Frontend Modifications

#### Task 2.1: Simplify Queue Template

**File**: `src/server/web/templates/queue.html`

**Objectives**:

-   Remove drag-drop handles and reordering UI
-   Remove bulk selection checkboxes
-   Remove pause/resume buttons
-   Remove priority badges
-   Simplify pending queue section with Start/Stop buttons
-   Update active downloads section (single item max)
-   Keep completed and failed sections with clear buttons
-   Ensure proper section headers and counts

**Dependencies**: Task 1.2

**Estimated Time**: 2 hours

---

#### Task 2.2: Simplify Queue JavaScript

**File**: `src/server/web/static/js/queue.js`

**Objectives**:

-   Remove drag-drop initialization and handlers
-   Remove bulk operation functions
-   Remove pause/resume queue functions
-   Implement `startDownload()` function calling `/api/queue/start`
-   Implement `stopDownloads()` function calling `/api/queue/stop`
-   Update render functions to remove drag-drop and bulk features
-   Update WebSocket handlers for new events (`download_started`, `queue_stopped`)
-   Simplify UI state management (show/hide start/stop buttons)

**Dependencies**: Task 2.1

**Estimated Time**: 3 hours

---

#### Task 2.3: Clean Up CSS

**File**: `src/server/web/static/css/ux_features.css`

**Objectives**:

-   Remove drag-handle styles
-   Remove bulk selection checkbox styles
-   Remove priority badge styles
-   Keep basic queue item layout and button styles
-   Keep status indicators and progress bars

**Dependencies**: Task 2.2

**Estimated Time**: 1 hour

---

### Phase 3: Testing

#### Task 3.1: Update Unit Tests

**File**: `tests/unit/test_download_service.py`

**Objectives**:

-   Remove tests for pause/resume/reorder/priority
-   Add `test_start_next_download()` - verify first item starts
-   Add `test_start_next_download_empty_queue()` - verify None returned
-   Add `test_start_next_download_already_active()` - verify error raised
-   Add `test_stop_downloads()` - verify queue stops processing
-   Add `test_download_completion_moves_to_list()` - verify completed list
-   Add `test_download_failure_moves_to_list()` - verify failed list

**Dependencies**: Task 1.1

**Estimated Time**: 2 hours

---

#### Task 3.2: Update API Tests

**File**: `tests/api/test_download_endpoints.py`

**Objectives**:

-   Remove tests for removed endpoints (pause/resume/reorder/bulk)
-   Add `test_start_download_success()` - verify 200 response with item_id
-   Add `test_start_download_empty_queue()` - verify 400 error
-   Add `test_start_download_already_active()` - verify 400 error
-   Add `test_stop_downloads()` - verify 200 response

**Dependencies**: Task 1.2

**Estimated Time**: 2 hours

---

#### Task 3.3: Manual Testing

**Objectives**:

-   Test add items via API appear in pending list
-   Test start button starts first pending item
-   Test completed items move to completed section
-   Test failed items move to failed section
-   Test stop button prevents new downloads
-   Test remove button works for pending items
-   Test clear completed/failed buttons
-   Test WebSocket real-time updates
-   Test UI state changes (start/stop button visibility)
-   Verify no console errors in browser

**Dependencies**: Tasks 2.1, 2.2, 2.3

**Estimated Time**: 2 hours

---

### Phase 4: Documentation

#### Task 4.1: Update features.md

**File**: `features.md`

**Objectives**:

-   Replace "Download Management" section with simplified feature list
-   Remove mentions of: drag-drop, reordering, pause/resume, bulk operations, priority
-   Add: manual start/stop, FIFO queue, organized status sections
-   Update queue statistics description

**Dependencies**: All implementation tasks

**Estimated Time**: 30 minutes

---

#### Task 4.2: Update infrastructure.md

**File**: `infrastructure.md`

**Objectives**:

-   Update "Download Management" API endpoints list
-   Remove endpoints: `/pause`, `/resume`, `/reorder`, bulk delete
-   Update "Queue Organization" section
-   Remove mentions of auto-processing and priority system
-   Add description of manual start/stop workflow

**Dependencies**: All implementation tasks

**Estimated Time**: 30 minutes

---

### Success Criteria

-   [ ] All 5 requirements from feature list are met
-   [ ] No auto-processing or background queue processing
-   [ ] Only one download active at a time
-   [ ] Manual start required to begin downloads
-   [ ] Stop prevents new downloads but allows current to complete
-   [ ] All unit tests passing (≥80% coverage)
-   [ ] All API tests passing
-   [ ] Manual testing checklist 100% complete
-   [ ] No browser console errors
-   [ ] WebSocket updates working in real-time
-   [ ] Documentation updated (features.md, infrastructure.md)
-   [ ] Code follows project coding standards
-   [ ] No breaking changes to other features

### Rollback Plan

1. Backend: Revert `download_service.py` and `download.py`
2. Frontend: Revert `queue.html`, `queue.js`, `ux_features.css`
3. Tests: Git revert test file changes
4. No database migration needed (no schema changes)

### Estimated Total Time

-   Backend: 6 hours
-   Frontend: 6 hours
-   Testing: 4 hours
-   Documentation: 1 hour
-   **Total**: ~17 hours (~2-3 working days)

### 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
-   No database schema changes required
-   WebSocket infrastructure remains unchanged