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

---

## <20> Credentials

**Admin Login:**

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

---

## <20>📚 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:

### Architecture Review Findings - Critical Issues (Priority: HIGH)

#### Issue 1: Direct Database Access in API Endpoints ✅ RESOLVED

- **Location**: `src/server/api/anime.py` (lines 339-394) - NOW FIXED
- **Problem**: `list_anime` endpoint directly accessed database using `get_sync_session()`, bypassing service layer
- **Impact**: Violated Service Layer Pattern, made testing difficult, mixed sync/async patterns
- **Fix Applied**:
    - Created new async method `list_series_with_filters()` in `AnimeService`
    - Removed all direct database access from `list_anime` endpoint
    - Converted synchronous database queries to async patterns using `get_db_session()`
    - Removed unused `series_app` dependency from endpoint signature
- **Resolution Date**: January 24, 2026
- **Files Modified**:
    - `src/server/services/anime_service.py` - Added `list_series_with_filters()` method
    - `src/server/api/anime.py` - Refactored `list_anime` endpoint to use service layer
    - `tests/api/test_anime_endpoints.py` - Updated test to skip direct unit test
- **Severity**: CRITICAL - Core architecture violation (FIXED)

#### Issue 2: Business Logic in Controllers (Fat Controllers)

- **Location**: `src/server/api/anime.py` (lines 303-470)
- **Problem**: 150+ lines of business logic in `list_anime` endpoint (filtering, querying, transformation, sorting)
- **Impact**: Violates Thin Controller principle, logic not reusable, testing complexity
- **Fix Required**: Extract all business logic to `AnimeService.list_anime_with_filters()` method
- **Severity**: CRITICAL - Major architecture violation

#### Issue 3: Mixed Sync/Async Database Access

- **Location**: `src/server/api/anime.py` line 339
- **Problem**: Async endpoint uses `get_sync_session()` which blocks event loop
- **Impact**: Performance degradation, defeats purpose of async, inconsistent with rest of codebase
- **Fix Required**: Convert to async session with `get_async_session_context()` pattern
- **Severity**: HIGH - Performance and consistency issue

#### Issue 4: Duplicated Validation Logic ✅ RESOLVED

- **Location**: `src/server/api/anime.py` - NOW FIXED
- **Problem**: Nearly identical "dangerous patterns" validation appeared twice with different pattern lists (lines 303 and 567)
- **Impact**: Violated DRY principle, inconsistent security validation, maintenance burden
- **Fix Applied**:
    - Created three validation utility functions in `src/server/utils/validators.py`:
        - `validate_sql_injection()` - Centralized SQL injection detection
        - `validate_search_query()` - Search query validation and normalization
        - `validate_filter_value()` - Filter parameter validation
    - Replaced duplicated validation code in `list_anime` endpoint with utility function calls
    - Removed duplicate `validate_search_query` function definition that was shadowing import
    - Created `_validate_search_query_extended()` helper for additional null byte and length checks
- **Resolution Date**: January 24, 2026
- **Files Modified**:
    - `src/server/utils/validators.py` - Added three new validation functions
    - `src/server/api/anime.py` - Replaced inline validation with utility calls
- **Severity**: HIGH - Security and code quality (FIXED)

#### Issue 5: Multiple NFO Service Initialization Patterns

- **Locations**:
    - `src/core/SeriesApp.py` (SeriesApp constructor)
    - `src/server/api/dependencies.py` (get_nfo_service dependency)
    - Various endpoints using `series_app.nfo_service`
- **Problem**: NFO service initialized in multiple places with different fallback logic
- **Impact**: Violates DRY principle, inconsistent behavior, not following singleton pattern
- **Fix Required**: Create single `get_nfo_service_singleton()` in `src/server/services/nfo_service.py`
- **Severity**: HIGH - Inconsistent service initialization

#### Issue 6: Validation Functions in Wrong Module

- **Current Location**: `src/server/api/anime.py`
- **Should Be**: `src/server/utils/validators.py`
- **Problem**: `validate_search_query()` function is in API layer but should be in utils
- **Impact**: Violates Separation of Concerns, can't be reused easily, inconsistent with existing pattern
- **Fix Required**: Move validation functions to utils module alongside existing validators
- **Severity**: MEDIUM - Code organization issue

#### Issue 7: Repository Pattern Not Used Consistently

- **Locations**:
    - ✅ Download queue uses repository pattern (`src/server/database/repository.py`)
    - ❌ Anime series access sometimes bypasses it
    - ❌ Episode access sometimes direct
- **Problem**: Repository pattern exists but only used for queue operations
- **Impact**: Inconsistent abstraction layer, makes database layer refactoring difficult
- **Fix Required**: Extend repository pattern to all entities OR document why it's queue-only
- **Severity**: MEDIUM - Architecture inconsistency

#### Issue 8: Service Layer Bypassed for "Simple" Queries

- **Location**: `src/server/api/anime.py` lines 339-394
- **Problem**: Direct database queries justified as "simple" but service method exists
- **Impact**: Creates precedent for bypassing service layer, service layer becomes incomplete
- **Fix Required**: Use existing `AnimeService.get_all_series_with_metadata()` consistently
- **Severity**: MEDIUM - Architecture violation

### Architecture Review Findings - Medium Priority Issues

#### Issue 9: Configuration Scattered Across Multiple Sources

- **Locations**:
    - `src/config/settings.py` (environment-based settings)
    - `data/config.json` (file-based configuration)
    - Hardcoded values in multiple service files
- **Problem**: Configuration access is inconsistent - unclear source of truth
- **Impact**: Difficult to trace where values come from, testing complexity
- **Fix Required**: Single configuration source with clear precedence rules
- **Severity**: MEDIUM - Maintenance burden

#### Issue 10: Inconsistent Error Handling Patterns

- **Problem**: Different error handling approaches across endpoints:
    - Some use custom exceptions (`ValidationError`, `ServerError`)
    - Some use `HTTPException` directly
    - Some catch and convert, others don't
- **Impact**: Inconsistent error responses to clients, some errors not properly logged
- **Fix Required**: Standardize on custom exceptions with global exception handler
- **Severity**: MEDIUM - API consistency

### Code Duplication Issues

#### Duplication 1: Validation Patterns

- **Files**: `src/server/api/anime.py` (2 locations)
- **What**: "Dangerous patterns" checking for SQL injection prevention
- **Fix**: Consolidate into single function in `src/server/utils/validators.py`

#### Duplication 2: NFO Service Initialization

- **Files**: `src/core/SeriesApp.py`, `src/server/api/dependencies.py`
- **What**: Logic for initializing NFOService with fallback to config file
- **Fix**: Create singleton pattern with centralized initialization

#### Duplication 3: Series Lookup Logic

- **Locations**: Multiple API endpoints
- **What**: Pattern of `series_app.list.GetList()` then filtering by `key`
- **Fix**: Create `AnimeService.get_series_by_key()` method

#### Duplication 4: Media Files Checking

- **Files**: `src/server/api/nfo.py`, similar logic in multiple NFO-related functions
- **What**: Checking for poster.jpg, logo.png, fanart.jpg existence
- **Fix**: Create utility function for media file validation

### Further Considerations (Require Architecture Decisions)

#### Consideration 1: Configuration Precedence Documentation

- **Question**: Should environment variables (`settings.py`) always override file-based config (`config.json`)?
- **Current State**: Implicit, inconsistent precedence
- **Needed**: Explicit precedence rules documented in `docs/CONFIGURATION.md`
- **Impact**: Affects service initialization, testing, deployment
- **Action**: Document explicit precedence: ENV vars > config.json > defaults

#### Consideration 2: Repository Pattern Scope

- **Question**: Should repository pattern be extended to all entities or remain queue-specific?
- **Options**:
    1. Extend to all entities (AnimeSeries, Episode, etc.) for consistency
    2. Keep queue-only with clear documentation why
- **Current State**: Only `DownloadQueueRepository` exists
- **Impact**: Affects `src/server/api/anime.py`, `src/server/services/episode_service.py`, `src/server/services/series_service.py`
- **Action**: Decide on approach and document in `docs/ARCHITECTURE.md`

#### Consideration 3: Error Handling Standardization

- **Question**: Should all endpoints use custom exceptions with global exception handler?
- **Options**:
    1. All custom exceptions (`ValidationError`, `NotFoundError`, etc.) with middleware handler
    2. Continue mixed approach with `HTTPException` and custom exceptions
- **Current State**: Mixed patterns across endpoints
- **Impact**: API consistency, error logging, client error handling
- **Action**: Decide on standard approach and implement globally

### Code Quality Metrics from Review

- **Lines of business logic in controllers**: ~150 lines (target: ~0)
- **Direct database queries in API layer**: 3 locations (target: 0)
- **Duplicated validation patterns**: 2 instances (target: 0)
- **Service layer bypass rate**: ~20% of database operations (target: 0%)

### Architecture Adherence Scores

- **Service Layer Pattern**: 60% adherence (target: 100%)
- **Repository Pattern**: 30% adherence (target: 100% or documented alternative)
- **Thin Controllers**: 50% adherence (target: 100%)
- **Core Layer Isolation**: 80% adherence (target: 100%)