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

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

### ✅ Feature: Enhanced Setup and Settings Pages (COMPLETED)

1. **Setup Page Configuration** ✅
    - [x] 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")
    - [x] Implement validation for all configuration fields
    - [x] Add form UI with appropriate input types and validation feedback
    - [x] Save configuration to config.json on setup completion

2. **Settings Page Enhancement** ✅
    - [x] Display all configuration settings in settings page
    - [x] 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`
    - [x] Implement save functionality with validation
    - [x] Add success/error notifications for settings updates
    - [x] Settings changes are applied immediately via API (some may require restart)
    - [x] Add configuration section headers for better organization
    - [x] Update JavaScript modules to handle all new configuration fields

**Implementation Notes:**
- The setup page ([setup.html](../src/server/web/templates/setup.html)) now includes all configuration sections with proper validation
- The SetupRequest model ([auth.py](../src/server/models/auth.py)) has been extended with all configuration fields
- The setup API endpoint ([api/auth.py](../src/server/api/auth.py)) now saves all configuration values
- The config modal in [index.html](../src/server/web/templates/index.html) displays all settings with organized sections
- JavaScript modules ([main-config.js](../src/server/web/static/js/index/main-config.js), [scheduler-config.js](../src/server/web/static/js/index/scheduler-config.js), [logging-config.js](../src/server/web/static/js/index/logging-config.js), [nfo-config.js](../src/server/web/static/js/index/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

---