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

---

TODO List:

✅ Feature: Enhanced Setup and Settings Pages (COMPLETED)

1. Setup Page Configuration ✅

   • Update setup page to allow configuration of the following settings:
     • name: Application name (default: "Aniworld")
     • data_dir: Data directory path (default: "data")
     • scheduler:
       • enabled: Enable/disable scheduler (default: true)
       • interval_minutes: Scheduler interval in minutes (default: 60)
     • logging:
       • level: Log level (default: "INFO")
       • file: Log file path (default: null)
       • max_bytes: Max log file size in bytes (default: null)
       • backup_count: Number of backup log files (default: 3)
     • backup:
       • enabled: Enable/disable backups (default: false)
       • path: Backup directory path (default: "data/backups")
       • keep_days: Days to keep backups (default: 30)
     • nfo:
       • tmdb_api_key: TMDB API key (default: null)
       • auto_create: Auto-create NFO files (default: true)
       • update_on_scan: Update NFO on scan (default: true)
       • download_poster: Download poster images (default: true)
       • download_logo: Download logo images (default: true)
       • download_fanart: Download fanart images (default: true)
       • image_size: Image size preference (default: "original")
   • Implement validation for all configuration fields
   • Add form UI with appropriate input types and validation feedback
   • Save configuration to config.json on setup completion

2. Settings Page Enhancement ✅

   • Display all configuration settings in settings page
   • Make all settings editable:
     • General: name, data_dir
     • Scheduler: enabled, interval_minutes
     • Logging: level, file, max_bytes, backup_count
     • Backup: enabled, path, keep_days
     • NFO: tmdb_api_key, auto_create, update_on_scan, download_poster, download_logo, download_fanart, image_size
     • Other: master_password_hash (allow password change), anime_directory
   • Implement save functionality with validation
   • Add success/error notifications for settings updates
   • Settings changes are applied immediately via API (some may require restart)
   • Add configuration section headers for better organization
   • Update JavaScript modules to handle all new configuration fields

Implementation Notes:

• The setup page (setup.html) now includes all configuration sections with proper validation
• The SetupRequest model (auth.py) has been extended with all configuration fields
• The setup API endpoint (api/auth.py) now saves all configuration values
• The config modal in index.html displays all settings with organized sections
• JavaScript modules (main-config.js, scheduler-config.js, logging-config.js, nfo-config.js) have been updated to use the unified config API
• All configuration is saved through the /api/config endpoint using PUT requests
• Configuration validation is performed both client-side and server-side

---