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

# 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