chore: bump version

After initial setup completes, the loading page now checks for unresolved
folders before showing completion. If any unresolved exist, redirects
to /setup/unresolved so users can manually resolve provider keys.

Without this fix, users with unresolved folders only saw the loading
screen with no way to access the unresolved page.

.dockerignore

@@ -17,6 +17,9 @@ __pycache__/
 # Docker files (not needed inside the image)
 Docker/
 
+# Exception: VERSION is needed by Dockerfile.app
+!Docker/VERSION
+
 # Test and dev files
 tests/
 Temp/

.gitignore

@@ -4,6 +4,7 @@
 /src/__pycache__/*
 /src/__pycache__/
 /.vs/*
+/.venv/*
 /src/Temp/*
 /src/Loaders/__pycache__/*
 /src/Loaders/provider/__pycache__/*
@@ -81,4 +82,5 @@ Temp/
 temp/
 tmp/
 *.tmp
-.coverage
+.coverage
+.venv/bin/dotenv

.vscode/settings.json

@@ -1,8 +1,11 @@
 {
-    "python.defaultInterpreterPath": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
     "python.terminal.activateEnvironment": true,
-    "python.condaPath": "C:\\Users\\lukas\\anaconda3\\Scripts\\conda.exe",
     "python.terminal.activateEnvInCurrentTerminal": true,
+    "terminal.integrated.env.linux": {
+        "VIRTUAL_ENV": "${workspaceFolder}/.venv",
+        "PATH": "${workspaceFolder}/.venv/bin:${env:PATH}"
+    },
     "python.linting.enabled": true,
     "python.linting.flake8Enabled": true,
     "python.linting.pylintEnabled": true,

Docker/Containerfile

@@ -13,12 +13,13 @@ RUN apk add --no-cache \
 # Create wireguard config directory (config is mounted at runtime)
 RUN mkdir -p /etc/wireguard
 
-# Copy entrypoint
+# Copy version file and entrypoint
+COPY VERSION /etc/wireguard/VERSION
 COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 
 # Health check: can we reach the internet through the VPN?
-HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
-    CMD ping -c 1 -W 5 1.1.1.1 || exit 1
+HEALTHCHECK --interval=30s --timeout=10s --retries=5 \
+    CMD curl -sf --max-time 5 http://1.1.1.1 || exit 1
 
 ENTRYPOINT ["/entrypoint.sh"]

Docker/Dockerfile.app

@@ -2,12 +2,13 @@ FROM python:3.12-slim
 
 WORKDIR /app
 
-# Install system dependencies for compiled Python packages
+# Install system dependencies for compiled Python packages and ffmpeg for HLS support
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
         gcc \
         g++ \
         libffi-dev \
+        ffmpeg \
     && rm -rf /var/lib/apt/lists/*
 
 # Install Python dependencies (cached layer)
@@ -19,6 +20,7 @@ COPY src/ ./src/
 COPY run_server.py .
 COPY pyproject.toml .
 COPY data/config.json ./data/config.json
+COPY Docker/VERSION ./Docker/VERSION
 
 # Create runtime directories
 RUN mkdir -p /app/data/config_backups /app/logs

Docker/VERSION

@@ -0,0 +1 @@
+v1.4.4

Docker/entrypoint.sh

@@ -1,6 +1,14 @@
 #!/bin/bash
 set -e
 
+VERSION_FILE="/etc/wireguard/VERSION"
+if [ -f "$VERSION_FILE" ]; then
+    VERSION=$(cat "$VERSION_FILE")
+else
+    VERSION="unknown"
+fi
+echo "[init] VPN Container Entrypoint ${VERSION}"
+
 INTERFACE="wg0"
 MOUNT_CONFIG="/etc/wireguard/${INTERFACE}.conf"
 CONFIG_DIR="/run/wireguard"
@@ -64,9 +72,11 @@ setup_killswitch() {
     iptables -A INPUT  -i "$INTERFACE" -j ACCEPT
     iptables -A OUTPUT -o "$INTERFACE" -j ACCEPT
 
-    # Allow DNS to the VPN DNS server (through wg0)
-    iptables -A OUTPUT -o "$INTERFACE" -p udp --dport 53 -j ACCEPT
-    iptables -A OUTPUT -o "$INTERFACE" -p tcp --dport 53 -j ACCEPT
+    # Allow DNS (VPN DNS servers are routed through wg0; allow before routing decision)
+    iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+    iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
+    iptables -A INPUT  -p udp --sport 53 -j ACCEPT
+    iptables -A INPUT  -p tcp --sport 53 -j ACCEPT
 
     # Allow DHCP (for container networking)
     iptables -A OUTPUT -p udp --dport 67:68 -j ACCEPT
@@ -101,7 +111,9 @@ setup_killswitch() {
 # ──────────────────────────────────────────────
 enable_forwarding() {
     echo "[init] Enabling IP forwarding..."
-    if echo 1 > /proc/sys/net/ipv4/ip_forward 2>/dev/null; then
+    if cat /proc/sys/net/ipv4/ip_forward 2>/dev/null | grep -q 1; then
+        echo "[init] IP forwarding already enabled."
+    elif echo 1 > /proc/sys/net/ipv4/ip_forward 2>/dev/null; then
         echo "[init] IP forwarding enabled via /proc."
     else
         echo "[init] /proc read-only — relying on --sysctl net.ipv4.ip_forward=1"
@@ -118,35 +130,91 @@ start_vpn() {
     ip link add "$INTERFACE" type wireguard
 
     # Apply the WireGuard config (keys, peer, endpoint)
+    # Filter out wg-quick directives that wg setconf doesn't understand
     wg setconf "$INTERFACE" <(grep -v -i '^\(Address\|DNS\|MTU\|Table\|PreUp\|PostUp\|PreDown\|PostDown\|SaveConfig\)' "$CONFIG_FILE")
 
+    # Log public key so it can be verified against the server's peer list
+    local PUBKEY
+    PUBKEY=$(wg show "$INTERFACE" public-key 2>/dev/null || echo "unknown")
+    echo "[vpn] Public key: ${PUBKEY}"
+
     # Assign the address
     ip -4 address add "$VPN_ADDRESS" dev "$INTERFACE"
 
-    # Set MTU
+    # Set MTU and bring up
     ip link set mtu 1420 up dev "$INTERFACE"
 
-    # Find default gateway/interface for the endpoint route
+    # ── fwmark-based routing (mirrors wg-quick behavior) ──
+    # WireGuard marks its own encapsulated UDP packets with this fwmark.
+    # Policy rules then ensure:
+    #   - Normal packets (no mark) → VPN routing table → wg0
+    #   - WireGuard-encapsulated packets (marked) → main table → eth0
+    local FW_MARK=51820
+    local FW_TABLE=51820
+    wg set "$INTERFACE" fwmark "$FW_MARK"
+
+    # Remove any auto-created default route on wg0
+    ip route del default dev "$INTERFACE" 2>/dev/null || true
+
+    # VPN routing table: send everything through the tunnel
+    ip -4 route add default dev "$INTERFACE" table "$FW_TABLE"
+
+    # Policy rules:
+    # 1. Packets NOT marked by WireGuard use the VPN table (→ wg0)
+    # 2. suppress_prefixlength 0: ignore bare default routes in main table,
+    #    but keep more-specific routes (e.g. LAN, endpoint) working
+    ip -4 rule add not fwmark "$FW_MARK" table "$FW_TABLE"
+    ip -4 rule add table main suppress_prefixlength 0
+
+    # Find default gateway/interface
     DEFAULT_GW=$(ip route | grep '^default' | head -1 | awk '{print $3}')
     DEFAULT_IF=$(ip route | grep '^default' | head -1 | awk '{print $5}')
 
-    # Route VPN endpoint through the container's default gateway
+    # ── Policy routing: ensure responses to incoming LAN traffic go back via eth0 ──
     if [ -n "$DEFAULT_GW" ] && [ -n "$DEFAULT_IF" ]; then
-        ip route add "$VPN_ENDPOINT/32" via "$DEFAULT_GW" dev "$DEFAULT_IF" 2>/dev/null || true
+        # Get the container's eth0 IP address (BusyBox-compatible, no grep -P)
+        ETH0_IP=$(ip -4 addr show "$DEFAULT_IF" | awk '/inet / {split($2, a, "/"); print a[1]}' | head -1)
+        ETH0_SUBNET=$(ip -4 route show dev "$DEFAULT_IF" | grep -v default | head -1 | awk '{print $1}')
+        if [ -n "$ETH0_IP" ] && [ -n "$ETH0_SUBNET" ]; then
+            echo "[vpn] Setting up policy routing for incoming traffic (${ETH0_IP} on ${DEFAULT_IF})"
+            ip route add default via "$DEFAULT_GW" dev "$DEFAULT_IF" table 100 2>/dev/null || true
+            ip route add "$ETH0_SUBNET" dev "$DEFAULT_IF" table 100 2>/dev/null || true
+            ip rule add from "$ETH0_IP" table 100 priority 100 2>/dev/null || true
+            echo "[vpn] Policy routing active — incoming connections will be routed back via ${DEFAULT_IF}"
+        fi
     fi
 
-    # Route all traffic through the WireGuard tunnel
-    ip route add 0.0.0.0/1 dev "$INTERFACE"
-    ip route add 128.0.0.0/1 dev "$INTERFACE"
-
-    # Set up DNS
+    # Set up DNS (handle comma-separated DNS servers)
     VPN_DNS=$(grep -i '^DNS' "$CONFIG_FILE" | head -1 | sed 's/.*= *//;s/ //g')
     if [ -n "$VPN_DNS" ]; then
-        echo "nameserver $VPN_DNS" > /etc/resolv.conf
-        echo "[vpn] DNS set to ${VPN_DNS}"
+        # Clear resolv.conf and add each DNS server on its own line
+        > /etc/resolv.conf
+        for dns in $(echo "$VPN_DNS" | tr ',' ' '); do
+            echo "nameserver $dns" >> /etc/resolv.conf
+            # Add explicit route to DNS server through wg0 so it's found in main table
+            # (suppress_prefixlength 0 ignores default routes but allows host routes)
+            ip -4 route add "$dns" dev "$INTERFACE" 2>/dev/null || true
+        done
+        echo "[vpn] DNS set to: ${VPN_DNS}"
     fi
 
+    # Add explicit host route for the health-check target so it is picked up by
+    # the 'lookup main suppress_prefixlength 0' rule (same as DNS servers above).
+    # Without this, CHECK_HOST falls through to the VPN table default route whose
+    # source-address selection can be defeated by the priority-100 'from ETH0_IP'
+    # policy rule, causing pings to bypass wg0 and be dropped by the kill switch.
+    ip -4 route add "${CHECK_HOST}" dev "$INTERFACE" 2>/dev/null || true
+    echo "[vpn] Health-check route: ${CHECK_HOST} → ${INTERFACE}"
+
     echo "[vpn] WireGuard interface ${INTERFACE} is up."
+    echo "[vpn] Main routes:"
+    ip route show | sed 's/^/[vpn]   /'
+    echo "[vpn] VPN table ($FW_TABLE):"
+    ip route show table "$FW_TABLE" 2>/dev/null | sed 's/^/[vpn]   /'
+    echo "[vpn] Policy rules:"
+    ip rule show | sed 's/^/[vpn]   /'
+    echo "[vpn] WireGuard status:"
+    wg show "$INTERFACE" 2>/dev/null | sed 's/^/[vpn]   /'
 }
 
 # ──────────────────────────────────────────────
@@ -154,6 +222,21 @@ start_vpn() {
 # ──────────────────────────────────────────────
 stop_vpn() {
     echo "[vpn] Stopping WireGuard interface ${INTERFACE}..."
+
+    local FW_MARK=51820
+    local FW_TABLE=51820
+
+    # Remove fwmark-based policy rules
+    ip -4 rule del not fwmark "$FW_MARK" table "$FW_TABLE" 2>/dev/null || true
+    ip -4 rule del table main suppress_prefixlength 0 2>/dev/null || true
+
+    # Flush VPN routing table
+    ip -4 route flush table "$FW_TABLE" 2>/dev/null || true
+
+    # Remove LAN policy routing
+    ip -4 rule del table 100 2>/dev/null || true
+    ip -4 route flush table 100 2>/dev/null || true
+
     ip link del "$INTERFACE" 2>/dev/null || true
 }
 
@@ -174,9 +257,26 @@ health_loop() {
                 echo "[health] VPN recovered."
                 failures=0
             fi
+            # Secondary DNS check
+            if ping -c 1 -W 5 "google.com" > /dev/null 2>&1; then
+                : # DNS OK — silent
+            else
+                echo "[health] WARN google.com unreachable — possible DNS issue"
+            fi
         else
             failures=$((failures + 1))
-            echo "[health] Ping failed ($failures/$max_failures)"
+            echo "[health] Check failed ($failures/$max_failures) — ping ${CHECK_HOST} failed"
+            # Secondary check: distinguish IP failure from DNS failure
+            if ping -c 1 -W 5 "google.com" > /dev/null 2>&1; then
+                echo "[health] INFO google.com reachable — DNS works, ${CHECK_HOST} may be filtered"
+            else
+                echo "[health] INFO google.com also unreachable — DNS or general routing failure"
+            fi
+            # Dump WireGuard stats to show if handshake is stale and how much data flows
+            echo "[health] wg stats:"
+            wg show "$INTERFACE" 2>/dev/null | grep -E 'latest handshake|transfer|endpoint' | sed 's/^/[health]   /' || echo "[health]   wg0 not found"
+            echo "[health] routes:"
+            ip route show | grep -E 'wg0|default' | sed 's/^/[health]   /'
 
             if [ "$failures" -ge "$max_failures" ]; then
                 echo "[health] VPN appears down. Restarting WireGuard..."
@@ -205,8 +305,83 @@ cleanup() {
 
 trap cleanup SIGTERM SIGINT
 
+# ──────────────────────────────────────────────
+# Startup connectivity checks — diagnose issues early
+# ──────────────────────────────────────────────
+check_vpn_connectivity() {
+    echo "[check] ── Startup connectivity checks ──"
+
+    # 1. Wait for WireGuard handshake (up to 15s)
+    local elapsed=0
+    local handshake_ts=0
+    echo "[check] Waiting for WireGuard handshake (up to 15s)..."
+    while [ "$elapsed" -lt 15 ]; do
+        handshake_ts=$(wg show "$INTERFACE" latest-handshakes 2>/dev/null | awk '{print $2}' | head -1)
+        if [ -n "$handshake_ts" ] && [ "$handshake_ts" != "0" ]; then
+            local age=$(( $(date +%s) - handshake_ts ))
+            echo "[check] OK   Handshake established ${age}s ago"
+            break
+        fi
+        sleep 1
+        elapsed=$((elapsed + 1))
+    done
+    if [ "$elapsed" -ge 15 ]; then
+        echo "[check] FAIL No WireGuard handshake after 15s — tunnel is not up"
+        echo "[check]      This container's public key (must be on the server):"
+        echo "[check]        PublicKey  = $(wg show "$INTERFACE" public-key 2>/dev/null || echo 'unknown')"
+        echo "[check]        AllowedIPs = ${VPN_ADDRESS}"
+        echo "[check]      Verify on server: wg show"
+    fi
+
+    # 2. Check whether traffic actually flows through the tunnel
+    echo "[check] Testing traffic through tunnel (ping ${CHECK_HOST})..."
+    local rx_before
+    rx_before=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{print $2}' | head -1)
+
+    if ping -c 1 -W 8 "${CHECK_HOST}" > /dev/null 2>&1; then
+        echo "[check] OK   Traffic flows — tunnel is fully working"
+    else
+        local rx_after
+        rx_after=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{print $2}' | head -1)
+        echo "[check] FAIL ping ${CHECK_HOST} unreachable through tunnel"
+
+        if [ -n "$rx_before" ] && [ -n "$rx_after" ]; then
+            if [ "$rx_after" -le "$rx_before" ]; then
+                echo "[check]      RX bytes unchanged (${rx_before} → ${rx_after})"
+                echo "[check]      Server receives packets but does NOT route them back"
+                echo "[check]      Fix on VPN server (${VPN_ENDPOINT}):"
+                echo "[check]        sysctl net.ipv4.ip_forward              # must output 1"
+                echo "[check]        iptables -t nat -L POSTROUTING -v -n    # must have MASQUERADE"
+                echo "[check]        wg show                                  # check peer + AllowedIPs"
+            else
+                echo "[check]      RX increased (${rx_before} → ${rx_after}) — tunnel passes data"
+                echo "[check]      Issue may be specific to ${CHECK_HOST} or DNS"
+            fi
+        fi
+
+        local transfer
+        transfer=$(wg show "$INTERFACE" transfer 2>/dev/null | awk '{printf "rx=%s tx=%s", $2, $3}')
+        echo "[check]      wg transfer: ${transfer}"
+    fi
+
+    # 3. DNS check
+    echo "[check] Testing DNS resolution..."
+    if nslookup 1.1.1.1 > /dev/null 2>&1 || nslookup google.com > /dev/null 2>&1; then
+        echo "[check] OK   DNS resolves"
+    else
+        echo "[check] FAIL DNS resolution failed"
+        echo "[check]      resolv.conf: $(tr '\n' ' ' < /etc/resolv.conf)"
+        echo "[check]      Check that DNS servers are reachable through wg0"
+        echo "[check] ── End of checks ──"
+        exit 1
+    fi
+
+    echo "[check] ── End of checks ──"
+}
+
 # ── Main ──
 enable_forwarding
 setup_killswitch
 start_vpn
+check_vpn_connectivity
 health_loop

Docker/nl.conf

@@ -1,17 +1,16 @@
 [Interface]
-PrivateKey = iO5spIue/6ciwUoR95hYtuxdtQxV/Q9EOoQ/jHe18kM=
-Address = 10.2.0.2/32
-DNS = 10.2.0.1
+PrivateKey = EPRa2f/v72LvIXAY4yqIRJifsSb+nCcYHqC2rwA94UI=
+Address = 100.64.244.78/32
+DNS = 198.18.0.1,198.18.0.2
 
 # Route zum VPN-Server direkt über dein lokales Netz
-PostUp = ip route add 185.183.34.149 via 192.168.178.1 dev wlp4s0f0
+PostUp = ip route add 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
 PostUp = ip route add 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
-PostDown = ip route del 185.183.34.149 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
 PostDown = ip route del 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
 
 [Peer]
-PublicKey = J4XVdtoBVc/EoI2Yk673Oes97WMnQSH5KfamZNjtM2s=
-AllowedIPs = 0.0.0.0/1, 128.0.0.0/1
-Endpoint = 185.183.34.149:51820
-
+PublicKey = KgTUh3KLijVluDvNpzDCJJfrJ7EyLzYLmdHCksG4sRg=
+AllowedIPs = 0.0.0.0/0
+Endpoint = 91.148.236.64:51820
 

Docker/podman-compose.prod.yml

@@ -0,0 +1,56 @@
+# Production compose — pulls pre-built images from Gitea registry.
+#
+# Usage:
+#   podman login git.lpl-mind.de
+#   podman-compose -f podman-compose.prod.yml pull
+#   podman-compose -f podman-compose.prod.yml up -d
+#
+# Required files:
+#   - wg0.conf  (WireGuard configuration in the same directory)
+
+services:
+  vpn:
+    image: git.lpl-mind.de/lukas.pupkalipinski/aniworld/vpn:latest
+    container_name: vpn-wireguard
+    cap_add:
+      - NET_ADMIN
+      - SYS_MODULE
+      - NET_RAW
+    sysctls:
+      - net.ipv4.ip_forward=1
+      - net.ipv4.conf.all.src_valid_mark=1
+    volumes:
+      - /server/server_aniworld/wg0.conf:/etc/wireguard/wg0.conf:ro
+      - /lib/modules:/lib/modules:ro
+    ports:
+      - "8000:8000"
+    environment:
+      - HEALTH_CHECK_INTERVAL=10
+      - HEALTH_CHECK_HOST=1.1.1.1
+      - LOCAL_PORTS=8000
+      - PUID=1013
+      - PGID=1001
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "--max-time", "5", "http://1.1.1.1"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 60s
+
+  app:
+    image: git.lpl-mind.de/lukas.pupkalipinski/aniworld/app:latest
+    container_name: aniworld-app
+    network_mode: "service:vpn"
+    depends_on:
+      vpn:
+        condition: service_healthy
+    environment:
+      - PYTHONUNBUFFERED=1
+      - PUID=1013
+      - PGID=1001
+    volumes:
+      - /server/server_aniworld/data:/app/data
+      - /server/server_aniworld/logs:/app/logs
+      - /media/serien/Serien:/data
+    restart: unless-stopped

Docker/podman-compose.yml

@@ -7,6 +7,7 @@ services:
     cap_add:
       - NET_ADMIN
       - SYS_MODULE
+      - NET_RAW
     sysctls:
       - net.ipv4.ip_forward=1
       - net.ipv4.conf.all.src_valid_mark=1
@@ -37,6 +38,7 @@ services:
         condition: service_healthy
     environment:
       - PYTHONUNBUFFERED=1
+      - LOG_LEVEL=DEBUG
     volumes:
       - app-data:/app/data
       - app-logs:/app/logs

Docker/push.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+#
+# Build and push AniWorld container images to the Gitea registry.
+#
+# Usage:
+#   ./push.sh              # builds & pushes app with tag "latest"
+#   ./push.sh app          # builds & pushes app image
+#   ./push.sh vpn          # builds & pushes vpn image
+#   ./push.sh all          # builds & pushes both images
+#   ./push.sh app v1.2.3   # builds & pushes app with tag "v1.2.3"
+#   ./push.sh vpn v1.2.3   # builds & pushes vpn with tag "v1.2.3"
+#   ./push.sh all v1.2.3   # builds & pushes both images
+#   ./push.sh app v1.2.3 --no-build   # pushes existing image only
+#
+# Prerequisites:
+#   podman login git.lpl-mind.de   (or: docker login git.lpl-mind.de)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+REGISTRY="git.lpl-mind.de"
+NAMESPACE="lukas.pupkalipinski"
+PROJECT="aniworld"
+
+APP_IMAGE="${REGISTRY}/${NAMESPACE}/${PROJECT}/app"
+VPN_IMAGE="${REGISTRY}/${NAMESPACE}/${PROJECT}/vpn"
+
+# Parse arguments
+TARGET="${1:-app}"
+TAG="${2:-latest}"
+SKIP_BUILD=false
+if [[ "${3:-}" == "--no-build" ]]; then
+    SKIP_BUILD=true
+fi
+
+# Validate target
+if [[ "${TARGET}" != "app" && "${TARGET}" != "vpn" && "${TARGET}" != "all" ]]; then
+    echo "ERROR: Invalid target '${TARGET}'. Must be one of: app, vpn, all" >&2
+    exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+log() { echo -e "\n>>> $*"; }
+err() { echo -e "\nERROR: $*" >&2; exit 1; }
+
+# Detect container engine (podman preferred, docker fallback)
+if command -v podman &>/dev/null; then
+    ENGINE="podman"
+elif command -v docker &>/dev/null; then
+    ENGINE="docker"
+else
+    err "Neither podman nor docker is installed."
+fi
+
+# ---------------------------------------------------------------------------
+# Pre-flight checks
+# ---------------------------------------------------------------------------
+echo "============================================"
+echo " AniWorld — Build & Push"
+echo " Engine   : ${ENGINE}"
+echo " Registry : ${REGISTRY}"
+echo " Target   : ${TARGET}"
+echo " Tag      : ${TAG}"
+echo "============================================"
+
+log "Logging in to ${REGISTRY}"
+"${ENGINE}" login "${REGISTRY}"
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+build_app() {
+    log "Building app image  →  ${APP_IMAGE}:${TAG}"
+    "${ENGINE}" build \
+        -t "${APP_IMAGE}:${TAG}" \
+        -f "${SCRIPT_DIR}/Dockerfile.app" \
+        "${PROJECT_ROOT}"
+}
+
+build_vpn() {
+    log "Building vpn image  →  ${VPN_IMAGE}:${TAG}"
+    "${ENGINE}" build \
+        -t "${VPN_IMAGE}:${TAG}" \
+        -f "${SCRIPT_DIR}/Containerfile" \
+        "${SCRIPT_DIR}"
+}
+
+if [[ "${SKIP_BUILD}" == false ]]; then
+    case "${TARGET}" in
+        app)  build_app ;;
+        vpn)  build_vpn ;;
+        all)  build_app; build_vpn ;;
+    esac
+fi
+
+# ---------------------------------------------------------------------------
+# Push
+# ---------------------------------------------------------------------------
+push_app() {
+    log "Pushing ${APP_IMAGE}:${TAG}"
+    "${ENGINE}" push "${APP_IMAGE}:${TAG}"
+}
+
+push_vpn() {
+    log "Pushing ${VPN_IMAGE}:${TAG}"
+    "${ENGINE}" push "${VPN_IMAGE}:${TAG}"
+}
+
+case "${TARGET}" in
+    app)  push_app ;;
+    vpn)  push_vpn ;;
+    all)  push_app; push_vpn ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Summary
+# ---------------------------------------------------------------------------
+echo ""
+echo "============================================"
+echo "  Push complete!"
+echo ""
+echo " Images:"
+case "${TARGET}" in
+    app)  echo "   ${APP_IMAGE}:${TAG}" ;;
+    vpn)  echo "   ${VPN_IMAGE}:${TAG}" ;;
+    all)  echo "   ${APP_IMAGE}:${TAG}"; echo "   ${VPN_IMAGE}:${TAG}" ;;
+esac
+echo ""
+echo " Deploy on server:"
+echo "   ${ENGINE} login ${REGISTRY}"
+echo "   ${ENGINE} compose -f Docker/podman-compose.prod.yml pull"
+echo "   ${ENGINE} compose -f Docker/podman-compose.prod.yml up -d"
+echo "============================================"

Docker/release.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Bump the project version and push images to the registry.
+#
+# Usage:
+#   ./release.sh
+#
+# The current version is stored in VERSION (next to this script).
+# You will be asked whether to bump major, minor, or patch.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VERSION_FILE="${SCRIPT_DIR}/VERSION"
+
+# ---------------------------------------------------------------------------
+# Read current version
+# ---------------------------------------------------------------------------
+if [[ ! -f "${VERSION_FILE}" ]]; then
+    echo "0.0.0" > "${VERSION_FILE}"
+fi
+
+CURRENT="$(cat "${VERSION_FILE}")"
+# Strip leading 'v' for arithmetic
+VERSION="${CURRENT#v}"
+
+IFS='.' read -r MAJOR MINOR PATCH <<< "${VERSION}"
+
+echo "============================================"
+echo " AniWorld — Release"
+echo " Current version: v${MAJOR}.${MINOR}.${PATCH}"
+echo "============================================"
+echo ""
+echo "Which image(s) would you like to release?"
+echo "  1) app  (Dockerfile.app)"
+echo "  2) vpn  (Containerfile)"
+echo "  3) all  (both images)"
+echo ""
+read -rp "Enter choice [1/2/3]: " TARGET_CHOICE
+
+case "${TARGET_CHOICE}" in
+    1) TARGET="app" ;;
+    2) TARGET="vpn" ;;
+    3) TARGET="all" ;;
+    *)
+        echo "Invalid choice. Aborting." >&2
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "How would you like to bump the version?"
+echo "  1) patch  (v${MAJOR}.${MINOR}.${PATCH} → v${MAJOR}.${MINOR}.$((PATCH + 1)))"
+echo "  2) minor  (v${MAJOR}.${MINOR}.${PATCH} → v${MAJOR}.$((MINOR + 1)).0)"
+echo "  3) major  (v${MAJOR}.${MINOR}.${PATCH} → v$((MAJOR + 1)).0.0)"
+echo ""
+read -rp "Enter choice [1/2/3]: " CHOICE
+
+case "${CHOICE}" in
+    1) NEW_TAG="v${MAJOR}.${MINOR}.$((PATCH + 1))" ;;
+    2) NEW_TAG="v${MAJOR}.$((MINOR + 1)).0" ;;
+    3) NEW_TAG="v$((MAJOR + 1)).0.0" ;;
+    *)
+        echo "Invalid choice. Aborting." >&2
+        exit 1
+        ;;
+esac
+
+echo ""
+echo "New version: ${NEW_TAG}"
+echo "Target: ${TARGET}"
+read -rp "Confirm? [y/N]: " CONFIRM
+if [[ ! "${CONFIRM}" =~ ^[yY]$ ]]; then
+    echo "Aborted."
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Write new version
+# ---------------------------------------------------------------------------
+echo "${NEW_TAG}" > "${VERSION_FILE}"
+echo "Version file updated → ${VERSION_FILE}"
+
+# Keep root package.json in sync.
+FRONT_VERSION="${NEW_TAG#v}"
+FRONT_PKG="${SCRIPT_DIR}/../package.json"
+if [[ -f "${FRONT_PKG}" ]]; then
+    sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"${FRONT_VERSION}\"/" "${FRONT_PKG}"
+    echo "package.json version updated → ${FRONT_VERSION}"
+else
+    echo "Warning: package.json not found, skipping package.json version sync" >&2
+fi
+
+# Keep root pyproject.toml in sync.
+BACKEND_PYPROJECT="${SCRIPT_DIR}/../pyproject.toml"
+if [[ -f "${BACKEND_PYPROJECT}" ]]; then
+    # Update version under [project] section if present
+    if grep -q '^\[project\]' "${BACKEND_PYPROJECT}"; then
+        sed -i "/^\[project\]/,/^\[/ s/^version = \".*\"/version = \"${FRONT_VERSION}\"/" "${BACKEND_PYPROJECT}"
+    else
+        sed -i "s/^version = \".*\"/version = \"${FRONT_VERSION}\"/" "${BACKEND_PYPROJECT}"
+    fi
+    echo "pyproject.toml version updated → ${FRONT_VERSION}"
+else
+    echo "Warning: pyproject.toml not found, skipping pyproject.toml version sync" >&2
+fi
+
+# ---------------------------------------------------------------------------
+# Push containers
+# ---------------------------------------------------------------------------
+bash "${SCRIPT_DIR}/push.sh" "${TARGET}" "${NEW_TAG}"
+bash "${SCRIPT_DIR}/push.sh" "${TARGET}"
+
+
+# ---------------------------------------------------------------------------
+# Git tag (local only; push after container build)
+# ---------------------------------------------------------------------------
+cd "${SCRIPT_DIR}/.."
+git add Docker/VERSION package.json pyproject.toml
+git commit -m "chore: bump version"
+git tag -a "${NEW_TAG}" -m "Release ${NEW_TAG}"
+echo "Local git commit + tag ${NEW_TAG} created."
+
+# ---------------------------------------------------------------------------
+# Push git commits & tag
+# ---------------------------------------------------------------------------
+git push origin HEAD
+git push origin "${NEW_TAG}"
+echo "Git commit and tag ${NEW_TAG} pushed."

Docker/test_vpn.py

@@ -6,22 +6,31 @@ Verifies:
 2. The container starts and becomes healthy.
 3. The public IP inside the VPN differs from the host IP.
 4. Kill switch blocks traffic when WireGuard is down.
+5. AllowedIPs routes are set dynamically from the config.
 
 Requirements:
     - podman installed
-    - Root/sudo (NET_ADMIN capability)
+    - Root/sudo (NET_ADMIN capability) for container runtime tests
     - A valid WireGuard config at ./wg0.conf (or ./nl.conf)
 
 Usage:
+    # Build-only test (no sudo needed):
+    python3 -m pytest test_vpn.py::TestVPNImage::test_00_build_image -v
+
+    # Full integration test (requires sudo):
     sudo python3 -m pytest test_vpn.py -v
     # or
     sudo python3 test_vpn.py
 """
 
+import logging
+import os
 import subprocess
+import sys
 import time
 import unittest
-import os
+
+logger = logging.getLogger(__name__)
 
 IMAGE_NAME = "vpn-wireguard-test"
 CONTAINER_NAME = "vpn-test-container"
@@ -32,6 +41,11 @@ STARTUP_TIMEOUT = 30  # seconds to wait for VPN to come up
 HEALTH_POLL_INTERVAL = 2  # seconds between health checks
 
 
+def is_root() -> bool:
+    """Check if running as root."""
+    return os.geteuid() == 0
+
+
 def run(cmd: list[str], timeout: int = 30, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command and return the result."""
     return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=check)
@@ -52,6 +66,7 @@ class TestVPNImage(unittest.TestCase):
     """Test suite for the WireGuard VPN container."""
 
     host_ip: str = ""
+    container_id: str = ""
 
     @classmethod
     def setUpClass(cls):
@@ -63,23 +78,32 @@ class TestVPNImage(unittest.TestCase):
         )
 
         # ── 1. Get host public IP before VPN ──
-        print("\n[setup] Fetching host public IP...")
+        logger.info("Fetching host public IP...")
         cls.host_ip = get_host_ip()
-        print(f"[setup] Host public IP: {cls.host_ip}")
+        logger.info("Host public IP: %s", cls.host_ip)
         assert cls.host_ip, "Could not determine host public IP"
 
         # ── 2. Build the image ──
-        print(f"[setup] Building image '{IMAGE_NAME}'...")
+        logger.info("Building image '%s'...", IMAGE_NAME)
         result = run(
             ["podman", "build", "-t", IMAGE_NAME, BUILD_DIR],
             timeout=180,
         )
-        print(result.stdout[-500:] if len(result.stdout) > 500 else result.stdout)
+        logger.debug(
+            "Build output: %s",
+            result.stdout[-500:] if len(result.stdout) > 500 else result.stdout,
+        )
         assert result.returncode == 0, f"Build failed:\n{result.stderr}"
-        print("[setup] Image built successfully.")
+        logger.info("Image built successfully.")
+
+        # Skip container runtime tests if not root
+        if not is_root():
+            logger.warning("Not running as root — skipping container runtime tests.")
+            cls.container_id = ""
+            return
 
         # ── 3. Start the container ──
-        print(f"[setup] Starting container '{CONTAINER_NAME}'...")
+        logger.info("Starting container '%s'...", CONTAINER_NAME)
         result = run(
             [
                 "podman", "run", "-d",
@@ -96,7 +120,7 @@ class TestVPNImage(unittest.TestCase):
         )
         assert result.returncode == 0, f"Container failed to start:\n{result.stderr}"
         cls.container_id = result.stdout.strip()
-        print(f"[setup] Container started: {cls.container_id[:12]}")
+        logger.info("Container started: %s", cls.container_id[:12])
 
         # Verify it's running
         inspect = run(
@@ -106,17 +130,19 @@ class TestVPNImage(unittest.TestCase):
         assert inspect.stdout.strip() == "true", "Container is not running"
 
         # ── 4. Wait for VPN to come up ──
-        print(f"[setup] Waiting up to {STARTUP_TIMEOUT}s for VPN tunnel...")
+        logger.info("Waiting up to %d seconds for VPN tunnel...", STARTUP_TIMEOUT)
         vpn_up = cls._wait_for_vpn_cls(STARTUP_TIMEOUT)
         assert vpn_up, f"VPN did not come up within {STARTUP_TIMEOUT}s"
-        print("[setup] VPN tunnel is up. Running tests.\n")
+        logger.info("VPN tunnel is up. Running tests.")
 
     @classmethod
     def tearDownClass(cls):
         """Stop and remove the container."""
-        print("\n[teardown] Cleaning up...")
+        if not is_root():
+            return
+        logger.info("Cleaning up test container...")
         subprocess.run(["podman", "rm", "-f", CONTAINER_NAME], capture_output=True, check=False)
-        print("[teardown] Done.")
+        logger.info("Cleanup complete.")
 
     @classmethod
     def _wait_for_vpn_cls(cls, timeout: int = STARTUP_TIMEOUT) -> bool:
@@ -138,13 +164,25 @@ class TestVPNImage(unittest.TestCase):
         )
         return result.stdout.strip()
 
+    def _skip_if_not_root(self):
+        """Skip test if not running as root."""
+        if not is_root():
+            self.skipTest("This test requires root/sudo privileges")
+
     # ── Tests ────────────────────────────────────────────────
 
+    def test_00_build_image(self):
+        """The image builds successfully."""
+        # This is already verified in setUpClass, just confirm here
+        result = run(["podman", "images", "--format", "{{.Repository}}:{{.Tag}}"])
+        self.assertIn(IMAGE_NAME, result.stdout, "Image was not built")
+
     def test_01_ip_differs_from_host(self):
         """Public IP inside VPN is different from host IP."""
+        self._skip_if_not_root()
         vpn_ip = self._get_vpn_ip()
-        print(f"\n[test] VPN public IP:  {vpn_ip}")
-        print(f"[test] Host public IP: {self.host_ip}")
+        logger.info("VPN public IP: %s", vpn_ip)
+        logger.info("Host public IP: %s", self.host_ip)
 
         self.assertTrue(vpn_ip, "Could not fetch IP from inside the container")
         self.assertNotEqual(
@@ -155,12 +193,42 @@ class TestVPNImage(unittest.TestCase):
 
     def test_02_wireguard_interface_exists(self):
         """The wg0 interface is present in the container."""
+        self._skip_if_not_root()
         result = podman_exec(CONTAINER_NAME, ["wg", "show", "wg0"])
         self.assertEqual(result.returncode, 0, f"wg show failed:\n{result.stderr}")
         self.assertIn("peer", result.stdout.lower(), "No peer information in wg show output")
+        # AllowedIPs should be present in wg show output
+        self.assertIn("allowed ips", result.stdout.lower(), "AllowedIPs not found in wg show output")
 
-    def test_03_kill_switch_blocks_traffic(self):
+    def test_03_allowedips_routes_set(self):
+        """Routes are set dynamically based on AllowedIPs from config."""
+        self._skip_if_not_root()
+        # Check that routes exist for the AllowedIPs
+        result = podman_exec(CONTAINER_NAME, ["ip", "route", "show", "dev", "wg0"])
+        self.assertEqual(result.returncode, 0, f"ip route show failed:\n{result.stderr}")
+        # The config has AllowedIPs = 0.0.0.0/0, which should result in:
+        # 0.0.0.0/1 dev wg0 and 128.0.0.0/1 dev wg0
+        self.assertIn("0.0.0.0/1", result.stdout, "Route 0.0.0.0/1 not found")
+        self.assertIn("128.0.0.0/1", result.stdout, "Route 128.0.0.0/1 not found")
+        # Make sure there is NO default route through wg0 (Table = off should prevent this)
+        self.assertNotIn("default dev wg0", result.stdout, "Default route through wg0 found — Table = off not working!")
+        logger.info("AllowedIPs routes verified: %s", result.stdout.strip())
+
+    def test_03b_dns_configured(self):
+        """DNS is configured correctly with multiple nameserver lines."""
+        self._skip_if_not_root()
+        result = podman_exec(CONTAINER_NAME, ["cat", "/etc/resolv.conf"])
+        self.assertEqual(result.returncode, 0, f"cat /etc/resolv.conf failed:\n{result.stderr}")
+        # Should have two separate nameserver lines, not one with commas
+        self.assertIn("nameserver 198.18.0.1", result.stdout, "DNS 198.18.0.1 not found")
+        self.assertIn("nameserver 198.18.0.2", result.stdout, "DNS 198.18.0.2 not found")
+        # Make sure there are no commas in nameserver lines
+        self.assertNotIn("nameserver 198.18.0.1,198.18.0.2", result.stdout, "DNS servers written on one line with comma!")
+        logger.info("DNS config verified: %s", result.stdout.strip())
+
+    def test_04_kill_switch_blocks_traffic(self):
         """When WireGuard is down, traffic is blocked (kill switch)."""
+        self._skip_if_not_root()
         # Bring down the WireGuard interface by deleting it
         down_result = podman_exec(CONTAINER_NAME, ["ip", "link", "del", "wg0"], timeout=10)
         self.assertEqual(down_result.returncode, 0, f"ip link del wg0 failed:\n{down_result.stderr}")
@@ -178,7 +246,7 @@ class TestVPNImage(unittest.TestCase):
             result.returncode, 0,
             "Traffic went through even with WireGuard down — kill switch is NOT working!",
         )
-        print("\n[test] Kill switch confirmed: traffic blocked with VPN down")
+        logger.info("Kill switch confirmed: traffic blocked with VPN down")
 
 
 if __name__ == "__main__":

Docker/wg0.conf

@@ -1,10 +1,18 @@
 [Interface]
-PrivateKey = iO5spIue/6ciwUoR95hYtuxdtQxV/Q9EOoQ/jHe18kM=
-Address = 10.2.0.2/32
-DNS = 10.2.0.1
+PrivateKey = EPRa2f/v72LvIXAY4yqIRJifsSb+nCcYHqC2rwA94UI=
+Address = 100.64.244.78/32
+#DNS = 198.18.0.1,198.18.0.2
+DNS = 8.8.8.8
+
+# Route zum VPN-Server direkt über dein lokales Netz
+PostUp = ip route add 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
+PostUp = ip route add 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 91.148.236.64 via 192.168.178.1 dev wlp4s0f0
+PostDown = ip route del 192.168.178.0/24 via 192.168.178.1 dev wlp4s0f0
 
 [Peer]
-PublicKey = J4XVdtoBVc/EoI2Yk673Oes97WMnQSH5KfamZNjtM2s=
+PublicKey = KgTUh3KLijVluDvNpzDCJJfrJ7EyLzYLmdHCksG4sRg=
 AllowedIPs = 0.0.0.0/0
-Endpoint = 185.183.34.149:51820
+Endpoint = 91.148.236.64:51820
 PersistentKeepalive = 25
+

docs/API.md

@@ -203,14 +203,14 @@ List library series that have missing episodes.
 | `page` | int | 1 | Page number (must be positive) |
 | `per_page` | int | 20 | Items per page (max 1000) |
 | `sort_by` | string | null | Sort field: `title`, `id`, `name`, `missing_episodes` |
-| `filter` | string | null | Filter: `no_episodes` (shows only series with missing episodes - episodes in DB that haven't been downloaded yet) |
+| `filter` | string | null | Filter: `missing_episodes` (shows series with any missing episodes), `no_episodes` (shows series with zero downloaded episodes) |
 
 **Filter Details:**
 
-- `no_episodes`: Returns series that have at least one episode in the database with `is_downloaded=False`
+- `missing_episodes`: Returns series that have at least one missing episode recorded in the database (`is_downloaded=False`)
+- `no_episodes`: Returns series that have missing episodes and no downloaded episodes (i.e., only missing episodes exist in the database)
 - Episodes in the database represent MISSING episodes (from episodeDict during scanning)
 - `is_downloaded=False` means the episode file was not found in the folder
-- This effectively shows series where no video files were found for missing episodes
 
 **Response (200 OK):**
 
@@ -1285,7 +1285,7 @@ Basic health check endpoint.
 {
     "status": "healthy",
     "timestamp": "2025-12-13T10:30:00.000Z",
-    "version": "1.0.0"
+    "version": "1.0.1"
 }
 ```
 
@@ -1303,7 +1303,7 @@ Comprehensive health check with database, filesystem, and system metrics.
 {
     "status": "healthy",
     "timestamp": "2025-12-13T10:30:00.000Z",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "dependencies": {
         "database": {
             "status": "healthy",

docs/ARCHITECTURE.md

@@ -81,6 +81,8 @@ src/server/
 |   +-- websocket_service.py# WebSocket broadcasting
 |   +-- queue_repository.py # Database persistence
 |   +-- nfo_service.py      # NFO metadata management
+|   +-- setup_service.py    # Series key resolution from folder names
+|   +-- folder_scan_service.py # Daily folder maintenance scan
 +-- models/                 # Pydantic models
 |   +-- auth.py             # Auth request/response models
 |   +-- config.py           # Configuration models
@@ -290,8 +292,9 @@ The FastAPI lifespan function (`src/server/fastapi_app.py`) runs the following s
 8. Background loader service started
 
 9. Scheduler service started
-
-10. NFO repair scan (queue incomplete tvshow.nfo files for background reload)
+   +-- Cron-based library rescans configured
+   +-- Optional: auto-download missing episodes after rescan
+   +-- Optional: folder maintenance (NFO repair, key resolution, renaming, poster checks) during scheduled runs
 ```
 
 ### 12.2 Temp Folder Guarantee

docs/CHANGELOG.md

@@ -37,10 +37,30 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
 
 ---
 
+## [Unreleased] - 2026-06-05
+
+### Fixed
+
+- **Folder scan series key resolution**: Fixed "Could not resolve series key for folder, skipping" warnings during library setup. `_resolve_key_via_search()` now uses fuzzy title matching instead of exact string comparison.
+    - Added `_normalize_title()` to strip anime suffixes: `(TV)`, `(Anime)`, `(OAD)`, `(OVA)`, `(Special)`, `(Movie)`, `(Spin-Off)`
+    - Added `_titles_match()` using `difflib.SequenceMatcher` with 0.85 similarity threshold for tolerance of minor title variations
+    - Added debug logging for title mismatches and multiple search results
+
+---
+
 ## [1.3.1] - 2026-02-22
 
 ### Added
 
+- **Encoding detection for HTML parsing** (`src/core/providers/aniworld_provider.py`):
+  Added `_decode_html_content()` function that uses `chardet` to detect the actual
+  encoding of HTML content before parsing. Falls back to UTF-8 with `errors='replace'`
+  to handle pages with mismatched encoding declarations. Applied to all BeautifulSoup
+  parsing calls to prevent "Some characters could not be decoded" warnings.
+- **chardet dependency**: Added `chardet>=5.2.0` to `requirements.txt` for encoding detection.
+
+### Added
+
 - **Temp file cleanup after every download** (`src/core/providers/aniworld_provider.py`,
   `src/core/providers/enhanced_provider.py`): Module-level helper
   `_cleanup_temp_file()` removes the working temp file and any yt-dlp `.part`
@@ -73,17 +93,16 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
   that detects incomplete `tvshow.nfo` files and triggers TMDB re-fetch.
   Provides `parse_nfo_tags()`, `find_missing_tags()`, `nfo_needs_repair()`, and
   `NfoRepairService.repair_series()`. 13 required tags are checked.
-- **`perform_nfo_repair_scan()` startup hook
-  (`src/server/services/initialization_service.py`)**: New async function
-  called during application startup. Iterates every series directory, checks
-  whether `tvshow.nfo` is missing required tags using `nfo_needs_repair()`, and
-  either queues the series for background reload (when a `background_loader` is
-  provided) or calls `NfoRepairService.repair_series()` directly. Skips
-  gracefully when `tmdb_api_key` or `anime_directory` is not configured.
-- **NFO repair wired into startup lifespan (`src/server/fastapi_app.py`)**:
-  `perform_nfo_repair_scan(background_loader)` is called at the end of the
-  FastAPI lifespan startup, after `perform_media_scan_if_needed`, ensuring
-  every existing series NFO is checked and repaired on each server start.
+- **`perform_nfo_repair_scan()`
+  (`src/server/services/folder_scan_service.py`)**: New async function
+  that iterates every series directory, checks whether `tvshow.nfo` is missing
+  required tags using `nfo_needs_repair()`, and queues the series for background
+  reload via `asyncio.create_task`. Skips gracefully when `tmdb_api_key` or
+  `anime_directory` is not configured.
+- **NFO repair wired into scheduled folder scan (`src/server/services/folder_scan_service.py`)**:
+  `perform_nfo_repair_scan(background_loader=None)` is called during the
+  scheduled daily folder scan, keeping startup fast while ensuring regular
+  maintenance.
 
 ### Changed
 
@@ -131,6 +150,10 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
 - Modified `src/server/api/anime.py` to save scanned episodes to database
 - Episodes table properly tracks missing episodes with automatic cleanup
 
+### Deprecated
+
+- **Legacy Series Files (key/data)**: File-based series storage is deprecated. `key` and `data` files in anime folders will be removed in v3.0.0. Database storage is now the primary method. See [docs/MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md) for details.
+
 ---
 
 ## Sections for Each Release

docs/CONFIGURATION.md

@@ -117,7 +117,8 @@ Location: `data/config.json`
         "interval_minutes": 60,
         "schedule_time": "03:00",
         "schedule_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
-        "auto_download_after_rescan": false
+        "auto_download_after_rescan": false,
+        "folder_scan_enabled": false
     },
     "logging": {
         "level": "INFO",
@@ -143,7 +144,7 @@ Location: `data/config.json`
         "master_password_hash": "$pbkdf2-sha256$...",
         "anime_directory": "/path/to/anime"
     },
-    "version": "1.0.0"
+    "version": "1.0.1"
 }
 ```
 
@@ -173,6 +174,7 @@ Controls automatic cron-based library rescanning (powered by APScheduler).
 | `scheduler.schedule_time`              | string       | `"03:00"`                                     | Daily run time in 24-h `HH:MM` format.                               |
 | `scheduler.schedule_days`              | list[string] | `["mon","tue","wed","thu","fri","sat","sun"]` | Days of the week to run the scan. Empty list disables the cron job.  |
 | `scheduler.auto_download_after_rescan` | bool         | `false`                                       | Automatically queue missing episodes for download after each rescan. |
+| `scheduler.folder_scan_enabled`        | bool         | `false`                                       | Run folder maintenance (NFO repair, folder renaming, poster checks) during scheduled runs. **When enabled, series folders are automatically renamed to match the `<title> (<year>)` convention derived from their `tvshow.nfo` files.** |
 
 Valid day abbreviations: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`.
 
@@ -216,7 +218,9 @@ Source: [src/server/models/config.py](../src/server/models/config.py#L15-L24)
 - Obtain a TMDB API key from https://www.themoviedb.org/settings/api
 - `auto_create` creates NFO files during the download process
 - `update_on_scan` refreshes metadata when scanning existing anime
+- `download_poster` also controls whether the scheduled folder scan checks for and re-downloads missing or corrupted `poster.jpg` files (see [NFO_GUIDE.md](NFO_GUIDE.md#6-poster-check))
 - Image downloads require valid `tmdb_api_key`
+- `TMDB_API_KEY` environment variable is optional when `nfo.tmdb_api_key` is configured in `data/config.json`
 - Larger image sizes (`w780`, `original`) consume more storage space
 
 Source: [src/server/models/config.py](../src/server/models/config.py#L109-L132)

docs/DATABASE.md

@@ -83,17 +83,23 @@ Source: [src/server/database/models.py](../src/server/database/models.py), [src/
 
 ### 3.2 anime_series
 
-Stores anime series metadata.
+Stores anime series metadata. Corresponds to the core `Serie` class.
 
-| Column       | Type          | Constraints                | Description                                             |
-| ------------ | ------------- | -------------------------- | ------------------------------------------------------- |
-| `id`         | INTEGER       | PRIMARY KEY, AUTOINCREMENT | Internal database ID                                    |
-| `key`        | VARCHAR(255)  | UNIQUE, NOT NULL, INDEX    | **Primary identifier** - provider-assigned URL-safe key |
-| `name`       | VARCHAR(500)  | NOT NULL, INDEX            | Display name of the series                              |
-| `site`       | VARCHAR(500)  | NOT NULL                   | Provider site URL                                       |
-| `folder`     | VARCHAR(1000) | NOT NULL                   | Filesystem folder name (metadata only)                  |
-| `created_at` | DATETIME      | NOT NULL, DEFAULT NOW      | Record creation timestamp                               |
-| `updated_at` | DATETIME      | NOT NULL, ON UPDATE NOW    | Last update timestamp                                   |
+| Column           | Type          | Constraints                | Description                                             |
+| ---------------- | ------------- | -------------------------- | ------------------------------------------------------- |
+| `id`             | INTEGER       | PRIMARY KEY, AUTOINCREMENT | Internal database ID                                    |
+| `key`            | VARCHAR(255)  | UNIQUE, NOT NULL, INDEX    | **Primary identifier** - provider-assigned URL-safe key |
+| `name`           | VARCHAR(500)  | NOT NULL, INDEX            | Display name of the series                              |
+| `site`           | VARCHAR(500)  | NOT NULL                   | Provider site URL                                       |
+| `folder`         | VARCHAR(1000) | NOT NULL                   | Filesystem folder name (metadata only)                  |
+| `year`           | INTEGER       | NULLABLE                   | Release year of the series                               |
+| `nfo_path`       | VARCHAR(1000) | NULLABLE                   | Path to tvshow.nfo metadata file                        |
+| `tmdb_id`        | INTEGER       | NULLABLE, INDEX             | TMDB (The Movie Database) ID for metadata               |
+| `tvdb_id`        | INTEGER       | NULLABLE, INDEX             | TVDB (TheTVDB) ID for metadata                          |
+| `has_nfo`        | BOOLEAN       | NOT NULL, DEFAULT FALSE    | Whether tvshow.nfo exists                               |
+| `loading_status` | VARCHAR(50)   | NOT NULL, DEFAULT 'completed' | Status: pending, loading_episodes, loading_nfo, completed, failed |
+| `created_at`     | DATETIME      | NOT NULL, DEFAULT NOW       | Record creation timestamp                               |
+| `updated_at`     | DATETIME      | NOT NULL, ON UPDATE NOW     | Last update timestamp                                   |
 
 **Identifier Convention:**
 
@@ -101,7 +107,13 @@ Stores anime series metadata.
 - `folder` is **metadata only** for filesystem operations (e.g., `"Attack on Titan (2013)"`)
 - `id` is used only for database relationships
 
-Source: [src/server/database/models.py](../src/server/database/models.py#L23-L87)
+**EpisodeDict Mapping:**
+
+The `episodeDict` (season → episode numbers mapping) is stored as individual `Episode` records:
+- Each `Episode` has `season` and `episode_number` columns
+- Relationship: `AnimeSeries.episodes` returns all Episode records for that series
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L23-L150)
 
 ### 3.3 episodes
 
@@ -441,7 +453,187 @@ items = await db.execute(
 
 ---
 
-## 12. Database Location
+## 12. Series Storage: Database vs Files (Deprecated)
+
+### File-Based Storage (Removed in v2.0)
+
+Prior to v2.0, series metadata was stored in two files per anime folder:
+
+| File     | Contents                                                |
+| -------- | ------------------------------------------------------- |
+| `key`    | Series provider key (e.g., `"attack-on-titan"`)        |
+| `data`   | JSON serialization of `Serie` object                    |
+
+File structure example:
+```
+/anime/Attack on Titan (2013)/
+├── key          # Contains: attack-on-titan
+├── data         # Contains: {"key": "...", "name": "...", "episodeDict": {...}}
+├── Season 1/
+│   └── ...
+```
+
+### Database Storage (Current)
+
+Since v2.0, all series metadata is stored in the `anime_series` table with `Episode` records for episode tracking. This provides:
+
+- **ACID transactions** for data consistency
+- **Foreign key constraints** (cascade delete)
+- **Indexed queries** for fast lookups
+- **No filesystem dependency** for metadata
+
+### Migration from Files to Database
+
+The `Serie.save_to_file()` and `Serie.load_from_file()` methods are deprecated but still functional for backward compatibility during migration:
+
+```python
+from src.core.entities.series import Serie
+
+# Old file-based loading (deprecated)
+serie = Serie.load_from_file("/anime/Attack on Titan (2013)/data")
+
+# New database-based loading
+from src.server.database.service import AnimeSeriesService
+serie = await AnimeSeriesService.get_by_key(db, "attack-on-titan")
+```
+
+### Removing File Dependencies
+
+After verifying database schema supports all fields, file-based storage can be removed:
+
+1. ✅ Schema verified: All `Serie` fields have corresponding DB columns
+2. ✅ Migration complete: All existing series migrated to database
+3. ❌ File cleanup: Remove `key` and `data` files (pending)
+
+**Note:** The `save_to_file()` and `load_from_file()` methods will be removed in v3.0.0.
+
+---
+
+## 12. Series Persistence Flow
+
+When a directory scan discovers or updates series, the scanner persists data to the database instead of writing to disk files.
+
+### Scan Flow
+
+```
+Scan Directory
+    │
+    ▼
+Find MP4 Files → Extract Serie Key
+    │
+    ▼
+Check DB for Existing Series (by key)
+    │
+    ├─── EXISTS ──────────────────────► Update Series Metadata
+    │                                        │
+    │                                        ▼
+    │                                 Sync Episodes to DB
+    │                                      │
+    │◄──────────────────────────────────────┘
+    │
+    └─── NEW ───────────────────────────► Create New Series Record
+                                             │
+                                             ▼
+                                      Create Episode Records
+                                             │
+                                             ▼
+                                      Return to Scan Loop
+```
+
+### Key Methods
+
+**SerieScanner._persist_serie_to_db()**
+- Called after `get_missing_episodes_and_season()` computes episodeDict
+- Uses `AnimeSeriesService.get_by_key()` to check if series exists
+- If exists: calls `AnimeSeriesService.update()` + `_sync_episodes_to_db()`
+- If new: calls `AnimeSeriesService.create()` + creates episodes
+
+**SerieScanner._sync_episodes_to_db()**
+- Gets existing episodes from DB via `EpisodeService.get_by_series()`
+- Compares with new episodeDict
+- Removes episodes no longer missing (unless `is_downloaded=True`)
+- Adds new missing episodes
+- Preserves `is_downloaded=True` episodes when removing missing ones
+
+**SerieList.add_to_db()**
+- Used when adding a new discovered series via API
+- Creates filesystem folder + database record + episode records
+
+### Episode Sync Logic
+
+```python
+# For each episode in DB but not in new episodeDict:
+if episode.is_downloaded:
+    # Keep - file exists, don't remove
+    pass
+else:
+    # Remove - no longer missing
+    EpisodeService.delete()
+
+# For each episode in new episodeDict but not in DB:
+# Add as new missing episode
+EpisodeService.create(is_downloaded=False)
+```
+
+### Transaction Handling
+
+- DB operations use their own session with commit/rollback
+- If DB write fails, error is logged and scan continues
+- File-based `save_to_file()` no longer called during scan
+
+### Migration Path
+
+1. v2.x: Scanner writes to both DB (primary) and files (fallback)
+2. v3.0: Scanner writes only to DB, file methods removed
+
+---
+
+## 13. Series Persistence
+
+### Schema
+
+**AnimeSeries Table**: Stores series metadata (key, name, site, folder, year)
+
+| Column    | Type         | Constraints               | Description           |
+|-----------|--------------|---------------------------|----------------------|
+| `id`      | INTEGER      | PRIMARY KEY               | Auto-increment       |
+| `key`     | VARCHAR(255) | UNIQUE, NOT NULL          | Series provider key   |
+| `name`    | VARCHAR(500) | NOT NULL                 | Display name         |
+| `site`    | VARCHAR(500) |                           | Provider site URL    |
+| `folder`  | VARCHAR(1000)|                           | Filesystem folder    |
+
+**Episode Table**: Stores per-episode metadata (season, episode_number, is_downloaded)
+
+| Column          | Type         | Constraints               | Description           |
+|-----------------|--------------|---------------------------|----------------------|
+| `id`            | INTEGER      | PRIMARY KEY               | Auto-increment       |
+| `series_id`     | INTEGER      | FOREIGN KEY → anime_series| Parent series        |
+| `season`        | INTEGER      | NOT NULL                  | Season number        |
+| `episode_number`| INTEGER      | NOT NULL                  | Episode number       |
+| `is_downloaded` | BOOLEAN      | DEFAULT FALSE            | Download status      |
+
+### Relationships
+
+- `AnimeSeries.episodes` → List of Episode objects (one-to-many)
+- `Episode.series` → Parent AnimeSeries (many-to-one)
+- Cascade delete: Deleting a series removes all its episodes
+
+### Queries
+
+```python
+# Get all series with episodes
+AnimeSeriesService.get_all(db, with_episodes=True)
+
+# Get by provider key
+AnimeSeriesService.get_by_key(db, key)
+
+# Get by folder path
+AnimeSeriesService.get_by_folder(db, folder)
+```
+
+---
+
+## 14. Database Location
 
 | Environment | Default Location                                  |
 | ----------- | ------------------------------------------------- |

docs/DEVELOPMENT.md

@@ -61,4 +61,376 @@ This document provides guidance for developers working on the Aniworld project.
     - Commit message format
     - Pull request process
 8. Common Development Tasks
+
+### Adding Queue Deduplication
+
+The download queue prevents duplicate entries at two levels:
+
+**In-Memory Deduplication** (`src/server/services/download_service.py`):
+- `_pending_by_episode` dict tracks pending episodes: key = `(serie_id, season, episode)`
+- `_add_to_pending_queue()` updates the dict when adding items
+- `add_to_queue()` checks this dict before adding episodes (includes batch-local dedup)
+- `_remove_from_pending_queue()` cleans up the dict when items are removed
+
+**Database Constraint** (`src/server/models.py`):
+- `DownloadQueueItem` has a unique index on `episode_id` via `__table_args__`
+- Prevents duplicate queue entries at the database level
+- Unique constraint: `Index("ix_download_queue_episode_pending", "episode_id", unique=True)`
+
+**Scheduler Cooldown** (`src/server/services/scheduler_service.py`):
+- `_last_auto_download_time` tracks when auto-download last ran
+- 5-minute cooldown prevents rapid re-triggers
+- Checked at start of `_auto_download_missing()`
+
+### Episode Lifecycle
+
+Episodes transition through states stored in the `episodes` table:
+
+| State | `is_downloaded` | `file_path` | Description |
+|-------|----------------|-------------|-------------|
+| Missing | `False` | `NULL` | Episode not yet downloaded |
+| Downloaded | `True` | Set | Episode exists on disk |
+
+**State Transitions:**
+1. **Missing → Downloaded**: When download completes, `_remove_episode_from_missing_list()` calls `EpisodeService.mark_downloaded()` to set `is_downloaded=True` and populate `file_path`. The episode record is NOT deleted.
+
+**Query Implications:**
+- `get_series_with_missing_episodes()`: Filters for `is_downloaded=False` to find series with undownloaded episodes
+- `get_series_with_no_episodes()`: Finds series with `is_downloaded=False` episodes but NO `is_downloaded=True` episodes (completely unwatched series)
+
+### Mocking the Download Queue
+
+When testing components that use the download queue:
+
+```python
+# Mock repository for unit tests
+class MockQueueRepository:
+    def __init__(self):
+        self._items: Dict[str, DownloadItem] = {}
+
+    async def save_item(self, item: DownloadItem) -> DownloadItem:
+        self._items[item.id] = item
+        return item
+
+    async def get_all_items(self) -> List[DownloadItem]:
+        return list(self._items.values())
+
+# Use in fixture
+@pytest.fixture
+def mock_queue_repository():
+    return MockQueueRepository()
+
+@pytest.fixture
+def download_service(mock_anime_service, mock_queue_repository):
+    return DownloadService(
+        anime_service=mock_anime_service,
+        queue_repository=mock_queue_repository,
+        max_retries=3,
+    )
+```
+
 9. Troubleshooting Development Issues
+
+### Async Context Managers for aiohttp
+
+All `aiohttp.ClientSession` usages must be wrapped in `async with`:
+
+```python
+# Correct — session properly closed on exit
+async with TMDBClient(api_key="key") as client:
+    result = await client.search_tv_show("Show")
+
+# Wrong — session may leak if exception occurs
+client = TMDBClient(api_key="key")
+result = await client.search_tv_show("Show")
+await client.close()  # May not be called if exception raised earlier
+```
+
+**Why:**
+- `aiohttp.ClientSession` holds TCP connections that must be explicitly closed
+- If exception occurs before `close()`, session leaks
+- Context manager guarantees `__aexit__` runs even on exceptions
+
+**Services that use aiohttp:**
+- `TMDBClient` — has `__aenter__`/`__aexit__`, use `async with`
+- `ImageDownloader` — has `__aenter__`/`__aexit__`, use `async with`
+- `NFOService` — wraps both above, use `async with`
+
+**Verification:**
+- Missing context manager usage triggers `__del__` warning on garbage collection
+- Integration tests verify no "Unclosed client session" errors in logs
+
+### Scheduler Persistence and Recovery
+
+The scheduler uses APScheduler's in-memory job store. Jobs are reconstructed from `config.json` on every startup — no separate database is needed.
+
+```python
+# Jobs are built from config on startup — no persistence DB required
+scheduler = AsyncIOScheduler()  # default MemoryJobStore
+scheduler.add_job(..., replace_existing=True)
+```
+
+**Startup misfire recovery:** On `start()`, the scheduler checks `system_settings.last_scan_timestamp` in `aniworld.db`. If the last scan is overdue (>23h but <25h ago), an immediate rescan is triggered. This replaces APScheduler's built-in misfire handling which required a separate SQLite database.
+
+**Grace period:** If the server was down for more than 25 hours, no automatic recovery occurs to avoid surprise rescans after long downtime.
+
+**Health endpoint:** `GET /health` returns `scheduler_next_run` and `scheduler_last_run` for external monitors (Uptime Kuma, Prometheus, etc.).
+
+**If server is down too long:** Manual trigger via `POST /api/scheduler/trigger-rescan` or wait for next scheduled run.
+
+### Database Session Management
+
+`get_async_session_factory()` returns a **new AsyncSession instance** directly (not a factory). The function name is historical — callers receive the session immediately:
+
+```python
+# Correct usage:
+db = get_async_session_factory()  # db IS the session
+await db.execute(...)
+await db.commit()
+await db.close()
+```
+
+Do NOT call the result again with `()` — that tries to call an `AsyncSession` object, causing `'AsyncSession' object is not callable`.
+
+For context manager usage, prefer `get_db_session()` (auto-commits) or `get_transactional_session()` (manual commit).
+
+### Health Check Endpoints
+
+The application provides health check endpoints for monitoring and container orchestration:
+
+#### `GET /health`
+Basic health check returning service status and startup health check results.
+
+**Response fields:**
+- `status`: "healthy", "degraded", or "unhealthy" based on startup checks
+- `timestamp`: ISO timestamp of the check
+- `series_app_initialized`: Whether the series app is loaded
+- `anime_directory_configured`: Whether anime_directory is set
+- `scheduler_next_run` / `scheduler_last_run`: Scheduler times
+- `checks`: Detailed startup check results (ffmpeg, DNS, anime_directory)
+
+#### `GET /health/ready`
+Readiness check for container orchestrators (Kubernetes, Docker Swarm).
+
+**Response when ready:**
+```json
+{
+  "status": "ready",
+  "ready": true,
+  "timestamp": "2024-01-01T00:00:00",
+  "checks": {...}
+}
+```
+
+**Response when not ready (503):**
+```json
+{
+  "status": "not_ready",
+  "ready": false,
+  "timestamp": "2024-01-01T00:00:00",
+  "critical_failures": ["anime_directory: not configured"],
+  "checks": {...}
+}
+```
+
+#### `GET /health/detailed`
+Comprehensive health check including database, filesystem, and system metrics.
+
+#### Startup Health Checks
+
+On application startup, the following checks are performed:
+
+| Check | Failure Status | Impact |
+|-------|---------------|--------|
+| `ffmpeg` | warning | HLS downloads may fail |
+| `dns_aniworld` | warning | Provider requests may fail |
+| `dns_tmdb` | warning | TMDB API calls may fail |
+| `anime_directory` | error | Download service disabled |
+
+DNS checks are warnings because failures can be transient. anime_directory errors disable the download service to prevent failures.
+
+### Troubleshooting Development Issues
+
+#### Scheduler missed a run
+
+1. Server was down at scheduled time (03:00 UTC by default).
+2. On restart, the scheduler checks `last_scan_timestamp` — if overdue by 23-25h, it triggers immediately.
+3. If server was down >25 hours, missed job is skipped to avoid surprise rescans.
+4. Trigger manually: `POST /api/scheduler/trigger-rescan`
+5. Monitor next run: `GET /health` → `scheduler_next_run`
+
+#### Scheduler not firing (no events at scheduled time)
+
+If the scheduler appears configured but never triggers:
+
+1. **Check application logs for scheduler startup:**
+   ```
+   grep "Scheduler service started" fastapi_app.log
+   ```
+   - If missing, the scheduler failed to start — check for errors above this line
+   - If present, scheduler started successfully
+
+2. **Verify the job is registered:**
+   ```
+   grep "Scheduler started with cron trigger" fastapi_app.log
+   ```
+
+3. **Verify APScheduler events in logs:**
+   ```
+   grep "apscheduler.executors.default" fastapi_app.log
+   ```
+   - `Running job` = job triggered
+   - `executed successfully` = job completed
+   - No output = job never fired
+
+4. **Test manual trigger:**
+   ```bash
+   curl -X POST http://localhost:8000/api/scheduler/trigger-rescan -H "Authorization: Bearer <token>"
+   ```
+   - If manual trigger works but cron doesn't, the issue is APScheduler configuration
+
+5. **Check next_run_time via health endpoint:**
+   ```bash
+   curl http://localhost:8000/health | jq .scheduler_next_run
+   ```
+   - If `null`, the job is not scheduled
+   - If set, the scheduler knows when to run next
+
+6. **Check timezone handling:**
+   - APScheduler uses UTC internally
+   - The schedule_time config (e.g., "03:00") is interpreted as UTC
+   - If you expect local time, adjust the schedule_time accordingly
+
+#### Startup health check failures
+
+If `/health` returns `unhealthy` status:
+
+1. **anime_directory error**: Directory not configured or not writable
+   - Check `ANIME_DIRECTORY` environment variable
+   - Verify directory exists and permissions allow write access
+   - Download service will not initialize until resolved
+
+2. **ffmpeg warning**: ffmpeg not found in PATH
+   - HLS stream downloads will fail
+   - Install ffmpeg: `apt install ffmpeg` or `brew install ffmpeg`
+
+3. **DNS warnings**: Domain resolution failed
+   - Check network connectivity
+   - DNS failures are transient — warnings don't block startup
+   - Retry later to verify: `GET /health`
+
+### Provider Failure Handling
+
+Download providers (VOE, Doodstream, Vidmoly, Vidoza, SpeedFiles, Streamtape,
+Luluvdo) regularly break: URLs expire, sites change their player markup, geo
+blocks appear, and `yt-dlp` extractors lag behind upstream changes. The
+`AniworldLoader.download()` flow is designed to fail fast and rotate.
+
+**Rotation order**
+
+1. The episode page is scraped for the providers AniWorld actually advertises.
+2. Results are ordered by the preference in `DEFAULT_PROVIDERS`
+   (`provider_config.py`); providers not listed run last.
+3. For each candidate the loader:
+   1. Calls `_check_url_alive()` — HEAD probe with GET fallback. Any 4xx
+      response or connection error skips the provider immediately.
+   2. Resolves the redirect via `_resolve_direct_link()` to obtain a direct
+      stream URL plus headers. Provider-specific extractors (e.g. `VOE`) are
+      preferred; unknown providers fall back to the embed URL so `yt-dlp` can
+      attempt extraction.
+   3. Tries `_try_direct_stream()` — straight `requests.get(stream=True)` when
+      `Content-Type` is `video/*` or `application/octet-stream`. This avoids
+      `yt-dlp` entirely for direct MP4 links.
+   4. Falls back to `yt-dlp` with the ffmpeg downloader for HLS streams.
+4. On any failure, temp files are cleaned and the loop moves to the next
+   provider. When the chain is exhausted, the loader logs
+   `All download providers failed for S{season}E{episode} ...; tried=[...]`
+   to both the application log and `logs/download_errors.log`.
+
+**Do not hardcode provider URLs.** Provider domains shift constantly (e.g.
+Doodstream alternates between `dood.li`, `dood.so`, `dood.la`). Only the
+referer hints in `PROVIDER_HEADERS` are persisted — discovery still happens
+at runtime through AniWorld's redirect endpoint.
+
+### HLS Stream Handling
+
+HLS (HTTP Live Streaming) manifests (`.m3u8`) require yt-dlp to use the
+`ffmpeg` downloader with `--hls-use-mpegts`. Both providers configure this
+automatically:
+
+```python
+ydl_opts = {
+    "downloader": "ffmpeg",     # Use ffmpeg instead of native
+    "hls_use_mpegts": True,     # Write transport stream (.ts) segments
+}
+```
+
+**Why this matters**: Without ffmpeg, yt-dlp logs:
+`"Live HLS streams are not supported by the native downloader"`
+
+**Requirements**:
+- ffmpeg must be installed and in PATH (`which ffmpeg`)
+- Install: `apt install ffmpeg` (Debian/Ubuntu) or `brew install ffmpeg` (macOS)
+- Startup health check (see Health Check Endpoints) verifies ffmpeg presence
+
+**Trade-offs**:
+- HLS downloads are slower than direct MP4 (reassembly of .ts segments)
+- Requires more disk space during download
+- May need post-processing if .ts format is not desired
+
+**Detection**: VOE provider extracts HLS URLs via `HLS_PATTERN` regex. Other
+providers let yt-dlp auto-detect from URL/content-type.
+
+### Updating yt-dlp
+
+When extractors break (typical symptoms: every provider HEAD probe succeeds
+but `yt-dlp` raises `Unable to extract` or `HTTP Error 404`):
+
+1. Check the upstream tracker first: https://github.com/yt-dlp/yt-dlp/issues
+2. Upgrade in the conda environment:
+   ```bash
+   conda run -n AniWorld pip install --upgrade yt-dlp
+   ```
+3. Smoke-test against a known-good episode before pinning a new floor in
+   `requirements.txt` (`yt-dlp>=YYYY.MM.DD`).
+4. Re-run the provider test suite:
+   ```bash
+   conda run -n AniWorld python -m pytest tests/unit/test_aniworld_provider.py -v
+   ```
+5. If a specific extractor is removed upstream, drop the provider from
+   `DEFAULT_PROVIDERS` rather than patching `yt-dlp` in tree.
+
+### User Notification on Total Failure
+
+`SeriesApp.download_episode()` already emits a `download_status="failed"`
+WebSocket event when `loader.download()` returns `False`. Operators should
+forward this to `notification_service.notify_download_failed()` so users see
+a HIGH-priority alert. The loader keeps the failure detail in
+`logs/download_errors.log` for post-mortem.
+
+## Series Storage
+
+### Overview
+
+Series metadata now stored in the database (SQLAlchemy ORM).
+Legacy files (`key` and `data` per folder) are deprecated but preserved
+for backward compatibility.
+
+### Architecture
+
+- **Database**: Single source of truth for all series metadata
+- **In-Memory Cache**: SeriesApp maintains a cache for performance
+- **Filesystem**: Only used for episode files themselves, not metadata
+
+### Migration
+
+First startup after upgrade automatically imports any legacy
+series files into the database.
+
+### Legacy Files
+
+- `key` file: Contains series provider key (deprecated)
+- `data` file: Contains Serie JSON object (deprecated)
+
+Both are safe to delete after migration; not needed for normal operation.
+

docs/InstructionsLogging.md

@@ -0,0 +1,94 @@
+# Logging Instructions
+
+This document describes how to write and refactor logging across the AniWorld codebase to make logs **human-readable**, **debug-friendly**, and **noise-free**.
+
+> ✅ Goal: Logs should help a developer understand what happened, why it happened, and what to inspect next — without overwhelming them with duplicates or irrelevant details.
+
+---
+
+## 1. Principles for Great Logs
+
+### 1.1 Use the Right Log Level
+
+- `DEBUG`: Detailed internal state useful when debugging a specific issue (e.g., decision points, returned values, request/response payloads). Not for normal operation.
+- `INFO`: High-level events that represent what the system is doing (e.g., "Import started", "New series added", "Config reloaded"). Use sparingly.
+- `WARNING`: Something unexpected happened, but the system can continue (e.g., missing optional file, fallback behavior).
+- `ERROR`: An operation failed and needs attention (e.g., exception caught, failed database write).
+- `CRITICAL`: The system is in an unusable state (e.g., config corruption, failed startup).
+
+### 1.2 Keep Logs Human-Readable
+
+- Write messages in a clear, descriptive sentence-style format.
+- Avoid cryptic codes or single-word log messages.
+- Prefer `logger.debug("... %s", value)`-style formatting over f-strings to avoid unnecessary work when the log level is disabled.
+
+### 1.3 Avoid Log Spam
+
+- Don’t log inside hot loops unless you explicitly aggregate and log a summary (e.g., "Processed 124 files, 3 failures").
+- Avoid repeated/logging the same event at the same level (e.g., do not log "Retrying" 10 times at INFO; log once at INFO and then use DEBUG for each retry).
+- Use rate limiting or debounce patterns for logs that can fire rapidly (e.g., external service health checks).
+- Prefer a single higher-level log with context rather than many low-level logs that clutter output.
+
+### 1.4 Log Objects Usefully
+
+- When logging objects, log the minimal useful representation (e.g., ID, name, status) rather than the full object or its memory address.
+- If an object has a `.dict()`, `.to_dict()`, or `.as_dict()` helper (common in Pydantic models), log that rather than relying on `repr()`.
+- Add a `__repr__` or `__str__` implementation to domain models that returns a helpful, concise string with key identifiers.
+- Use structured logging (e.g., `logger.info("Series added", extra={"series_id": series.id, "title": series.title})`) where supported.
+- For exceptions, prefer `logger.exception("Failed to ...")` to capture stack traces.
+
+---
+
+## 2. Refactoring Existing Logs
+
+When improving or refactoring existing log statements, aim to make them:
+
+- **Actionable**: A developer reading the log should know what happened and what to check next.
+- **Non-redundant**: Remove duplicates and ensure only one log records the same high-level event at a given level.
+- **Context-rich**: Include identifiers (e.g., `series_id`, `file_path`, `user_id`) and key state that explains why a decision was made.
+- **Level-appropriate**: Downgrade noisy INFO logs to DEBUG, and elevate critical failures to ERROR/CRITICAL.
+
+### 2.1 Refactor Checklist
+
+1. **Locate noisy logs**: Search for repeated messages (e.g., "Start", "Done") and determine whether they should be DEBUG or removed.
+2. **Replace ad-hoc prints**: Remove `print()` statements or `print(obj)` and replace with `logger.*` calls.
+3. **Use structured context**: If a function logs multiple related messages, include the same context in each (e.g., `extra={"series_id": series.id}`) or use a context manager that attaches it.
+4. **Validate object output**: Ensure any logged object produces a useful representation (add methods or translate to dict). If not, log the key fields explicitly.
+5. **Batch repetitive events**: If a loop logs per item, consider collecting stats and logging a summary at the end.
+
+## 3. Adding New Logs
+
+When adding logs to new code paths:
+
+- Log **important state transitions** (e.g., "Queue started", "Download completed", "Config reloaded").
+- For error paths, include what failed and why (e.g., "Could not load config from X: {exc}").
+- Prefer logging at the boundaries of operations, not deep inside utility functions unless it aids debugging.
+- Write logs in full sentences, with a clear subject, verb, and object.
+
+---
+
+## 4. Example Patterns
+
+```python
+logger.info("Import completed", extra={"series_id": series.id, "count": len(imported)})
+
+logger.debug(
+    "Fetched feed items",
+    extra={"feed_url": feed.url, "item_count": len(items)},
+)
+
+try:
+    result = download_episode(episode)
+except Exception:
+    logger.exception("Failed to download episode %s", episode.id)
+```
+
+> 💡 When in doubt, favor **fewer, richer logs** over many noisy logs.
+
+---
+
+## 5. Logging Audit Task List
+
+For a guided checklist of files and logging improvements, see **`docs/tasks.md`**. This is where we track which files have been reviewed and which logging items still need attention.
+
+> ✅ After applying the guidelines above, update `docs/tasks.md` to indicate which tasks are complete.

docs/MIGRATION_GUIDE.md

@@ -0,0 +1,111 @@
+# Migration Guide: File-Based to Database Storage
+
+## Overview
+
+This guide covers the transition from file-based series metadata storage to the new database-backed system introduced in v2.0.
+
+## What Changed
+
+**Before v2.0**: Series metadata stored in `key` and `data` files alongside anime folders.
+
+**After v2.0**: All metadata stored in SQLite database (`aniworld.db`). Files are deprecated but still supported for backward compatibility during migration.
+
+## Automated Migration
+
+The application automatically migrates on first startup:
+
+1. Scans anime directory for `key` and `data` files
+2. Parses legacy files into `AnimeSeries` and `Episode` records
+3. Loads series into in-memory cache
+4. Logs migration results
+
+**No manual action required.**
+
+## Manual Verification
+
+After first startup with the new version:
+
+1. **Check logs** for: `"Migrated X series from files to DB"`
+2. **Verify series count**: UI shows same number of series as before
+3. **Confirm episodes**: Episode counts match expected totals
+
+```bash
+# Check migration log
+grep "Migrated" logs/app.log
+
+# Verify series via API
+curl http://localhost:8000/api/anime | jq '.total'
+```
+
+## After Migration
+
+### Safe to Delete
+
+Once verified, these files can be removed:
+
+```
+<anime_folder>/
+├── Attack on Titan (2013)/
+│   ├── key     # ❌ Can delete
+│   ├── data    # ❌ Can delete
+│   └── Season 1/
+│       └── ...
+```
+
+**Deleting these files does not affect the database.** The metadata now lives in `aniworld.db`.
+
+### Backup (Recommended)
+
+Before deleting, backup the files:
+
+```bash
+# Create backup directory
+mkdir -p backup/legacy_series_files
+
+# Copy all key and data files
+find /path/to/anime -name "key" -o -name "data" | while read f; do
+    cp "$f" "backup/legacy_series_files/"
+done
+```
+
+## Reverting (Not Recommended)
+
+If you must revert to file-based storage:
+
+1. **Restore from database backup** (if available)
+2. **Export manually** (no export script exists)
+
+**Warning**: File-based storage is deprecated and will be removed in v3.0.0.
+
+## Troubleshooting
+
+### Series Not Appearing After Migration
+
+1. Check logs for migration errors: `grep -i error logs/app.log`
+2. Verify `key` and `data` files exist and are readable
+3. Manually trigger rescan: `POST /api/scheduler/trigger-rescan`
+
+### Duplicate Series
+
+1. Check for duplicate `key` files (same series in multiple folders)
+2. Verify series key uniqueness in database:
+
+```bash
+sqlite3 aniworld.db "SELECT key, COUNT(*) FROM anime_series GROUP BY key HAVING COUNT(*) > 1;"
+```
+
+### Missing Episodes
+
+1. Trigger targeted scan for affected series
+2. Check episode sync logs
+3. Verify file permissions on anime directory
+
+## Deprecation Timeline
+
+| Version | Status |
+|---------|--------|
+| v2.0.x  | Legacy files supported, migration automated |
+| v2.1.x  | Legacy files still supported, warnings in logs |
+| v3.0.0  | **Legacy files removed** - database only |
+
+Upgrade to v3.0.0 before legacy file support ends.

docs/NFO_GUIDE.md

@@ -171,6 +171,35 @@ Response:
 }
 ```
 
+### 3.6 Fallback Behavior When TMDB is Unavailable
+
+When TMDB lookup fails (network issues, API errors, or no match found), the system creates a **minimal NFO** to ensure the series is still tracked. This behavior applies to:
+
+- Manual NFO creation via API
+- Batch NFO creation operations
+- Automatic NFO creation during downloads
+
+**What a minimal NFO contains:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<tvshow>
+    <title>Series Name</title>
+    <year>2024</year>
+    <plot>No metadata available for Series Name. TMDB lookup failed.</plot>
+</tvshow>
+```
+
+**Limitations of minimal NFOs:**
+- No poster, logo, or fanart images
+- No rating, genre, or studio information
+- No TMDB or other provider IDs
+- May not display correctly in some media servers
+
+**To upgrade a minimal NFO:**
+1. Use the Update endpoint (`PUT /api/nfo/{serie_id}/update`) when TMDB is available
+2. Or delete the NFO and recreate it with full metadata
+
 ---
 
 ## 4. File Structure
@@ -217,6 +246,7 @@ NFO files are created in the anime directory:
     <genre>Action</genre>
     <genre>Sci-Fi & Fantasy</genre>
     <uniqueid type="tmdb">1429</uniqueid>
+    <tmdbid>1429</tmdbid>
     <thumb aspect="poster">https://image.tmdb.org/t/p/w500/...</thumb>
     <fanart>
         <thumb>https://image.tmdb.org/t/p/original/...</thumb>
@@ -224,6 +254,13 @@ NFO files are created in the anime directory:
 </tvshow>
 ```
 
+**Manual TMDB ID Override**: To skip TMDB search and use a specific ID directly, include `<tmdbid>YOUR_ID</tmdbid>` in the NFO. This is useful when:
+- TMDB search fails for your series (e.g., new or obscure anime)
+- You already know the correct TMDB ID
+- You want to avoid rate limiting from repeated searches
+
+Aniworld reads `<tmdbid>` element and `<uniqueid type="tmdb">` first. If found, it uses the ID directly instead of searching.
+
 ### 4.3 Episode NFO Format
 
 ```xml
@@ -246,7 +283,84 @@ NFO files are created in the anime directory:
 
 ---
 
-## 5. API Reference
+## 5. Folder Naming Convention
+
+### 5.1 Expected Format
+
+After the daily folder scan (when **Update on library scan** is enabled), Aniworld validates every series folder against its `tvshow.nfo` metadata. If the folder name does not match the expected convention, it is automatically renamed.
+
+**Format:**
+
+```
+{title} ({year})
+```
+
+**Examples:**
+
+| NFO `<title>` | NFO `<year>` | Expected Folder Name |
+|---------------|--------------|----------------------|
+| `Attack on Titan` | `2013` | `Attack on Titan (2013)` |
+| `One Piece` | `1999` | `One Piece (1999)` |
+| `Demon Slayer: Kimetsu no Yaiba` | `2019` | `Demon Slayer Kimetsu no Yaiba (2019)` |
+
+### 5.2 Sanitization Rules
+
+Illegal filesystem characters are removed or replaced to ensure cross-platform compatibility:
+
+- Removed: `< > : " / \ | ? *` and null bytes
+- Control characters stripped
+- Multiple spaces collapsed to one
+- Leading/trailing dots and whitespace trimmed
+- Maximum length: 200 characters (truncated at word boundary if possible)
+
+### 5.3 Skip Conditions
+
+A folder is **not** renamed when any of the following apply:
+
+- `tvshow.nfo` is missing `<title>` or `<year>` (or they are empty)
+- The series has an **active or pending download**
+- The target folder name already exists (duplicate)
+- The resulting path would exceed the OS path-length limit
+- The app lacks write permission to the anime directory
+
+All skipped and renamed actions are logged.
+
+---
+
+## 6. Poster Check
+
+### 6.1 Overview
+
+During the daily folder scan, Aniworld checks every series folder for a valid `poster.jpg`. If the file is missing or smaller than 1 KB, the application attempts to re-download it from the URL stored in the series' `tvshow.nfo` file.
+
+### 6.2 How It Works
+
+1. **Scan** — After folder renaming, the scan iterates over all series folders that contain a `tvshow.nfo`.
+2. **Validate** — For each folder, it checks whether `poster.jpg` exists and is at least 1 KB.
+3. **Parse NFO** — If the poster is missing or too small, the scan reads `tvshow.nfo` and looks for a `<thumb aspect="poster">` (or any `<thumb>`) URL.
+4. **Download** — If a URL is found, the poster is downloaded using `ImageDownloader` with a concurrency limit of 3 simultaneous downloads.
+5. **Validate Download** — The downloaded image is validated with PIL to ensure it is not corrupted.
+
+### 6.3 Skip Conditions
+
+A folder is **not** processed for poster download when any of the following apply:
+
+- `tvshow.nfo` does not exist in the folder.
+- `poster.jpg` already exists and is ≥ 1 KB.
+- No `<thumb>` URL is found in the NFO (the NFO may have been created before thumb tags were added).
+- The `nfo.download_poster` setting is `false` (poster checks are still performed, but downloads are skipped if the setting is disabled; see [CONFIGURATION.md](CONFIGURATION.md)).
+
+### 6.4 Logging
+
+Every poster check action is logged:
+
+- **INFO** — When a poster is successfully downloaded.
+- **WARNING** — When a download fails or no URL is found.
+- **ERROR** — When an unexpected exception occurs during download.
+
+---
+
+## 7. API Reference
 
 ### 5.1 Check NFO Status
 
@@ -523,6 +637,36 @@ NFO files are created in the anime directory:
 4. Check network speed to TMDB servers
 5. Verify disk I/O performance
 
+### 6.7 TMDB Lookup Fails for My Series
+
+**Problem**: TMDB search fails with "No results found" for a valid series.
+
+**Solutions**:
+
+1. **Check if series exists on TMDB**: Visit https://www.themoviedb.org and search for your series
+2. **Use manual ID override**: Add TMDB ID directly to `tvshow.nfo`:
+   ```xml
+   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+   <tvshow>
+       <title>Your Series Name</title>
+       <tmdbid>12345</tmdbid>
+       <uniqueid type="tmdb">12345</uniqueid>
+   </tvshow>
+   ```
+   Aniworld will use this ID directly instead of searching.
+
+3. **Try alternative titles**: Some anime have different titles (Japanese, romaji, English). If you have access to the folder, rename it to match the TMDB title.
+
+4. **Add to existing NFO**: If `tvshow.nfo` exists but has no TMDB ID, edit it to add:
+   ```xml
+   <tmdbid>YOUR_TMDB_ID</tmdbid>
+   ```
+   Then use the Update endpoint to refresh metadata.
+
+5. **Check for rate limiting**: If many lookups fail at once, you may be hitting TMDB rate limits. Wait and retry later.
+
+6. **Verify API key**: Ensure your TMDB API key is valid and has not exceeded usage limits.
+
 ---
 
 ## 7. Best Practices
@@ -675,21 +819,25 @@ The XML serialisation lives in `src/core/utils/nfo_generator.py`
 
 ## 11. Automatic NFO Repair
 
-Every time the server starts, Aniworld scans all existing `tvshow.nfo` files and
-automatically repairs any that are missing required tags.
+NFO repair now runs as part of the scheduled daily folder scan rather than on every
+startup.  When the scheduler triggers `FolderScanService.run_folder_scan()`, the first
+step is `perform_nfo_repair_scan(background_loader=None)`.  Each incomplete NFO is
+queued as a background `asyncio` task, so the scan returns quickly while repairs
+continue asynchronously.
 
 ### How It Works
 
 1. **Scan** — `perform_nfo_repair_scan()` in
-   `src/server/services/initialization_service.py` is called from the FastAPI
-   lifespan after `perform_media_scan_if_needed()`.
+   `src/server/services/initialization_service.py` is called from
+   `FolderScanService.run_folder_scan()` (`src/server/services/folder_scan_service.py`).
 2. **Detect** — `nfo_needs_repair(nfo_path)` from
    `src/core/services/nfo_repair_service.py` parses each `tvshow.nfo` with
    `lxml` and checks for the 13 required tags listed below.
 3. **Repair** — Series whose NFO is incomplete are queued for background reload
-   via `BackgroundLoaderService.add_series_loading_task()`. The background
-   loader re-fetches metadata from TMDB and rewrites the NFO with all tags
-   populated.
+   via `asyncio.create_task`. Each task creates its own isolated
+   :class:`NFOService` / :class:`TMDBClient` so concurrent tasks never share an
+   ``aiohttp`` session — this prevents "Connector is closed" errors when many repairs
+   run in parallel.  A semaphore caps TMDB concurrency at 3 to stay within rate limits.
 
 ### Tags Checked (13 required)
 
@@ -734,8 +882,7 @@ This calls `NFOService.update_tvshow_nfo()` directly and overwrites the existing
 | File                                            | Purpose                                                                                        |
 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
 | `src/core/services/nfo_repair_service.py`       | `REQUIRED_TAGS`, `parse_nfo_tags`, `find_missing_tags`, `nfo_needs_repair`, `NfoRepairService` |
-| `src/server/services/initialization_service.py` | `perform_nfo_repair_scan` startup hook                                                         |
-| `src/server/fastapi_app.py`                     | Wires `perform_nfo_repair_scan` into the lifespan                                              |
+| `src/server/services/folder_scan_service.py`    | `perform_nfo_repair_scan` — invoked during the scheduled daily folder scan                     |
 
 ---
 

docs/TESTING.md

@@ -62,6 +62,81 @@ This document describes the testing strategy, guidelines, and practices for the
     - What to mock
     - Mock patterns
     - External service mocks
+
+### Mocking the Download Queue
+
+Use `MockQueueRepository` for testing download queue functionality:
+
+```python
+from src.server.models.download import DownloadItem, EpisodeIdentifier
+
+class MockQueueRepository:
+    def __init__(self):
+        self._items: Dict[str, DownloadItem] = {}
+```
+
+### Testing SetupService
+
+SetupService handles series key resolution from folder names during library setup. Test file: `tests/unit/test_setup_service.py`.
+
+Key methods tested:
+- `_extract_year_from_folder_name()` — parses `(YYYY)` suffix
+- `_extract_title_from_folder_name()` — strips year suffix
+- `_resolve_key_via_search()` — resolves provider key via fuzzy title matching
+
+```python
+@pytest.mark.asyncio
+async def test_returns_key_when_single_exact_match(self):
+    """Search returns 1 result with same name → returns key."""
+    mock_series_app = AsyncMock()
+    mock_series_app.search.return_value = [
+        {'title': 'Attack on Titan', 'link': '/anime/stream/attack-on-titan'}
+    ]
+
+    with patch('src.server.services.setup_service.get_series_app', return_value=mock_series_app):
+        result = await SetupService._resolve_key_via_search("Attack on Titan")
+
+    assert result == 'attack-on-titan'
+```
+
+### Mocking aiohttp Sessions
+
+When testing code that uses `aiohttp.ClientSession`:
+
+```python
+from unittest.mock import AsyncMock, MagicMock, patch
+from aiohttp import ClientSession
+
+# Mock aiohttp session for testing
+class MockAiohttpSession:
+    def __init__(self):
+        self.closed = False
+    
+    async def close(self):
+        self.closed = True
+    
+    def get(self, url, **kwargs):
+        mock_response = AsyncMock()
+        mock_response.status = 200
+        mock_response.json = AsyncMock(return_value={"data": "test"})
+        mock_response.__aenter__ = AsyncMock(return_value=mock_response)
+        mock_response.__aexit__ = AsyncMock(return_value=None)
+        return mock_response
+
+# Use in fixture
+@pytest.fixture
+async def mock_tmdb_session():
+    session = MockAiohttpSession()
+    yield session
+    # Cleanup verification
+    assert session.closed, "Session was not closed"
+```
+
+**Key points:**
+- Always verify `session.closed` is `True` after context manager exits
+- Mock `__aenter__` and `__aexit__` for response context managers
+- Set `closed = False` on mock session for unclosed warning tests
+
 7. Coverage Requirements
 8. CI/CD Integration
 9. Writing Good Tests

docs/diagrams/system-architecture.mmd

@@ -31,14 +31,16 @@ flowchart TB
 
     subgraph Core["Core Layer"]
         SeriesApp["SeriesApp"]
+        SeriesCache["SeriesCache<br/>(In-Memory)"]
         SerieScanner["SerieScanner"]
         SerieList["SerieList"]
     end
 
     subgraph Data["Data Layer"]
-        SQLite[(SQLite<br/>aniworld.db)]
+        SQLite[("SQLite<br/>aniworld.db")]
         ConfigJSON[(config.json)]
-        FileSystem[(File System<br/>Anime Directory)]
+        FileSystem[(File System<br/>Anime Episodes)]
+        LegacyFiles[("Legacy Files<br/>key/data<br/>(Deprecated)")]
     end
 
     subgraph External["External"]
@@ -71,9 +73,13 @@ flowchart TB
     AnimeService --> SQLite
 
     %% Core to Data
+    SeriesApp --> SeriesCache
+    SeriesCache -.->|Cached Series| SQLite
     SeriesApp --> SerieScanner
     SeriesApp --> SerieList
-    SerieScanner --> FileSystem
+    SerieScanner -->|Scan Episodes| FileSystem
+    SerieScanner -->|Detect Series| SQLite
+    SerieScanner -->|Migrate Legacy| LegacyFiles
     SerieScanner --> Provider
 
     %% Event flow

docs/features.md

@@ -59,6 +59,10 @@ The application now features a comprehensive configuration system that allows us
 ## Anime Management
 
 - **Anime Library Page**: Display list of anime series with missing episodes
+- **Library Filters**:
+    - "Missing Episodes Only" (shows only series with missing episodes, including series that currently have no downloaded episodes)
+    - "No Episodes" (shows series that are present in the library but have zero downloaded episodes)
+    - "Show All Series" (overrides other filters to show every series)
 - **Database-Backed Series Storage**: All series metadata and missing episodes stored in SQLite database
 - **Automatic Database Synchronization**: Series loaded from database on startup, stays in sync with filesystem
 - **Series Selection**: Select individual anime series and add episodes to download queue
@@ -103,6 +107,10 @@ The application now features a comprehensive configuration system that allows us
 - **Progress Tracking**: Live progress updates for downloads and scans
 - **System Notifications**: Real-time system messages and alerts
 
+## Folder Management
+
+- **Fuzzy Series Key Resolution**: Automatic series key resolution from folder names using fuzzy title matching — tolerates title variations like `(TV)`, `(OVA)`, `(Movie)` suffixes and uses similarity matching to resolve provider keys during library setup
+
 ## Core Functionality Overview
 
 The web application provides a complete interface for managing anime downloads with user-friendly pages for configuration, library management, search capabilities, and download monitoring. All operations are tracked in real-time with comprehensive progress reporting and error handling.

docs/instructions.md

@@ -117,6 +117,3 @@ For each task completed:
 
 ---
 
-## TODO List:
-
----

docs/key

@@ -2,3 +2,50 @@ API key : 299ae8f630a31bda814263c551361448
 
 /mnt/server/serien/Serien/
 
+{
+  "name": "Aniworld",
+  "data_dir": "data",
+  "scheduler": {
+    "enabled": true,
+    "interval_minutes": 60,
+    "schedule_time": "03:00",
+    "schedule_days": [
+      "mon",
+      "tue",
+      "wed",
+      "thu",
+      "fri",
+      "sat",
+      "sun"
+    ],
+    "auto_download_after_rescan": true,
+    "folder_scan_enabled": true
+  },
+  "logging": {
+    "level": "INFO",
+    "file": null,
+    "max_bytes": null,
+    "backup_count": 3
+  },
+  "backup": {
+    "enabled": false,
+    "path": "data/backups",
+    "keep_days": 30
+  },
+  "nfo": {
+    "tmdb_api_key": "9bc3e547caff878615cbdba2cc421d37",
+    "auto_create": true,
+    "update_on_scan": true,
+    "download_poster": true,
+    "download_logo": true,
+    "download_fanart": true,
+    "image_size": "original"
+  },
+  "other": {
+    "master_password_hash": "$pbkdf2-sha256$29000$HQNASKk1xpgTAgAgJGRMaQ$73TOCCM0UEZONyNXQEPa3SmIoXeG6C1l5mMFDNgYfMQ",
+    "anime_directory": "/data"
+  },
+  "version": "1.0.0"
+}
+
+

docs/runner.csx

@@ -0,0 +1,154 @@
+#!/usr/bin/env dotnet-script
+#nullable enable
+
+using System;
+using System.IO;
+using System.Diagnostics;
+using System.Threading;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Linq;
+using System.Collections.Generic;
+
+// ── Ctrl+C: kill active process and exit cleanly ──────────────────────────────
+var cts = new CancellationTokenSource();
+Process? activeProcess = null;
+
+Console.CancelKeyPress += (_, e) =>
+{
+    e.Cancel = true;
+    Console.WriteLine("\n[runner] Interrupted — shutting down...");
+    cts.Cancel();
+    try { activeProcess?.Kill(entireProcessTree: true); } catch { }
+};
+
+// ── Paths ─────────────────────────────────────────────────────────────────────
+var repoRoot = Directory.GetCurrentDirectory();
+var tasksFile = Path.Combine(repoRoot, "Docs", "Tasks.md");
+
+if (!File.Exists(tasksFile))
+{
+    Console.Error.WriteLine($"[runner] ERROR: Tasks.md not found at {tasksFile}");
+    Console.Error.WriteLine("[runner] Run this script from the repository root.");
+    Environment.Exit(1);
+}
+
+// ── Read & split by "---" separator lines ────────────────────────────────────
+var content = File.ReadAllText(tasksFile);
+var items = Regex
+    .Split(content, @"\r?\n---\r?\n")
+    .Select(s => s.Trim())
+    .Where(s => s.Length > 0)
+    .ToList();
+
+Console.WriteLine($"[runner] Found {items.Count} section(s) in Tasks.md");
+
+// ── Helper: run copilot and stream output, return full output ─────────────────
+async Task<string> RunCopilot(IEnumerable<string> extraArgs, string prompt)
+{
+    var output = new StringBuilder();
+
+    var argList = new List<string> { "launch", "copilot", "--model", "minimax-m2.7:cloud", "--yes", "--", "--allow-all-tools" };
+    argList.AddRange(extraArgs);
+    argList.Add("-p");
+    argList.Add(prompt);
+
+    var psi = new ProcessStartInfo("ollama")
+    {
+        WorkingDirectory = repoRoot,
+        RedirectStandardOutput = true,
+        RedirectStandardError = true,
+        UseShellExecute = false,
+    };
+    foreach (var a in argList)
+        psi.ArgumentList.Add(a);
+
+    activeProcess = new Process { StartInfo = psi };
+
+    activeProcess.OutputDataReceived += (_, e) =>
+    {
+        if (e.Data is null) return;
+        Console.WriteLine(e.Data);
+        output.AppendLine(e.Data);
+    };
+    activeProcess.ErrorDataReceived += (_, e) =>
+    {
+        if (e.Data is null) return;
+        Console.Error.WriteLine(e.Data);
+        output.AppendLine(e.Data);
+    };
+
+    activeProcess.Start();
+    activeProcess.BeginOutputReadLine();
+    activeProcess.BeginErrorReadLine();
+
+    await activeProcess.WaitForExitAsync(cts.Token);
+    activeProcess = null;
+
+    return output.ToString();
+}
+
+// ── Main loop ─────────────────────────────────────────────────────────────────
+for (int i = 0; i < items.Count; i++)
+{
+    var item = items[i];
+    if (cts.IsCancellationRequested) break;
+
+    Console.WriteLine();
+    Console.WriteLine("[runner] ══════════════════════════════════════════════");
+    Console.WriteLine($"[runner] Task:\n{item}");
+    Console.WriteLine("[runner] ══════════════════════════════════════════════");
+    Console.WriteLine();
+
+    // Step 1 — run the task prompt
+    await RunCopilot(Enumerable.Empty<string>(), $"/caveman full");
+    await RunCopilot(new[] { "--continue" }, $"read ./Docs/instructions.md. {item}");
+    if (cts.IsCancellationRequested) break;
+
+    // Step 2 — confirm completion in the same chat session
+    Console.WriteLine("\n[runner] Asking for task confirmation...\n");
+    var confirmation = await RunCopilot(
+        new[] { "--continue" },
+        "are you sure tasks is done. reply with yes"
+    );
+    if (cts.IsCancellationRequested) break;
+
+    // Step 3 — check for "yes" in the reply, with retry logic for issue resolution
+    int maxRetries = 3;
+    int retryCount = 0;
+    bool taskConfirmed = confirmation.Contains("yes", StringComparison.OrdinalIgnoreCase);
+
+    while (!taskConfirmed && retryCount < maxRetries)
+    {
+        retryCount++;
+        Console.WriteLine($"\n[runner] Attempt {retryCount}/{maxRetries}: Resolving remaining issues and running tests...\n");
+
+        confirmation = await RunCopilot(
+            new[] { "--continue" },
+            "resolve any remaining issues, make sure all tests are running and pass. then confirm with yes if done"
+        );
+        if (cts.IsCancellationRequested) break;
+
+        taskConfirmed = confirmation.Contains("yes", StringComparison.OrdinalIgnoreCase);
+    }
+
+    if (!taskConfirmed)
+    {
+        Console.WriteLine($"\n[runner] Task not confirmed as done after {maxRetries} attempts. Stopping.");
+        break;
+    }
+
+    // Step 4 — commit the work
+    Console.WriteLine("\n[runner] Task confirmed. Making git commit...\n");
+
+    await RunCopilot(Enumerable.Empty<string>(), $"/caveman full");
+    await RunCopilot(new[] { "--continue" }, "make git commit");
+    if (cts.IsCancellationRequested) break;
+
+    // Step 5 — remove completed task from Tasks.md
+    var remaining = items.Skip(i + 1).ToList();
+    File.WriteAllText(tasksFile, string.Join("\n\n---\n\n", remaining));
+    Console.WriteLine("[runner] Removed completed task from Tasks.md");
+}
+
+Console.WriteLine("\n[runner] Finished.");

docs/tasks.md

@@ -0,0 +1,178 @@
+# Tasks
+
+## 1. Scheduled Folder Scan
+
+### Task 1.1: Add folder scan scheduler configuration
+
+**Where is that found**
+- `src/server/models/config.py` (`SchedulerConfig`)
+- `data/config.json` (example/default config)
+- `src/server/web/templates/setup.html` (setup UI)
+- `src/server/api/auth.py` (config save endpoint, if it validates scheduler fields)
+
+**Goal. How it should be**
+Add a new boolean field `folder_scan_enabled` (default `false`) to `SchedulerConfig`. When `true`, the scheduler will execute the folder maintenance routine during its scheduled run. Add the field to the setup page as a checkbox. Ensure existing configs without this field load successfully (Pydantic default handles this).
+
+**Possible traps and issues**
+- Backward compatibility: old `data/config.json` files must load without errors. Pydantic defaults solve this, but verify by loading an old config.
+- The setup page JavaScript must include the new field in the payload sent to `/api/config`.
+- Do not confuse this with `auto_download_after_rescan` — this is a separate toggle.
+
+**Docs changes needed**
+- `docs/CONFIGURATION.md`: Document the new `scheduler.folder_scan_enabled` option.
+- `docs/ARCHITECTURE.md`: Mention folder scan in the scheduler section.
+
+**Why this is needed**
+Users need an opt-in toggle to enable automatic daily folder maintenance (NFO repair, folder renaming, poster checks) without forcing it on everyone.
+
+---
+
+### Task 1.2: Create FolderScanService skeleton
+
+**Where is that found**
+- New file: `src/server/services/folder_scan_service.py`
+- `src/server/services/scheduler_service.py` (to call it)
+
+**Goal. How it should be**
+Create a new `FolderScanService` class with a single async entry point `async def run_folder_scan(self) -> None`. The method should:
+1. Log start/completion with structlog.
+2. Check prerequisites (`settings.anime_directory` exists, `settings.tmdb_api_key` is set).
+3. Skip gracefully with a warning log if prerequisites are missing.
+4. Use a module-level semaphore (similar to `_NFO_REPAIR_SEMAPHORE`) to limit concurrent TMDB operations to 3.
+
+Keep the implementation empty for the sub-tasks (1.3–1.5) to fill in. Just add the skeleton and the semaphore.
+
+**Possible traps and issues**
+- Circular imports: `folder_scan_service.py` will import from `initialization_service`, `config.settings`, etc. Keep imports inside methods or at the bottom if circular issues arise.
+- The service should follow the singleton pattern like `SchedulerService` and `DownloadService` if it holds state, or be stateless. For simplicity, make it a plain class instantiated per call or a module-level function set.
+- Exception handling: any unhandled exception in the scheduled task should be caught and logged so it doesn't crash the scheduler.
+
+**Docs changes needed**
+- `docs/ARCHITECTURE.md`: Add `folder_scan_service.py` to the services list.
+
+**Why this is needed**
+Encapsulates the new daily maintenance logic in its own module, keeping `scheduler_service.py` clean and allowing the folder scan to be tested independently.
+
+---
+
+### Task 1.3: Integrate NFO repair into folder scan
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/server/services/initialization_service.py` (`perform_nfo_repair_scan`)
+
+**Goal. How it should be**
+Inside `FolderScanService.run_folder_scan()`, call `perform_nfo_repair_scan(background_loader=None)` as the first step. Reuse the existing function exactly — do not copy its logic. Log a message before and after the call.
+
+**Possible traps and issues**
+- `perform_nfo_repair_scan` spawns `asyncio.create_task` for each repair. When called from the scheduler, these background tasks will still run after `run_folder_scan` returns. This is fine, but log that repairs are queued.
+- The function already handles missing `tmdb_api_key` and `anime_directory`, so the caller doesn't need to double-check, but the skeleton from Task 1.2 already checks prerequisites.
+- `perform_nfo_repair_scan` imports `nfo_needs_repair` and `NfoRepairService` inside the function, so no heavy import-time dependencies.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Update the "Automatic NFO Repair" section to state that repair now runs as part of the scheduled folder scan instead of every startup.
+
+**Why this is needed**
+Reuses the existing, tested NFO repair logic. Moves NFO repair from startup blocking to scheduled background maintenance.
+
+---
+
+### Task 1.4: Validate and rename series folders
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/core/services/nfo_repair_service.py` (for `parse_nfo_tags` or similar NFO parsing)
+- `src/server/database/models.py` / `src/server/database/system_settings_service.py` (if folder paths are stored in DB)
+
+**Goal. How it should be**
+After NFO repair, iterate over every subfolder in `settings.anime_directory` that contains a `tvshow.nfo`. For each folder:
+1. Parse the NFO to extract `<title>` and `<year>` text values.
+2. Compute the expected folder name: `f"{title} ({year})"`.
+3. Sanitize the expected name for filesystem safety (remove/replace illegal characters like `/`, `\`, `:`, etc.).
+4. Compare with the current folder name (`series_dir.name`).
+5. If different, rename the folder using `series_dir.rename(expected_path)`.
+6. If the series path is stored in the database (check `anime_service` or DB models), update the database record to point to the new path.
+
+Skip folders where title or year is missing/empty. Log every rename action.
+
+**Possible traps and issues**
+- **Database path consistency**: If `Series` or `Episode` models store absolute or relative paths, renaming the folder on disk without updating the DB will break downloads, NFO updates, and the web UI. Must verify whether paths are stored in the DB and update them.
+- **Active downloads**: A series currently being downloaded should not be renamed. Check the download queue or lock status before renaming. If no lock mechanism exists, this is a major trap — document it.
+- **Filesystem permissions**: The app may not have write permission to the anime directory. Catch `PermissionError` and `OSError` and log gracefully.
+- **Special characters**: Titles like `"A / B"` or `"Show: Subtitle"` contain characters illegal in folder names. Define a sanitization function (e.g., replace `/` with `-`, remove trailing dots on Windows, etc.).
+- **Duplicate names**: Two different series could sanitize to the same name. Check if target path already exists before renaming.
+- **Path length limits**: Very long titles might exceed OS path limits.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Add a section "Folder Naming Convention" explaining the `<title> (<year>)` format.
+- `docs/CONFIGURATION.md`: Mention that enabling folder scan will rename folders.
+
+**Why this is needed**
+Enforces a consistent, predictable folder naming scheme across the library, making it easier for media center apps (Kodi, Jellyfin, Plex) to match metadata.
+
+---
+
+### Task 1.5: Check and download missing poster.jpg
+
+**Where is that found**
+- `src/server/services/folder_scan_service.py`
+- `src/core/utils/image_downloader.py` (`ImageDownloader`)
+- `src/core/services/nfo_service.py` or `src/core/services/nfo_repair_service.py` (to get poster URL from NFO or TMDB)
+
+**Goal. How it should be**
+After folder renaming, iterate over series folders again (or combine with Task 1.4 loop). For each folder:
+1. Check if `poster.jpg` exists and has a size ≥ `ImageDownloader.min_file_size` (1 KB by default).
+2. If missing or too small:
+   a. Parse `tvshow.nfo` for `<thumb aspect="poster">` or `<thumb>` URL.
+   b. If no URL in NFO, skip (do not query TMDB again to keep tasks small; the NFO should already have it after repair).
+   c. Use `ImageDownloader` (with context manager) to download the image to `series_dir / "poster.jpg"`.
+   d. Validate the downloaded image with `ImageDownloader._validate_image` (or similar existing validation).
+3. Use the existing `_NFO_REPAIR_SEMAPHORE` or a new `POSTER_DOWNLOAD_SEMAPHORE` to limit concurrent downloads to 3.
+
+**Possible traps and issues**
+- **TMDB rate limiting**: Even downloading images hits TMDB CDN. The semaphore limits concurrency.
+- **Invalid images**: A download might produce a 0-byte or corrupted file. `ImageDownloader` already validates with PIL; reuse that.
+- **NFO without thumb URL**: If the NFO was created before thumb tags were added, there may be no URL. In that case, skip and log. A future task could query TMDB directly.
+- **Write permissions**: Same as Task 1.4.
+- **Async session sharing**: `ImageDownloader` manages its own `aiohttp` session. Use `async with ImageDownloader() as downloader:` to ensure cleanup.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Add "Poster Check" subsection under folder scan.
+- `docs/CONFIGURATION.md`: Mention that `nfo.download_poster` setting also affects scheduled poster checks.
+
+**Why this is needed**
+Ensures every series has artwork, which is required by most media center front-ends for a polished library view.
+
+---
+
+## 2. Remove startup NFO repair
+
+### Task 2.1: Remove perform_nfo_repair_scan from startup lifespan
+
+**Where is that found**
+- `src/server/fastapi_app.py` (lifespan startup block, lines ~245 and ~319)
+- `src/server/services/initialization_service.py` (keep the function, just remove the call site)
+- `tests/integration/test_nfo_repair_startup.py`
+- `tests/unit/test_initialization_service.py` (tests that call `perform_nfo_repair_scan` directly can stay, but integration tests verifying startup wiring must change)
+
+**Goal. How it should be**
+1. In `src/server/fastapi_app.py`, remove the import of `perform_nfo_repair_scan` from the `initialization_service` import block.
+2. Remove the line `await perform_nfo_repair_scan(background_loader)` from the lifespan startup sequence.
+3. Update `tests/integration/test_nfo_repair_startup.py`:
+   - Remove or modify `test_perform_nfo_repair_scan_imported_in_lifespan` and `test_perform_nfo_repair_scan_called_after_media_scan` since the startup wiring is gone.
+   - Replace with a test that verifies `perform_nfo_repair_scan` is NOT called during startup (or simply delete the file if it has no other purpose).
+4. `tests/unit/test_initialization_service.py` tests for `perform_nfo_repair_scan` can remain because they test the function itself, not the startup wiring.
+
+**Possible traps and issues**
+- **Test failures**: `test_nfo_repair_startup.py` will fail immediately after the code change. It must be updated in the same PR.
+- **Documentation drift**: `docs/NFO_GUIDE.md`, `docs/CHANGELOG.md`, and `docs/ARCHITECTURE.md` all describe the startup NFO repair behavior. If docs are not updated, users will expect repair on every start.
+- **Background loader parameter**: The `background_loader` variable was created partly for `perform_nfo_repair_scan`. After removal, check if `background_loader` is still needed for other startup steps (yes — `perform_media_scan_if_needed` uses it). Do not remove `background_loader` entirely.
+- **Import cleanup**: Ensure no unused imports remain in `fastapi_app.py` after removal.
+
+**Docs changes needed**
+- `docs/NFO_GUIDE.md`: Update section 11 "Automatic NFO Repair" to remove startup references and state it runs via scheduler.
+- `docs/CHANGELOG.md`: Add an entry under "Changed" or "Removed" noting that startup NFO repair is replaced by scheduled folder scan.
+- `docs/ARCHITECTURE.md`: Update the startup sequence description.
+
+**Why this is needed**
+Running `perform_nfo_repair_scan` on every startup slows down server restarts, especially for large libraries. Moving it to a scheduled task keeps startup fast while still ensuring regular maintenance.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aniworld-web",
-  "version": "1.0.0",
+  "version": "1.4.4",
   "description": "Aniworld Anime Download Manager - Web Frontend",
   "type": "module",
   "scripts": {

requirements.txt

@@ -18,4 +18,11 @@ aiosqlite>=0.19.0
 aiohttp>=3.9.0
 lxml>=5.0.0
 pillow>=10.0.0
-APScheduler>=3.10.4
+APScheduler>=3.10.4
+Events>=0.5
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+chardet>=5.2.0
+fake-useragent>=1.4.0
+yt-dlp>=2024.1.0
+urllib3>=2.0.0

src/cli/nfo_cli.py

@@ -1,61 +1,59 @@
 """CLI command for NFO management.
 
-This script provides command-line interface for creating, updating,
-and checking NFO metadata files.
+Note: NFO service has been removed. This CLI is no longer functional.
 """
 
-import asyncio
+import logging
 import sys
 from pathlib import Path
 
 # Add src to path
 sys.path.insert(0, str(Path(__file__).parent.parent.parent))
 
-from src.config.settings import settings
-from src.core.services.series_manager_service import SeriesManagerService
+logger = logging.getLogger(__name__)
 
 
 async def scan_and_create_nfo():
     """Scan all series and create missing NFO files."""
-    print("=" * 70)
-    print("NFO Auto-Creation Tool")
-    print("=" * 70)
-    
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Auto-Creation Tool")
+    logger.info("%s", "=" * 70)
+
     if not settings.tmdb_api_key:
-        print("\n❌ Error: TMDB_API_KEY not configured")
-        print("   Set TMDB_API_KEY in .env file or environment")
-        print("   Get API key from: https://www.themoviedb.org/settings/api")
+        logger.error("TMDB_API_KEY not configured")
+        logger.error("Set TMDB_API_KEY in .env file or environment")
+        logger.error("Get API key from: https://www.themoviedb.org/settings/api")
         return 1
     
     if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
+        logger.error("ANIME_DIRECTORY not configured")
         return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    print(f"Auto-create NFO: {settings.nfo_auto_create}")
-    print(f"Update on scan: {settings.nfo_update_on_scan}")
-    print(f"Download poster: {settings.nfo_download_poster}")
-    print(f"Download logo: {settings.nfo_download_logo}")
-    print(f"Download fanart: {settings.nfo_download_fanart}")
-    
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+    logger.info("Auto-create NFO: %s", settings.nfo_auto_create)
+    logger.info("Update on scan: %s", settings.nfo_update_on_scan)
+    logger.info("Download poster: %s", settings.nfo_download_poster)
+    logger.info("Download logo: %s", settings.nfo_download_logo)
+    logger.info("Download fanart: %s", settings.nfo_download_fanart)
+
     if not settings.nfo_auto_create:
-        print("\n⚠️  Warning: NFO_AUTO_CREATE is set to False")
-        print("   Enable it in .env to auto-create NFO files")
-        print("\n   Continuing anyway to demonstrate functionality...")
+        logger.warning("NFO_AUTO_CREATE is set to False")
+        logger.warning("Enable it in .env to auto-create NFO files")
+        logger.info("Continuing anyway to demonstrate functionality...")
         # Override for demonstration
         settings.nfo_auto_create = True
     
-    print("\nInitializing series manager...")
+    logger.info("Initializing series manager...")
     manager = SeriesManagerService.from_settings()
-    
+
     # Get series list first
     serie_list = manager.get_serie_list()
     all_series = serie_list.get_all()
-    
-    print(f"Found {len(all_series)} series in directory")
-    
+
+    logger.info("Found %d series in directory", len(all_series))
+
     if not all_series:
-        print("\n⚠️  No series found. Add some anime series first.")
+        logger.warning("No series found. Add some anime series first.")
         return 0
     
     # Show series without NFO
@@ -65,25 +63,25 @@ async def scan_and_create_nfo():
             series_without_nfo.append(serie)
     
     if series_without_nfo:
-        print(f"\nSeries without NFO: {len(series_without_nfo)}")
+        logger.info("Series without NFO: %d", len(series_without_nfo))
         for serie in series_without_nfo[:5]:  # Show first 5
-            print(f"  - {serie.name} ({serie.folder})")
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
         if len(series_without_nfo) > 5:
-            print(f"  ... and {len(series_without_nfo) - 5} more")
+            logger.info("... and %d more", len(series_without_nfo) - 5)
     else:
-        print("\n✅ All series already have NFO files!")
-        
+        logger.info("All series already have NFO files")
+
         if not settings.nfo_update_on_scan:
-            print("\nNothing to do. Enable NFO_UPDATE_ON_SCAN to update existing NFOs.")
+            logger.info("Nothing to do. Enable NFO_UPDATE_ON_SCAN to update existing NFOs.")
             return 0
     
-    print("\nProcessing NFO files...")
-    print("(This may take a while depending on the number of series)")
-    
+    logger.info("Processing NFO files...")
+    logger.info("This may take a while depending on the number of series")
+
     try:
         await manager.scan_and_process_nfo()
-        print("\n✅ NFO processing complete!")
-        
+        logger.info("NFO processing complete")
+
         # Show updated stats
         serie_list.load_series()  # Reload to get updated stats
         all_series = serie_list.get_all()
@@ -91,17 +89,17 @@ async def scan_and_create_nfo():
         series_with_poster = [s for s in all_series if s.has_poster()]
         series_with_logo = [s for s in all_series if s.has_logo()]
         series_with_fanart = [s for s in all_series if s.has_fanart()]
-        
-        print("\nFinal Statistics:")
-        print(f"  Series with NFO:    {len(series_with_nfo)}/{len(all_series)}")
-        print(f"  Series with poster: {len(series_with_poster)}/{len(all_series)}")
-        print(f"  Series with logo:   {len(series_with_logo)}/{len(all_series)}")
-        print(f"  Series with fanart: {len(series_with_fanart)}/{len(all_series)}")
-        
-    except Exception as e:
-        print(f"\n❌ Error: {e}")
-        import traceback
-        traceback.print_exc()
+
+        logger.info("Final statistics", extra={
+            "total_series": len(all_series),
+            "with_nfo": len(series_with_nfo),
+            "with_poster": len(series_with_poster),
+            "with_logo": len(series_with_logo),
+            "with_fanart": len(series_with_fanart),
+        })
+
+    except Exception:
+        logger.exception("Failed to process NFO files")
         return 1
     finally:
         await manager.close()
@@ -111,169 +109,95 @@ async def scan_and_create_nfo():
 
 async def check_nfo_status():
     """Check NFO status for all series."""
-    print("=" * 70)
-    print("NFO Status Check")
-    print("=" * 70)
-    
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Status Check")
+    logger.info("%s", "=" * 70)
+
     if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
+        logger.error("ANIME_DIRECTORY not configured")
         return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+
     # Create series list (no NFO service needed for status check)
-    from src.core.entities.SerieList import SerieList
+    from src.server.database.SerieList import SerieList
     serie_list = SerieList(settings.anime_directory)
     all_series = serie_list.get_all()
-    
+
     if not all_series:
-        print("\n⚠️  No series found")
+        logger.warning("No series found")
         return 0
-    
-    print(f"\nTotal series: {len(all_series)}")
-    
+
+    logger.info("Total series: %d", len(all_series))
+
     # Categorize series
     with_nfo = []
     without_nfo = []
-    
+
     for serie in all_series:
         if serie.has_nfo():
             with_nfo.append(serie)
         else:
             without_nfo.append(serie)
-    
-    print(f"\nWith NFO:    {len(with_nfo)} ({len(with_nfo) * 100 // len(all_series)}%)")
-    print(f"Without NFO: {len(without_nfo)} ({len(without_nfo) * 100 // len(all_series)}%)")
-    
+
+    logger.info(
+        "Series NFO coverage",
+        extra={
+            "with_nfo": len(with_nfo),
+            "without_nfo": len(without_nfo),
+            "total": len(all_series),
+        },
+    )
+
     if without_nfo:
-        print("\nSeries missing NFO:")
+        logger.info("Series missing NFO: %d", len(without_nfo))
         for serie in without_nfo[:10]:
-            print(f"  ❌ {serie.name} ({serie.folder})")
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
         if len(without_nfo) > 10:
-            print(f"  ... and {len(without_nfo) - 10} more")
-    
+            logger.info("... and %d more", len(without_nfo) - 10)
+
     # Media file statistics
     with_poster = sum(1 for s in all_series if s.has_poster())
     with_logo = sum(1 for s in all_series if s.has_logo())
     with_fanart = sum(1 for s in all_series if s.has_fanart())
-    
-    print("\nMedia Files:")
-    print(f"  Posters: {with_poster}/{len(all_series)} ({with_poster * 100 // len(all_series)}%)")
-    print(f"  Logos:   {with_logo}/{len(all_series)} ({with_logo * 100 // len(all_series)}%)")
-    print(f"  Fanart:  {with_fanart}/{len(all_series)} ({with_fanart * 100 // len(all_series)}%)")
-    
-    return 0
 
+    logger.info(
+        "Media file coverage",
+        extra={
+            "posters": with_poster,
+            "logos": with_logo,
+            "fanart": with_fanart,
+            "total": len(all_series),
+        },
+    )
 
-async def update_nfo_files():
-    """Update existing NFO files with fresh data from TMDB."""
-    print("=" * 70)
-    print("NFO Update Tool")
-    print("=" * 70)
-    
-    if not settings.tmdb_api_key:
-        print("\n❌ Error: TMDB_API_KEY not configured")
-        print("   Set TMDB_API_KEY in .env file or environment")
-        print("   Get API key from: https://www.themoviedb.org/settings/api")
-        return 1
-    
-    if not settings.anime_directory:
-        print("\n❌ Error: ANIME_DIRECTORY not configured")
-        return 1
-    
-    print(f"\nAnime Directory: {settings.anime_directory}")
-    print(f"Download media: {settings.nfo_download_poster or settings.nfo_download_logo or settings.nfo_download_fanart}")
-    
-    # Get series with NFO
-    from src.core.entities.SerieList import SerieList
-    serie_list = SerieList(settings.anime_directory)
-    all_series = serie_list.get_all()
-    series_with_nfo = [s for s in all_series if s.has_nfo()]
-    
-    if not series_with_nfo:
-        print("\n⚠️  No series with NFO files found")
-        print("   Run 'scan' command first to create NFO files")
-        return 0
-    
-    print(f"\nFound {len(series_with_nfo)} series with NFO files")
-    print("Updating NFO files with fresh data from TMDB...")
-    print("(This may take a while)")
-    
-    # Initialize NFO service using factory
-    from src.core.services.nfo_factory import create_nfo_service
-    try:
-        nfo_service = create_nfo_service()
-    except ValueError as e:
-        print(f"\nError: {e}")
-        return 1
-    
-    success_count = 0
-    error_count = 0
-    
-    try:
-        for i, serie in enumerate(series_with_nfo, 1):
-            print(f"\n[{i}/{len(series_with_nfo)}] Updating: {serie.name}")
-            
-            try:
-                await nfo_service.update_tvshow_nfo(
-                    serie_folder=serie.folder,
-                    download_media=(
-                        settings.nfo_download_poster or 
-                        settings.nfo_download_logo or 
-                        settings.nfo_download_fanart
-                    )
-                )
-                print(f"  ✅ Updated successfully")
-                success_count += 1
-                
-                # Small delay to respect API rate limits
-                await asyncio.sleep(0.5)
-                
-            except Exception as e:
-                print(f"  ❌ Error: {e}")
-                error_count += 1
-        
-        print("\n" + "=" * 70)
-        print(f"✅ Update complete!")
-        print(f"  Success: {success_count}")
-        print(f"  Errors:  {error_count}")
-        
-    except Exception as e:
-        print(f"\n❌ Fatal error: {e}")
-        import traceback
-        traceback.print_exc()
-        return 1
-    finally:
-        await nfo_service.close()
-    
     return 0
 
 
 def main():
     """Main CLI entry point."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
     if len(sys.argv) < 2:
-        print("NFO Management Tool")
-        print("\nUsage:")
-        print("  python -m src.cli.nfo_cli scan     # Scan and create missing NFO files")
-        print("  python -m src.cli.nfo_cli status   # Check NFO status for all series")
-        print("  python -m src.cli.nfo_cli update   # Update existing NFO files with fresh data")
-        print("\nConfiguration:")
-        print("  Set TMDB_API_KEY in .env file")
-        print("  Set NFO_AUTO_CREATE=true to enable auto-creation")
-        print("  Set NFO_UPDATE_ON_SCAN=true to update existing NFOs during scan")
+        logger.info("NFO Management Tool")
+        logger.info("\nUsage:")
+        logger.info("  python -m src.cli.nfo_cli scan     # Scan and create missing NFO files")
+        logger.info("  python -m src.cli.nfo_cli status   # Check NFO status for all series")
+        logger.info("\nConfiguration:")
+        logger.info("  Set TMDB_API_KEY in .env file")
+        logger.info("  Set NFO_AUTO_CREATE=true to enable auto-creation")
+        logger.info("  Set NFO_UPDATE_ON_SCAN=true to update existing NFOs during scan")
         return 1
-    
+
     command = sys.argv[1].lower()
-    
+
     if command == "scan":
         return asyncio.run(scan_and_create_nfo())
     elif command == "status":
         return asyncio.run(check_nfo_status())
-    elif command == "update":
-        return asyncio.run(update_nfo_files())
     else:
-        print(f"Unknown command: {command}")
-        print("Use 'scan', 'status', or 'update'")
+        logger.error("Unknown command: %s", command)
+        logger.info("Use 'scan' or 'status'")
         return 1
 
 

src/config/settings.py

@@ -1,3 +1,4 @@
+import re
 import secrets
 from typing import Optional
 
@@ -114,6 +115,40 @@ class Settings(BaseSettings):
         validation_alias="NFO_PREFER_FSK_RATING",
         description="Prefer German FSK rating over MPAA rating in NFO files"
     )
+    nfo_folder_ignore_patterns: str = Field(
+        default="The Last of Us|Loki|Chernobyl|Star Trek Discovery|Marvel|Matrix|Fast & Furious|Jurassic|James Bond|Mission: Impossible|Bourne|Hunger Games|Die Hard|John Wick|Pacific Rim|Guardians of the Galaxy|Avengers|Batman|Superman|Wonder Woman|Spider-Man|X-Men|Fantastic Four|Terminator|Predator|Rambo|Rocky|Expendables|Tomb Raider|Jumanji|Jurassic Park|Pirates of the Caribbean|Harry Potter|Lord of the Rings|Hobbit|Game of Thrones|Westworld|Stranger Things|Breaking Bad|Better Call Saul|Sherlock|Downton Abbey|The Crown|Bridgerton|Sex Education|Normal People|Emily in Paris|The Witcher|Servant|Lucifer|Dark|Shadow and Bone|Grimm|Fairytale",
+        validation_alias="NFO_FOLDER_IGNORE_PATTERNS",
+        description="Regex patterns for folder names to skip during scan (pipe-separated)"
+    )
+
+    @property
+    def folder_ignore_patterns(self) -> list[str]:
+        """Parse ignore patterns from comma-separated string into list.
+
+        Returns:
+            List of regex patterns to skip during folder scanning.
+        """
+        if not self.nfo_folder_ignore_patterns:
+            return []
+        return [
+            pattern.strip()
+            for pattern in self.nfo_folder_ignore_patterns.split("|")
+            if pattern.strip()
+        ]
+
+    def should_ignore_folder(self, folder_name: str) -> bool:
+        """Check if folder should be ignored based on ignore patterns.
+
+        Args:
+            folder_name: Name of folder to check.
+
+        Returns:
+            True if folder matches any ignore pattern, False otherwise.
+        """
+        for pattern in self.folder_ignore_patterns:
+            if re.search(pattern, folder_name, re.IGNORECASE):
+                return True
+        return False
 
     @property
     def allowed_origins(self) -> list[str]:
@@ -134,5 +169,23 @@ class Settings(BaseSettings):
             ]
         return [origin.strip() for origin in raw.split(",") if origin.strip()]
 
+    @property
+    def scan_key_overrides(self) -> dict[str, str]:
+        """Return scan key overrides from config.json.
+        
+        Maps folder names to provider keys for cases where auto-generated
+        keys from folder names are incorrect.
+        
+        Returns:
+            Dict mapping folder names to provider keys.
+        """
+        from src.server.services.config_service import ConfigService
+        try:
+            config_service = ConfigService()
+            config = config_service.load_config()
+            return config.scan_key_overrides or {}
+        except Exception:
+            return {}
+
 
 settings = Settings()

src/core/entities/SerieList.py

@@ -1,320 +0,0 @@
-"""Utilities for loading and managing stored anime series metadata.
-
-This module provides the SerieList class for managing collections of anime
-series metadata. It uses file-based storage only.
-
-Note:
-    This module is part of the core domain layer and has no database
-    dependencies. All database operations are handled by the service layer.
-"""
-
-from __future__ import annotations
-
-import logging
-import os
-import warnings
-from json import JSONDecodeError
-from typing import Dict, Iterable, List, Optional
-
-from src.core.entities.series import Serie
-
-logger = logging.getLogger(__name__)
-
-
-class SerieList:
-    """
-    Represents the collection of cached series stored on disk.
-    
-    Series are identified by their unique 'key' (provider identifier).
-    The 'folder' is metadata only and not used for lookups.
-    
-    This class manages in-memory series data loaded from filesystem.
-    It has no database dependencies - all persistence is handled by
-    the service layer.
-    
-    Example:
-        # File-based mode
-        serie_list = SerieList("/path/to/anime")
-        series = serie_list.get_all()
-    
-    Attributes:
-        directory: Path to the anime directory
-        keyDict: Internal dictionary mapping serie.key to Serie objects
-    """
-
-    def __init__(
-        self,
-        base_path: str,
-        skip_load: bool = False
-    ) -> None:
-        """Initialize the SerieList.
-        
-        Args:
-            base_path: Path to the anime directory
-            skip_load: If True, skip automatic loading of series from files.
-                Useful when planning to load from database instead.
-        """
-        self.directory: str = base_path
-        # Internal storage using serie.key as the dictionary key
-        self.keyDict: Dict[str, Serie] = {}
-        
-        # Only auto-load from files if not skipping
-        if not skip_load:
-            self.load_series()
-
-    def add(self, serie: Serie, use_sanitized_folder: bool = True) -> str:
-        """
-        Persist a new series if it is not already present (file-based mode).
-        
-        Uses serie.key for identification. Creates the filesystem folder
-        using either the sanitized display name (default) or the existing
-        folder property.
-        
-        Args:
-            serie: The Serie instance to add
-            use_sanitized_folder: If True (default), use serie.sanitized_folder
-                for the filesystem folder name based on display name.
-                If False, use serie.folder as-is for backward compatibility.
-        
-        Returns:
-            str: The folder path that was created/used
-        
-        Note:
-            This method creates data files on disk. For database storage,
-            use add_to_db() instead.
-        """
-        if self.contains(serie.key):
-            # Return existing folder path
-            existing = self.keyDict[serie.key]
-            return os.path.join(self.directory, existing.folder)
-
-        # Determine folder name to use
-        if use_sanitized_folder:
-            folder_name = serie.sanitized_folder
-            # Update the serie's folder property to match what we create
-            serie.folder = folder_name
-        else:
-            folder_name = serie.folder
-
-        data_path = os.path.join(self.directory, folder_name, "data")
-        anime_path = os.path.join(self.directory, folder_name)
-        os.makedirs(anime_path, exist_ok=True)
-        if not os.path.isfile(data_path):
-            serie.save_to_file(data_path)
-            # Store by key, not folder
-            self.keyDict[serie.key] = serie
-        
-        return anime_path
-
-    def contains(self, key: str) -> bool:
-        """
-        Return True when a series identified by ``key`` already exists.
-        
-        Args:
-            key: The unique provider identifier for the series
-            
-        Returns:
-            True if the series exists in the collection
-        """
-        return key in self.keyDict
-
-    def load_series(self) -> None:
-        """Populate the in-memory map with metadata discovered on disk."""
-
-        logging.info("Scanning anime folders in %s", self.directory)
-        try:
-            entries: Iterable[str] = os.listdir(self.directory)
-        except OSError as error:
-            logging.error(
-                "Unable to scan directory %s: %s",
-                self.directory,
-                error,
-            )
-            return
-
-        nfo_stats = {"total": 0, "with_nfo": 0, "without_nfo": 0}
-        media_stats = {
-            "with_poster": 0,
-            "without_poster": 0,
-            "with_logo": 0,
-            "without_logo": 0,
-            "with_fanart": 0,
-            "without_fanart": 0
-        }
-
-        for anime_folder in entries:
-            anime_path = os.path.join(self.directory, anime_folder, "data")
-            if os.path.isfile(anime_path):
-                logging.debug("Found data file for folder %s", anime_folder)
-                serie = self._load_data(anime_folder, anime_path)
-                
-                if serie:
-                    nfo_stats["total"] += 1
-                    # Check for NFO file
-                    nfo_file_path = os.path.join(
-                        self.directory, anime_folder, "tvshow.nfo"
-                    )
-                    if os.path.isfile(nfo_file_path):
-                        serie.nfo_path = nfo_file_path
-                        nfo_stats["with_nfo"] += 1
-                    else:
-                        nfo_stats["without_nfo"] += 1
-                        logging.debug(
-                            "Series '%s' (key: %s) is missing tvshow.nfo",
-                            serie.name,
-                            serie.key
-                        )
-                    
-                    # Check for media files
-                    folder_path = os.path.join(self.directory, anime_folder)
-                    
-                    poster_path = os.path.join(folder_path, "poster.jpg")
-                    if os.path.isfile(poster_path):
-                        media_stats["with_poster"] += 1
-                    else:
-                        media_stats["without_poster"] += 1
-                        logging.debug(
-                            "Series '%s' (key: %s) is missing poster.jpg",
-                            serie.name,
-                            serie.key
-                        )
-                    
-                    logo_path = os.path.join(folder_path, "logo.png")
-                    if os.path.isfile(logo_path):
-                        media_stats["with_logo"] += 1
-                    else:
-                        media_stats["without_logo"] += 1
-                        logging.debug(
-                            "Series '%s' (key: %s) is missing logo.png",
-                            serie.name,
-                            serie.key
-                        )
-                    
-                    fanart_path = os.path.join(folder_path, "fanart.jpg")
-                    if os.path.isfile(fanart_path):
-                        media_stats["with_fanart"] += 1
-                    else:
-                        media_stats["without_fanart"] += 1
-                        logging.debug(
-                            "Series '%s' (key: %s) is missing fanart.jpg",
-                            serie.name,
-                            serie.key
-                        )
-                
-                continue
-
-            logging.warning(
-                "Skipping folder %s because no metadata file was found",
-                anime_folder,
-            )
-        
-        # Log summary statistics
-        if nfo_stats["total"] > 0:
-            logging.info(
-                "NFO scan complete: %d series total, %d with NFO, %d without NFO",
-                nfo_stats["total"],
-                nfo_stats["with_nfo"],
-                nfo_stats["without_nfo"]
-            )
-            logging.info(
-                "Media scan complete: Poster (%d/%d), Logo (%d/%d), Fanart (%d/%d)",
-                media_stats["with_poster"],
-                nfo_stats["total"],
-                media_stats["with_logo"],
-                nfo_stats["total"],
-                media_stats["with_fanart"],
-                nfo_stats["total"]
-            )
-
-    def _load_data(self, anime_folder: str, data_path: str) -> Optional[Serie]:
-        """
-        Load a single series metadata file into the in-memory collection.
-        
-        Args:
-            anime_folder: The folder name (for logging only)
-            data_path: Path to the metadata file
-            
-        Returns:
-            Serie: The loaded Serie object, or None if loading failed
-        """
-        try:
-            serie = Serie.load_from_file(data_path)
-            # Store by key, not folder
-            self.keyDict[serie.key] = serie
-            logging.debug(
-                "Successfully loaded metadata for %s (key: %s)",
-                anime_folder,
-                serie.key
-            )
-            return serie
-        except (OSError, JSONDecodeError, KeyError, ValueError) as error:
-            logging.error(
-                "Failed to load metadata for folder %s from %s: %s",
-                anime_folder,
-                data_path,
-                error,
-            )
-            return None
-
-    def GetMissingEpisode(self) -> List[Serie]:
-        """Return all series that still contain missing episodes."""
-        return [
-            serie
-            for serie in self.keyDict.values()
-            if serie.episodeDict
-        ]
-
-    def get_missing_episodes(self) -> List[Serie]:
-        """PEP8-friendly alias for :meth:`GetMissingEpisode`."""
-        return self.GetMissingEpisode()
-
-    def GetList(self) -> List[Serie]:
-        """Return all series instances stored in the list."""
-        return list(self.keyDict.values())
-
-    def get_all(self) -> List[Serie]:
-        """PEP8-friendly alias for :meth:`GetList`."""
-        return self.GetList()
-    
-    def get_by_key(self, key: str) -> Optional[Serie]:
-        """
-        Get a series by its unique provider key.
-        
-        This is the primary method for series lookup.
-        
-        Args:
-            key: The unique provider identifier (e.g., "attack-on-titan")
-            
-        Returns:
-            The Serie instance if found, None otherwise
-        """
-        return self.keyDict.get(key)
-    
-    def get_by_folder(self, folder: str) -> Optional[Serie]:
-        """
-        Get a series by its folder name.
-        
-        .. deprecated:: 2.0.0
-            Use :meth:`get_by_key` instead. Folder-based lookups will be
-            removed in version 3.0.0. The `folder` field is metadata only
-            and should not be used for identification.
-        
-        This method is provided for backward compatibility only.
-        Prefer using get_by_key() for new code.
-        
-        Args:
-            folder: The filesystem folder name (e.g., "Attack on Titan (2013)")
-            
-        Returns:
-            The Serie instance if found, None otherwise
-        """
-        warnings.warn(
-            "get_by_folder() is deprecated and will be removed in v3.0.0. "
-            "Use get_by_key() instead. The 'folder' field is metadata only.",
-            DeprecationWarning,
-            stacklevel=2
-        )
-        for serie in self.keyDict.values():
-            if serie.folder == folder:
-                return serie
-        return None

src/core/entities/series.py

@@ -1,400 +0,0 @@
-import json
-import logging
-import os
-import warnings
-from pathlib import Path
-from typing import Optional
-
-from src.server.utils.filesystem import sanitize_folder_name
-
-logger = logging.getLogger(__name__)
-
-
-class Serie:
-    """
-    Represents an anime series with metadata and episode information.
-    
-    The `key` property is the unique identifier for the series
-    (provider-assigned, URL-safe).
-    The `folder` property is the filesystem folder name
-    (metadata only, not used for lookups).
-    
-    Args:
-        key: Unique series identifier from provider
-            (e.g., "attack-on-titan"). Cannot be empty.
-        name: Display name of the series
-        site: Provider site URL
-        folder: Filesystem folder name (metadata only,
-            e.g., "Attack on Titan (2013)")
-        episodeDict: Dictionary mapping season numbers to
-            lists of episode numbers
-        year: Release year of the series (optional)
-        
-    Raises:
-        ValueError: If key is None or empty string
-    """
-    
-    def __init__(
-        self,
-        key: str,
-        name: str,
-        site: str,
-        folder: str,
-        episodeDict: dict[int, list[int]],
-        year: int | None = None,
-        nfo_path: Optional[str] = None
-    ):
-        if not key or not key.strip():
-            raise ValueError("Serie key cannot be None or empty")
-        
-        self._key = key.strip()
-        self._name = name
-        self._site = site
-        self._folder = folder
-        self._episodeDict = episodeDict
-        self._year = year
-        self._nfo_path = nfo_path
-        
-    def __str__(self):
-        """String representation of Serie object"""
-        year_str = f", year={self.year}" if self.year else ""
-        return (
-            f"Serie(key='{self.key}', name='{self.name}', "
-            f"site='{self.site}', folder='{self.folder}', "
-            f"episodeDict={self.episodeDict}{year_str})"
-        )
-
-    @property
-    def key(self) -> str:
-        """
-        Unique series identifier (primary identifier for all lookups).
-        
-        This is the provider-assigned, URL-safe identifier used
-        throughout the application for series identification,
-        lookups, and operations.
-        
-        Returns:
-            str: The unique series key
-        """
-        return self._key
-
-    @key.setter
-    def key(self, value: str):
-        """
-        Set the unique series identifier.
-        
-        Args:
-            value: New key value
-            
-        Raises:
-            ValueError: If value is None or empty string
-        """
-        if not value or not value.strip():
-            raise ValueError("Serie key cannot be None or empty")
-        self._key = value.strip()
-
-    @property
-    def name(self) -> str:
-        return self._name
-
-    @name.setter
-    def name(self, value: str):
-        self._name = value
-
-    @property
-    def site(self) -> str:
-        return self._site
-
-    @site.setter
-    def site(self, value: str):
-        self._site = value
-
-    @property
-    def folder(self) -> str:
-        """
-        Filesystem folder name (metadata only, not used for lookups).
-        
-        This property contains the local directory name where the series
-        files are stored. It should NOT be used as an identifier for
-        series lookups - use `key` instead.
-        
-        Returns:
-            str: The filesystem folder name
-        """
-        return self._folder
-
-    @folder.setter
-    def folder(self, value: str):
-        """
-        Set the filesystem folder name.
-        
-        Args:
-            value: Folder name for the series
-        """
-        self._folder = value
-
-    @property
-    def episodeDict(self) -> dict[int, list[int]]:
-        return self._episodeDict
-
-    @episodeDict.setter
-    def episodeDict(self, value: dict[int, list[int]]):
-        self._episodeDict = value
-
-    @property
-    def year(self) -> int | None:
-        """
-        Release year of the series.
-        
-        Returns:
-            int or None: The year the series was released, or None if unknown
-        """
-        return self._year
-
-    @year.setter
-    def year(self, value: int | None):
-        """Set the release year of the series."""
-        self._year = value
-
-    @property
-    def nfo_path(self) -> Optional[str]:
-        """
-        Path to the tvshow.nfo metadata file.
-        
-        Returns:
-            str or None: Path to the NFO file, or None if not set
-        """
-        return self._nfo_path
-
-    @nfo_path.setter
-    def nfo_path(self, value: Optional[str]):
-        """Set the path to the NFO file."""
-        self._nfo_path = value
-
-    def has_nfo(self, base_directory: Optional[str] = None) -> bool:
-        """
-        Check if tvshow.nfo file exists for this series.
-        
-        Args:
-            base_directory: Base anime directory path. If provided, checks
-                relative to base_directory/folder/tvshow.nfo. If not provided,
-                uses nfo_path directly.
-        
-        Returns:
-            bool: True if tvshow.nfo exists, False otherwise
-        """
-        if base_directory:
-            nfo_file = Path(base_directory) / self.folder / "tvshow.nfo"
-        elif self._nfo_path:
-            nfo_file = Path(self._nfo_path)
-        else:
-            return False
-        
-        return nfo_file.exists() and nfo_file.is_file()
-
-    def has_poster(self, base_directory: Optional[str] = None) -> bool:
-        """
-        Check if poster.jpg file exists for this series.
-        
-        Args:
-            base_directory: Base anime directory path. If provided, checks
-                relative to base_directory/folder/poster.jpg.
-        
-        Returns:
-            bool: True if poster.jpg exists, False otherwise
-        """
-        if not base_directory:
-            return False
-        
-        poster_file = Path(base_directory) / self.folder / "poster.jpg"
-        return poster_file.exists() and poster_file.is_file()
-
-    def has_logo(self, base_directory: Optional[str] = None) -> bool:
-        """
-        Check if logo.png file exists for this series.
-        
-        Args:
-            base_directory: Base anime directory path. If provided, checks
-                relative to base_directory/folder/logo.png.
-        
-        Returns:
-            bool: True if logo.png exists, False otherwise
-        """
-        if not base_directory:
-            return False
-        
-        logo_file = Path(base_directory) / self.folder / "logo.png"
-        return logo_file.exists() and logo_file.is_file()
-
-    def has_fanart(self, base_directory: Optional[str] = None) -> bool:
-        """
-        Check if fanart.jpg file exists for this series.
-        
-        Args:
-            base_directory: Base anime directory path. If provided, checks
-                relative to base_directory/folder/fanart.jpg.
-        
-        Returns:
-            bool: True if fanart.jpg exists, False otherwise
-        """
-        if not base_directory:
-            return False
-        
-        fanart_file = Path(base_directory) / self.folder / "fanart.jpg"
-        return fanart_file.exists() and fanart_file.is_file()
-
-    @property
-    def name_with_year(self) -> str:
-        """
-        Get the series name with year appended if available.
-        
-        Returns a name in the format "Name (Year)" if year is available,
-        otherwise returns just the name. This should be used for creating
-        filesystem folders to distinguish series with the same name.
-        
-        Returns:
-            str: Name with year in format "Name (Year)", or just name if no year
-            
-        Example:
-            >>> serie = Serie("dororo", "Dororo", ..., year=2025)
-            >>> serie.name_with_year
-            'Dororo (2025)'
-        """
-        if self._year:
-            return f"{self._name} ({self._year})"
-        return self._name
-
-    @property
-    def sanitized_folder(self) -> str:
-        """
-        Get a filesystem-safe folder name derived from the display name with year.
-        
-        This property returns a sanitized version of the series name with year
-        (if available) suitable for use as a filesystem folder name. It removes/
-        replaces characters that are invalid for filesystems while preserving
-        Unicode characters.
-        
-        Use this property when creating folders for the series on disk.
-        The `folder` property stores the actual folder name used.
-        
-        Returns:
-            str: Filesystem-safe folder name based on display name with year
-            
-        Example:
-            >>> serie = Serie("attack-on-titan", "Attack on Titan: Final", ..., year=2025)
-            >>> serie.sanitized_folder
-            'Attack on Titan Final (2025)'
-        """
-        # Use name_with_year if available, fall back to folder, then key
-        name_to_sanitize = self.name_with_year or self._folder or self._key
-        try:
-            return sanitize_folder_name(name_to_sanitize)
-        except ValueError:
-            # Fallback to key if name cannot be sanitized
-            return sanitize_folder_name(self._key)
-
-    def ensure_folder_with_year(self) -> str:
-        """Ensure folder name includes year if available.
-        
-        If the serie has a year and the current folder name doesn't include it,
-        updates the folder name to include the year in format "Name (Year)".
-        
-        This method should be called before creating folders or NFO files to
-        ensure consistent naming across the application.
-        
-        Returns:
-            str: The folder name (updated if needed)
-            
-        Example:
-            >>> serie = Serie("perfect-blue", "Perfect Blue", ..., folder="Perfect Blue", year=1997)
-            >>> serie.ensure_folder_with_year()
-            'Perfect Blue (1997)'
-            >>> serie.folder  # folder property is updated
-            'Perfect Blue (1997)'
-        """
-        if self._year:
-            # Check if folder already has year format
-            year_pattern = f"({self._year})"
-            if year_pattern not in self._folder:
-                # Update folder to include year
-                self._folder = self.sanitized_folder
-                logger.info(
-                    f"Updated folder name for '{self._key}' to include year: {self._folder}"
-                )
-        return self._folder
-
-    def to_dict(self):
-        """Convert Serie object to dictionary for JSON serialization."""
-        return {
-            "key": self.key,
-            "name": self.name,
-            "site": self.site,
-            "folder": self.folder,
-            "episodeDict": {
-                str(k): list(v) for k, v in self.episodeDict.items()
-            },
-            "year": self.year,
-            "nfo_path": self.nfo_path
-        }
-
-    @staticmethod
-    def from_dict(data: dict):
-        """Create a Serie object from dictionary."""
-        # Convert keys to int
-        episode_dict = {
-            int(k): v for k, v in data["episodeDict"].items()
-        }
-        return Serie(
-            data["key"],
-            data["name"],
-            data["site"],
-            data["folder"],
-            episode_dict,
-            data.get("year"),  # Optional year field for backward compatibility
-            data.get("nfo_path")  # Optional nfo_path field
-        )
-
-    def save_to_file(self, filename: str):
-        """Save Serie object to JSON file.
-        
-        .. deprecated::
-            File-based storage is deprecated. Use database storage via
-            `AnimeSeriesService.create()` instead. This method will be
-            removed in v3.0.0.
-            
-        Args:
-            filename: Path to save the JSON file
-        """
-        warnings.warn(
-            "save_to_file() is deprecated and will be removed in v3.0.0. "
-            "Use database storage via AnimeSeriesService.create() instead.",
-            DeprecationWarning,
-            stacklevel=2
-        )
-        with open(filename, "w", encoding="utf-8") as file:
-            json.dump(self.to_dict(), file, indent=4)
-
-    @classmethod
-    def load_from_file(cls, filename: str) -> "Serie":
-        """Load Serie object from JSON file.
-        
-        .. deprecated::
-            File-based storage is deprecated. Use database storage via
-            `AnimeSeriesService.get_by_key()` instead. This method will be
-            removed in v3.0.0.
-            
-        Args:
-            filename: Path to load the JSON file from
-            
-        Returns:
-            Serie: The loaded Serie object
-        """
-        warnings.warn(
-            "load_from_file() is deprecated and will be removed in v3.0.0. "
-            "Use database storage via AnimeSeriesService instead.",
-            DeprecationWarning,
-            stacklevel=2
-        )
-        with open(filename, "r", encoding="utf-8") as file:
-            data = json.load(file)
-        return cls.from_dict(data)

src/core/error_handler.py

@@ -1,149 +0,0 @@
-"""
-Error handling and recovery strategies for core providers.
-
-This module provides custom exceptions and decorators for handling
-errors in provider operations with automatic retry mechanisms.
-"""
-
-import functools
-import logging
-from typing import Any, Callable, TypeVar
-
-logger = logging.getLogger(__name__)
-
-# Type variable for decorator
-F = TypeVar("F", bound=Callable[..., Any])
-
-
-class RetryableError(Exception):
-    """Exception that indicates an operation can be safely retried."""
-
-    pass
-
-
-class NonRetryableError(Exception):
-    """Exception that indicates an operation should not be retried."""
-
-    pass
-
-
-class NetworkError(Exception):
-    """Exception for network-related errors."""
-
-    pass
-
-
-class DownloadError(Exception):
-    """Exception for download-related errors."""
-
-    pass
-
-
-class RecoveryStrategies:
-    """Strategies for handling errors and recovering from failures."""
-
-    @staticmethod
-    def handle_network_failure(
-        func: Callable, *args: Any, **kwargs: Any
-    ) -> Any:
-        """Handle network failures with basic retry logic."""
-        max_retries = 3
-        for attempt in range(max_retries):
-            try:
-                return func(*args, **kwargs)
-            except (NetworkError, ConnectionError):
-                if attempt == max_retries - 1:
-                    raise
-                logger.warning(
-                    f"Network error on attempt {attempt + 1}, retrying..."
-                )
-                continue
-
-    @staticmethod
-    def handle_download_failure(
-        func: Callable, *args: Any, **kwargs: Any
-    ) -> Any:
-        """Handle download failures with retry logic."""
-        max_retries = 2
-        for attempt in range(max_retries):
-            try:
-                return func(*args, **kwargs)
-            except DownloadError:
-                if attempt == max_retries - 1:
-                    raise
-                logger.warning(
-                    f"Download error on attempt {attempt + 1}, retrying..."
-                )
-                continue
-
-
-class FileCorruptionDetector:
-    """Detector for corrupted files."""
-
-    @staticmethod
-    def is_valid_video_file(filepath: str) -> bool:
-        """Check if a video file is valid and not corrupted."""
-        try:
-            import os
-            if not os.path.exists(filepath):
-                return False
-            
-            file_size = os.path.getsize(filepath)
-            # Video files should be at least 1MB
-            return file_size > 1024 * 1024
-        except Exception as e:
-            logger.error(f"Error checking file validity: {e}")
-            return False
-
-
-def with_error_recovery(
-    max_retries: int = 3, context: str = ""
-) -> Callable[[F], F]:
-    """
-    Decorator for adding error recovery to functions.
-    
-    Args:
-        max_retries: Maximum number of retry attempts
-        context: Context string for logging
-        
-    Returns:
-        Decorated function with retry logic
-    """
-
-    def decorator(func: F) -> F:
-        @functools.wraps(func)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
-            last_error = None
-            for attempt in range(max_retries):
-                try:
-                    return func(*args, **kwargs)
-                except NonRetryableError:
-                    raise
-                except Exception as e:
-                    last_error = e
-                    if attempt < max_retries - 1:
-                        logger.warning(
-                            f"Error in {context} (attempt {attempt + 1}/"
-                            f"{max_retries}): {e}, retrying..."
-                        )
-                    else:
-                        logger.error(
-                            f"Error in {context} failed after {max_retries} "
-                            f"attempts: {e}"
-                        )
-
-            if last_error:
-                raise last_error
-            
-            raise RuntimeError(
-                f"Unexpected error in {context} after {max_retries} attempts"
-            )
-
-        return wrapper  # type: ignore
-
-    return decorator
-
-
-# Create module-level instances for use in provider code
-recovery_strategies = RecoveryStrategies()
-file_corruption_detector = FileCorruptionDetector()

src/core/providers/aniworld_provider.py

@@ -1,694 +0,0 @@
-
-import html
-import json
-import logging
-import os
-import re
-import shutil
-import threading
-from pathlib import Path
-from urllib.parse import quote
-
-import requests
-from bs4 import BeautifulSoup
-from events import Events
-from fake_useragent import UserAgent
-from requests.adapters import HTTPAdapter
-from urllib3.util.retry import Retry
-from yt_dlp import YoutubeDL
-from yt_dlp.utils import DownloadCancelled
-
-from ..interfaces.providers import Providers
-from .base_provider import Loader
-
-
-def _cleanup_temp_file(temp_path: str) -> None:
-    """Clean up a temp file and any associated partial download files.
-
-    Removes the temp file itself and any yt-dlp partial files
-    (e.g. ``<name>.part``) that may have been left behind.
-
-    Args:
-        temp_path: Absolute or relative path to the temp file.
-    """
-    paths_to_remove = [temp_path]
-    # yt-dlp writes partial fragments to <file>.part
-    paths_to_remove.extend(
-        str(p) for p in Path(temp_path).parent.glob(
-            Path(temp_path).name + ".*"
-        )
-    )
-    for path in paths_to_remove:
-        if os.path.exists(path):
-            try:
-                os.remove(path)
-                logging.debug(f"Removed temp file: {path}")
-            except OSError as exc:
-                logging.warning(f"Failed to remove temp file {path}: {exc}")
-
-# Imported shared provider configuration
-from .provider_config import (
-    ANIWORLD_HEADERS,
-    DEFAULT_DOWNLOAD_TIMEOUT,
-    DEFAULT_PROVIDERS,
-    INVALID_PATH_CHARS,
-    LULUVDO_USER_AGENT,
-    ProviderType,
-)
-
-# Configure persistent loggers but don't add duplicate handlers when module
-# is imported multiple times (common in test environments).
-# Use absolute paths for log files to prevent security issues
-
-# Determine project root (assuming this file is in src/core/providers/)
-_module_dir = Path(__file__).parent
-_project_root = _module_dir.parent.parent.parent
-_logs_dir = _project_root / "logs"
-
-# Ensure logs directory exists
-_logs_dir.mkdir(parents=True, exist_ok=True)
-
-download_error_logger = logging.getLogger("DownloadErrors")
-if not download_error_logger.handlers:
-    log_path = _logs_dir / "download_errors.log"
-    download_error_handler = logging.FileHandler(str(log_path))
-    download_error_handler.setLevel(logging.ERROR)
-    download_error_logger.addHandler(download_error_handler)
-
-noKeyFound_logger = logging.getLogger()
-
-
-class AniworldLoader(Loader):
-    def __init__(self) -> None:
-        self.SUPPORTED_PROVIDERS = DEFAULT_PROVIDERS
-        # Copy default AniWorld headers so modifications remain local
-        self.AniworldHeaders = dict(ANIWORLD_HEADERS)
-        self.INVALID_PATH_CHARS = INVALID_PATH_CHARS
-        self.RANDOM_USER_AGENT = UserAgent().random
-        self.LULUVDO_USER_AGENT = LULUVDO_USER_AGENT
-        self.PROVIDER_HEADERS = {
-            ProviderType.VIDMOLY.value: ['Referer: "https://vidmoly.to"'],
-            ProviderType.DOODSTREAM.value: ['Referer: "https://dood.li/"'],
-            ProviderType.VOE.value: [f"User-Agent: {self.RANDOM_USER_AGENT}"],
-            ProviderType.LULUVDO.value: [
-                f"User-Agent: {self.LULUVDO_USER_AGENT}",
-                "Accept-Language: de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7",
-                'Origin: "https://luluvdo.com"',
-                'Referer: "https://luluvdo.com/"',
-            ],
-        }
-        self.ANIWORLD_TO = "https://aniworld.to"
-        self.session = requests.Session()
-
-        # Cancellation flag for graceful shutdown
-        self._cancel_flag = threading.Event()
-
-        # Configure retries with backoff
-        retries = Retry(
-            total=5,  # Number of retries
-            backoff_factor=1,  # Delay multiplier (1s, 2s, 4s, ...)
-            status_forcelist=[500, 502, 503, 504],
-            allowed_methods=["GET"]
-        )
-
-        adapter = HTTPAdapter(max_retries=retries)
-        self.session.mount("https://", adapter)
-        # Default HTTP request timeout used for requests.Session calls.
-        # Allows overriding via DOWNLOAD_TIMEOUT env var at runtime.
-        self.DEFAULT_REQUEST_TIMEOUT = int(
-            os.getenv("DOWNLOAD_TIMEOUT") or DEFAULT_DOWNLOAD_TIMEOUT
-        )
-
-        self._KeyHTMLDict = {}
-        self._EpisodeHTMLDict = {}
-        self.Providers = Providers()
-
-        # Events: download_progress is triggered with progress dict
-        self.events = Events()
-
-    def subscribe_download_progress(self, handler):
-        """Subscribe a handler to the download_progress event.
-        Args:
-            handler: Callable to be called with progress dict.
-        """
-        self.events.download_progress += handler
-
-    def unsubscribe_download_progress(self, handler):
-        """Unsubscribe a handler from the download_progress event.
-        Args:
-            handler: Callable previously subscribed.
-        """
-        self.events.download_progress -= handler
-        
-    def clear_cache(self):
-        """Clear the cached HTML data."""
-        logging.debug("Clearing HTML cache")
-        self._KeyHTMLDict = {}
-        self._EpisodeHTMLDict = {}
-        logging.debug("HTML cache cleared successfully")
-
-    def remove_from_cache(self):
-        """Remove episode HTML from cache."""
-        logging.debug("Removing episode HTML from cache")
-        self._EpisodeHTMLDict = {}
-        logging.debug("Episode HTML cache cleared")
-
-    def search(self, word: str) -> list:
-        """Search for anime series.
-        
-        Args:
-            word: Search term
-            
-        Returns:
-            List of found series
-        """
-        logging.info(f"Searching for anime with keyword: '{word}'")
-        search_url = (
-            f"{self.ANIWORLD_TO}/ajax/seriesSearch?keyword={quote(word)}"
-        )
-        logging.debug(f"Search URL: {search_url}")
-        anime_list = self.fetch_anime_list(search_url)
-        logging.info(f"Found {len(anime_list)} anime series for keyword '{word}'")
-
-        return anime_list
-
-    def fetch_anime_list(self, url: str) -> list:
-        logging.debug(f"Fetching anime list from URL: {url}")
-        response = self.session.get(url, timeout=self.DEFAULT_REQUEST_TIMEOUT)
-        response.raise_for_status()
-        logging.debug(f"Response status code: {response.status_code}")
-
-        clean_text = response.text.strip()
-
-        try:
-            decoded_data = json.loads(html.unescape(clean_text))
-            logging.debug(f"Successfully decoded JSON data on first attempt")
-            return decoded_data if isinstance(decoded_data, list) else []
-        except json.JSONDecodeError:
-            logging.warning("Initial JSON decode failed, attempting cleanup")
-            try:
-                # Remove BOM and problematic characters
-                clean_text = clean_text.encode('utf-8').decode('utf-8-sig')
-                # Remove problematic characters
-                clean_text = re.sub(r'[\x00-\x1F\x7F-\x9F]', '', clean_text)
-                # Parse the new text
-                decoded_data = json.loads(clean_text)
-                logging.debug("Successfully decoded JSON after cleanup")
-                return decoded_data if isinstance(decoded_data, list) else []
-            except (requests.RequestException, json.JSONDecodeError) as exc:
-                logging.error(f"Failed to decode anime list from {url}: {exc}")
-                raise ValueError("Could not get valid anime: ") from exc
-
-    def _get_language_key(self, language: str) -> int:
-        """Convert language name to language code.
-        
-        Language Codes:
-            1: German Dub
-            2: English Sub
-            3: German Sub
-        """
-        language_code = 0
-        if language == "German Dub":
-            language_code = 1
-        if language == "English Sub":
-            language_code = 2
-        if language == "German Sub":
-            language_code = 3
-        logging.debug(f"Converted language '{language}' to code {language_code}")
-        return language_code
-
-    def is_language(
-        self,
-        season: int,
-        episode: int,
-        key: str,
-        language: str = "German Dub"
-    ) -> bool:
-        """Check if episode is available in specified language."""
-        logging.debug(f"Checking if S{season:02}E{episode:03} ({key}) is available in {language}")
-        language_code = self._get_language_key(language)
-
-        episode_soup = BeautifulSoup(
-            self._get_episode_html(season, episode, key).content,
-            'html.parser'
-        )
-        change_language_box_div = episode_soup.find(
-            'div', class_='changeLanguageBox')
-        languages = []
-
-        if change_language_box_div:
-            img_tags = change_language_box_div.find_all('img')
-            for img in img_tags:
-                lang_key = img.get('data-lang-key')
-                if lang_key and lang_key.isdigit():
-                    languages.append(int(lang_key))
-
-        is_available = language_code in languages
-        logging.debug(f"Available languages for S{season:02}E{episode:03}: {languages}, requested: {language_code}, available: {is_available}")
-        return is_available    
-
-    def download(
-        self,
-        base_directory: str,
-        serie_folder: str,
-        season: int,
-        episode: int,
-        key: str,
-        language: str = "German Dub"
-    ) -> bool:
-        """Download episode to specified directory.
-        
-        Args:
-            base_directory: Base download directory path
-            serie_folder: Filesystem folder name (metadata only, used for
-                file path construction)
-            season: Season number
-            episode: Episode number
-            key: Series unique identifier from provider (used for
-                identification and API calls)
-            language: Audio language preference (default: German Dub)
-        Returns:
-            bool: True if download succeeded, False otherwise
-        """
-        logging.info(
-            f"Starting download for S{season:02}E{episode:03} "
-            f"({key}) in {language}"
-        )
-        sanitized_anime_title = ''.join(
-            char for char in self.get_title(key)
-            if char not in self.INVALID_PATH_CHARS
-        )
-        logging.debug(f"Sanitized anime title: {sanitized_anime_title}")
-
-        if season == 0:
-            output_file = (
-                f"{sanitized_anime_title} - "
-                f"Movie {episode:02} - "
-                f"({language}).mp4"
-            )
-        else:
-            output_file = (
-                f"{sanitized_anime_title} - "
-                f"S{season:02}E{episode:03} - "
-                f"({language}).mp4"
-            )
-
-        folder_path = os.path.join(
-            os.path.join(base_directory, serie_folder),
-            f"Season {season}"
-        )
-        output_path = os.path.join(folder_path, output_file)
-        logging.debug(f"Output path: {output_path}")
-        os.makedirs(os.path.dirname(output_path), exist_ok=True)
-
-        temp_dir = "./Temp/"
-        os.makedirs(os.path.dirname(temp_dir), exist_ok=True)
-        temp_path = os.path.join(temp_dir, output_file)
-        logging.debug(f"Temporary path: {temp_path}")
-
-        for provider in self.SUPPORTED_PROVIDERS:
-            logging.debug(f"Attempting download with provider: {provider}")
-            link, header = self._get_direct_link_from_provider(
-                season, episode, key, language
-            )
-            logging.debug("Direct link obtained from provider")
-
-            cancel_flag = self._cancel_flag
-
-            def events_progress_hook(d):
-                if cancel_flag.is_set():
-                    logging.info("Cancellation detected in progress hook")
-                    raise DownloadCancelled("Download cancelled by user")
-                # Fire the event for progress
-                self.events.download_progress(d)
-
-            ydl_opts = {
-                'fragment_retries': float('inf'),
-                'outtmpl': temp_path,
-                'quiet': True,
-                'no_warnings': True,
-                'progress_with_newline': False,
-                'nocheckcertificate': True,
-                'progress_hooks': [events_progress_hook],
-            }
-
-            if header:
-                ydl_opts['http_headers'] = header
-                logging.debug("Using custom headers for download")
-
-            try:
-                logging.debug("Starting YoutubeDL download")
-                logging.debug(f"Download link: {link[:100]}...")
-                logging.debug(f"YDL options: {ydl_opts}")
-
-                with YoutubeDL(ydl_opts) as ydl:
-                    info = ydl.extract_info(link, download=True)
-                    logging.debug(
-                        f"Download info: "
-                        f"title={info.get('title')}, "
-                        f"filesize={info.get('filesize')}"
-                    )
-
-                if os.path.exists(temp_path):
-                    logging.debug("Moving file from temp to final destination")
-                    # Use copyfile instead of copy to avoid metadata permission issues
-                    shutil.copyfile(temp_path, output_path)
-                    os.remove(temp_path)
-                    logging.info(
-                        f"Download completed successfully: {output_file}"
-                    )
-                    self.clear_cache()
-                    return True
-                else:
-                    logging.error(
-                        f"Download failed: temp file not found at {temp_path}"
-                    )
-                    self.clear_cache()
-                    return False
-            except BrokenPipeError as e:
-                logging.error(
-                    f"Broken pipe error with provider {provider}: {e}. "
-                    f"This usually means the stream connection was closed."
-                )
-                _cleanup_temp_file(temp_path)
-                continue
-            except Exception as e:
-                logging.error(
-                    f"YoutubeDL download failed with provider {provider}: "
-                    f"{type(e).__name__}: {e}"
-                )
-                _cleanup_temp_file(temp_path)
-                continue
-            break
-
-        # If we get here, all providers failed
-        logging.error("All download providers failed")
-        _cleanup_temp_file(temp_path)
-        self.clear_cache()
-        return False
-
-    def get_site_key(self) -> str:
-        """Get the site key for this provider."""
-        return "aniworld.to"
-
-    def get_title(self, key: str) -> str:
-        """Get anime title from series key."""
-        logging.debug(f"Getting title for key: {key}")
-        soup = BeautifulSoup(
-            self._get_key_html(key).content,
-            'html.parser'
-        )
-        title_div = soup.find('div', class_='series-title')
-
-        if title_div:
-            h1_tag = title_div.find('h1')
-            span_tag = h1_tag.find('span') if h1_tag else None
-            if span_tag:
-                title = span_tag.text
-                logging.debug(f"Found title: {title}")
-                return title
-
-        logging.warning(f"No title found for key: {key}")
-        return ""
-
-    def get_year(self, key: str) -> int | None:
-        """Get anime release year from series key.
-        
-        Attempts to extract the year from the series page metadata.
-        Returns None if year cannot be determined.
-        
-        Args:
-            key: Series identifier
-            
-        Returns:
-            int or None: Release year if found, None otherwise
-        """
-        logging.debug(f"Getting year for key: {key}")
-        try:
-            soup = BeautifulSoup(
-                self._get_key_html(key).content,
-                'html.parser'
-            )
-            
-            # Try to find year in metadata
-            # Check for "Jahr:" or similar metadata fields
-            for p_tag in soup.find_all('p'):
-                text = p_tag.get_text()
-                if 'Jahr:' in text or 'Year:' in text:
-                    # Extract year from text like "Jahr: 2025"
-                    match = re.search(r'(\d{4})', text)
-                    if match:
-                        year = int(match.group(1))
-                        logging.debug(f"Found year in metadata: {year}")
-                        return year
-            
-            # Try alternative: look for year in genre/info section
-            info_div = soup.find('div', class_='series-info')
-            if info_div:
-                text = info_div.get_text()
-                match = re.search(r'\b(19\d{2}|20\d{2})\b', text)
-                if match:
-                    year = int(match.group(1))
-                    logging.debug(f"Found year in info section: {year}")
-                    return year
-            
-            logging.debug(f"No year found for key: {key}")
-            return None
-            
-        except Exception as e:
-            logging.warning(f"Error extracting year for key {key}: {e}")
-            return None
-
-    def _get_key_html(self, key: str):
-        """Get cached HTML for series key.
-        
-        Args:
-            key: Series identifier (will be URL-encoded for safety)
-            
-        Returns:
-            Cached or fetched HTML response
-        """
-        if key in self._KeyHTMLDict:
-            logging.debug(f"Using cached HTML for key: {key}")
-            return self._KeyHTMLDict[key]
-
-        # Sanitize key parameter for URL
-        safe_key = quote(key, safe='')
-        url = f"{self.ANIWORLD_TO}/anime/stream/{safe_key}"
-        logging.debug(f"Fetching HTML for key: {key} from {url}")
-        self._KeyHTMLDict[key] = self.session.get(
-            url,
-            timeout=self.DEFAULT_REQUEST_TIMEOUT
-        )
-        logging.debug(f"Cached HTML for key: {key}")
-        return self._KeyHTMLDict[key]
-
-    def _get_episode_html(self, season: int, episode: int, key: str):
-        """Get cached HTML for episode.
-        
-        Args:
-            season: Season number (validated to be positive)
-            episode: Episode number (validated to be positive)
-            key: Series identifier (will be URL-encoded for safety)
-            
-        Returns:
-            Cached or fetched HTML response
-            
-        Raises:
-            ValueError: If season or episode are invalid
-        """
-        # Validate season and episode numbers
-        if season < 1 or season > 999:
-            logging.error(f"Invalid season number: {season}")
-            raise ValueError(f"Invalid season number: {season}")
-        if episode < 1 or episode > 9999:
-            logging.error(f"Invalid episode number: {episode}")
-            raise ValueError(f"Invalid episode number: {episode}")
-        
-        if key in self._EpisodeHTMLDict:
-            logging.debug(f"Using cached HTML for S{season:02}E{episode:03} ({key})")
-            return self._EpisodeHTMLDict[(key, season, episode)]
-
-        # Sanitize key parameter for URL
-        safe_key = quote(key, safe='')
-        link = (
-            f"{self.ANIWORLD_TO}/anime/stream/{safe_key}/"
-            f"staffel-{season}/episode-{episode}"
-        )
-        logging.debug(f"Fetching episode HTML from: {link}")
-        html = self.session.get(link, timeout=self.DEFAULT_REQUEST_TIMEOUT)
-        self._EpisodeHTMLDict[(key, season, episode)] = html
-        logging.debug(f"Cached episode HTML for S{season:02}E{episode:03} ({key})")
-        return self._EpisodeHTMLDict[(key, season, episode)]
-
-    def _get_provider_from_html(
-        self,
-        season: int,
-        episode: int,
-        key: str
-    ) -> dict:
-        """Parse HTML content to extract streaming providers.
-
-        Returns a dictionary with provider names as keys
-        and language key-to-redirect URL mappings as values.
-
-        Example:
-            {
-                'VOE': {1: 'https://aniworld.to/redirect/1766412',
-                        2: 'https://aniworld.to/redirect/1766405'},
-            }
-        """
-        logging.debug(f"Extracting providers from HTML for S{season:02}E{episode:03} ({key})")
-        soup = BeautifulSoup(
-            self._get_episode_html(season, episode, key).content,
-            'html.parser'
-        )
-        providers: dict[str, dict[int, str]] = {}
-
-        episode_links = soup.find_all(
-            'li', class_=lambda x: x and x.startswith('episodeLink')
-        )
-
-        if not episode_links:
-            logging.warning(f"No episode links found for S{season:02}E{episode:03} ({key})")
-            return providers
-
-        for link in episode_links:
-            provider_name_tag = link.find('h4')
-            provider_name = (
-                provider_name_tag.text.strip()
-                if provider_name_tag else None
-            )
-
-            redirect_link_tag = link.find('a', class_='watchEpisode')
-            redirect_link = (
-                redirect_link_tag.get('href')
-                if redirect_link_tag else None
-            )
-
-            lang_key = link.get('data-lang-key')
-            lang_key = (
-                int(lang_key)
-                if lang_key and lang_key.isdigit() else None
-            )
-
-            if provider_name and redirect_link and lang_key:
-                if provider_name not in providers:
-                    providers[provider_name] = {}
-                providers[provider_name][lang_key] = (
-                    f"{self.ANIWORLD_TO}{redirect_link}"
-                )
-                logging.debug(f"Found provider: {provider_name}, lang_key: {lang_key}")
-
-        logging.debug(f"Total providers found: {len(providers)}")
-        return providers
-
-    def _get_redirect_link(
-        self,
-        season: int,
-        episode: int,
-        key: str,
-        language: str = "German Dub"
-    ):
-        """Get redirect link for episode in specified language."""
-        logging.debug(f"Getting redirect link for S{season:02}E{episode:03} ({key}) in {language}")
-        language_code = self._get_language_key(language)
-        if self.is_language(season, episode, key, language):
-            for (provider_name, lang_dict) in (
-                self._get_provider_from_html(
-                    season, episode, key
-                ).items()
-            ):
-                if language_code in lang_dict:
-                    logging.debug(f"Found redirect link with provider: {provider_name}")
-                    return (lang_dict[language_code], provider_name)
-        logging.warning(f"No redirect link found for S{season:02}E{episode:03} ({key}) in {language}")
-        return None
-
-    def _get_embeded_link(
-        self,
-        season: int,
-        episode: int,
-        key: str,
-        language: str = "German Dub"
-    ):
-        """Get embedded link from redirect link."""
-        logging.debug(f"Getting embedded link for S{season:02}E{episode:03} ({key}) in {language}")
-        redirect_link, provider_name = (
-            self._get_redirect_link(season, episode, key, language)
-        )
-        logging.debug(f"Redirect link: {redirect_link}, provider: {provider_name}")
-
-        embeded_link = self.session.get(
-            redirect_link,
-            timeout=self.DEFAULT_REQUEST_TIMEOUT,
-            headers={'User-Agent': self.RANDOM_USER_AGENT}
-        ).url
-        logging.debug(f"Embedded link: {embeded_link}")
-        return embeded_link
-
-    def _get_direct_link_from_provider(
-        self,
-        season: int,
-        episode: int,
-        key: str,
-        language: str = "German Dub"
-    ):
-        """Get direct download link from streaming provider."""
-        logging.debug(f"Getting direct link from provider for S{season:02}E{episode:03} ({key}) in {language}")
-        embeded_link = self._get_embeded_link(
-            season, episode, key, language
-        )
-        if embeded_link is None:
-            logging.error(f"No embedded link found for S{season:02}E{episode:03} ({key})")
-            return None
-
-        logging.debug(f"Using VOE provider to extract direct link")
-        return self.Providers.GetProvider(
-            "VOE"
-        ).get_link(embeded_link, self.DEFAULT_REQUEST_TIMEOUT)
-
-    def get_season_episode_count(self, slug: str) -> dict:
-        """Get episode count for each season.
-        
-        Args:
-            slug: Series identifier (will be URL-encoded for safety)
-            
-        Returns:
-            Dictionary mapping season numbers to episode counts
-        """
-        logging.info(f"Getting season and episode count for slug: {slug}")
-        # Sanitize slug parameter for URL
-        safe_slug = quote(slug, safe='')
-        base_url = f"{self.ANIWORLD_TO}/anime/stream/{safe_slug}/"
-        logging.debug(f"Base URL: {base_url}")
-        response = requests.get(base_url, timeout=self.DEFAULT_REQUEST_TIMEOUT)
-        soup = BeautifulSoup(response.content, 'html.parser')
-
-        season_meta = soup.find('meta', itemprop='numberOfSeasons')
-        number_of_seasons = int(season_meta['content']) if season_meta else 0
-        logging.info(f"Found {number_of_seasons} seasons for '{slug}'")
-
-        episode_counts = {}
-
-        for season in range(1, number_of_seasons + 1):
-            season_url = f"{base_url}staffel-{season}"
-            logging.debug(f"Fetching episodes for season {season} from: {season_url}")
-            response = requests.get(
-                season_url,
-                timeout=self.DEFAULT_REQUEST_TIMEOUT,
-            )
-            soup = BeautifulSoup(response.content, 'html.parser')
-
-            episode_links = soup.find_all('a', href=True)
-            unique_links = set(
-                link['href']
-                for link in episode_links
-                if f"staffel-{season}/episode-" in link['href']
-            )
-
-            episode_counts[season] = len(unique_links)
-            logging.debug(f"Season {season} has {episode_counts[season]} episodes")
-
-        logging.info(f"Episode count retrieval complete for '{slug}': {episode_counts}")
-        return episode_counts

src/core/services/nfo_factory.py

@@ -1,237 +0,0 @@
-"""NFO Service Factory Module.
-
-This module provides a centralized factory for creating NFOService instances
-with consistent configuration and initialization logic.
-
-The factory supports both direct instantiation and FastAPI dependency injection,
-while remaining testable through optional dependency overrides.
-"""
-
-import logging
-from typing import Optional
-
-from src.config.settings import settings
-from src.core.services.nfo_service import NFOService
-
-logger = logging.getLogger(__name__)
-
-
-class NFOServiceFactory:
-    """Factory for creating NFOService instances with consistent configuration.
-    
-    This factory centralizes NFO service initialization logic that was previously
-    duplicated across multiple modules (SeriesApp, SeriesManagerService, API endpoints).
-    
-    The factory follows these precedence rules for configuration:
-    1. Explicit parameters (highest priority)
-    2. Environment variables via settings
-    3. config.json via ConfigService (fallback)
-    4. Raise error if TMDB API key unavailable
-    
-    Example:
-        >>> factory = NFOServiceFactory()
-        >>> nfo_service = factory.create()
-        >>> # Or with custom settings:
-        >>> nfo_service = factory.create(tmdb_api_key="custom_key")
-    """
-    
-    def __init__(self):
-        """Initialize the NFO service factory."""
-        self._config_service = None
-    
-    def create(
-        self,
-        tmdb_api_key: Optional[str] = None,
-        anime_directory: Optional[str] = None,
-        image_size: Optional[str] = None,
-        auto_create: Optional[bool] = None
-    ) -> NFOService:
-        """Create an NFOService instance with proper configuration.
-        
-        This method implements the configuration precedence:
-        1. Use explicit parameters if provided
-        2. Fall back to settings (from ENV vars)
-        3. Fall back to config.json (only if ENV not set)
-        4. Raise ValueError if TMDB API key still unavailable
-        
-        Args:
-            tmdb_api_key: TMDB API key (optional, falls back to settings/config)
-            anime_directory: Anime directory path (optional, defaults to settings)
-            image_size: Image size for downloads (optional, defaults to settings)
-            auto_create: Whether to auto-create NFO files (optional, defaults to settings)
-            
-        Returns:
-            NFOService: Configured NFO service instance
-            
-        Raises:
-            ValueError: If TMDB API key cannot be determined from any source
-            
-        Example:
-            >>> factory = NFOServiceFactory()
-            >>> # Use all defaults from settings
-            >>> service = factory.create()
-            >>> # Override specific settings
-            >>> service = factory.create(auto_create=False)
-        """
-        # Step 1: Determine TMDB API key with fallback logic
-        api_key = tmdb_api_key or settings.tmdb_api_key
-        
-        # Step 2: If no API key in settings, try config.json as fallback
-        if not api_key:
-            api_key = self._get_api_key_from_config()
-        
-        # Step 3: Validate API key is available
-        if not api_key:
-            raise ValueError(
-                "TMDB API key not configured. Set TMDB_API_KEY environment "
-                "variable or configure in config.json (nfo.tmdb_api_key)."
-            )
-        
-        # Step 4: Use provided values or fall back to settings
-        directory = anime_directory or settings.anime_directory
-        size = image_size or settings.nfo_image_size
-        auto = auto_create if auto_create is not None else settings.nfo_auto_create
-        
-        # Step 5: Create and return the service
-        logger.debug(
-            "Creating NFOService: directory=%s, size=%s, auto_create=%s",
-            directory, size, auto
-        )
-        
-        return NFOService(
-            tmdb_api_key=api_key,
-            anime_directory=directory,
-            image_size=size,
-            auto_create=auto
-        )
-    
-    def create_optional(
-        self,
-        tmdb_api_key: Optional[str] = None,
-        anime_directory: Optional[str] = None,
-        image_size: Optional[str] = None,
-        auto_create: Optional[bool] = None
-    ) -> Optional[NFOService]:
-        """Create an NFOService instance, returning None if configuration unavailable.
-        
-        This is a convenience method for cases where NFO service is optional.
-        Unlike create(), this returns None instead of raising ValueError when
-        the TMDB API key is not configured.
-        
-        Args:
-            tmdb_api_key: TMDB API key (optional)
-            anime_directory: Anime directory path (optional)
-            image_size: Image size for downloads (optional)
-            auto_create: Whether to auto-create NFO files (optional)
-            
-        Returns:
-            Optional[NFOService]: Configured service or None if key unavailable
-            
-        Example:
-            >>> factory = NFOServiceFactory()
-            >>> service = factory.create_optional()
-            >>> if service:
-            ...     service.create_tvshow_nfo(...)
-        """
-        try:
-            return self.create(
-                tmdb_api_key=tmdb_api_key,
-                anime_directory=anime_directory,
-                image_size=image_size,
-                auto_create=auto_create
-            )
-        except ValueError as e:
-            logger.debug("NFO service not available: %s", e)
-            return None
-    
-    def _get_api_key_from_config(self) -> Optional[str]:
-        """Get TMDB API key from config.json as fallback.
-        
-        This method is only called when the API key is not in settings
-        (i.e., not set via environment variable). It provides backward
-        compatibility with config.json configuration.
-        
-        Returns:
-            Optional[str]: API key from config.json, or None if unavailable
-        """
-        try:
-            # Lazy import to avoid circular dependencies
-            from src.server.services.config_service import get_config_service
-            
-            if self._config_service is None:
-                self._config_service = get_config_service()
-            
-            config = self._config_service.load_config()
-            
-            if config.nfo and config.nfo.tmdb_api_key:
-                logger.debug("Using TMDB API key from config.json")
-                return config.nfo.tmdb_api_key
-                
-        except Exception as e:  # pylint: disable=broad-except
-            logger.debug("Could not load API key from config.json: %s", e)
-        
-        return None
-
-
-# Global factory instance for convenience
-_factory_instance: Optional[NFOServiceFactory] = None
-
-
-def get_nfo_factory() -> NFOServiceFactory:
-    """Get the global NFO service factory instance.
-    
-    This function provides a singleton factory instance for the application.
-    The singleton pattern here is for the factory itself (which is stateless),
-    not for the NFO service instances it creates.
-    
-    Returns:
-        NFOServiceFactory: The global factory instance
-        
-    Example:
-        >>> factory = get_nfo_factory()
-        >>> service = factory.create()
-    """
-    global _factory_instance
-    
-    if _factory_instance is None:
-        _factory_instance = NFOServiceFactory()
-    
-    return _factory_instance
-
-
-def create_nfo_service(
-    tmdb_api_key: Optional[str] = None,
-    anime_directory: Optional[str] = None,
-    image_size: Optional[str] = None,
-    auto_create: Optional[bool] = None
-) -> NFOService:
-    """Convenience function to create an NFOService instance.
-    
-    This is a shorthand for get_nfo_factory().create() that can be used
-    when you need a quick NFO service instance without interacting with
-    the factory directly.
-    
-    Args:
-        tmdb_api_key: TMDB API key (optional)
-        anime_directory: Anime directory path (optional)
-        image_size: Image size for downloads (optional)
-        auto_create: Whether to auto-create NFO files (optional)
-        
-    Returns:
-        NFOService: Configured NFO service instance
-        
-    Raises:
-        ValueError: If TMDB API key cannot be determined
-        
-    Example:
-        >>> service = create_nfo_service()
-        >>> # Or with custom settings:
-        >>> service = create_nfo_service(auto_create=False)
-    """
-    factory = get_nfo_factory()
-    return factory.create(
-        tmdb_api_key=tmdb_api_key,
-        anime_directory=anime_directory,
-        image_size=image_size,
-        auto_create=auto_create
-    )

src/core/services/nfo_repair_service.py

@@ -1,180 +0,0 @@
-"""NFO repair service for detecting and fixing incomplete tvshow.nfo files.
-
-This module provides utilities to check whether an existing ``tvshow.nfo``
-contains all required tags and to trigger a repair (re-fetch from TMDB) when
-needed.
-
-Example:
-    >>> service = NfoRepairService(nfo_service)
-    >>> repaired = await service.repair_series(Path("/anime/Attack on Titan"), "Attack on Titan")
-"""
-
-import logging
-from pathlib import Path
-from typing import Dict, List
-
-from lxml import etree
-
-from src.core.services.nfo_service import NFOService
-
-logger = logging.getLogger(__name__)
-
-
-# XPath relative to <tvshow> root → human-readable label
-REQUIRED_TAGS: Dict[str, str] = {
-    "./title": "title",
-    "./originaltitle": "originaltitle",
-    "./year": "year",
-    "./plot": "plot",
-    "./runtime": "runtime",
-    "./premiered": "premiered",
-    "./status": "status",
-    "./imdbid": "imdbid",
-    "./genre": "genre",
-    "./studio": "studio",
-    "./country": "country",
-    "./actor/name": "actor/name",
-    "./watched": "watched",
-}
-
-
-def parse_nfo_tags(nfo_path: Path) -> Dict[str, List[str]]:
-    """Parse an existing tvshow.nfo and return present tag values.
-
-    Evaluates every XPath in :data:`REQUIRED_TAGS` against the document root
-    and collects all non-empty text values.
-
-    Args:
-        nfo_path: Absolute path to the ``tvshow.nfo`` file.
-
-    Returns:
-        Mapping of XPath expression → list of non-empty text strings found in
-        the document.  Returns an empty dict on any error (missing file,
-        invalid XML, permission error).
-
-    Example:
-        >>> tags = parse_nfo_tags(Path("/anime/Attack on Titan/tvshow.nfo"))
-        >>> tags.get("./title")
-        ['Attack on Titan']
-    """
-    if not nfo_path.exists():
-        logger.debug("NFO file not found: %s", nfo_path)
-        return {}
-
-    try:
-        tree = etree.parse(str(nfo_path))
-        root = tree.getroot()
-
-        result: Dict[str, List[str]] = {}
-        for xpath in REQUIRED_TAGS:
-            elements = root.findall(xpath)
-            result[xpath] = [e.text for e in elements if e.text]
-
-        return result
-
-    except etree.XMLSyntaxError as exc:
-        logger.warning("Malformed XML in %s: %s", nfo_path, exc)
-        return {}
-    except Exception as exc:  # pylint: disable=broad-except
-        logger.warning("Unexpected error parsing %s: %s", nfo_path, exc)
-        return {}
-
-
-def find_missing_tags(nfo_path: Path) -> List[str]:
-    """Return tags that are absent or empty in the NFO.
-
-    Args:
-        nfo_path: Absolute path to the ``tvshow.nfo`` file.
-
-    Returns:
-        List of human-readable tag labels (values from :data:`REQUIRED_TAGS`)
-        whose XPath matched no elements or only elements with empty text.
-        An empty list means the NFO is complete.
-
-    Example:
-        >>> missing = find_missing_tags(Path("/anime/series/tvshow.nfo"))
-        >>> if missing:
-        ...     print("Missing:", missing)
-    """
-    parsed = parse_nfo_tags(nfo_path)
-    missing: List[str] = []
-    for xpath, label in REQUIRED_TAGS.items():
-        if not parsed.get(xpath):
-            missing.append(label)
-    return missing
-
-
-def nfo_needs_repair(nfo_path: Path) -> bool:
-    """Return ``True`` if the NFO is missing any required tag.
-
-    Args:
-        nfo_path: Absolute path to the ``tvshow.nfo`` file.
-
-    Returns:
-        True if :func:`find_missing_tags` returns a non-empty list.
-
-    Example:
-        >>> if nfo_needs_repair(Path("/anime/series/tvshow.nfo")):
-        ...     await service.repair_series(series_path, series_name)
-    """
-    return bool(find_missing_tags(nfo_path))
-
-
-class NfoRepairService:
-    """Service that detects and repairs incomplete tvshow.nfo files.
-
-    Wraps the module-level helpers with structured logging and delegates
-    the actual TMDB re-fetch to an injected :class:`NFOService` instance.
-
-    Attributes:
-        _nfo_service: The underlying NFOService used to update NFOs.
-    """
-
-    def __init__(self, nfo_service: NFOService) -> None:
-        """Initialise the repair service.
-
-        Args:
-            nfo_service: Configured :class:`NFOService` instance.
-        """
-        self._nfo_service = nfo_service
-
-    async def repair_series(self, series_path: Path, series_name: str) -> bool:
-        """Repair an NFO file if required tags are missing.
-
-        Checks ``{series_path}/tvshow.nfo`` for completeness.  If tags are
-        missing, logs them and calls
-        ``NFOService.update_tvshow_nfo(series_name)`` to re-fetch metadata
-        from TMDB.
-
-        Args:
-            series_path: Absolute path to the series folder.
-            series_name: Series folder name used as the identifier for
-                         :meth:`NFOService.update_tvshow_nfo`.
-
-        Returns:
-            ``True`` if a repair was triggered, ``False`` if the NFO was
-            already complete (or did not exist).
-        """
-        nfo_path = series_path / "tvshow.nfo"
-        missing = find_missing_tags(nfo_path)
-
-        if not missing:
-            logger.info(
-                "NFO repair skipped — complete: %s",
-                series_name,
-            )
-            return False
-
-        logger.info(
-            "NFO repair triggered for %s — missing tags: %s",
-            series_name,
-            ", ".join(missing),
-        )
-
-        await self._nfo_service.update_tvshow_nfo(
-            series_name,
-            download_media=False,
-        )
-
-        logger.info("NFO repair completed: %s", series_name)
-        return True

src/core/services/nfo_service.py

@@ -1,471 +0,0 @@
-"""NFO service for creating and managing tvshow.nfo files.
-
-This service orchestrates TMDB API calls, XML generation, and media downloads
-to create complete NFO metadata for TV series.
-
-Example:
-    >>> nfo_service = NFOService(tmdb_api_key="key", anime_directory="/anime")
-    >>> await nfo_service.create_tvshow_nfo("Attack on Titan", "/anime/aot", 2013)
-"""
-
-import logging
-import re
-from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
-
-from lxml import etree
-
-from src.core.services.tmdb_client import TMDBAPIError, TMDBClient
-from src.core.utils.image_downloader import ImageDownloader
-from src.core.utils.nfo_generator import generate_tvshow_nfo
-from src.core.utils.nfo_mapper import tmdb_to_nfo_model
-
-logger = logging.getLogger(__name__)
-
-
-class NFOService:
-    """Service for creating and managing tvshow.nfo files.
-    
-    Attributes:
-        tmdb_client: TMDB API client
-        image_downloader: Image downloader utility
-        anime_directory: Base directory for anime series
-    """
-    
-    def __init__(
-        self,
-        tmdb_api_key: str,
-        anime_directory: str,
-        image_size: str = "original",
-        auto_create: bool = True
-    ):
-        """Initialize NFO service.
-        
-        Args:
-            tmdb_api_key: TMDB API key
-            anime_directory: Base anime directory path
-            image_size: Image size to download (original, w500, etc.)
-            auto_create: Whether to auto-create NFOs
-        """
-        self.tmdb_client = TMDBClient(api_key=tmdb_api_key)
-        self.image_downloader = ImageDownloader()
-        self.anime_directory = Path(anime_directory)
-        self.image_size = image_size
-        self.auto_create = auto_create
-    
-    def has_nfo(self, serie_folder: str) -> bool:
-        """Check if tvshow.nfo exists for a series.
-        
-        Args:
-            serie_folder: Series folder name
-            
-        Returns:
-            True if NFO file exists
-        """
-        nfo_path = self.anime_directory / serie_folder / "tvshow.nfo"
-        return nfo_path.exists()
-    
-    @staticmethod
-    def _extract_year_from_name(serie_name: str) -> Tuple[str, Optional[int]]:
-        """Extract year from series name if present in format 'Name (YYYY)'.
-        
-        Args:
-            serie_name: Series name, possibly with year in parentheses
-            
-        Returns:
-            Tuple of (clean_name, year)
-            - clean_name: Series name without year
-            - year: Extracted year or None
-            
-        Examples:
-            >>> _extract_year_from_name("Attack on Titan (2013)")
-            ("Attack on Titan", 2013)
-            >>> _extract_year_from_name("Attack on Titan")
-            ("Attack on Titan", None)
-        """
-        # Match year in parentheses at the end: (YYYY)
-        match = re.search(r'\((\d{4})\)\s*$', serie_name)
-        if match:
-            year = int(match.group(1))
-            clean_name = serie_name[:match.start()].strip()
-            return clean_name, year
-        return serie_name, None
-    
-    async def check_nfo_exists(self, serie_folder: str) -> bool:
-        """Check if tvshow.nfo exists for a series.
-        
-        Args:
-            serie_folder: Series folder name
-            
-        Returns:
-            True if tvshow.nfo exists
-        """
-        nfo_path = self.anime_directory / serie_folder / "tvshow.nfo"
-        return nfo_path.exists()
-    
-    async def create_tvshow_nfo(
-        self,
-        serie_name: str,
-        serie_folder: str,
-        year: Optional[int] = None,
-        download_poster: bool = True,
-        download_logo: bool = True,
-        download_fanart: bool = True
-    ) -> Path:
-        """Create tvshow.nfo by scraping TMDB.
-        
-        Args:
-            serie_name: Name of the series to search (may include year in parentheses)
-            serie_folder: Series folder name
-            year: Release year (helps narrow search). If None and name contains year, 
-                  year will be auto-extracted
-            download_poster: Whether to download poster.jpg
-            download_logo: Whether to download logo.png
-            download_fanart: Whether to download fanart.jpg
-            
-        Returns:
-            Path to created NFO file
-            
-        Raises:
-            TMDBAPIError: If TMDB API fails
-            FileNotFoundError: If series folder doesn't exist
-        """
-        # Extract year from name if not provided
-        clean_name, extracted_year = self._extract_year_from_name(serie_name)
-        if year is None and extracted_year is not None:
-            year = extracted_year
-            logger.info(f"Extracted year {year} from series name")
-        
-        # Use clean name for search
-        search_name = clean_name
-        
-        logger.info(f"Creating NFO for {search_name} (year: {year})")
-        
-        folder_path = self.anime_directory / serie_folder
-        if not folder_path.exists():
-            logger.info(f"Creating series folder: {folder_path}")
-            folder_path.mkdir(parents=True, exist_ok=True)
-        
-        async with self.tmdb_client:
-            # Search for TV show with clean name (without year)
-            logger.debug(f"Searching TMDB for: {search_name}")
-            search_results = await self.tmdb_client.search_tv_show(search_name)
-            
-            if not search_results.get("results"):
-                raise TMDBAPIError(f"No results found for: {search_name}")
-            
-            # Find best match (consider year if provided)
-            tv_show = self._find_best_match(search_results["results"], search_name, year)
-            tv_id = tv_show["id"]
-            
-            logger.info(f"Found match: {tv_show['name']} (ID: {tv_id})")
-            
-            # Get detailed information
-            details = await self.tmdb_client.get_tv_show_details(
-                tv_id,
-                append_to_response="credits,external_ids,images"
-            )
-            
-            # Get content ratings for FSK
-            content_ratings = await self.tmdb_client.get_tv_show_content_ratings(tv_id)
-            
-            # Convert TMDB data to TVShowNFO model
-            nfo_model = tmdb_to_nfo_model(
-                details,
-                content_ratings,
-                self.tmdb_client.get_image_url,
-                self.image_size,
-            )
-            
-            # Generate XML
-            nfo_xml = generate_tvshow_nfo(nfo_model)
-            
-            # Save NFO file
-            nfo_path = folder_path / "tvshow.nfo"
-            nfo_path.write_text(nfo_xml, encoding="utf-8")
-            logger.info(f"Created NFO: {nfo_path}")
-            
-            # Download media files
-            await self._download_media_files(
-                details,
-                folder_path,
-                download_poster=download_poster,
-                download_logo=download_logo,
-                download_fanart=download_fanart
-            )
-            
-            return nfo_path
-    
-    async def update_tvshow_nfo(
-        self,
-        serie_folder: str,
-        download_media: bool = True
-    ) -> Path:
-        """Update existing tvshow.nfo with fresh data from TMDB.
-        
-        Args:
-            serie_folder: Series folder name
-            download_media: Whether to re-download media files
-            
-        Returns:
-            Path to updated NFO file
-            
-        Raises:
-            FileNotFoundError: If NFO file doesn't exist
-            TMDBAPIError: If TMDB API fails or no TMDB ID found in NFO
-        """
-        folder_path = self.anime_directory / serie_folder
-        nfo_path = folder_path / "tvshow.nfo"
-        
-        if not nfo_path.exists():
-            raise FileNotFoundError(f"NFO file not found: {nfo_path}")
-        
-        logger.info(f"Updating NFO for {serie_folder}")
-        
-        # Parse existing NFO to extract TMDB ID
-        try:
-            tree = etree.parse(str(nfo_path))
-            root = tree.getroot()
-            
-            # Try to find TMDB ID from uniqueid elements
-            tmdb_id = None
-            for uniqueid in root.findall(".//uniqueid"):
-                if uniqueid.get("type") == "tmdb":
-                    tmdb_id = int(uniqueid.text)
-                    break
-            
-            # Fallback: check for tmdbid element
-            if tmdb_id is None:
-                tmdbid_elem = root.find(".//tmdbid")
-                if tmdbid_elem is not None and tmdbid_elem.text:
-                    tmdb_id = int(tmdbid_elem.text)
-            
-            if tmdb_id is None:
-                raise TMDBAPIError(
-                    f"No TMDB ID found in existing NFO. "
-                    f"Delete the NFO and create a new one instead."
-                )
-            
-            logger.debug(f"Found TMDB ID: {tmdb_id}")
-            
-        except etree.XMLSyntaxError as e:
-            raise TMDBAPIError(f"Invalid XML in NFO file: {e}")
-        except ValueError as e:
-            raise TMDBAPIError(f"Invalid TMDB ID format in NFO: {e}")
-        
-        # Fetch fresh data from TMDB
-        async with self.tmdb_client:
-            logger.debug(f"Fetching fresh data for TMDB ID: {tmdb_id}")
-            details = await self.tmdb_client.get_tv_show_details(
-                tmdb_id,
-                append_to_response="credits,external_ids,images"
-            )
-            
-            # Get content ratings for FSK
-            content_ratings = await self.tmdb_client.get_tv_show_content_ratings(tmdb_id)
-            
-            # Convert TMDB data to TVShowNFO model
-            nfo_model = tmdb_to_nfo_model(
-                details,
-                content_ratings,
-                self.tmdb_client.get_image_url,
-                self.image_size,
-            )
-            
-            # Generate XML
-            nfo_xml = generate_tvshow_nfo(nfo_model)
-            
-            # Save updated NFO file
-            nfo_path.write_text(nfo_xml, encoding="utf-8")
-            logger.info(f"Updated NFO: {nfo_path}")
-            
-            # Re-download media files if requested
-            if download_media:
-                await self._download_media_files(
-                    details,
-                    folder_path,
-                    download_poster=True,
-                    download_logo=True,
-                    download_fanart=True
-                )
-            
-            return nfo_path
-    
-    def parse_nfo_ids(self, nfo_path: Path) -> Dict[str, Optional[int]]:
-        """Parse TMDB ID and TVDB ID from an existing NFO file.
-        
-        Args:
-            nfo_path: Path to tvshow.nfo file
-            
-        Returns:
-            Dictionary with 'tmdb_id' and 'tvdb_id' keys.
-            Values are integers if found, None otherwise.
-            
-        Example:
-            >>> ids = nfo_service.parse_nfo_ids(Path("/anime/series/tvshow.nfo"))
-            >>> print(ids)
-            {'tmdb_id': 1429, 'tvdb_id': 79168}
-        """
-        result = {"tmdb_id": None, "tvdb_id": None}
-        
-        if not nfo_path.exists():
-            logger.debug(f"NFO file not found: {nfo_path}")
-            return result
-        
-        try:
-            tree = etree.parse(str(nfo_path))
-            root = tree.getroot()
-            
-            # Try to find TMDB ID from uniqueid elements first
-            for uniqueid in root.findall(".//uniqueid"):
-                uid_type = uniqueid.get("type")
-                uid_text = uniqueid.text
-                
-                if uid_type == "tmdb" and uid_text:
-                    try:
-                        result["tmdb_id"] = int(uid_text)
-                    except ValueError:
-                        logger.warning(
-                            f"Invalid TMDB ID format in NFO: {uid_text}"
-                        )
-                
-                elif uid_type == "tvdb" and uid_text:
-                    try:
-                        result["tvdb_id"] = int(uid_text)
-                    except ValueError:
-                        logger.warning(
-                            f"Invalid TVDB ID format in NFO: {uid_text}"
-                        )
-            
-            # Fallback: check for dedicated tmdbid/tvdbid elements
-            if result["tmdb_id"] is None:
-                tmdbid_elem = root.find(".//tmdbid")
-                if tmdbid_elem is not None and tmdbid_elem.text:
-                    try:
-                        result["tmdb_id"] = int(tmdbid_elem.text)
-                    except ValueError:
-                        logger.warning(
-                            f"Invalid TMDB ID format in tmdbid element: "
-                            f"{tmdbid_elem.text}"
-                        )
-            
-            if result["tvdb_id"] is None:
-                tvdbid_elem = root.find(".//tvdbid")
-                if tvdbid_elem is not None and tvdbid_elem.text:
-                    try:
-                        result["tvdb_id"] = int(tvdbid_elem.text)
-                    except ValueError:
-                        logger.warning(
-                            f"Invalid TVDB ID format in tvdbid element: "
-                            f"{tvdbid_elem.text}"
-                        )
-            
-            logger.debug(
-                f"Parsed IDs from NFO: {nfo_path.name} - "
-                f"TMDB: {result['tmdb_id']}, TVDB: {result['tvdb_id']}"
-            )
-            
-        except etree.XMLSyntaxError as e:
-            logger.error(f"Invalid XML in NFO file {nfo_path}: {e}")
-        except Exception as e:  # pylint: disable=broad-except
-            logger.error(f"Error parsing NFO file {nfo_path}: {e}")
-        
-        return result
-    
-    def _find_best_match(
-        self,
-        results: List[Dict[str, Any]],
-        query: str,
-        year: Optional[int] = None
-    ) -> Dict[str, Any]:
-        """Find best matching TV show from search results.
-        
-        Args:
-            results: TMDB search results
-            query: Original search query
-            year: Expected release year
-            
-        Returns:
-            Best matching TV show data
-        """
-        if not results:
-            raise TMDBAPIError("No search results to match")
-        
-        # If year is provided, try to find exact match
-        if year:
-            for result in results:
-                first_air_date = result.get("first_air_date", "")
-                if first_air_date.startswith(str(year)):
-                    logger.debug(f"Found year match: {result['name']} ({first_air_date})")
-                    return result
-        
-        # Return first result (usually best match)
-        return results[0]
-    
-
-    
-    async def _download_media_files(
-        self,
-        tmdb_data: Dict[str, Any],
-        folder_path: Path,
-        download_poster: bool = True,
-        download_logo: bool = True,
-        download_fanart: bool = True
-    ) -> Dict[str, bool]:
-        """Download media files (poster, logo, fanart).
-        
-        Args:
-            tmdb_data: TMDB TV show details
-            folder_path: Series folder path
-            download_poster: Download poster.jpg
-            download_logo: Download logo.png
-            download_fanart: Download fanart.jpg
-            
-        Returns:
-            Dictionary with download status for each file
-        """
-        poster_url = None
-        logo_url = None
-        fanart_url = None
-        
-        # Get poster URL
-        if download_poster and tmdb_data.get("poster_path"):
-            poster_url = self.tmdb_client.get_image_url(
-                tmdb_data["poster_path"],
-                self.image_size
-            )
-        
-        # Get fanart URL
-        if download_fanart and tmdb_data.get("backdrop_path"):
-            fanart_url = self.tmdb_client.get_image_url(
-                tmdb_data["backdrop_path"],
-                "original"  # Always use original for fanart
-            )
-        
-        # Get logo URL
-        if download_logo:
-            images_data = tmdb_data.get("images", {})
-            logos = images_data.get("logos", [])
-            if logos:
-                logo_url = self.tmdb_client.get_image_url(
-                    logos[0]["file_path"],
-                    "original"  # Logos should be original size
-                )
-        
-        # Download all media concurrently
-        results = await self.image_downloader.download_all_media(
-            folder_path,
-            poster_url=poster_url,
-            logo_url=logo_url,
-            fanart_url=fanart_url,
-            skip_existing=True
-        )
-        
-        logger.info(f"Media download results: {results}")
-        return results
-    
-
-    
-    async def close(self):
-        """Clean up resources."""
-        await self.tmdb_client.close()

src/core/services/series_manager_service.py

@@ -1,279 +0,0 @@
-"""Service for managing series with NFO metadata support.
-
-This service layer component orchestrates SerieList (core entity) with
-NFOService to provide automatic NFO creation and updates during series scans.
-
-This follows clean architecture principles by keeping the core entities
-independent of external services like TMDB API.
-"""
-
-import asyncio
-import logging
-from pathlib import Path
-from typing import Optional
-
-from src.config.settings import settings
-from src.core.entities.SerieList import SerieList
-from src.core.services.nfo_service import NFOService
-from src.core.services.tmdb_client import TMDBAPIError
-
-logger = logging.getLogger(__name__)
-
-
-class SeriesManagerService:
-    """Service for managing series with optional NFO metadata support.
-    
-    This service wraps SerieList and adds NFO creation/update capabilities
-    based on configuration settings. It maintains clean separation between
-    core entities and external services.
-    
-    Attributes:
-        serie_list: SerieList instance for series management
-        nfo_service: Optional NFOService for metadata management
-        auto_create_nfo: Whether to auto-create NFO files
-        update_on_scan: Whether to update existing NFO files
-    """
-    
-    def __init__(
-        self,
-        anime_directory: str,
-        tmdb_api_key: Optional[str] = None,
-        auto_create_nfo: bool = False,
-        update_on_scan: bool = False,
-        download_poster: bool = True,
-        download_logo: bool = True,
-        download_fanart: bool = True,
-        image_size: str = "original"
-    ):
-        """Initialize series manager service.
-        
-        Args:
-            anime_directory: Base directory for anime series
-            tmdb_api_key: TMDB API key (optional, required for NFO features)
-            auto_create_nfo: Automatically create NFO files when scanning
-            update_on_scan: Update existing NFO files when scanning
-            download_poster: Download poster.jpg
-            download_logo: Download logo.png
-            download_fanart: Download fanart.jpg
-            image_size: Image size to download
-        """
-        self.anime_directory = anime_directory
-        # Skip automatic folder scanning - we load from database instead
-        self.serie_list = SerieList(anime_directory, skip_load=True)
-        
-        # NFO configuration
-        self.auto_create_nfo = auto_create_nfo
-        self.update_on_scan = update_on_scan
-        self.download_poster = download_poster
-        self.download_logo = download_logo
-        self.download_fanart = download_fanart
-        
-        # Initialize NFO service if API key provided and NFO features enabled
-        self.nfo_service: Optional[NFOService] = None
-        if tmdb_api_key and (auto_create_nfo or update_on_scan):
-            try:
-                from src.core.services.nfo_factory import get_nfo_factory
-                factory = get_nfo_factory()
-                self.nfo_service = factory.create(
-                    tmdb_api_key=tmdb_api_key,
-                    anime_directory=anime_directory,
-                    image_size=image_size,
-                    auto_create=auto_create_nfo
-                )
-                logger.info("NFO service initialized (auto_create=%s, update=%s)",
-                           auto_create_nfo, update_on_scan)
-            except (ValueError, Exception) as e:  # pylint: disable=broad-except
-                logger.warning(
-                    "Failed to initialize NFO service: %s", str(e)
-                )
-                self.nfo_service = None
-        elif auto_create_nfo or update_on_scan:
-            logger.warning(
-                "NFO features requested but TMDB_API_KEY not provided. "
-                "NFO creation/updates will be skipped."
-            )
-    
-    @classmethod
-    def from_settings(cls) -> "SeriesManagerService":
-        """Create SeriesManagerService from application settings.
-        
-        Returns:
-            Configured SeriesManagerService instance
-        """
-        return cls(
-            anime_directory=settings.anime_directory,
-            tmdb_api_key=settings.tmdb_api_key,
-            auto_create_nfo=settings.nfo_auto_create,
-            update_on_scan=settings.nfo_update_on_scan,
-            download_poster=settings.nfo_download_poster,
-            download_logo=settings.nfo_download_logo,
-            download_fanart=settings.nfo_download_fanart,
-            image_size=settings.nfo_image_size
-        )
-    
-    async def process_nfo_for_series(
-        self,
-        serie_folder: str,
-        serie_name: str,
-        serie_key: str,
-        year: Optional[int] = None
-    ):
-        """Process NFO file for a series (create or update).
-        
-        Args:
-            serie_folder: Series folder name
-            serie_name: Series display name
-            serie_key: Series unique identifier for database updates
-            year: Release year (helps with TMDB matching)
-        """
-        if not self.nfo_service:
-            return
-        
-        try:
-            folder_path = Path(self.anime_directory) / serie_folder
-            nfo_path = folder_path / "tvshow.nfo"
-            nfo_exists = await self.nfo_service.check_nfo_exists(serie_folder)
-            
-            # If NFO exists, parse IDs and update database
-            if nfo_exists:
-                logger.debug(f"Parsing IDs from existing NFO for '{serie_name}'")
-                ids = self.nfo_service.parse_nfo_ids(nfo_path)
-                
-                if ids["tmdb_id"] or ids["tvdb_id"]:
-                    # Update database using service layer
-                    from datetime import datetime, timezone
-
-                    from src.server.database.connection import get_db_session
-                    from src.server.database.service import AnimeSeriesService
-                    
-                    async with get_db_session() as db:
-                        series = await AnimeSeriesService.get_by_key(db, serie_key)
-                        
-                        if series:
-                            now = datetime.now(timezone.utc)
-                            
-                            # Prepare update fields
-                            update_fields = {
-                                "has_nfo": True,
-                                "nfo_updated_at": now,
-                            }
-                            
-                            if series.nfo_created_at is None:
-                                update_fields["nfo_created_at"] = now
-                            
-                            if ids["tmdb_id"] is not None:
-                                update_fields["tmdb_id"] = ids["tmdb_id"]
-                                logger.debug(
-                                    f"Updated TMDB ID for '{serie_name}': "
-                                    f"{ids['tmdb_id']}"
-                                )
-                            
-                            if ids["tvdb_id"] is not None:
-                                update_fields["tvdb_id"] = ids["tvdb_id"]
-                                logger.debug(
-                                    f"Updated TVDB ID for '{serie_name}': "
-                                    f"{ids['tvdb_id']}"
-                                )
-                            
-                            # Use service layer for update
-                            await AnimeSeriesService.update(db, series.id, **update_fields)
-                            await db.commit()
-                            
-                            logger.info(
-                                f"Updated database with IDs from NFO for "
-                                f"'{serie_name}' - TMDB: {ids['tmdb_id']}, "
-                                f"TVDB: {ids['tvdb_id']}"
-                            )
-                        else:
-                            logger.warning(
-                                f"Series not found in database for NFO ID "
-                                f"update: {serie_key}"
-                            )
-            
-            # Create NFO file only if it doesn't exist and auto_create enabled
-            if not nfo_exists and self.auto_create_nfo:
-                logger.info(
-                    f"Creating NFO for '{serie_name}' ({serie_folder})"
-                )
-                await self.nfo_service.create_tvshow_nfo(
-                    serie_name=serie_name,
-                    serie_folder=serie_folder,
-                    year=year,
-                    download_poster=self.download_poster,
-                    download_logo=self.download_logo,
-                    download_fanart=self.download_fanart
-                )
-                logger.info(f"Successfully created NFO for '{serie_name}'")
-            elif nfo_exists:
-                logger.debug(
-                    f"NFO exists for '{serie_name}', skipping download"
-                )
-                    
-        except TMDBAPIError as e:
-            logger.error(f"TMDB API error processing '{serie_name}': {e}")
-        except Exception as e:
-            logger.error(
-                f"Unexpected error processing NFO for '{serie_name}': {e}",
-                exc_info=True
-            )
-    
-    async def scan_and_process_nfo(self):
-        """Scan all series and process NFO files based on configuration.
-        
-        This method:
-        1. Loads series from database (avoiding filesystem scan)
-        2. For each series with existing NFO, reads TMDB/TVDB IDs
-           and updates database
-        3. For each series without NFO (if auto_create=True), creates one
-        4. For each series with NFO (if update_on_scan=True), updates it
-        5. Runs operations concurrently for better performance
-        """
-        if not self.nfo_service:
-            logger.info("NFO service not enabled, skipping NFO processing")
-            return
-        
-        # Import database dependencies
-        from src.server.database.connection import get_db_session
-        from src.server.database.service import AnimeSeriesService
-
-        # Load series from database (not from filesystem)
-        async with get_db_session() as db:
-            anime_series_list = await AnimeSeriesService.get_all(
-                db, with_episodes=False
-            )
-        
-        if not anime_series_list:
-            logger.info("No series found in database to process")
-            return
-        
-        logger.info(f"Processing NFO for {len(anime_series_list)} series...")
-        
-        # Create tasks for concurrent processing
-        # Each task creates its own database session
-        tasks = []
-        for anime_series in anime_series_list:
-            # Extract year if available
-            year = getattr(anime_series, 'year', None)
-            
-            task = self.process_nfo_for_series(
-                serie_folder=anime_series.folder,
-                serie_name=anime_series.name,
-                serie_key=anime_series.key,
-                year=year
-            )
-            tasks.append(task)
-        
-        # Process in batches to avoid overwhelming TMDB API
-        batch_size = 5
-        for i in range(0, len(tasks), batch_size):
-            batch = tasks[i:i + batch_size]
-            await asyncio.gather(*batch, return_exceptions=True)
-            
-            # Small delay between batches to respect rate limits
-            if i + batch_size < len(tasks):
-                await asyncio.sleep(2)
-    
-    async def close(self):
-        """Clean up resources."""
-        if self.nfo_service:
-            await self.nfo_service.close()

src/infrastructure/security/config_encryption.py

@@ -36,10 +36,10 @@ class ConfigEncryption:
     def _ensure_key_exists(self) -> None:
         """Ensure encryption key exists or create one."""
         if not self.key_file.exists():
-            logger.info(f"Creating new encryption key at {self.key_file}")
+            logger.info("Creating new encryption key at %s", self.key_file)
             self._generate_new_key()
         else:
-            logger.info(f"Using existing encryption key from {self.key_file}")
+            logger.info("Using existing encryption key from %s", self.key_file)
 
     def _generate_new_key(self) -> None:
         """Generate and store a new encryption key."""
@@ -56,7 +56,7 @@ class ConfigEncryption:
             logger.info("Generated new encryption key")
 
         except IOError as e:
-            logger.error(f"Failed to generate encryption key: {e}")
+            logger.error("Failed to generate encryption key: %s", e)
             raise
 
     def _load_key(self) -> bytes:
@@ -77,7 +77,7 @@ class ConfigEncryption:
             key = self.key_file.read_bytes()
             return key
         except IOError as e:
-            logger.error(f"Failed to load encryption key: {e}")
+            logger.error("Failed to load encryption key: %s", e)
             raise
 
     def _get_cipher(self) -> Fernet:
@@ -117,7 +117,7 @@ class ConfigEncryption:
             return encrypted_str
 
         except Exception as e:
-            logger.error(f"Failed to encrypt value: {e}")
+            logger.error("Failed to encrypt value: %s", e)
             raise
 
     def decrypt_value(self, encrypted_value: str) -> str:
@@ -149,7 +149,7 @@ class ConfigEncryption:
             return decrypted_str
 
         except Exception as e:
-            logger.error(f"Failed to decrypt value: {e}")
+            logger.error("Failed to decrypt value: %s", e)
             raise
 
     def encrypt_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
@@ -191,9 +191,9 @@ class ConfigEncryption:
                         'encrypted': True,
                         'value': self.encrypt_value(value)
                     }
-                    logger.debug(f"Encrypted config field: {key}")
+                    logger.debug("Encrypted config field: %s", key)
                 except Exception as e:
-                    logger.warning(f"Failed to encrypt {key}: {e}")
+                    logger.warning("Failed to encrypt %s: %s", key, e)
                     encrypted_config[key] = value
             else:
                 encrypted_config[key] = value
@@ -222,9 +222,9 @@ class ConfigEncryption:
                     decrypted_config[key] = self.decrypt_value(
                         value['value']
                     )
-                    logger.debug(f"Decrypted config field: {key}")
+                    logger.debug("Decrypted config field: %s", key)
                 except Exception as e:
-                    logger.error(f"Failed to decrypt {key}: {e}")
+                    logger.error("Failed to decrypt %s: %s", key, e)
                     decrypted_config[key] = None
             else:
                 decrypted_config[key] = value
@@ -248,7 +248,7 @@ class ConfigEncryption:
         if self.key_file.exists():
             backup_path = self.key_file.with_suffix('.key.bak')
             self.key_file.rename(backup_path)
-            logger.info(f"Backed up old key to {backup_path}")
+            logger.info("Backed up old key to %s", backup_path)
 
         # Generate new key
         if new_key_file:

src/infrastructure/security/database_integrity.py

@@ -276,13 +276,13 @@ class DatabaseIntegrityChecker:
                 removed += 1
 
             self.session.commit()
-            logger.info(f"Removed {removed} orphaned records")
+            logger.info("Removed %s orphaned records", removed)
 
             return removed
 
         except Exception as e:
             self.session.rollback()
-            logger.error(f"Error removing orphaned records: {e}")
+            logger.error("Error removing orphaned records: %s", e)
             raise
 
 

src/infrastructure/security/file_integrity.py

@@ -39,13 +39,15 @@ class FileIntegrityManager:
                     self.checksums = json.load(f)
                 count = len(self.checksums)
                 logger.info(
-                    f"Loaded {count} checksums from {self.checksum_file}"
+                    "Loaded %d checksums from %s",
+                    count,
+                    self.checksum_file,
                 )
             except (json.JSONDecodeError, IOError) as e:
-                logger.error(f"Failed to load checksums: {e}")
+                logger.error("Failed to load checksums: %s", e)
                 self.checksums = {}
         else:
-            logger.info(f"Checksum file does not exist: {self.checksum_file}")
+            logger.info("Checksum file does not exist: %s", self.checksum_file)
             self.checksums = {}
 
     def _save_checksums(self) -> None:
@@ -56,10 +58,12 @@ class FileIntegrityManager:
                 json.dump(self.checksums, f, indent=2)
             count = len(self.checksums)
             logger.debug(
-                f"Saved {count} checksums to {self.checksum_file}"
+                "Saved %d checksums to %s",
+                count,
+                self.checksum_file,
             )
         except IOError as e:
-            logger.error(f"Failed to save checksums: {e}")
+            logger.error("Failed to save checksums: %s", e)
 
     def calculate_checksum(
         self, file_path: Path, algorithm: str = "sha256"
@@ -94,12 +98,15 @@ class FileIntegrityManager:
             checksum = hash_obj.hexdigest()
             filename = file_path.name
             logger.debug(
-                f"Calculated {algorithm} checksum for {filename}: {checksum}"
+                "Calculated %s checksum for %s: %s",
+                algorithm,
+                filename,
+                checksum,
             )
             return checksum
         
         except IOError as e:
-            logger.error(f"Failed to read file {file_path}: {e}")
+            logger.error("Failed to read file %s: %s", file_path, e)
             raise
 
     def store_checksum(
@@ -126,7 +133,7 @@ class FileIntegrityManager:
         self.checksums[key] = checksum
         self._save_checksums()
         
-        logger.info(f"Stored checksum for {file_path.name}")
+        logger.info("Stored checksum for %s", file_path.name)
         return checksum
 
     def verify_checksum(
@@ -197,10 +204,10 @@ class FileIntegrityManager:
         if key in self.checksums:
             del self.checksums[key]
             self._save_checksums()
-            logger.info(f"Removed checksum for {file_path.name}")
+            logger.info("Removed checksum for %s", file_path.name)
             return True
         else:
-            logger.debug(f"No checksum found to remove for {file_path.name}")
+            logger.debug("No checksum found to remove for %s", file_path.name)
             return False
 
     def has_checksum(self, file_path: Path) -> bool:

src/server/SeriesApp.py

@@ -14,17 +14,15 @@ import asyncio
 import logging
 import os
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from events import Events
 
 from src.config.settings import settings
-from src.core.entities.SerieList import SerieList
-from src.core.entities.series import Serie
-from src.core.providers.provider_factory import Loaders
-from src.core.SerieScanner import SerieScanner
-from src.core.services.nfo_service import NFOService
-from src.core.services.tmdb_client import TMDBAPIError
+from src.server.database.SerieList import SerieList
+from src.server.database.models import AnimeSeries
+from src.server.providers.provider_factory import Loaders
+from src.server.SerieScanner import SerieScanner
 
 logger = logging.getLogger(__name__)
 
@@ -162,32 +160,21 @@ class SeriesApp:
         self.loaders = Loaders()
         self.loader = self.loaders.GetLoader(key="aniworld.to")
         self.serie_scanner = SerieScanner(
-            directory_to_search, self.loader
+            directory_to_search,
+            self.loader,
         )
-        # Skip automatic loading from data files - series will be loaded
-        # from database by the service layer during application setup
-        self.list = SerieList(self.directory_to_search, skip_load=True)
+        # Series will be loaded from database by the service layer during application setup
+        self.list = SerieList(self.directory_to_search)
         self.series_list: List[Any] = []
         # Initialize empty list - series loaded later via load_series_from_list()
         # No need to call _init_list_sync() anymore
         
-        # Initialize NFO service if TMDB API key is configured
-        self.nfo_service: Optional[NFOService] = None
-        if settings.tmdb_api_key:
-            try:
-                from src.core.services.nfo_factory import get_nfo_factory
-                factory = get_nfo_factory()
-                self.nfo_service = factory.create()
-                logger.info("NFO service initialized successfully")
-            except (ValueError, Exception) as e:  # pylint: disable=broad-except
-                logger.warning(
-                    "Failed to initialize NFO service: %s", str(e)
-                )
-                self.nfo_service = None
-
+        # NFO service removed - metadata handling moved to server layer
+        self.nfo_service = None
+        
         logger.info(
             "SeriesApp initialized for directory: %s",
-            directory_to_search
+            directory_to_search,
         )
 
     @property
@@ -346,101 +333,15 @@ class SeriesApp:
                 )
                 return False
 
-        # Check and create NFO files if needed
-        if self.nfo_service and settings.nfo_auto_create:
-            try:
-                # Check if NFO exists
-                nfo_exists = await self.nfo_service.check_nfo_exists(
-                    serie_folder
-                )
-                
-                if not nfo_exists:
-                    logger.info(
-                        "NFO not found for %s, creating metadata...",
-                        serie_folder
-                    )
-                    
-                    # Fire NFO creation started event
-                    self._events.download_status(
-                        DownloadStatusEventArgs(
-                            serie_folder=serie_folder,
-                            key=key,
-                            season=season,
-                            episode=episode,
-                            status="nfo_creating",
-                            message="Creating NFO metadata...",
-                            item_id=item_id,
-                        )
-                    )
-                    
-                    # Create NFO and download media files
-                    try:
-                        # Use folder name as series name
-                        await self.nfo_service.create_tvshow_nfo(
-                            serie_name=serie_folder,
-                            serie_folder=serie_folder,
-                            download_poster=settings.nfo_download_poster,
-                            download_logo=settings.nfo_download_logo,
-                            download_fanart=settings.nfo_download_fanart
-                        )
-                        
-                        logger.info(
-                            "NFO and media files created for %s",
-                            serie_folder
-                        )
-                        
-                        # Fire NFO creation completed event
-                        self._events.download_status(
-                            DownloadStatusEventArgs(
-                                serie_folder=serie_folder,
-                                key=key,
-                                season=season,
-                                episode=episode,
-                                status="nfo_completed",
-                                message="NFO metadata created",
-                                item_id=item_id,
-                            )
-                        )
-                        
-                    except TMDBAPIError as tmdb_error:
-                        logger.warning(
-                            "Failed to create NFO for %s: %s",
-                            serie_folder,
-                            str(tmdb_error)
-                        )
-                        # Fire failed event (but continue with download)
-                        self._events.download_status(
-                            DownloadStatusEventArgs(
-                                serie_folder=serie_folder,
-                                key=key,
-                                season=season,
-                                episode=episode,
-                                status="nfo_failed",
-                                message=(
-                                    f"NFO creation failed: "
-                                    f"{str(tmdb_error)}"
-                                ),
-                                item_id=item_id,
-                            )
-                        )
-                else:
-                    logger.debug("NFO already exists for %s", serie_folder)
-                    
-            except Exception as nfo_error:  # pylint: disable=broad-except
-                logger.error(
-                    "Error checking/creating NFO for %s: %s",
-                    serie_folder,
-                    str(nfo_error),
-                    exc_info=True
-                )
-                # Don't fail the download if NFO creation fails
-
         try:
             def download_progress_handler(progress_info):
                 """Handle download progress events from loader."""
-                logger.debug(
-                    "download_progress_handler called with: %s", progress_info
-                )
+                # Throttle progress logging to avoid spam
+                status = progress_info.get("status", "")
+                if status in ("downloading", "finished"):
+                    logger.debug(
+                        "download_progress_handler called with: %s", progress_info
+                    )
 
                 downloaded = progress_info.get('downloaded_bytes', 0)
                 total_bytes = (
@@ -752,7 +653,7 @@ class SeriesApp:
         """
         await self._init_list()
     
-    def _get_serie_by_key(self, key: str) -> Optional[Serie]:
+    def _get_serie_by_key(self, key: str) -> Optional[AnimeSeries]:
         """
         Get a series by its unique provider key.
         
@@ -763,7 +664,7 @@ class SeriesApp:
                 "attack-on-titan")
             
         Returns:
-            The Serie instance if found, None otherwise
+            The AnimeSeries instance if found, None otherwise
             
         Note:
             This method uses the SerieList.get_by_key() method which
@@ -771,39 +672,40 @@ class SeriesApp:
         """
         return self.list.get_by_key(key)
 
-    def get_all_series_from_data_files(self) -> List[Serie]:
+    def get_all_series_from_data_files(self) -> List[AnimeSeries]:
         """
         Get all series from data files in the anime directory.
 
         Scans the directory_to_search for all 'data' files and loads
-        the Serie metadata from each file. This method is synchronous
+        the AnimeSeries metadata from each file. This method is synchronous
         and can be wrapped with asyncio.to_thread if needed for async
         contexts.
 
         Returns:
-            List of Serie objects found in data files. Returns an empty
+            List of AnimeSeries objects found in data files. Returns an empty
             list if no data files are found or if the directory doesn't
             exist.
 
         Example:
             series_app = SeriesApp("/path/to/anime")
             all_series = series_app.get_all_series_from_data_files()
-            for serie in all_series:
-                print(f"Found: {serie.name} (key={serie.key})")
+            for anime in all_series:
+                print(f"Found: {anime.name} (key={anime.key})")
         """
         logger.info(
             "Scanning for data files in directory: %s",
             self.directory_to_search
         )
 
-        # Create a fresh SerieList instance for file-based loading
-        # This ensures we get all series from data files without
-        # interfering with the main instance's state
+        all_series: List[AnimeSeries] = []
+
         try:
-            temp_list = SerieList(
-                self.directory_to_search,
-                skip_load=False  # Allow automatic loading
-            )
+            if not os.path.isdir(self.directory_to_search):
+                logger.warning(
+                    "Directory does not exist: %s",
+                    self.directory_to_search
+                )
+                return []
         except (OSError, ValueError) as e:
             logger.error(
                 "Failed to scan directory for data files: %s",
@@ -812,8 +714,53 @@ class SeriesApp:
             )
             return []
 
-        # Get all series from the temporary list
-        all_series = temp_list.get_all()
+        try:
+            for folder_name in os.listdir(self.directory_to_search):
+                folder_path = os.path.join(
+                    self.directory_to_search, folder_name
+                )
+                if not os.path.isdir(folder_path):
+                    continue
+
+                data_file = os.path.join(folder_path, "data")
+                if not os.path.isfile(data_file):
+                    continue
+
+                series_data = _load_data_file(data_file)
+                if series_data is None:
+                    continue
+
+                key = series_data.get("key")
+                if not key:
+                    logger.warning(
+                        "Data file missing key, skipping: %s",
+                        data_file
+                    )
+                    continue
+
+                anime = AnimeSeries(
+                    key=key,
+                    name=series_data.get("name") or folder_name,
+                    site=series_data.get("site", "https://aniworld.to"),
+                    folder=series_data.get("folder", folder_name),
+                    year=series_data.get("year"),
+                )
+
+                episode_dict = series_data.get("episodeDict", {})
+                if episode_dict:
+                    anime._episode_dict_cache = {
+                        int(season): episodes
+                        for season, episodes in episode_dict.items()
+                    }
+
+                all_series.append(anime)
+        except (OSError, ValueError) as e:
+            logger.error(
+                "Failed to scan directory for data files: %s",
+                str(e),
+                exc_info=True
+            )
+            return []
 
         logger.info(
             "Found %d series from data files in %s",
@@ -833,3 +780,38 @@ class SeriesApp:
         if hasattr(self, 'executor'):
             self.executor.shutdown(wait=True)
             logger.info("ThreadPoolExecutor shut down successfully")
+
+
+def _load_data_file(data_file_path: str) -> Optional[dict]:
+    """Load and parse a legacy 'data' file (JSON).
+
+    Args:
+        data_file_path: Path to the data file
+
+    Returns:
+        Parsed data dict or None if parsing fails
+    """
+    import json
+
+    try:
+        with open(data_file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        if not isinstance(data, dict):
+            logger.warning("Data file is not a dictionary: %s", data_file_path)
+            return None
+
+        return data
+
+    except json.JSONDecodeError as e:
+        logger.warning(
+            "Failed to parse legacy data file (JSON error): %s - %s",
+            data_file_path, str(e)
+        )
+        return None
+    except Exception as e:
+        logger.warning(
+            "Failed to read legacy data file: %s - %s",
+            data_file_path, str(e)
+        )
+        return None

src/server/api/anime.py

@@ -1,4 +1,5 @@
 import logging
+import re
 import warnings
 from typing import Any, List, Optional
 
@@ -6,7 +7,8 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel, Field
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.core.entities.series import Serie
+from src.config.settings import settings
+from src.server.database.models import AnimeSeries
 from src.server.database.service import AnimeSeriesService
 from src.server.exceptions import (
     BadRequestError,
@@ -14,16 +16,19 @@ from src.server.exceptions import (
     ServerError,
     ValidationError,
 )
+from src.server.models.anime import AnimeMetadataUpdate
 from src.server.services.anime_service import AnimeService, AnimeServiceError
 from src.server.services.background_loader_service import BackgroundLoaderService
 from src.server.utils.dependencies import (
     get_anime_service,
     get_background_loader_service,
+    get_database_session,
     get_optional_database_session,
     get_series_app,
     require_auth,
 )
 from src.server.utils.filesystem import sanitize_folder_name
+from src.server.utils.key_utils import generate_key_from_folder, is_valid_key
 from src.server.utils.validators import validate_filter_value, validate_search_query
 
 logger = logging.getLogger(__name__)
@@ -31,6 +36,31 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/anime", tags=["anime"])
 
 
+def _compute_folder_name(name: str, year: Optional[int]) -> str:
+    """Compute sanitized folder name from display name and year.
+
+    If year is provided, strips any existing year in (YYYY) format to avoid
+    duplicates, then appends the new year. If year is None, preserves the
+    original name (with any existing year).
+
+    Args:
+        name: Display name of the series
+        year: Release year from provider, or None
+
+    Returns:
+        Sanitized folder name in format "Name (YYYY)" or just "Name"
+    """
+    if year:
+        # Strip any existing year in (YYYY) format before adding new year
+        clean_name = re.sub(r'\s*\(\d{4}\)\s*$', '', name).strip()
+        folder_name_with_year = f"{clean_name} ({year})"
+    else:
+        # No new year provided, preserve original name (with any existing year)
+        folder_name_with_year = name
+
+    return sanitize_folder_name(folder_name_with_year)
+
+
 @router.get("/status")
 async def get_anime_status(
     _auth: dict = Depends(require_auth),
@@ -70,6 +100,37 @@ async def get_anime_status(
         ) from exc
 
 
+class DuplicateFolderGroup(BaseModel):
+    """Placeholder - duplicates functionality removed."""
+    key: str = Field(..., description="Series key (unique identifier)")
+    folders: List[str] = Field(..., description="List of duplicate folder names")
+    folder_count: int = Field(..., description="Number of duplicate folders")
+
+
+class DuplicateFoldersResponse(BaseModel):
+    """Placeholder - duplicates functionality removed."""
+    total_groups: int = Field(..., description="Total number of duplicate groups")
+    duplicate_groups: List[DuplicateFolderGroup] = Field(
+        ..., description="List of duplicate folder groups"
+    )
+    message: str = Field(..., description="Human-readable summary")
+
+
+@router.get("/duplicate-folders", response_model=DuplicateFoldersResponse)
+async def get_duplicate_folders(
+    _auth: dict = Depends(require_auth),
+) -> DuplicateFoldersResponse:
+    """List all pre-existing duplicate folder groups.
+
+    Note: Duplicate folder scanning has been removed. Returns empty response.
+    """
+    return DuplicateFoldersResponse(
+        total_groups=0,
+        duplicate_groups=[],
+        message="Duplicate folder scanning has been removed.",
+    )
+
+
 class AnimeSummary(BaseModel):
     """Summary of an anime series with missing episodes.
     
@@ -236,8 +297,8 @@ async def list_anime(
         sort_by: Optional sorting parameter. Allowed: title, id, name,
             missing_episodes
         filter: Optional filter parameter. Allowed values:
-            - "no_episodes": Show only series with no downloaded
-              episodes in folder
+            - "missing_episodes": Show only series that have any missing episodes
+            - "no_episodes": Show only series that have no downloaded episodes
         _auth: Ensures the caller is authenticated (value unused)
         anime_service: AnimeService instance provided via dependency
 
@@ -298,7 +359,7 @@ async def list_anime(
     # Validate filter parameter
     if filter:
         try:
-            allowed_filters = ["no_episodes"]
+            allowed_filters = ["missing_episodes", "no_episodes"]
             validate_filter_value(filter, allowed_filters)
         except ValueError as e:
             raise ValidationError(message=str(e))
@@ -724,18 +785,13 @@ async def add_series(
         if series_app and hasattr(series_app, 'loader'):
             try:
                 year = series_app.loader.get_year(key)
-                logger.info(f"Fetched year for {key}: {year}")
+                logger.info("Fetched year for %s: %s", key, year)
             except Exception as e:
-                logger.warning(f"Could not fetch year for {key}: {e}")
-        
-        # Create folder name with year if available
-        if year:
-            folder_name_with_year = f"{name} ({year})"
-        else:
-            folder_name_with_year = name
+                logger.warning("Could not fetch year for %s: %s", key, e)
         
+        # Step B: Compute sanitized folder name with year (deduplicates if year already in name)
         try:
-            folder = sanitize_folder_name(folder_name_with_year)
+            folder = _compute_folder_name(name, year)
         except ValueError as e:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
@@ -744,7 +800,37 @@ async def add_series(
         
         db_id = None
         
-        # Step C: Save to database if available
+        # Step C: Create folder on disk if it doesn't exist, and rename if needed
+        # Determine the anime directory path
+        anime_dir = settings.anime_directory if hasattr(settings, 'anime_directory') else None
+        current_folder_on_disk = None
+        
+        if anime_dir:
+            import os
+            anime_path = os.path.join(anime_dir, folder)
+            
+            # Check if an existing folder (without year) needs renaming
+            # Look for folder that matches name without year
+            if year:
+                potential_old_name = sanitize_folder_name(name)
+                potential_old_path = os.path.join(anime_dir, potential_old_name)
+                if potential_old_path != anime_path and os.path.exists(potential_old_path):
+                    current_folder_on_disk = potential_old_name
+                    logger.info(
+                        "Found existing folder without year for %s: %s, renaming to %s",
+                        key,
+                        potential_old_name,
+                        folder
+                    )
+                elif not os.path.exists(anime_path):
+                    # No existing folder to rename, create new one
+                    os.makedirs(anime_path, exist_ok=True)
+            else:
+                # No year, just ensure folder exists
+                if not os.path.exists(anime_path):
+                    os.makedirs(anime_path, exist_ok=True)
+        
+        # Step D: Save to database if available
         if db is not None:
             # Check if series already exists in database
             existing = await AnimeSeriesService.get_by_key(db, key)
@@ -790,18 +876,18 @@ async def add_series(
         
         # Step D: Add to SerieList (in-memory only, no folder creation)
         if series_app and hasattr(series_app, "list"):
-            serie = Serie(
+            from src.server.database.models import AnimeSeries
+            anime = AnimeSeries(
                 key=key,
                 name=name,
                 site="aniworld.to",
                 folder=folder,
-                episodeDict={},
                 year=year
             )
-            
+
             # Add to in-memory cache without creating folder on disk
             if hasattr(series_app.list, 'keyDict'):
-                series_app.list.keyDict[key] = serie
+                series_app.list.keyDict[key] = anime
                 logger.info(
                     "Added series to in-memory cache: %s (key=%s, folder=%s, year=%s)",
                     name,
@@ -810,7 +896,32 @@ async def add_series(
                     year
                 )
         
-        # Step E: Queue background loading task for episodes, NFO, and images
+        # Step E: Rename existing folder if needed (e.g., folder existed without year)
+        if current_folder_on_disk:
+            try:
+                renamed = await anime_service.rename_folder_if_needed(
+                    key=key,
+                    current_folder=current_folder_on_disk,
+                    target_folder=folder,
+                    db=db
+                )
+                if renamed:
+                    logger.info(
+                        "Successfully renamed folder for %s: %s -> %s",
+                        key,
+                        current_folder_on_disk,
+                        folder
+                    )
+            except Exception as e:
+                logger.warning(
+                    "Failed to rename folder for %s: %s -> %s: %s",
+                    key,
+                    current_folder_on_disk,
+                    folder,
+                    e
+                )
+        
+        # Step F: Queue background loading task for episodes, NFO, and images
         try:
             await background_loader.add_series_loading_task(
                 key=key,
@@ -831,12 +942,12 @@ async def add_series(
                 e
             )
 
-        # Step F: Scan missing episodes immediately if background loader is not running
+        # Step G: Scan missing episodes immediately if background loader is not running
         # Uses existing SerieScanner and AnimeService sync to avoid duplicates
         try:
-            loader_running = (
-                background_loader.worker_task is not None
-                and not background_loader.worker_task.done()
+            loader_running = bool(
+                background_loader.worker_tasks
+                and any(not t.done() for t in background_loader.worker_tasks)
             )
             if (
                 not loader_running
@@ -1084,3 +1195,75 @@ async def get_anime(
 # Maximum allowed input size for security
 MAX_INPUT_LENGTH = 100000  # 100KB
 
+
+@router.put("/{anime_key}")
+async def update_anime_metadata(
+    anime_key: str,
+    body: AnimeMetadataUpdate,
+    _auth: dict = Depends(require_auth),
+    db: AsyncSession = Depends(get_database_session),
+) -> dict:
+    """Update anime metadata (key, tmdb_id, tvdb_id).
+
+    Args:
+        anime_key: Current series key to update
+        body: Fields to update (all optional)
+        _auth: Authentication dependency
+        db: Database session
+
+    Returns:
+        Updated series metadata
+
+    Raises:
+        HTTPException 404: Series not found
+        HTTPException 409: Key conflict (new key already exists)
+        HTTPException 422: Validation error
+    """
+    series = await AnimeSeriesService.get_by_key(db, anime_key)
+    if not series:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Series with key '{anime_key}' not found",
+        )
+
+    updates = {}
+
+    if body.key is not None and body.key != anime_key:
+        existing = await AnimeSeriesService.get_by_key(db, body.key)
+        if existing:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"A series with key '{body.key}' already exists",
+            )
+        updates["key"] = body.key
+
+    if body.tmdb_id is not None:
+        updates["tmdb_id"] = body.tmdb_id
+
+    if body.tvdb_id is not None:
+        updates["tvdb_id"] = body.tvdb_id
+
+    if not updates:
+        return {
+            "key": series.key,
+            "tmdb_id": series.tmdb_id,
+            "tvdb_id": series.tvdb_id,
+            "message": "No changes",
+        }
+
+    updated = await AnimeSeriesService.update(db, series.id, **updates)
+    await db.commit()
+
+    logger.info(
+        "Updated metadata for '%s': %s",
+        anime_key,
+        updates,
+    )
+
+    return {
+        "key": updated.key,
+        "tmdb_id": updated.tmdb_id,
+        "tvdb_id": updated.tvdb_id,
+        "message": "Metadata updated successfully",
+    }
+

src/server/api/auth.py

@@ -161,6 +161,22 @@ async def setup_auth(req: SetupRequest):
                 # Perform NFO scan if configured
                 await perform_nfo_scan_if_needed(progress_service)
                 
+                # Start scheduler if anime_directory is now set
+                try:
+                    from src.server.services.scheduler.scheduler_service import (
+                        get_scheduler_service,
+                    )
+
+                    scheduler_svc = get_scheduler_service()
+                    logger.info("Starting scheduler after initialization")
+                    await scheduler_svc.ensure_started()
+                    logger.info("Scheduler started successfully during setup")
+                except Exception as sched_exc:
+                    logger.warning(
+                        "Failed to start scheduler during setup: %s", sched_exc
+                    )
+                    # Continue — scheduler failure should not break initialization
+                
                 # Send completion event
                 from src.server.services.progress_service import ProgressType
                 await progress_service.start_progress(

src/server/api/config.py

@@ -1,7 +1,10 @@
+import logging
 from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, status
 
+logger = logging.getLogger(__name__)
+
 from src.server.models.config import AppConfig, ConfigUpdate, ValidationResult
 from src.server.services.config_service import (
     ConfigBackupError,
@@ -28,16 +31,53 @@ def get_config(auth: Optional[dict] = Depends(require_auth)) -> AppConfig:
 
 
 @router.put("", response_model=AppConfig)
-def update_config(
+async def update_config(
     update: ConfigUpdate, auth: dict = Depends(require_auth)
 ) -> AppConfig:
     """Apply an update to the configuration and persist it.
 
-    Creates automatic backup before applying changes.
+    Creates automatic backup before applying changes. If anime_directory
+    is configured, starts the scheduler service.
     """
     try:
         config_service = get_config_service()
-        return config_service.update_config(update)
+        updated_config = config_service.update_config(update)
+
+        # Sync anime_directory to settings if it was updated
+        from src.config.settings import settings as app_settings
+
+        anime_dir_changed = False
+        if update.other and update.other.get("anime_directory"):
+            anime_dir = update.other.get("anime_directory")
+            if anime_dir and not app_settings.anime_directory:
+                app_settings.anime_directory = str(anime_dir)
+                anime_dir_changed = True
+                logger.info("Synced anime_directory from config: %s", anime_dir)
+
+        # Start scheduler if anime_directory was just configured
+        if anime_dir_changed:
+            try:
+                from src.server.services.scheduler.scheduler_service import (
+                    get_scheduler_service,
+                )
+
+                scheduler_svc = get_scheduler_service()
+                logger.info(
+                    "Starting scheduler after anime_directory configuration"
+                )
+                await scheduler_svc.ensure_started()
+                logger.info(
+                    "Scheduler started successfully after config update"
+                )
+            except Exception as sched_exc:
+                logger.warning(
+                    "Failed to start scheduler after config update: %s",
+                    sched_exc,
+                )
+                # Config was already saved, don't fail the request
+
+        return updated_config
+
     except ConfigValidationError as e:
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
@@ -244,9 +284,9 @@ async def update_directory(
         try:
             import structlog
 
-            from src.server.services.anime_service import sync_series_from_data_files
+            from src.server.services.anime_service import sync_legacy_series_to_db
             logger = structlog.get_logger(__name__)
-            sync_count = await sync_series_from_data_files(directory, logger)
+            sync_count = await sync_legacy_series_to_db(directory, logger)
             logger.info(
                 "Directory updated: synced series from data files",
                 directory=directory,

src/server/api/health.py

@@ -5,7 +5,7 @@ from datetime import datetime
 from typing import Any, Dict, Optional
 
 import psutil
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
 from pydantic import BaseModel
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -17,15 +17,21 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/health", tags=["health"])
 
 
+from src.server.utils.version import APP_VERSION
+
+
 class HealthStatus(BaseModel):
     """Basic health status response."""
 
     status: str
     timestamp: str
-    version: str = "1.0.0"
+    version: str = APP_VERSION
     service: str = "aniworld-api"
     series_app_initialized: bool = False
     anime_directory_configured: bool = False
+    scheduler_next_run: Optional[str] = None
+    scheduler_last_run: Optional[str] = None
+    checks: Optional[Dict[str, Any]] = None
 
 
 class DatabaseHealth(BaseModel):
@@ -60,7 +66,7 @@ class DetailedHealthStatus(BaseModel):
 
     status: str
     timestamp: str
-    version: str = "1.0.0"
+    version: str = APP_VERSION
     dependencies: DependencyHealth
     startup_time: datetime
 
@@ -91,7 +97,7 @@ async def check_database_health(db: AsyncSession) -> DatabaseHealth:
             message="Database connection successful",
         )
     except Exception as e:
-        logger.error(f"Database health check failed: {e}")
+        logger.error("Database health check failed: %s", e)
         return DatabaseHealth(
             status="unhealthy",
             connection_time_ms=0,
@@ -121,7 +127,7 @@ async def check_filesystem_health() -> Dict[str, Any]:
             "message": "Filesystem check completed",
         }
     except Exception as e:
-        logger.error(f"Filesystem health check failed: {e}")
+        logger.error("Filesystem health check failed: %s", e)
         return {
             "status": "unhealthy",
             "message": f"Filesystem check failed: {str(e)}",
@@ -164,36 +170,99 @@ def get_system_metrics() -> SystemMetrics:
             uptime_seconds=uptime_seconds,
         )
     except Exception as e:
-        logger.error(f"System metrics collection failed: {e}")
+        logger.error("System metrics collection failed: %s", e)
         raise HTTPException(
             status_code=500, detail=f"Failed to collect system metrics: {str(e)}"
         )
 
 
 @router.get("", response_model=HealthStatus)
-async def basic_health_check() -> HealthStatus:
+async def basic_health_check(request: Request) -> HealthStatus:
     """Basic health check endpoint.
     
     This endpoint does not depend on anime_directory configuration
     and should always return 200 OK for basic health monitoring.
     Includes service information for identification.
+    Includes scheduler next/last run times for monitoring tools.
+    Includes startup health check results.
 
     Returns:
         HealthStatus: Simple health status with timestamp and service info.
     """
     from src.config.settings import settings
     from src.server.utils.dependencies import _series_app
+
+    # Get scheduler status for health monitoring
+    scheduler_status: dict = {}
+    try:
+        from src.server.services.scheduler.scheduler_service import (
+            get_scheduler_service,
+        )
+        scheduler_status = get_scheduler_service().get_status()
+    except Exception:
+        pass
+
+    # Get startup checks from app state
+    checks = getattr(request.app.state, "startup_checks", None)
+    
+    # Determine overall status based on checks
+    overall_status = "healthy"
+    if checks:
+        for check_name, check_data in checks.items():
+            if check_data.get("status") == "error":
+                overall_status = "unhealthy"
+                break
+            elif check_data.get("status") == "warning":
+                overall_status = "degraded"
     
     logger.debug("Basic health check requested")
     return HealthStatus(
-        status="healthy",
+        status=overall_status,
         timestamp=datetime.now().isoformat(),
         service="aniworld-api",
         series_app_initialized=_series_app is not None,
         anime_directory_configured=bool(settings.anime_directory),
+        scheduler_next_run=scheduler_status.get("next_run"),
+        scheduler_last_run=scheduler_status.get("last_run"),
+        checks=checks,
     )
 
 
+@router.get("/ready")
+async def ready_check(request: Request) -> Dict[str, Any]:
+    """Readiness check endpoint for container orchestrators.
+    
+    Returns 503 if critical dependencies are not available.
+    This endpoint is used by Kubernetes, Docker Swarm, etc. to determine
+    if the container should receive traffic.
+    
+    Returns:
+        dict: Readiness status with checks details.
+    """
+    checks = getattr(request.app.state, "startup_checks", {})
+    
+    critical_failures = []
+    for check_name, check_data in checks.items():
+        if check_data.get("status") == "error":
+            critical_failures.append(f"{check_name}: {check_data.get('message')}")
+    
+    if critical_failures:
+        return {
+            "status": "not_ready",
+            "ready": False,
+            "timestamp": datetime.now().isoformat(),
+            "critical_failures": critical_failures,
+            "checks": checks,
+        }
+    
+    return {
+        "status": "ready",
+        "ready": True,
+        "timestamp": datetime.now().isoformat(),
+        "checks": checks,
+    }
+
+
 @router.get("/detailed", response_model=DetailedHealthStatus)
 async def detailed_health_check(
     db: AsyncSession = Depends(get_database_session),
@@ -236,7 +305,7 @@ async def detailed_health_check(
             startup_time=startup_time,
         )
     except Exception as e:
-        logger.error(f"Detailed health check failed: {e}")
+        logger.error("Detailed health check failed: %s", e)
         raise HTTPException(status_code=500, detail="Health check failed")
 
 

src/server/api/nfo.py

@@ -1,758 +1,70 @@
 """NFO Management API endpoints.
 
-This module provides REST API endpoints for managing tvshow.nfo files
-and associated media (poster, logo, fanart).
+Note: NFO service has been removed. All NFO endpoints return 503.
 """
-import asyncio
-import logging
-from datetime import datetime
-from pathlib import Path
-from typing import List
-
-from fastapi import APIRouter, Depends, HTTPException, status
-
-from src.config.settings import settings
-from src.core.entities.series import Serie
-from src.core.SeriesApp import SeriesApp
-from src.core.services.nfo_factory import get_nfo_factory
-from src.core.services.nfo_service import NFOService
-from src.core.services.tmdb_client import TMDBAPIError
-from src.server.models.nfo import (
-    MediaDownloadRequest,
-    MediaFilesStatus,
-    NFOBatchCreateRequest,
-    NFOBatchCreateResponse,
-    NFOBatchResult,
-    NFOCheckResponse,
-    NFOContentResponse,
-    NFOCreateRequest,
-    NFOCreateResponse,
-    NFOMissingResponse,
-    NFOMissingSeries,
-)
-from src.server.utils.dependencies import get_series_app, require_auth
-from src.server.utils.media import check_media_files, get_media_file_paths
-
-logger = logging.getLogger(__name__)
+from fastapi import APIRouter, HTTPException, status
 
 router = APIRouter(prefix="/api/nfo", tags=["nfo"])
 
 
-async def get_nfo_service() -> NFOService:
-    """Get NFO service dependency.
-    
-    Returns:
-        NFOService instance
-        
-    Raises:
-        HTTPException: If NFO service not configured
-    """
-    try:
-        # Use centralized factory for consistent initialization
-        factory = get_nfo_factory()
-        return factory.create()
-    except ValueError as e:
-        # Factory raises ValueError if API key not configured
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail=str(e)
-        ) from e
-
-
-# =============================================================================
-# IMPORTANT: Literal path routes must be defined BEFORE path parameter routes
-# to avoid route matching conflicts. For example, /batch/create must come
-# before /{serie_id}/create, otherwise "batch" is treated as a serie_id.
-# =============================================================================
-
-
-@router.post("/batch/create", response_model=NFOBatchCreateResponse)
-async def batch_create_nfo(
-    request: NFOBatchCreateRequest,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOBatchCreateResponse:
-    """Batch create NFO files for multiple series.
-    
-    Args:
-        request: Batch creation options
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOBatchCreateResponse with results
-    """
-    results: List[NFOBatchResult] = []
-    successful = 0
-    failed = 0
-    skipped = 0
-    
-    # Get all series
-    series_list = series_app.list.GetList()
-    series_map = {
-        getattr(s, 'key', None): s
-        for s in series_list
-        if getattr(s, 'key', None)
-    }
-    
-    # Process each series
-    semaphore = asyncio.Semaphore(request.max_concurrent)
-    
-    async def process_serie(serie_id: str) -> NFOBatchResult:
-        """Process a single series."""
-        async with semaphore:
-            try:
-                serie = series_map.get(serie_id)
-                if not serie:
-                    return NFOBatchResult(
-                        serie_id=serie_id,
-                        serie_folder="",
-                        success=False,
-                        message="Series not found"
-                    )
-                
-                # Ensure folder name includes year if available
-                serie_folder = serie.ensure_folder_with_year()
-                
-                # Check if NFO exists
-                if request.skip_existing:
-                    has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-                    if has_nfo:
-                        return NFOBatchResult(
-                            serie_id=serie_id,
-                            serie_folder=serie_folder,
-                            success=False,
-                            message="Skipped - NFO already exists"
-                        )
-                
-                # Create NFO
-                nfo_path = await nfo_service.create_tvshow_nfo(
-                    serie_name=serie.name or serie_folder,
-                    serie_folder=serie_folder,
-                    download_poster=request.download_media,
-                    download_logo=request.download_media,
-                    download_fanart=request.download_media
-                )
-                
-                return NFOBatchResult(
-                    serie_id=serie_id,
-                    serie_folder=serie_folder,
-                    success=True,
-                    message="NFO created successfully",
-                    nfo_path=str(nfo_path)
-                )
-                
-            except Exception as e:
-                logger.error(
-                    f"Error creating NFO for {serie_id}: {e}",
-                    exc_info=True
-                )
-                return NFOBatchResult(
-                    serie_id=serie_id,
-                    serie_folder=serie.folder if serie else "",
-                    success=False,
-                    message=f"Error: {str(e)}"
-                )
-    
-    # Process all series concurrently
-    tasks = [process_serie(sid) for sid in request.serie_ids]
-    results = await asyncio.gather(*tasks)
-    
-    # Count results
-    for result in results:
-        if result.success:
-            successful += 1
-        elif "Skipped" in result.message:
-            skipped += 1
-        else:
-            failed += 1
-    
-    return NFOBatchCreateResponse(
-        total=len(request.serie_ids),
-        successful=successful,
-        failed=failed,
-        skipped=skipped,
-        results=list(results)
+@router.get("/disabled")
+async def nfo_disabled():
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
     )
 
 
-@router.get("/missing", response_model=NFOMissingResponse)
-async def get_missing_nfo(
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOMissingResponse:
-    """Get list of series without NFO files.
-    
-    Args:
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOMissingResponse with series list
-    """
-    try:
-        series_list = series_app.list.GetList()
-        missing_series: List[NFOMissingSeries] = []
-        
-        for serie in series_list:
-            serie_id = getattr(serie, 'key', None)
-            if not serie_id:
-                continue
-            
-            # Ensure folder name includes year if available
-            serie_folder = serie.ensure_folder_with_year()
-            has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-            
-            if not has_nfo:
-                # Build full path and check media files
-                folder_path = Path(settings.anime_directory) / serie_folder
-                media_status = check_media_files(folder_path)
-                file_paths = get_media_file_paths(folder_path)
-                
-                media_files = MediaFilesStatus(
-                    has_poster=media_status.get("poster", False),
-                    has_logo=media_status.get("logo", False),
-                    has_fanart=media_status.get("fanart", False),
-                    poster_path=str(file_paths["poster"]) if file_paths.get("poster") else None,
-                    logo_path=str(file_paths["logo"]) if file_paths.get("logo") else None,
-                    fanart_path=str(file_paths["fanart"]) if file_paths.get("fanart") else None
-                )
-                
-                has_media = (
-                    media_files.has_poster
-                    or media_files.has_logo
-                    or media_files.has_fanart
-                )
-                
-                missing_series.append(NFOMissingSeries(
-                    serie_id=serie_id,
-                    serie_folder=serie_folder,
-                    serie_name=serie.name or serie_folder,
-                    has_media=has_media,
-                    media_files=media_files
-                ))
-        
-        return NFOMissingResponse(
-            total_series=len(series_list),
-            missing_nfo_count=len(missing_series),
-            series=missing_series
-        )
-        
-    except Exception as e:
-        logger.error(f"Error getting missing NFOs: {e}", exc_info=True)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to get missing NFOs: {str(e)}"
-        ) from e
+@router.post("/batch/create")
+async def batch_create_nfo():
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )
 
 
-# =============================================================================
-# Series-specific endpoints (with {serie_id} path parameter)
-# These must come AFTER literal path routes like /batch/create and /missing
-# =============================================================================
+@router.post("/{serie_id}/create")
+async def create_nfo(serie_id: str):
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )
 
 
-@router.get("/{serie_id}/check", response_model=NFOCheckResponse)
-async def check_nfo(
-    serie_id: str,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOCheckResponse:
-    """Check if NFO and media files exist for a series.
-    
-    Args:
-        serie_id: Series identifier
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOCheckResponse with NFO and media status
-        
-    Raises:
-        HTTPException: If series not found
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Ensure folder name includes year if available
-        serie_folder = serie.ensure_folder_with_year()
-        folder_path = Path(settings.anime_directory) / serie_folder
-        
-        # Check NFO
-        has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-        nfo_path = None
-        if has_nfo:
-            nfo_path = str(folder_path / "tvshow.nfo")
-        
-        # Check media files using utility function
-        media_status = check_media_files(
-            folder_path,
-            check_poster=True,
-            check_logo=True,
-            check_fanart=True,
-            check_nfo=False  # Already checked above
-        )
-        
-        # Get file paths
-        file_paths = get_media_file_paths(folder_path)
-        
-        # Build MediaFilesStatus model
-        media_files = MediaFilesStatus(
-            has_poster=media_status.get("poster", False),
-            has_logo=media_status.get("logo", False),
-            has_fanart=media_status.get("fanart", False),
-            poster_path=str(file_paths["poster"]) if file_paths["poster"] else None,
-            logo_path=str(file_paths["logo"]) if file_paths["logo"] else None,
-            fanart_path=str(file_paths["fanart"]) if file_paths["fanart"] else None
-        )
-        
-        return NFOCheckResponse(
-            serie_id=serie_id,
-            serie_folder=serie_folder,
-            has_nfo=has_nfo,
-            nfo_path=nfo_path,
-            media_files=media_files
-        )
-        
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Error checking NFO for {serie_id}: {e}", exc_info=True)
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to check NFO: {str(e)}"
-        ) from e
+@router.get("/{serie_id}/status")
+async def get_nfo_status(serie_id: str):
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )
 
 
-@router.post("/{serie_id}/create", response_model=NFOCreateResponse)
-async def create_nfo(
-    serie_id: str,
-    request: NFOCreateRequest,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOCreateResponse:
-    """Create NFO file and download media for a series.
-    
-    Args:
-        serie_id: Series identifier
-        request: NFO creation options
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOCreateResponse with creation result
-        
-    Raises:
-        HTTPException: If series not found or creation fails
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Ensure folder name includes year if available
-        serie_folder = serie.ensure_folder_with_year()
-        
-        # If year not provided in request but serie has year, use it
-        year = request.year or serie.year
-        
-        # Check if NFO already exists
-        if not request.overwrite_existing:
-            has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-            if has_nfo:
-                raise HTTPException(
-                    status_code=status.HTTP_409_CONFLICT,
-                    detail="NFO already exists. Use overwrite_existing=true"
-                )
-        
-        # Create NFO
-        serie_name = request.serie_name or serie.name or serie_folder
-        nfo_path = await nfo_service.create_tvshow_nfo(
-            serie_name=serie_name,
-            serie_folder=serie_folder,
-            year=year,
-            download_poster=request.download_poster,
-            download_logo=request.download_logo,
-            download_fanart=request.download_fanart
-        )
-        
-        # Check media files
-        folder_path = Path(settings.anime_directory) / serie_folder
-        media_status = check_media_files(folder_path)
-        file_paths = get_media_file_paths(folder_path)
-        
-        media_files = MediaFilesStatus(
-            has_poster=media_status.get("poster", False),
-            has_logo=media_status.get("logo", False),
-            has_fanart=media_status.get("fanart", False),
-            poster_path=str(file_paths["poster"]) if file_paths.get("poster") else None,
-            logo_path=str(file_paths["logo"]) if file_paths.get("logo") else None,
-            fanart_path=str(file_paths["fanart"]) if file_paths.get("fanart") else None
-        )
-        
-        return NFOCreateResponse(
-            serie_id=serie_id,
-            serie_folder=serie_folder,
-            nfo_path=str(nfo_path),
-            media_files=media_files,
-            message="NFO and media files created successfully"
-        )
-        
-    except HTTPException:
-        raise
-    except TMDBAPIError as e:
-        logger.warning(f"TMDB API error creating NFO for {serie_id}: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail=f"TMDB API error: {str(e)}"
-        ) from e
-    except Exception as e:
-        logger.error(
-            f"Error creating NFO for {serie_id}: {e}",
-            exc_info=True
-        )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to create NFO: {str(e)}"
-        ) from e
+@router.delete("/{serie_id}/delete")
+async def delete_nfo(serie_id: str):
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )
 
 
-@router.put("/{serie_id}/update", response_model=NFOCreateResponse)
-async def update_nfo(
-    serie_id: str,
-    download_media: bool = True,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOCreateResponse:
-    """Update existing NFO file with fresh TMDB data.
-    
-    Args:
-        serie_id: Series identifier
-        download_media: Whether to re-download media files
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOCreateResponse with update result
-        
-    Raises:
-        HTTPException: If series or NFO not found
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Ensure folder name includes year if available
-        serie_folder = serie.ensure_folder_with_year()
-        
-        # Check if NFO exists
-        has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-        if not has_nfo:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="NFO file not found. Use create endpoint instead."
-            )
-        
-        # Update NFO
-        nfo_path = await nfo_service.update_tvshow_nfo(
-            serie_folder=serie_folder,
-            download_media=download_media
-        )
-        
-        # Check media files
-        folder_path = Path(settings.anime_directory) / serie_folder
-        media_status = check_media_files(folder_path)
-        file_paths = get_media_file_paths(folder_path)
-        
-        media_files = MediaFilesStatus(
-            has_poster=media_status.get("poster", False),
-            has_logo=media_status.get("logo", False),
-            has_fanart=media_status.get("fanart", False),
-            poster_path=str(file_paths["poster"]) if file_paths.get("poster") else None,
-            logo_path=str(file_paths["logo"]) if file_paths.get("logo") else None,
-            fanart_path=str(file_paths["fanart"]) if file_paths.get("fanart") else None
-        )
-        
-        return NFOCreateResponse(
-            serie_id=serie_id,
-            serie_folder=serie_folder,
-            nfo_path=str(nfo_path),
-            media_files=media_files,
-            message="NFO updated successfully"
-        )
-        
-    except HTTPException:
-        raise
-    except TMDBAPIError as e:
-        logger.warning(f"TMDB API error updating NFO for {serie_id}: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail=f"TMDB API error: {str(e)}"
-        ) from e
-    except Exception as e:
-        logger.error(
-            f"Error updating NFO for {serie_id}: {e}",
-            exc_info=True
-        )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to update NFO: {str(e)}"
-        ) from e
+@router.get("/poster/{serie_id}")
+async def get_nfo_poster(serie_id: str):
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )
 
 
-@router.get("/{serie_id}/content", response_model=NFOContentResponse)
-async def get_nfo_content(
-    serie_id: str,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> NFOContentResponse:
-    """Get NFO file content for a series.
-    
-    Args:
-        serie_id: Series identifier
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        NFOContentResponse with NFO content
-        
-    Raises:
-        HTTPException: If series or NFO not found
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Ensure folder name includes year if available
-        serie_folder = serie.ensure_folder_with_year()
-        
-        # Check if NFO exists
-        nfo_path = (
-            Path(settings.anime_directory) / serie_folder / "tvshow.nfo"
-        )
-        if not nfo_path.exists():
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="NFO file not found"
-            )
-        
-        # Read NFO content
-        content = nfo_path.read_text(encoding="utf-8")
-        file_size = nfo_path.stat().st_size
-        last_modified = datetime.fromtimestamp(nfo_path.stat().st_mtime)
-        
-        return NFOContentResponse(
-            serie_id=serie_id,
-            serie_folder=serie_folder,
-            content=content,
-            file_size=file_size,
-            last_modified=last_modified
-        )
-        
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(
-            f"Error reading NFO content for {serie_id}: {e}",
-            exc_info=True
-        )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to read NFO content: {str(e)}"
-        ) from e
-
-
-@router.get("/{serie_id}/media/status", response_model=MediaFilesStatus)
-async def get_media_status(
-    serie_id: str,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app)
-) -> MediaFilesStatus:
-    """Get media files status for a series.
-    
-    Args:
-        serie_id: Series identifier
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        
-    Returns:
-        MediaFilesStatus with file existence info
-        
-    Raises:
-        HTTPException: If series not found
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Build full path and check media files
-        folder_path = Path(settings.anime_directory) / serie.folder
-        media_status = check_media_files(folder_path)
-        file_paths = get_media_file_paths(folder_path)
-        
-        return MediaFilesStatus(
-            has_poster=media_status.get("poster", False),
-            has_logo=media_status.get("logo", False),
-            has_fanart=media_status.get("fanart", False),
-            poster_path=str(file_paths["poster"]) if file_paths.get("poster") else None,
-            logo_path=str(file_paths["logo"]) if file_paths.get("logo") else None,
-            fanart_path=str(file_paths["fanart"]) if file_paths.get("fanart") else None
-        )
-        
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(
-            f"Error checking media status for {serie_id}: {e}",
-            exc_info=True
-        )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to check media status: {str(e)}"
-        ) from e
-
-
-@router.post("/{serie_id}/media/download", response_model=MediaFilesStatus)
-async def download_media(
-    serie_id: str,
-    request: MediaDownloadRequest,
-    _auth: dict = Depends(require_auth),
-    series_app: SeriesApp = Depends(get_series_app),
-    nfo_service: NFOService = Depends(get_nfo_service)
-) -> MediaFilesStatus:
-    """Download missing media files for a series.
-    
-    Args:
-        serie_id: Series identifier
-        request: Media download options
-        _auth: Authentication dependency
-        series_app: Series app dependency
-        nfo_service: NFO service dependency
-        
-    Returns:
-        MediaFilesStatus after download attempt
-        
-    Raises:
-        HTTPException: If series or NFO not found
-    """
-    try:
-        # Get series info
-        series_list = series_app.list.GetList()
-        serie = next(
-            (s for s in series_list if getattr(s, 'key', None) == serie_id),
-            None
-        )
-        
-        if not serie:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Series not found: {serie_id}"
-            )
-        
-        # Ensure folder name includes year if available
-        serie_folder = serie.ensure_folder_with_year()
-        
-        # Check if NFO exists (needed for TMDB ID)
-        has_nfo = await nfo_service.check_nfo_exists(serie_folder)
-        if not has_nfo:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="NFO required for media download. Create NFO first."
-            )
-        
-        # For now, update NFO which will re-download media
-        # In future, could add standalone media download
-        if (request.download_poster or request.download_logo
-                or request.download_fanart):
-            await nfo_service.update_tvshow_nfo(
-                serie_folder=serie_folder,
-                download_media=True
-            )
-        
-        # Build full path and check media files
-        folder_path = Path(settings.anime_directory) / serie_folder
-        media_status = check_media_files(folder_path)
-        file_paths = get_media_file_paths(folder_path)
-        
-        return MediaFilesStatus(
-            has_poster=media_status.get("poster", False),
-            has_logo=media_status.get("logo", False),
-            has_fanart=media_status.get("fanart", False),
-            poster_path=str(file_paths["poster"]) if file_paths.get("poster") else None,
-            logo_path=str(file_paths["logo"]) if file_paths.get("logo") else None,
-            fanart_path=str(file_paths["fanart"]) if file_paths.get("fanart") else None
-        )
-        
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(
-            f"Error downloading media for {serie_id}: {e}",
-            exc_info=True
-        )
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to download media: {str(e)}"
-        ) from e
+@router.get("/fanart/{serie_id}")
+async def get_nfo_fanart(serie_id: str):
+    """NFO endpoints disabled - NFO service removed."""
+    raise HTTPException(
+        status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+        detail="NFO service has been removed. Use series management endpoints instead."
+    )

src/server/api/scheduler.py

@@ -10,7 +10,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 
 from src.server.models.config import SchedulerConfig
 from src.server.services.config_service import ConfigServiceError, get_config_service
-from src.server.services.scheduler_service import get_scheduler_service
+from src.server.services.scheduler.scheduler_service import get_scheduler_service
 from src.server.utils.dependencies import require_auth
 
 logger = logging.getLogger(__name__)

src/server/api/setup_endpoints.py

@@ -0,0 +1,313 @@
+"""API endpoints for setup and unresolved folder management.
+
+Provides endpoints to:
+- List unresolved folders that couldn't be auto-resolved during setup
+- Get suggestions/search results for an unresolved folder
+- Resolve an unresolved folder by providing a provider key
+"""
+import json
+import logging
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
+
+from src.server.database.connection import get_db_session
+from src.server.database.service import AnimeSeriesService, UnresolvedFolderService
+from src.server.utils.dependencies import (
+    get_database_session,
+    get_series_app,
+    require_auth,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/setup", tags=["setup"])
+
+
+class UnresolvedFolderResponse(BaseModel):
+    """Response model for an unresolved folder."""
+    
+    folder_name: str = Field(..., description="Original filesystem folder name")
+    title: str = Field(..., description="Extracted title from folder name")
+    year: Optional[int] = Field(None, description="Extracted release year")
+    search_attempts: int = Field(..., description="Number of search attempts made")
+    search_suggestions: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Cached search results for potential matches"
+    )
+    
+    class Config:
+        from_attributes = True
+
+
+class ResolveFolderRequest(BaseModel):
+    """Request model for resolving an unresolved folder."""
+    
+    provider_key: str = Field(
+        ...,
+        min_length=1,
+        max_length=255,
+        description="Provider key to associate with this folder"
+    )
+
+
+class ResolveFolderResponse(BaseModel):
+    """Response model for resolving an unresolved folder."""
+    
+    status: str = Field(..., description="Operation status")
+    message: str = Field(..., description="Human-readable message")
+    folder_name: str = Field(..., description="Folder name that was resolved")
+    key: str = Field(..., description="Provider key that was used")
+    series_id: int = Field(..., description="Database ID of the created series")
+
+
+@router.get("/unresolved", response_model=list[UnresolvedFolderResponse])
+async def list_unresolved_folders(
+    db=Depends(get_database_session),
+) -> list[UnresolvedFolderResponse]:
+    """List all unresolved folders that need manual key resolution.
+    
+    Returns folders that couldn't be auto-resolved during setup,
+    including cached search suggestions when available.
+    
+    Returns:
+        List of UnresolvedFolderResponse objects
+    """
+    folders = await UnresolvedFolderService.get_all_unresolved(db)
+    
+    result = []
+    for folder in folders:
+        suggestions = []
+        if folder.last_search_result:
+            try:
+                suggestions = json.loads(folder.last_search_result)
+            except json.JSONDecodeError:
+                logger.warning(
+                    "Failed to parse search result for folder: %s",
+                    folder.folder_name
+                )
+        
+        result.append(UnresolvedFolderResponse(
+            folder_name=folder.folder_name,
+            title=folder.title,
+            year=folder.year,
+            search_attempts=folder.search_attempts,
+            search_suggestions=suggestions,
+        ))
+    
+    return result
+
+
+@router.get("/unresolved/{folder_name}", response_model=UnresolvedFolderResponse)
+async def get_unresolved_folder(
+    folder_name: str,
+    db=Depends(get_database_session),
+) -> UnresolvedFolderResponse:
+    """Get details for a specific unresolved folder.
+    
+    Args:
+        folder_name: URL-encoded folder name to look up
+        
+    Returns:
+        UnresolvedFolderResponse for the specified folder
+        
+    Raises:
+        HTTPException: 404 if folder not found or already resolved
+    """
+    folder = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+    
+    if not folder:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unresolved folder not found: {folder_name}"
+        )
+    
+    if folder.is_resolved:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Folder already resolved: {folder_name}"
+        )
+    
+    suggestions = []
+    if folder.last_search_result:
+        try:
+            suggestions = json.loads(folder.last_search_result)
+        except json.JSONDecodeError:
+            pass
+    
+    return UnresolvedFolderResponse(
+        folder_name=folder.folder_name,
+        title=folder.title,
+        year=folder.year,
+        search_attempts=folder.search_attempts,
+        search_suggestions=suggestions,
+    )
+
+
+@router.post("/unresolved/{folder_name}/resolve", response_model=ResolveFolderResponse)
+async def resolve_unresolved_folder(
+    folder_name: str,
+    request: ResolveFolderRequest,
+    db=Depends(get_database_session),
+) -> ResolveFolderResponse:
+    """Resolve an unresolved folder by providing the correct provider key.
+    
+    This endpoint:
+    1. Validates the provider key format
+    2. Updates the UnresolvedFolder record as resolved
+    3. Creates the AnimeSeries record in the database
+    4. Returns the created series information
+    
+    Args:
+        folder_name: URL-encoded folder name to resolve
+        request: ResolveFolderRequest with the provider_key
+        
+    Returns:
+        ResolveFolderResponse with created series details
+        
+    Raises:
+        HTTPException: 404 if folder not found
+        HTTPException: 400 if key is invalid or series already exists
+    """
+    # Check if folder exists and is unresolved
+    unresolved = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+    
+    if not unresolved:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unresolved folder not found: {folder_name}"
+        )
+    
+    if unresolved.is_resolved:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Folder already resolved: {folder_name}"
+        )
+    
+    # Check if a series with this key already exists
+    existing_series = await AnimeSeriesService.get_by_key(db, request.provider_key)
+    if existing_series:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Series with key '{request.provider_key}' already exists"
+        )
+    
+    # Mark as resolved
+    await UnresolvedFolderService.resolve(db, folder_name, request.provider_key)
+    
+    # Create the AnimeSeries record
+    series = await AnimeSeriesService.create(
+        db=db,
+        key=request.provider_key,
+        name=unresolved.title,
+        site="https://aniworld.to",
+        folder=folder_name,
+        year=unresolved.year,
+        loading_status="pending",
+        episodes_loaded=False,
+        logo_loaded=False,
+        images_loaded=False,
+    )
+    
+    logger.info(
+        "Resolved unresolved folder via API: %s -> key=%s (series_id=%d)",
+        folder_name, request.provider_key, series.id
+    )
+    
+    return ResolveFolderResponse(
+        status="success",
+        message=f"Successfully resolved and added series: {unresolved.title}",
+        folder_name=folder_name,
+        key=request.provider_key,
+        series_id=series.id,
+    )
+
+
+@router.post("/unresolved/{folder_name}/search", response_model=UnresolvedFolderResponse)
+async def search_unresolved_folder(
+    folder_name: str,
+    db=Depends(get_database_session),
+) -> UnresolvedFolderResponse:
+    """Re-search for a specific unresolved folder to get fresh suggestions.
+    
+    Performs a new search using the folder's title and caches the results.
+    
+    Args:
+        folder_name: URL-encoded folder name to search for
+        
+    Returns:
+        UnresolvedFolderResponse with updated search suggestions
+        
+    Raises:
+        HTTPException: 404 if folder not found or already resolved
+    """
+    from pathlib import Path
+    
+    folder = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+    
+    if not folder:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unresolved folder not found: {folder_name}"
+        )
+    
+    if folder.is_resolved:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Folder already resolved: {folder_name}"
+        )
+    
+    # Perform search
+    series_app = get_series_app()
+    try:
+        results = await series_app.search(folder.title)
+        search_result_json = json.dumps(results) if results else "[]"
+    except Exception as e:
+        logger.warning(
+            "Search failed for unresolved folder: %s, error: %s",
+            folder_name, str(e)
+        )
+        search_result_json = "[]"
+        results = []
+    
+    # Update the folder with new search results
+    await UnresolvedFolderService.update_search_result(db, folder_name, search_result_json)
+    
+    return UnresolvedFolderResponse(
+        folder_name=folder.folder_name,
+        title=folder.title,
+        year=folder.year,
+        search_attempts=folder.search_attempts,
+        search_suggestions=results,
+    )
+
+
+@router.delete("/unresolved/{folder_name}")
+async def delete_unresolved_folder(
+    folder_name: str,
+    db=Depends(get_database_session),
+) -> dict[str, str]:
+    """Delete an unresolved folder tracking record.
+    
+    Use this when you've manually added the series outside of this flow
+    (e.g., via POST /api/anime/add) to clean up the unresolved tracker.
+    
+    Args:
+        folder_name: URL-encoded folder name to delete
+        
+    Returns:
+        Dict with status message
+        
+    Raises:
+        HTTPException: 404 if folder not found
+    """
+    deleted = await UnresolvedFolderService.delete(db, folder_name)
+    
+    if not deleted:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Unresolved folder not found: {folder_name}"
+        )
+    
+    return {"status": "success", "message": f"Deleted unresolved folder: {folder_name}"}

src/server/config/__init__.py

@@ -39,7 +39,7 @@ def get_settings() -> Union[DevelopmentSettings, ProductionSettings]:
     Example:
         >>> settings = get_settings()
         >>> print(settings.log_level)
-        DEBUG
+        INFO
     """
     if ENVIRONMENT in {"development", "testing"}:
         return get_development_settings()

src/server/config/development.py

@@ -215,7 +215,7 @@ class DevelopmentSettings(BaseSettings):
     @property
     def debug_enabled(self) -> bool:
         """Check if debug mode is enabled."""
-        return True
+        return False
 
     @property
     def reload_enabled(self) -> bool:

src/server/config/logging_config.py

@@ -95,10 +95,10 @@ def setup_logging() -> Dict[str, logging.Logger]:
     # Log initial setup
     root_logger.info("=" * 80)
     root_logger.info("FastAPI Server Logging Initialized")
-    root_logger.info(f"Log Level: {settings.log_level.upper()}")
-    root_logger.info(f"Server Log: {server_log_file.absolute()}")
-    root_logger.info(f"Error Log: {error_log_file.absolute()}")
-    root_logger.info(f"Access Log: {access_log_file.absolute()}")
+    root_logger.info("Log Level: %s", settings.log_level.upper())
+    root_logger.info("Server Log: %s", server_log_file.absolute())
+    root_logger.info("Error Log: %s", error_log_file.absolute())
+    root_logger.info("Access Log: %s", access_log_file.absolute())
     root_logger.info("=" * 80)
     
     return {

src/server/controllers/page_controller.py

@@ -59,3 +59,13 @@ async def loading_page(request: Request):
         request,
         title="Initializing - Aniworld"
     )
+
+
+@router.get("/setup/unresolved", response_class=HTMLResponse)
+async def unresolved_page(request: Request):
+    """Serve the unresolved folders resolution page."""
+    return render_template(
+        "unresolved.html",
+        request,
+        title="Resolve Series - Aniworld"
+    )

src/server/database/SerieList.py

@@ -0,0 +1,288 @@
+"""Utilities for loading and managing stored anime series metadata.
+
+This module provides the SerieList class for managing collections of anime
+series metadata loaded from the database.
+
+Note:
+    This module is part of the server database layer. All persistence
+    is handled by the service layer.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List, Optional
+
+from src.server.database.models import AnimeSeries
+
+logger = logging.getLogger(__name__)
+
+
+class SerieList:
+    """
+    Represents the collection of cached series loaded from database.
+    
+    Series are identified by their unique 'key' (provider identifier).
+    The 'folder' is metadata only and not used for lookups.
+    
+    This class manages in-memory series data loaded from database.
+    
+    Example:
+        # Load from database
+        serie_list = SerieList("/path/to/anime")
+        await serie_list.load_all_from_db()
+        series = serie_list.get_all()
+    
+    Attributes:
+        directory: Path to the anime directory
+        keyDict: Internal dictionary mapping serie.key to AnimeSeries objects
+    """
+
+    def __init__(self, base_path: str) -> None:
+        """Initialize the SerieList.
+        
+        Args:
+            base_path: Path to the anime directory
+        """
+        self.directory: str = base_path
+        # Internal storage using serie.key as the dictionary key
+        self.keyDict: Dict[str, AnimeSeries] = {}
+
+    async def add_to_db(self, anime: AnimeSeries) -> bool:
+        """Persist a new series to the database.
+
+        Creates the filesystem folder using anime.folder, then persists
+        the series metadata to the database.
+
+        Args:
+            anime: The AnimeSeries instance to add
+
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            from src.server.database.connection import get_async_session_factory
+            from src.server.database.service import AnimeSeriesService, EpisodeService
+
+            folder_name = anime.folder
+            anime_path = self.directory + "/" + folder_name
+            import os
+            os.makedirs(anime_path, exist_ok=True)
+
+            session_factory = get_async_session_factory()
+            db = session_factory()
+            try:
+                existing = await AnimeSeriesService.get_by_key(db, anime.key)
+                if existing:
+                    logger.debug(
+                        "Series '%s' (key=%s) already exists in DB, skipping",
+                        anime.name, anime.key
+                    )
+                    return True
+
+                db_anime_series = await AnimeSeriesService.create(
+                    db=db,
+                    key=anime.key,
+                    name=anime.name,
+                    site=anime.site,
+                    folder=folder_name,
+                    year=anime.year
+                )
+                for ep in anime.episodes:
+                    await EpisodeService.create(
+                        db=db,
+                        series_id=db_anime_series.id,
+                        season=ep.season,
+                        episode_number=ep.episode_number
+                    )
+                await db.commit()
+                self.keyDict[anime.key] = anime
+                logger.info(
+                    "Persisted series '%s' to database",
+                    anime.name
+                )
+                return True
+            except Exception as e:
+                await db.rollback()
+                logger.error(
+                    "Failed to persist series '%s' to DB: %s",
+                    anime.key, e, exc_info=True
+                )
+                return False
+            finally:
+                await db.close()
+        except Exception as e:
+            logger.error(
+                "Could not add series '%s' to DB (DB unavailable?): %s",
+                anime.key, e
+            )
+            return False
+
+    def contains(self, key: str) -> bool:
+        """
+        Return True when a series identified by ``key`` already exists.
+        
+        Args:
+            key: The unique provider identifier for the series
+            
+        Returns:
+            True if the series exists in the collection
+        """
+        return key in self.keyDict
+
+    def GetMissingEpisode(self) -> List[AnimeSeries]:
+        """Return all series that still contain missing episodes."""
+        return [
+            anime for anime in self.keyDict.values()
+            if anime.episodeDict
+        ]
+
+    def get_missing_episodes(self) -> List[AnimeSeries]:
+        """PEP8-friendly alias for :meth:`GetMissingEpisode`."""
+        return self.GetMissingEpisode()
+
+    def GetList(self) -> List[AnimeSeries]:
+        """Return all series instances stored in the list."""
+        return list(self.keyDict.values())
+
+    def get_all(self) -> List[AnimeSeries]:
+        """PEP8-friendly alias for :meth:`GetList`."""
+        return self.GetList()
+    
+    def get_by_key(self, key: str) -> Optional[AnimeSeries]:
+        """
+        Get a series by its unique provider key.
+        
+        This is the primary method for series lookup.
+        
+        Args:
+            key: The unique provider identifier (e.g., "attack-on-titan")
+            
+        Returns:
+            The AnimeSeries instance if found, None otherwise
+        """
+        return self.keyDict.get(key)
+    
+    def get_by_folder(self, folder: str) -> Optional[AnimeSeries]:
+        """
+        Get a series by its folder name.
+        
+        .. deprecated:: 2.0.0
+            Use :meth:`get_by_key` instead. Folder-based lookups will be
+            removed in version 3.0.0. The `folder` field is metadata only
+            and should not be used for identification.
+        
+        This method is provided for backward compatibility only.
+        Prefer using get_by_key() for new code.
+        
+        Args:
+            folder: The filesystem folder name (e.g., "Attack on Titan (2013)")
+            
+        Returns:
+            The AnimeSeries instance if found, None otherwise
+        """
+        import warnings
+        warnings.warn(
+            "get_by_folder() is deprecated and will be removed in v3.0.0. "
+            "Use get_by_key() instead. The 'folder' field is metadata only.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        for anime in self.keyDict.values():
+            if anime.folder == folder:
+                return anime
+        return None
+
+    async def load_all_from_db(self) -> int:
+        """Load all series from database into in-memory cache.
+        
+        Retrieves all anime series from the database with their episodes
+        and populates the in-memory keyDict for fast access.
+        
+        Returns:
+            int: Number of series loaded into cache
+        """
+        from src.server.database.connection import get_async_session_factory
+        from src.server.database.service import AnimeSeriesService
+        
+        try:
+            session_factory = get_async_session_factory()
+            db = session_factory()
+            try:
+                anime_series_list = await AnimeSeriesService.get_all(
+                    db, with_episodes=True
+                )
+                
+                count = 0
+                for anime_series in anime_series_list:
+                    self.keyDict[anime_series.key] = anime_series
+                    count += 1
+                
+                logger.info(
+                    "Loaded %d series from database into in-memory cache",
+                    count
+                )
+                return count
+            finally:
+                await db.close()
+        except RuntimeError:
+            logger.warning(
+                "Database not available, skipping DB load"
+            )
+            return 0
+
+    async def _load_single_series_from_db(
+        self,
+        anime_folder: str
+    ) -> Optional[AnimeSeries]:
+        """Load a single series from database by folder name.
+        
+        Looks up a series in the database by its folder name and adds
+        it to the in-memory cache.
+        
+        Args:
+            anime_folder: The filesystem folder name to look up
+            
+        Returns:
+            AnimeSeries if found and loaded, None otherwise
+        """
+        from src.server.database.connection import get_async_session_factory
+        from src.server.database.service import AnimeSeriesService
+        
+        try:
+            session_factory = get_async_session_factory()
+            db = session_factory()
+            try:
+                anime_series = await AnimeSeriesService.get_by_folder(
+                    db, anime_folder
+                )
+                if not anime_series:
+                    logger.debug(
+                        "Series with folder '%s' not found in DB",
+                        anime_folder
+                    )
+                    return None
+                
+                self.keyDict[anime_series.key] = anime_series
+                logger.debug(
+                    "Loaded series '%s' (key=%s) from DB",
+                    anime_series.name, anime_series.key
+                )
+                return anime_series
+            finally:
+                await db.close()
+        except RuntimeError:
+            logger.warning(
+                "Database not available, cannot load series '%s'",
+                anime_folder
+            )
+            return None
+
+    def invalidate_cache(self) -> None:
+        """Clear the in-memory cache.
+        
+        Use after database modifications to force reload from DB
+        on next access.
+        """
+        self.keyDict.clear()
+        logger.debug("SerieList in-memory cache invalidated")

src/server/database/__init__.py

@@ -48,6 +48,7 @@ from src.server.database.service import (
     EpisodeService,
     UserSessionService,
 )
+from src.server.database.SerieList import SerieList
 from src.server.database.system_settings_service import SystemSettingsService
 
 __all__ = [
@@ -79,4 +80,6 @@ __all__ = [
     "DownloadQueueService",
     "SystemSettingsService",
     "UserSessionService",
+    # SerieList
+    "SerieList",
 ]

src/server/database/connection.py

@@ -88,7 +88,7 @@ async def init_db() -> None:
     try:
         # Get database URL
         db_url = _get_database_url()
-        logger.info(f"Initializing database: {db_url}")
+        logger.info("Initializing database: %s", db_url)
         
         # Build engine kwargs based on database type
         is_sqlite = "sqlite" in db_url
@@ -143,7 +143,7 @@ async def init_db() -> None:
         logger.info("Database initialization complete")
         
     except Exception as e:
-        logger.error(f"Failed to initialize database: {e}")
+        logger.error("Failed to initialize database: %s", e)
         raise
 
 
@@ -171,7 +171,7 @@ async def close_db() -> None:
                     conn.commit()
                 logger.info("SQLite WAL checkpoint completed")
             except Exception as e:
-                logger.warning(f"WAL checkpoint failed (non-critical): {e}")
+                logger.warning("WAL checkpoint failed (non-critical): %s", e)
         
         if _engine:
             logger.info("Closing async database engine...")
@@ -188,7 +188,7 @@ async def close_db() -> None:
         logger.info("Database connections closed")
         
     except Exception as e:
-        logger.error(f"Error closing database: {e}")
+        logger.error("Error closing database: %s", e)
 
 
 def get_engine() -> AsyncEngine:

src/server/database/init.py

@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)
 # Schema Version Constants
 # =============================================================================
 
-CURRENT_SCHEMA_VERSION = "1.0.0"
+CURRENT_SCHEMA_VERSION = "1.0.1"
 SCHEMA_VERSION_TABLE = "schema_version"
 
 # Expected tables in the current schema
@@ -98,7 +98,7 @@ async def initialize_database(
             seed_data=True
         )
         if result["success"]:
-            logger.info(f"Database initialized: {result['schema_version']}")
+            logger.info("Database initialized: %s", result['schema_version'])
     """
     if engine is None:
         engine = get_engine()
@@ -117,7 +117,12 @@ async def initialize_database(
         if create_schema:
             tables = await create_database_schema(engine)
             result["tables_created"] = tables
-            logger.info(f"Created {len(tables)} tables")
+            logger.info("Created %s tables", len(tables))
+        
+        # Migrate schema if needed (add missing columns to existing tables)
+        migrations = await migrate_schema_if_needed(engine)
+        if migrations:
+            logger.info("Applied %s schema migrations", len(migrations))
         
         # Validate schema if requested
         if validate_schema:
@@ -148,7 +153,7 @@ async def initialize_database(
         return result
         
     except Exception as e:
-        logger.error(f"Database initialization failed: {e}", exc_info=True)
+        logger.exception("Database initialization failed: %s", e)
         raise RuntimeError(f"Failed to initialize database: {e}") from e
 
 
@@ -194,14 +199,14 @@ async def create_database_schema(
         created_tables = [t for t in new_tables if t not in existing_tables]
         
         if created_tables:
-            logger.info(f"Created tables: {', '.join(created_tables)}")
+            logger.info("Created tables: %s", ', '.join(created_tables))
         else:
             logger.info("All tables already exist")
         
         return new_tables
         
     except Exception as e:
-        logger.error(f"Failed to create schema: {e}", exc_info=True)
+        logger.exception("Failed to create schema: %s", e)
         raise RuntimeError(f"Schema creation failed: {e}") from e
 
 
@@ -295,7 +300,7 @@ async def validate_database_schema(
         return result
         
     except Exception as e:
-        logger.error(f"Schema validation failed: {e}", exc_info=True)
+        logger.exception("Schema validation failed: %s", e)
         return {
             "valid": False,
             "missing_tables": [],
@@ -305,6 +310,66 @@ async def validate_database_schema(
         }
 
 
+# =============================================================================
+# Schema Migration
+# =============================================================================
+
+
+async def migrate_schema_if_needed(
+    engine: Optional[AsyncEngine] = None
+) -> List[str]:
+    """Migrate database schema to current version if needed.
+    
+    Handles adding missing columns to existing tables for backward
+    compatibility with older database schemas.
+    
+    Args:
+        engine: Optional database engine (uses default if not provided)
+    
+    Returns:
+        List of migration operations performed
+    """
+    if engine is None:
+        engine = get_engine()
+    
+    migrations_applied = []
+    
+    try:
+        async with engine.connect() as conn:
+            # Get existing columns in system_settings table
+            existing_columns = await conn.run_sync(
+                lambda sync_conn: [
+                    col["name"]
+                    for col in inspect(sync_conn).get_columns("system_settings")
+                ]
+            )
+            
+            # Migration: Add legacy_key_cleanup_completed column if missing
+            if "legacy_key_cleanup_completed" not in existing_columns:
+                logger.info(
+                    "Migrating system_settings table: "
+                    "adding legacy_key_cleanup_completed column"
+                )
+                await conn.execute(
+                    text("""
+                        ALTER TABLE system_settings
+                        ADD COLUMN legacy_key_cleanup_completed BOOLEAN
+                        NOT NULL DEFAULT 0
+                    """)
+                )
+                migrations_applied.append("added legacy_key_cleanup_completed")
+                logger.info(
+                    "Migration complete: added legacy_key_cleanup_completed column"
+                )
+    
+    except Exception as e:
+        logger.error("Schema migration failed: %s", e)
+        # Don't raise - migration failures shouldn't block startup
+        # The missing column will be handled gracefully by the application
+    
+    return migrations_applied
+
+
 # =============================================================================
 # Schema Version Management
 # =============================================================================
@@ -319,7 +384,7 @@ async def get_schema_version(engine: Optional[AsyncEngine] = None) -> str:
         engine: Optional database engine (uses default if not provided)
     
     Returns:
-        Schema version string (e.g., "1.0.0", "empty", "unknown")
+        Schema version string (e.g., "1.0.1", "empty", "unknown")
     """
     if engine is None:
         engine = get_engine()
@@ -342,7 +407,7 @@ async def get_schema_version(engine: Optional[AsyncEngine] = None) -> str:
                 return "unknown"
                 
     except Exception as e:
-        logger.error(f"Failed to get schema version: {e}")
+        logger.error("Failed to get schema version: %s", e)
         return "error"
 
 
@@ -409,7 +474,7 @@ async def seed_initial_data(engine: Optional[AsyncEngine] = None) -> None:
             logger.info("Data will be populated via normal application usage")
             
     except Exception as e:
-        logger.error(f"Failed to seed initial data: {e}", exc_info=True)
+        logger.exception("Failed to seed initial data: %s", e)
         raise
 
 
@@ -484,12 +549,12 @@ async def check_database_health(
                 f"(connectivity: {result['connectivity_ms']}ms)"
             )
         else:
-            logger.warning(f"Database health issues: {result['issues']}")
+            logger.warning("Database health issues: %s", result['issues'])
         
         return result
         
     except Exception as e:
-        logger.error(f"Database health check failed: {e}")
+        logger.error("Database health check failed: %s", e)
         return {
             "healthy": False,
             "accessible": False,
@@ -547,13 +612,13 @@ async def create_database_backup(
         backup_path = backup_dir / f"aniworld_{timestamp}.db"
     
     try:
-        logger.info(f"Creating database backup: {backup_path}")
+        logger.info("Creating database backup: %s", backup_path)
         shutil.copy2(db_path, backup_path)
-        logger.info(f"Backup created successfully: {backup_path}")
+        logger.info("Backup created successfully: %s", backup_path)
         return backup_path
         
     except Exception as e:
-        logger.error(f"Failed to create backup: {e}", exc_info=True)
+        logger.exception("Failed to create backup: %s", e)
         raise RuntimeError(f"Backup creation failed: {e}") from e
 
 

src/server/database/models.py

@@ -15,7 +15,7 @@ from datetime import datetime, timezone
 from enum import Enum
 from typing import List, Optional
 
-from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, func
+from sqlalchemy import Boolean, DateTime, ForeignKey, Index, Integer, String, Text, func
 from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
 
 from src.server.database.base import Base, TimestampMixin
@@ -83,6 +83,10 @@ class AnimeSeries(Base, TimestampMixin):
         Boolean, nullable=False, default=False, server_default="0",
         doc="Whether tvshow.nfo file exists for this series"
     )
+    nfo_path: Mapped[Optional[str]] = mapped_column(
+        String(1000), nullable=True,
+        doc="Path to the tvshow.nfo metadata file"
+    )
     nfo_created_at: Mapped[Optional[datetime]] = mapped_column(
         DateTime(timezone=True), nullable=True,
         doc="Timestamp when NFO was first created"
@@ -91,6 +95,7 @@ class AnimeSeries(Base, TimestampMixin):
         DateTime(timezone=True), nullable=True,
         doc="Timestamp when NFO was last updated"
     )
+    # TMDB (The Movie Database) ID for series metadata
     tmdb_id: Mapped[Optional[int]] = mapped_column(
         Integer, nullable=True, index=True,
         doc="TMDB (The Movie Database) ID for series metadata"
@@ -185,6 +190,54 @@ class AnimeSeries(Base, TimestampMixin):
             f"name='{self.name}')>"
         )
 
+    @property
+    def episodeDict(self) -> dict[int, list[int]]:
+        """Build episode dictionary from episodes relationship or private cache.
+
+        Returns:
+            Dictionary mapping season numbers to lists of episode numbers
+        """
+        # Check for private cache first (set when loading from JSON without DB)
+        if hasattr(self, '_episode_dict_cache') and self._episode_dict_cache is not None:
+            return self._episode_dict_cache
+        
+        episode_dict: dict[int, list[int]] = {}
+        if self.episodes:
+            for ep in self.episodes:
+                season = ep.season or 1
+                if season not in episode_dict:
+                    episode_dict[season] = []
+                episode_dict[season].append(ep.episode_number or 0)
+        return episode_dict
+
+    @property
+    def name_with_year(self) -> str:
+        """Get series name with year appended if available.
+
+        Returns:
+            Name in format "Name (Year)" if year is available, else just name
+        """
+        if self.year:
+            import re
+            year_suffix = f" ({self.year})"
+            clean_name = re.sub(r'(\s*\(\d{4}\))+\s*$', '', self.name or '').strip()
+            return f"{clean_name}{year_suffix}"
+        return self.name or ''
+
+    @property
+    def sanitized_folder(self) -> str:
+        """Get filesystem-safe folder name from display name with year.
+
+        Returns:
+            Sanitized folder name based on display name with year
+        """
+        from src.server.utils.filesystem import sanitize_folder_name
+        name_to_sanitize = self.name_with_year or self.folder or self.key
+        try:
+            return sanitize_folder_name(name_to_sanitize)
+        except ValueError:
+            return sanitize_folder_name(self.key)
+
 
 class Episode(Base, TimestampMixin):
     """SQLAlchemy model for anime episodes.
@@ -316,6 +369,7 @@ class DownloadQueueItem(Base, TimestampMixin):
         id: Primary key
         series_id: Foreign key to AnimeSeries
         episode_id: Foreign key to Episode
+        status: Queue status (pending/downloading/completed/failed/permanently_failed)
         error_message: Error description if failed
         download_url: Provider download URL
         file_destination: Target file path
@@ -347,6 +401,33 @@ class DownloadQueueItem(Base, TimestampMixin):
         index=True
     )
     
+    # Status column to track queue item state
+    # Allows distinguishing pending items from permanently failed ones
+    status: Mapped[str] = mapped_column(
+        String(50), nullable=False, default="pending",
+        doc="Queue item status: pending, downloading, completed, failed, permanently_failed"
+    )
+    
+    # Retry count to track failed download attempts
+    # Used to determine when to move item to permanently_failed
+    retry_count: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0,
+        doc="Number of retry attempts for this download"
+    )
+    
+    # Unique constraint to prevent duplicate pending queue items per episode
+    # An episode can only have one PENDING entry at a time
+    # The status column allows failed items to remain in DB while new
+    # pending items can be added (application-level dedup still required)
+    __table_args__ = (
+        Index(
+            "ix_download_queue_episode_status",
+            "episode_id",
+            "status",
+            unique=True,
+        ),
+    )
+    
     # Error handling
     error_message: Mapped[Optional[str]] = mapped_column(
         Text, nullable=True,
@@ -545,6 +626,96 @@ class UserSession(Base, TimestampMixin):
         self.is_active = False
 
 
+class UnresolvedFolder(Base, TimestampMixin):
+    """SQLAlchemy model for folders that couldn't be resolved during setup.
+    
+    Tracks anime folders whose provider key couldn't be auto-resolved
+    during the initial setup scan. Users can provide the correct key
+    via the API to complete the series registration.
+    
+    Attributes:
+        id: Primary key
+        folder_name: Original filesystem folder name
+        title: Extracted title from folder name
+        year: Extracted release year (optional)
+        provider_key: User-provided provider key to resolve this folder
+        search_attempts: Number of auto-search attempts made
+        last_search_result: Cached search results (JSON string) for UI suggestions
+        resolved_at: Timestamp when provider_key was provided
+        created_at: Creation timestamp (from TimestampMixin)
+        updated_at: Last update timestamp (from TimestampMixin)
+    """
+    __tablename__ = "unresolved_folders"
+    
+    # Primary key
+    id: Mapped[int] = mapped_column(
+        Integer, primary_key=True, autoincrement=True
+    )
+    
+    # Folder metadata
+    folder_name: Mapped[str] = mapped_column(
+        String(1000), unique=True, nullable=False, index=True,
+        doc="Original filesystem folder name"
+    )
+    title: Mapped[str] = mapped_column(
+        String(500), nullable=False,
+        doc="Extracted title from folder name"
+    )
+    year: Mapped[Optional[int]] = mapped_column(
+        Integer, nullable=True,
+        doc="Extracted release year"
+    )
+    
+    # Resolution data
+    provider_key: Mapped[Optional[str]] = mapped_column(
+        String(255), nullable=True,
+        doc="User-provided provider key to resolve this folder"
+    )
+    search_attempts: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0",
+        doc="Number of auto-search attempts made"
+    )
+    last_search_result: Mapped[Optional[str]] = mapped_column(
+        Text, nullable=True,
+        doc="Cached search results (JSON) for UI display"
+    )
+    resolved_at: Mapped[Optional[datetime]] = mapped_column(
+        DateTime(timezone=True), nullable=True,
+        doc="Timestamp when this folder was resolved"
+    )
+    
+    @validates('folder_name')
+    def validate_folder_name(self, key: str, value: str) -> str:
+        """Validate folder name is not empty."""
+        if not value or not value.strip():
+            raise ValueError("Folder name cannot be empty")
+        if len(value) > 1000:
+            raise ValueError("Folder name must be 1000 characters or less")
+        return value.strip()
+    
+    @validates('title')
+    def validate_title(self, key: str, value: str) -> str:
+        """Validate title is not empty."""
+        if not value or not value.strip():
+            raise ValueError("Title cannot be empty")
+        if len(value) > 500:
+            raise ValueError("Title must be 500 characters or less")
+        return value.strip()
+    
+    @property
+    def is_resolved(self) -> bool:
+        """Check if this folder has been resolved with a provider key."""
+        return self.provider_key is not None and self.resolved_at is not None
+    
+    def __repr__(self) -> str:
+        return (
+            f"<UnresolvedFolder(id={self.id}, "
+            f"folder_name='{self.folder_name}', "
+            f"title='{self.title}', "
+            f"resolved={self.is_resolved})>"
+        )
+
+
 class SystemSettings(Base, TimestampMixin):
     """SQLAlchemy model for system-wide settings and state.
     
@@ -580,6 +751,14 @@ class SystemSettings(Base, TimestampMixin):
         Boolean, nullable=False, default=False, server_default="0",
         doc="Whether the initial media scan has been completed"
     )
+    migration_legacy_files_completed: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default="0",
+        doc="Whether legacy key/data file migration has been completed"
+    )
+    legacy_key_cleanup_completed: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default="0",
+        doc="Whether legacy key file cleanup has been completed"
+    )
     last_scan_timestamp: Mapped[Optional[datetime]] = mapped_column(
         DateTime(timezone=True), nullable=True,
         doc="Timestamp of the last completed scan"

src/server/database/service.py

@@ -34,6 +34,7 @@ from src.server.database.models import (
     AnimeSeries,
     DownloadQueueItem,
     Episode,
+    UnresolvedFolder,
     UserSession,
 )
 
@@ -70,6 +71,10 @@ class AnimeSeriesService:
         logo_loaded: bool = False,
         images_loaded: bool = False,
         loading_started_at: datetime | None = None,
+        has_nfo: bool = False,
+        nfo_path: str | None = None,
+        nfo_created_at: datetime | None = None,
+        nfo_updated_at: datetime | None = None,
     ) -> AnimeSeries:
         """Create a new anime series.
         
@@ -85,6 +90,10 @@ class AnimeSeriesService:
             logo_loaded: Whether logo is loaded (default: False)
             images_loaded: Whether images are loaded (default: False)
             loading_started_at: When loading started (optional)
+            has_nfo: Whether tvshow.nfo exists (default: False)
+            nfo_path: Path to tvshow.nfo file (optional)
+            nfo_created_at: When NFO file was created (optional)
+            nfo_updated_at: When NFO file was last updated (optional)
         
         Returns:
             Created AnimeSeries instance
@@ -103,11 +112,15 @@ class AnimeSeriesService:
             logo_loaded=logo_loaded,
             images_loaded=images_loaded,
             loading_started_at=loading_started_at,
+            has_nfo=has_nfo,
+            nfo_path=nfo_path,
+            nfo_created_at=nfo_created_at,
+            nfo_updated_at=nfo_updated_at,
         )
         db.add(series)
         await db.flush()
         await db.refresh(series)
-        logger.info(f"Created anime series: {series.name} (key={series.key}, year={year})")
+        logger.info("Created anime series: %s (key=%s, year=%s)", series.name, series.key, year)
         return series
     
     @staticmethod
@@ -148,7 +161,47 @@ class AnimeSeriesService:
             select(AnimeSeries).where(AnimeSeries.key == key)
         )
         return result.scalar_one_or_none()
-    
+
+    @staticmethod
+    def get_by_folder_sync(db: Session, folder: str) -> Optional[AnimeSeries]:
+        """Look up an anime series by its filesystem folder name (sync).
+
+        Intended as a fallback for ``SerieScanner`` when neither a ``key``
+        file nor a ``data`` file exists on disk for a given folder.
+
+        Args:
+            db: Synchronous database session (from ``get_sync_session``).
+            folder: Filesystem folder name to match (e.g.
+                ``"Rooster Fighter (2026)"``).
+
+        Returns:
+            ``AnimeSeries`` instance or ``None`` if not found.
+        """
+        result = db.execute(
+            select(AnimeSeries).where(AnimeSeries.folder == folder)
+        )
+        return result.scalar_one_or_none()
+
+    @staticmethod
+    async def get_by_folder(db: AsyncSession, folder: str) -> Optional[AnimeSeries]:
+        """Look up an anime series by its filesystem folder name (async).
+
+        Intended as primary lookup for ``SerieScanner`` when scanning
+        directories, replacing the legacy file-based lookups (key/data files).
+
+        Args:
+            db: Async database session.
+            folder: Filesystem folder name to match (e.g.
+                ``"Rooster Fighter (2026)"``).
+
+        Returns:
+            ``AnimeSeries`` instance or ``None`` if not found.
+        """
+        result = await db.execute(
+            select(AnimeSeries).where(AnimeSeries.folder == folder)
+        )
+        return result.scalar_one_or_none()
+
     @staticmethod
     async def get_all(
         db: AsyncSession,
@@ -205,7 +258,7 @@ class AnimeSeriesService:
         
         await db.flush()
         await db.refresh(series)
-        logger.info(f"Updated anime series: {series.name} (id={series_id})")
+        logger.info("Updated anime series: %s (id=%s)", series.name, series_id)
         return series
     
     @staticmethod
@@ -226,7 +279,7 @@ class AnimeSeriesService:
         )
         deleted = result.rowcount > 0
         if deleted:
-            logger.info(f"Deleted anime series with id={series_id}")
+            logger.info("Deleted anime series with id=%s", series_id)
         return deleted
     
     @staticmethod
@@ -253,48 +306,92 @@ class AnimeSeriesService:
         return list(result.scalars().all())
     
     @staticmethod
-    async def get_series_with_no_episodes(
+    async def get_series_with_missing_episodes(
         db: AsyncSession,
         limit: Optional[int] = None,
         offset: int = 0,
     ) -> List[AnimeSeries]:
-        """Get anime series that have no episodes found in folder.
-        
-        Since episodes in the database represent MISSING episodes
-        (from episodeDict), this returns series that have episodes
-        in the DB with is_downloaded=False, meaning they have missing
-        episodes and no files were found in the folder for those episodes.
-        
-        Returns series where:
-        - At least one episode exists in database with is_downloaded=False
-        
+        """Get anime series that currently have missing episodes.
+
+        Episodes in the database represent missing episodes (from episodeDict).
+        This returns series that have at least one missing episode recorded in
+        the database (is_downloaded=False).
+
         Args:
             db: Database session
             limit: Optional limit for results
             offset: Offset for pagination
-        
+
         Returns:
-            List of AnimeSeries with missing episodes (not in folder)
+            List of AnimeSeries that have missing episodes.
         """
-        # Subquery to find series IDs with at least one undownloaded episode
-        undownloaded_series_ids = (
+        # Subquery to find series IDs with at least one missing episode
+        missing_series_ids = (
             select(Episode.series_id)
             .where(Episode.is_downloaded == False)
             .distinct()
             .subquery()
         )
-        
-        # Select series that have undownloaded episodes
+
         query = (
             select(AnimeSeries)
-            .where(AnimeSeries.id.in_(select(undownloaded_series_ids.c.series_id)))
+            .where(AnimeSeries.id.in_(select(missing_series_ids.c.series_id)))
             .order_by(AnimeSeries.name)
             .offset(offset)
         )
-        
+
         if limit:
             query = query.limit(limit)
-        
+
+        result = await db.execute(query)
+        return list(result.scalars().all())
+
+    @staticmethod
+    async def get_series_with_no_episodes(
+        db: AsyncSession,
+        limit: Optional[int] = None,
+        offset: int = 0,
+    ) -> List[AnimeSeries]:
+        """Get anime series that have no downloaded episodes.
+
+        A series has "no episodes" if it has at least one missing episode
+        (is_downloaded=False) and no downloaded episodes (is_downloaded=True).
+
+        Args:
+            db: Database session
+            limit: Optional limit for results
+            offset: Offset for pagination
+
+        Returns:
+            List of AnimeSeries where no episodes are downloaded.
+        """
+        # Series with missing episodes
+        missing_series_ids = (
+            select(Episode.series_id)
+            .where(Episode.is_downloaded == False)
+            .distinct()
+            .subquery()
+        )
+
+        # Series with any downloaded episodes
+        downloaded_series_ids = (
+            select(Episode.series_id)
+            .where(Episode.is_downloaded == True)
+            .distinct()
+            .subquery()
+        )
+
+        query = (
+            select(AnimeSeries)
+            .where(AnimeSeries.id.in_(select(missing_series_ids.c.series_id)))
+            .where(~AnimeSeries.id.in_(select(downloaded_series_ids.c.series_id)))
+            .order_by(AnimeSeries.name)
+            .offset(offset)
+        )
+
+        if limit:
+            query = query.limit(limit)
+
         result = await db.execute(query)
         return list(result.scalars().all())
     
@@ -477,6 +574,7 @@ class EpisodeService:
         db: AsyncSession,
         series_id: int,
         season: Optional[int] = None,
+        only_missing: bool = False,
     ) -> List[Episode]:
         """Get episodes for a series.
         
@@ -484,6 +582,9 @@ class EpisodeService:
             db: Database session
             series_id: Foreign key to AnimeSeries
             season: Optional season filter
+            only_missing: If True, only return episodes where
+                is_downloaded is False (i.e., missing episodes).
+                Default False returns all episodes.
         
         Returns:
             List of Episode instances
@@ -493,6 +594,9 @@ class EpisodeService:
         if season is not None:
             query = query.where(Episode.season == season)
         
+        if only_missing:
+            query = query.where(Episode.is_downloaded == False)
+        
         query = query.order_by(Episode.season, Episode.episode_number)
         result = await db.execute(query)
         return list(result.scalars().all())
@@ -558,11 +662,11 @@ class EpisodeService:
     @staticmethod
     async def delete(db: AsyncSession, episode_id: int) -> bool:
         """Delete episode.
-        
+
         Args:
             db: Database session
             episode_id: Episode primary key
-        
+
         Returns:
             True if deleted, False if not found
         """
@@ -571,6 +675,33 @@ class EpisodeService:
         )
         return result.rowcount > 0
 
+    @staticmethod
+    async def delete_by_series(
+        db: AsyncSession,
+        series_id: int,
+        season: int,
+        episode_number: int,
+    ) -> bool:
+        """Delete episode by series ID, season, and episode number.
+
+        Args:
+            db: Database session
+            series_id: Foreign key to AnimeSeries
+            season: Season number
+            episode_number: Episode number within season
+
+        Returns:
+            True if deleted, False if not found
+        """
+        result = await db.execute(
+            delete(Episode).where(
+                Episode.series_id == series_id,
+                Episode.season == season,
+                Episode.episode_number == episode_number,
+            )
+        )
+        return result.rowcount > 0
+
     @staticmethod
     async def delete_by_series_and_episode(
         db: AsyncSession,
@@ -657,7 +788,7 @@ class EpisodeService:
                 updated_count += 1
         
         await db.flush()
-        logger.info(f"Bulk marked {updated_count} episodes as downloaded")
+        logger.info("Bulk marked %s episodes as downloaded", updated_count)
         
         return updated_count
 
@@ -684,6 +815,8 @@ class DownloadQueueService:
         episode_id: int,
         download_url: Optional[str] = None,
         file_destination: Optional[str] = None,
+        status: str = "pending",
+        retry_count: int = 0,
     ) -> DownloadQueueItem:
         """Add item to download queue.
         
@@ -693,6 +826,8 @@ class DownloadQueueService:
             episode_id: Foreign key to Episode
             download_url: Optional provider download URL
             file_destination: Optional target file path
+            status: Queue item status (default: "pending")
+            retry_count: Number of retry attempts (default: 0)
         
         Returns:
             Created DownloadQueueItem instance
@@ -702,13 +837,15 @@ class DownloadQueueService:
             episode_id=episode_id,
             download_url=download_url,
             file_destination=file_destination,
+            status=status,
+            retry_count=retry_count,
         )
         db.add(item)
         await db.flush()
         await db.refresh(item)
         logger.info(
             f"Added to download queue: episode_id={episode_id} "
-            f"for series_id={series_id}"
+            f"for series_id={series_id}, status={status}"
         )
         return item
     
@@ -735,21 +872,24 @@ class DownloadQueueService:
     async def get_by_episode(
         db: AsyncSession,
         episode_id: int,
+        status_filter: Optional[str] = None,
     ) -> Optional[DownloadQueueItem]:
         """Get download queue item by episode ID.
         
         Args:
             db: Database session
             episode_id: Foreign key to Episode
+            status_filter: Optional status to filter by (e.g., "pending")
         
         Returns:
             DownloadQueueItem instance or None if not found
         """
-        result = await db.execute(
-            select(DownloadQueueItem).where(
-                DownloadQueueItem.episode_id == episode_id
-            )
+        query = select(DownloadQueueItem).where(
+            DownloadQueueItem.episode_id == episode_id
         )
+        if status_filter:
+            query = query.where(DownloadQueueItem.status == status_filter)
+        result = await db.execute(query)
         return result.scalar_one_or_none()
     
     @staticmethod
@@ -806,7 +946,96 @@ class DownloadQueueService:
         
         await db.flush()
         await db.refresh(item)
-        logger.debug(f"Set error on download queue item {item_id}")
+        logger.debug("Set error on download queue item %s", item_id)
+        return item
+    
+    @staticmethod
+    async def set_status(
+        db: AsyncSession,
+        item_id: int,
+        status: str,
+    ) -> Optional[DownloadQueueItem]:
+        """Set status on download queue item.
+        
+        Args:
+            db: Database session
+            item_id: Item primary key
+            status: New status value
+        
+        Returns:
+            Updated DownloadQueueItem instance or None if not found
+        """
+        item = await DownloadQueueService.get_by_id(db, item_id)
+        if not item:
+            return None
+        
+        item.status = status
+        
+        await db.flush()
+        await db.refresh(item)
+        logger.debug("Set status on download queue item %s to %s", item_id, status)
+        return item
+    
+    @staticmethod
+    async def increment_retry_count(
+        db: AsyncSession,
+        item_id: int,
+    ) -> Optional[DownloadQueueItem]:
+        """Increment retry count on download queue item.
+        
+        Args:
+            db: Database session
+            item_id: Item primary key
+        
+        Returns:
+            Updated DownloadQueueItem instance or None if not found
+        """
+        item = await DownloadQueueService.get_by_id(db, item_id)
+        if not item:
+            return None
+        
+        item.retry_count += 1
+        
+        await db.flush()
+        await db.refresh(item)
+        logger.debug(
+            "Incremented retry count on download queue item %s to %s",
+            item_id, item.retry_count
+        )
+        return item
+    
+    @staticmethod
+    async def set_status_and_error(
+        db: AsyncSession,
+        item_id: int,
+        status: str,
+        error_message: Optional[str] = None,
+    ) -> Optional[DownloadQueueItem]:
+        """Set status and error message on download queue item atomically.
+        
+        Args:
+            db: Database session
+            item_id: Item primary key
+            status: New status value
+            error_message: Optional error description
+        
+        Returns:
+            Updated DownloadQueueItem instance or None if not found
+        """
+        item = await DownloadQueueService.get_by_id(db, item_id)
+        if not item:
+            return None
+        
+        item.status = status
+        if error_message is not None:
+            item.error_message = error_message
+        
+        await db.flush()
+        await db.refresh(item)
+        logger.debug(
+            "Set status=%s on download queue item %s, error=%s",
+            status, item_id, error_message
+        )
         return item
     
     @staticmethod
@@ -825,7 +1054,7 @@ class DownloadQueueService:
         )
         deleted = result.rowcount > 0
         if deleted:
-            logger.info(f"Deleted download queue item with id={item_id}")
+            logger.info("Deleted download queue item with id=%s", item_id)
         return deleted
     
     @staticmethod
@@ -887,7 +1116,7 @@ class DownloadQueueService:
         )
         
         count = result.rowcount
-        logger.info(f"Bulk deleted {count} download queue items")
+        logger.info("Bulk deleted %s download queue items", count)
         
         return count
 
@@ -908,7 +1137,7 @@ class DownloadQueueService:
         """
         result = await db.execute(delete(DownloadQueueItem))
         count = result.rowcount
-        logger.info(f"Cleared all {count} download queue items")
+        logger.info("Cleared all %s download queue items", count)
         return count
 
 
@@ -962,7 +1191,7 @@ class UserSessionService:
         db.add(session)
         await db.flush()
         await db.refresh(session)
-        logger.info(f"Created user session: {session_id}")
+        logger.info("Created user session: %s", session_id)
         return session
     
     @staticmethod
@@ -1049,7 +1278,7 @@ class UserSessionService:
         
         session.revoke()
         await db.flush()
-        logger.info(f"Revoked user session: {session_id}")
+        logger.info("Revoked user session: %s", session_id)
         return True
     
     @staticmethod
@@ -1071,7 +1300,7 @@ class UserSessionService:
             )
         )
         count = result.rowcount
-        logger.info(f"Cleaned up {count} expired sessions")
+        logger.info("Cleaned up %s expired sessions", count)
         return count
 
     @staticmethod
@@ -1136,3 +1365,176 @@ class UserSessionService:
         
         return new_session
 
+
+# ============================================================================
+# Unresolved Folder Service
+# ============================================================================
+
+
+class UnresolvedFolderService:
+    """Service for tracking and resolving folders that couldn't be auto-resolved.
+    
+    During initial setup, some folders may not resolve to a provider key
+    (no search match or multiple ambiguous matches). These are tracked as
+    UnresolvedFolder records and can later be resolved by the user providing
+    the correct provider key.
+    """
+    
+    @staticmethod
+    async def create(
+        db: AsyncSession,
+        folder_name: str,
+        title: str,
+        year: int | None = None,
+        search_attempts: int = 1,
+        last_search_result: str | None = None,
+    ) -> UnresolvedFolder:
+        """Create a new unresolved folder tracking record.
+        
+        Args:
+            db: Database session
+            folder_name: Original filesystem folder name
+            title: Extracted title from folder name
+            year: Extracted release year (optional)
+            search_attempts: Number of search attempts made (default: 1)
+            last_search_result: JSON string of search results for UI (optional)
+        
+        Returns:
+            Created UnresolvedFolder instance
+        """
+        folder = UnresolvedFolder(
+            folder_name=folder_name,
+            title=title,
+            year=year,
+            search_attempts=search_attempts,
+            last_search_result=last_search_result,
+        )
+        db.add(folder)
+        await db.flush()
+        await db.refresh(folder)
+        logger.info(
+            "Created unresolved folder tracking: %s (title=%s, year=%s)",
+            folder_name, title, year
+        )
+        return folder
+    
+    @staticmethod
+    async def get_by_folder_name(
+        db: AsyncSession,
+        folder_name: str,
+    ) -> Optional[UnresolvedFolder]:
+        """Get unresolved folder by folder name.
+        
+        Args:
+            db: Database session
+            folder_name: Filesystem folder name to look up
+        
+        Returns:
+            UnresolvedFolder instance or None if not found
+        """
+        result = await db.execute(
+            select(UnresolvedFolder).where(
+                UnresolvedFolder.folder_name == folder_name
+            )
+        )
+        return result.scalar_one_or_none()
+    
+    @staticmethod
+    async def get_all_unresolved(
+        db: AsyncSession,
+    ) -> list[UnresolvedFolder]:
+        """Get all unresolved folders that haven't been resolved yet.
+        
+        Args:
+            db: Database session
+        
+        Returns:
+            List of unresolved UnresolvedFolder instances
+        """
+        result = await db.execute(
+            select(UnresolvedFolder)
+            .where(UnresolvedFolder.provider_key.is_(None))
+            .order_by(UnresolvedFolder.created_at)
+        )
+        return list(result.scalars().all())
+    
+    @staticmethod
+    async def resolve(
+        db: AsyncSession,
+        folder_name: str,
+        provider_key: str,
+    ) -> Optional[UnresolvedFolder]:
+        """Mark an unresolved folder as resolved with the given provider key.
+        
+        Args:
+            db: Database session
+            folder_name: Filesystem folder name to resolve
+            provider_key: Provider key to associate with this folder
+        
+        Returns:
+            Updated UnresolvedFolder instance or None if not found
+        """
+        from datetime import datetime, timezone
+        
+        folder = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+        if not folder:
+            return None
+        
+        folder.provider_key = provider_key
+        folder.resolved_at = datetime.now(timezone.utc)
+        await db.flush()
+        await db.refresh(folder)
+        logger.info(
+            "Resolved unresolved folder: %s -> key=%s",
+            folder_name, provider_key
+        )
+        return folder
+    
+    @staticmethod
+    async def delete(
+        db: AsyncSession,
+        folder_name: str,
+    ) -> bool:
+        """Delete an unresolved folder record (e.g., after manual add).
+        
+        Args:
+            db: Database session
+            folder_name: Filesystem folder name to delete
+        
+        Returns:
+            True if deleted, False if not found
+        """
+        folder = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+        if not folder:
+            return False
+        
+        await db.delete(folder)
+        await db.flush()
+        return True
+    
+    @staticmethod
+    async def update_search_result(
+        db: AsyncSession,
+        folder_name: str,
+        search_result: str,
+    ) -> Optional[UnresolvedFolder]:
+        """Update the cached search result for an unresolved folder.
+        
+        Args:
+            db: Database session
+            folder_name: Filesystem folder name to update
+            search_result: JSON string of search results
+        
+        Returns:
+            Updated UnresolvedFolder instance or None if not found
+        """
+        folder = await UnresolvedFolderService.get_by_folder_name(db, folder_name)
+        if not folder:
+            return None
+        
+        folder.search_attempts += 1
+        folder.last_search_result = search_result
+        await db.flush()
+        await db.refresh(folder)
+        return folder
+

src/server/database/system_settings_service.py

@@ -125,6 +125,66 @@ class SystemSettingsService:
         settings = await SystemSettingsService.get_or_create(db)
         return settings.initial_media_scan_completed
 
+    @staticmethod
+    async def is_migration_legacy_files_completed(db: AsyncSession) -> bool:
+        """Check if legacy key/data file migration has been completed.
+        
+        Args:
+            db: Database session
+            
+        Returns:
+            True if legacy migration is completed, False otherwise
+        """
+        settings = await SystemSettingsService.get_or_create(db)
+        return settings.migration_legacy_files_completed
+
+    @staticmethod
+    async def mark_migration_legacy_files_completed(
+        db: AsyncSession,
+        timestamp: Optional[datetime] = None
+    ) -> None:
+        """Mark the legacy key/data file migration as completed.
+        
+        Args:
+            db: Database session
+            timestamp: Optional timestamp to set, defaults to current time
+        """
+        settings = await SystemSettingsService.get_or_create(db)
+        settings.migration_legacy_files_completed = True
+        settings.last_scan_timestamp = timestamp or datetime.now(timezone.utc)
+        await db.commit()
+        logger.info("Marked legacy files migration as completed")
+
+    @staticmethod
+    async def is_legacy_key_cleanup_completed(db: AsyncSession) -> bool:
+        """Check if legacy key file cleanup has been completed.
+
+        Args:
+            db: Database session
+
+        Returns:
+            True if cleanup is completed, False otherwise
+        """
+        settings = await SystemSettingsService.get_or_create(db)
+        return settings.legacy_key_cleanup_completed
+
+    @staticmethod
+    async def mark_legacy_key_cleanup_completed(
+        db: AsyncSession,
+        timestamp: Optional[datetime] = None
+    ) -> None:
+        """Mark the legacy key file cleanup as completed.
+
+        Args:
+            db: Database session
+            timestamp: Optional timestamp to set, defaults to current time
+        """
+        settings = await SystemSettingsService.get_or_create(db)
+        settings.legacy_key_cleanup_completed = True
+        settings.last_scan_timestamp = timestamp or datetime.now(timezone.utc)
+        await db.commit()
+        logger.info("Marked legacy key file cleanup as completed")
+
     @staticmethod
     async def mark_initial_media_scan_completed(
         db: AsyncSession,
@@ -154,6 +214,8 @@ class SystemSettingsService:
         settings.initial_scan_completed = False
         settings.initial_nfo_scan_completed = False
         settings.initial_media_scan_completed = False
+        settings.migration_legacy_files_completed = False
+        settings.legacy_key_cleanup_completed = False
         settings.last_scan_timestamp = None
         await db.commit()
         logger.info("Reset all scan completion flags")

src/server/error_handler.py

@@ -0,0 +1,212 @@
+"""
+Error handling and recovery strategies for core providers.
+
+This module provides custom exceptions and decorators for handling
+errors in provider operations with automatic retry mechanisms.
+"""
+
+import functools
+import logging
+from typing import Any, Callable, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+# Type variable for decorator
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class RetryableError(Exception):
+    """Exception that indicates an operation can be safely retried."""
+
+    pass
+
+
+class NonRetryableError(Exception):
+    """Exception that indicates an operation should not be retried."""
+
+    pass
+
+
+class NetworkError(Exception):
+    """Exception for network-related errors."""
+
+    pass
+
+
+class DownloadError(Exception):
+    """Exception for download-related errors."""
+
+    pass
+
+
+class RecoveryStrategies:
+    """Strategies for handling errors and recovering from failures."""
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        exponential_base: float = 2.0,
+    ) -> None:
+        """Initialize recovery strategies.
+
+        Args:
+            max_retries: Maximum number of retry attempts.
+            base_delay: Initial delay between retries in seconds.
+            max_delay: Maximum delay between retries in seconds.
+            exponential_base: Base for exponential backoff multiplier.
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+
+    def _calculate_delay(self, attempt: int) -> float:
+        """Calculate delay for given retry attempt using exponential backoff.
+
+        Args:
+            attempt: Zero-based retry attempt number.
+
+        Returns:
+            Delay in seconds before next retry.
+        """
+        delay = self.base_delay * (self.exponential_base ** attempt)
+        return min(delay, self.max_delay)
+
+    @staticmethod
+    def handle_network_failure(
+        func: Callable, *args: Any, **kwargs: Any
+    ) -> Any:
+        """Handle network failures with exponential backoff retry logic."""
+        last_error: Optional[Exception] = None
+        max_retries = 3
+        base_delay = 1.0
+        max_delay = 60.0
+        exponential_base = 2.0
+        
+        for attempt in range(max_retries):
+            try:
+                return func(*args, **kwargs)
+            except (NetworkError, ConnectionError, TimeoutError) as exc:
+                last_error = exc
+                if attempt < max_retries - 1:
+                    delay = base_delay * (exponential_base ** attempt)
+                    delay = min(delay, max_delay)
+                    logger.warning(
+                        "Network error on attempt %d/%d, retrying in %.1fs: %s",
+                        attempt + 1, max_retries, delay, exc
+                    )
+                    import time
+                    time.sleep(delay)
+                    continue
+        if last_error:
+            raise last_error
+        raise NetworkError("Network failure after retries")
+
+    @staticmethod
+    def handle_download_failure(
+        func: Callable, *args: Any, **kwargs: Any
+    ) -> Any:
+        """Handle download failures with exponential backoff retry logic."""
+        last_error: Optional[Exception] = None
+        max_retries = 2
+        base_delay = 1.0
+        max_delay = 60.0
+        exponential_base = 2.0
+        
+        for attempt in range(max_retries):
+            try:
+                return func(*args, **kwargs)
+            except DownloadError as exc:
+                last_error = exc
+                if attempt < max_retries - 1:
+                    delay = base_delay * (exponential_base ** attempt)
+                    delay = min(delay, max_delay)
+                    logger.warning(
+                        "Download error on attempt %d/%d, retrying in %.1fs: %s",
+                        attempt + 1, max_retries, delay, exc
+                    )
+                    import time
+                    time.sleep(delay)
+                    continue
+        if last_error:
+            raise last_error
+        raise DownloadError("Download failed after retries")
+
+
+class FileCorruptionDetector:
+    """Detector for corrupted files."""
+
+    @staticmethod
+    def is_valid_video_file(filepath: str) -> bool:
+        """Check if a video file is valid and not corrupted."""
+        try:
+            import os
+            if not os.path.exists(filepath):
+                return False
+            
+            file_size = os.path.getsize(filepath)
+            # Video files should be at least 1MB
+            return file_size > 1024 * 1024
+        except Exception as e:
+            logger.error("Error checking file validity: %s", e)
+            return False
+
+
+def with_error_recovery(
+    max_retries: int = 3, context: str = ""
+) -> Callable[[F], F]:
+    """
+    Decorator for adding error recovery to functions.
+    
+    Args:
+        max_retries: Maximum number of retry attempts
+        context: Context string for logging
+        
+    Returns:
+        Decorated function with retry logic
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            last_error = None
+            for attempt in range(max_retries):
+                try:
+                    return func(*args, **kwargs)
+                except NonRetryableError:
+                    raise
+                except Exception as e:
+                    last_error = e
+                    if attempt < max_retries - 1:
+                        logger.warning(
+                            "Error in %s (attempt %d/%d): %s, retrying...",
+                            context,
+                            attempt + 1,
+                            max_retries,
+                            e,
+                        )
+                    else:
+                        logger.error(
+                            "Error in %s failed after %d attempts: %s",
+                            context,
+                            max_retries,
+                            e,
+                        )
+
+            if last_error:
+                raise last_error
+            
+            raise RuntimeError(
+                f"Unexpected error in {context} after {max_retries} attempts"
+            )
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+# Create module-level instances for use in provider code
+recovery_strategies = RecoveryStrategies()
+file_corruption_detector = FileCorruptionDetector()

src/server/exceptions/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from src.server.exceptions.exceptions.Exceptions import MatchNotFoundError, NoKeyFoundException
+
+__all__ = ["MatchNotFoundError", "NoKeyFoundException"]

src/server/fastapi_app.py

@@ -6,6 +6,7 @@ configuration, middleware setup, static file serving, and Jinja2 template
 integration.
 """
 import asyncio
+import logging
 from contextlib import asynccontextmanager
 from pathlib import Path
 
@@ -26,6 +27,7 @@ from src.server.api.health import router as health_router
 from src.server.api.logging import router as logging_router
 from src.server.api.nfo import router as nfo_router
 from src.server.api.scheduler import router as scheduler_router
+from src.server.api.setup_endpoints import router as setup_router
 from src.server.api.websocket import router as websocket_router
 from src.server.controllers.error_controller import (
     not_found_handler,
@@ -37,7 +39,6 @@ from src.server.controllers.page_controller import router as page_router
 from src.server.middleware.auth import AuthMiddleware
 from src.server.middleware.error_handler import register_exception_handlers
 from src.server.middleware.setup_redirect import SetupRedirectMiddleware
-from src.server.services.anime_service import sync_series_from_data_files
 from src.server.services.progress_service import get_progress_service
 from src.server.services.websocket_service import get_websocket_service
 
@@ -51,7 +52,7 @@ async def _check_incomplete_series_on_startup(background_loader) -> None:
     Args:
         background_loader: BackgroundLoaderService instance
     """
-    logger = setup_logging(log_level="INFO")
+    logger = logging.getLogger("aniworld")
     
     try:
         from src.server.database.connection import get_db_session
@@ -96,11 +97,112 @@ async def _check_incomplete_series_on_startup(background_loader) -> None:
                 else:
                     logger.info("All series data is complete. No background loading needed.")
                 
-            except Exception as e:
-                logger.error(f"Error checking incomplete series: {e}", exc_info=True)
+            except Exception:
+                logger.exception("Error checking incomplete series")
             
+    except Exception:
+        logger.exception("Failed to check incomplete series on startup")
+
+
+async def _run_startup_health_checks(logger) -> dict:
+    """Run startup health checks for critical dependencies.
+    
+    Checks:
+    - ffmpeg availability
+    - DNS resolution for aniworld.to and api.themoviedb.org
+    - anime_directory configuration and writability
+    
+    Args:
+        logger: Logger instance for recording check results.
+        
+    Returns:
+        dict: Health check results with status and details for each check.
+    """
+    import asyncio
+    import shutil
+    import socket
+    from typing import Any, Dict
+    
+    checks: Dict[str, Any] = {
+        "ffmpeg": {"status": "unknown", "message": None},
+        "dns_aniworld": {"status": "unknown", "message": None},
+        "dns_tmdb": {"status": "unknown", "message": None},
+        "anime_directory": {"status": "unknown", "message": None, "path": None},
+    }
+    
+    # Check ffmpeg availability
+    try:
+        ffmpeg_path = shutil.which("ffmpeg")
+        if ffmpeg_path:
+            checks["ffmpeg"]["status"] = "ok"
+            checks["ffmpeg"]["message"] = f"Found at {ffmpeg_path}"
+            logger.debug("ffmpeg health check passed: %s", ffmpeg_path)
+        else:
+            checks["ffmpeg"]["status"] = "warning"
+            checks["ffmpeg"]["message"] = "ffmpeg not found in PATH"
+            logger.warning("ffmpeg health check failed: not in PATH")
     except Exception as e:
-        logger.error(f"Failed to check incomplete series on startup: {e}", exc_info=True)
+        checks["ffmpeg"]["status"] = "error"
+        checks["ffmpeg"]["message"] = str(e)
+        logger.warning("Could not check ffmpeg: %s", e)
+    
+    # Check DNS resolution for aniworld.to
+    try:
+        socket.gethostbyname("aniworld.to")
+        checks["dns_aniworld"]["status"] = "ok"
+        checks["dns_aniworld"]["message"] = "Resolved successfully"
+        logger.debug("DNS health check passed for aniworld.to")
+    except socket.gaierror as e:
+        checks["dns_aniworld"]["status"] = "warning"
+        checks["dns_aniworld"]["message"] = f"DNS resolution failed: {e}"
+        logger.warning("DNS health check failed for aniworld.to: %s", e)
+    except Exception as e:
+        checks["dns_aniworld"]["status"] = "warning"
+        checks["dns_aniworld"]["message"] = f"Unexpected error: {e}"
+        logger.warning("Unexpected DNS error for aniworld.to: %s", e)
+    
+    # Check DNS resolution for api.themoviedb.org
+    try:
+        socket.gethostbyname("api.themoviedb.org")
+        checks["dns_tmdb"]["status"] = "ok"
+        checks["dns_tmdb"]["message"] = "Resolved successfully"
+        logger.debug("DNS health check passed for api.themoviedb.org")
+    except socket.gaierror as e:
+        checks["dns_tmdb"]["status"] = "warning"
+        checks["dns_tmdb"]["message"] = f"DNS resolution failed: {e}"
+        logger.warning("DNS health check failed for api.themoviedb.org: %s", e)
+    except Exception as e:
+        checks["dns_tmdb"]["status"] = "warning"
+        checks["dns_tmdb"]["message"] = f"Unexpected error: {e}"
+        logger.warning("Unexpected DNS error for api.themoviedb.org: %s", e)
+    
+    # Check anime_directory configuration and writability
+    from src.config.settings import settings
+    anime_dir = settings.anime_directory
+    
+    if not anime_dir:
+        checks["anime_directory"]["status"] = "error"
+        checks["anime_directory"]["message"] = "anime_directory not configured"
+        checks["anime_directory"]["path"] = None
+        logger.error("anime_directory health check failed: not configured")
+    else:
+        import os
+        checks["anime_directory"]["path"] = anime_dir
+        
+        if not os.path.isdir(anime_dir):
+            checks["anime_directory"]["status"] = "error"
+            checks["anime_directory"]["message"] = f"Directory does not exist: {anime_dir}"
+            logger.error("anime_directory health check failed: %s does not exist", anime_dir)
+        elif not os.access(anime_dir, os.W_OK):
+            checks["anime_directory"]["status"] = "error"
+            checks["anime_directory"]["message"] = f"Directory not writable: {anime_dir}"
+            logger.error("anime_directory health check failed: %s not writable", anime_dir)
+        else:
+            checks["anime_directory"]["status"] = "ok"
+            checks["anime_directory"]["message"] = f"Directory exists and is writable: {anime_dir}"
+            logger.debug("anime_directory health check passed: %s", anime_dir)
+    
+    return checks
 
 
 @asynccontextmanager
@@ -113,6 +215,7 @@ async def lifespan(_application: FastAPI):
     """
     # Setup logging first with INFO level
     logger = setup_logging(log_level="INFO")
+    logger.info("Starting FastAPI application v%s", APP_VERSION)
     
     # Track successful initialization steps
     initialized = {
@@ -241,7 +344,6 @@ async def lifespan(_application: FastAPI):
         from src.server.services.initialization_service import (
             perform_initial_setup,
             perform_media_scan_if_needed,
-            perform_nfo_repair_scan,
             perform_nfo_scan_if_needed,
         )
         
@@ -297,30 +399,29 @@ async def lifespan(_application: FastAPI):
                 except Exception as e:
                     logger.warning("Failed to start background loader service: %s", e)
 
-                # Initialize and start scheduler service
-                try:
-                    from src.server.services.scheduler_service import (
-                        get_scheduler_service,
-                    )
-                    scheduler_service = get_scheduler_service()
-                    await scheduler_service.start()
-                    initialized['scheduler'] = True
-                    logger.info("Scheduler service started")
-                except Exception as e:
-                    logger.warning("Failed to start scheduler service: %s", e)
-                    # Continue - scheduler is optional
-
                 # Run media scan only on first run
                 await perform_media_scan_if_needed(background_loader)
-
-                # Scan every series NFO on startup and repair any that are
-                # missing required tags by queuing them for background reload
-                await perform_nfo_repair_scan(background_loader)
             else:
                 logger.info(
                     "Download service initialization skipped - "
                     "anime directory not configured"
                 )
+
+            # Initialize and start scheduler service (independent of anime_directory)
+            # The scheduler loads its own config from config.json and the
+            # anime_directory may be configured there even if the env var is empty.
+            try:
+                logger.info("Initializing scheduler service...")
+                from src.server.services.scheduler.scheduler_service import (
+                    get_scheduler_service,
+                )
+                scheduler_service = get_scheduler_service()
+                logger.info("Scheduler service instance obtained, starting...")
+                await scheduler_service.start()
+                initialized['scheduler'] = True
+                logger.info("Scheduler service started successfully")
+            except Exception as e:
+                logger.warning("Failed to start scheduler service: %s", e)
         except (OSError, RuntimeError, ValueError) as e:
             logger.warning("Failed to initialize services: %s", e)
             # Continue startup - services can be initialized later
@@ -333,6 +434,27 @@ async def lifespan(_application: FastAPI):
         logger.info(
             "API documentation available at http://127.0.0.1:8000/api/docs"
         )
+
+        # Check for ffmpeg availability and warn if missing
+        try:
+            import shutil as _shutil
+            if _shutil.which("ffmpeg") is None:
+                logger.warning(
+                    "ffmpeg not found in PATH. HLS streams may fail to download. "
+                    "Install ffmpeg to enable HLS support."
+                )
+            else:
+                logger.debug("ffmpeg found at: %s", _shutil.which("ffmpeg"))
+        except Exception as _exc:
+            logger.warning("Could not check for ffmpeg: %s", _exc)
+
+        # Run startup health checks and store results for /health endpoint
+        try:
+            startup_checks = await _run_startup_health_checks(logger)
+            app.state.startup_checks = startup_checks
+        except Exception as _exc:
+            logger.warning("Could not run startup health checks: %s", _exc)
+            app.state.startup_checks = {}
     except Exception as e:
         logger.error("Error during startup: %s", e, exc_info=True)
         startup_error = e
@@ -377,7 +499,9 @@ async def lifespan(_application: FastAPI):
     # 1. Stop scheduler service (only if initialized)
     if initialized['scheduler']:
         try:
-            from src.server.services.scheduler_service import get_scheduler_service
+            from src.server.services.scheduler.scheduler_service import (
+                get_scheduler_service,
+            )
             scheduler_service = get_scheduler_service()
             logger.info("Stopping scheduler service...")
             await asyncio.wait_for(
@@ -422,8 +546,8 @@ async def lifespan(_application: FastAPI):
     
     # 4. Shutdown download service and persist active downloads
     try:
-        from src.server.services.download_service import (  # noqa: E501
-            _download_service_instance,
+        from src.server.services.download_service import (
+            _download_service_instance,  # noqa: E501
         )
         if _download_service_instance is not None:
             logger.info("Stopping download service...")
@@ -480,11 +604,13 @@ async def lifespan(_application: FastAPI):
         raise startup_error
 
 
+from src.server.utils.version import APP_VERSION
+
 # Initialize FastAPI app with lifespan
 app = FastAPI(
     title="Aniworld Download Manager",
     description="Modern web interface for Aniworld anime download management",
-    version="1.0.0",
+    version=APP_VERSION,
     docs_url="/api/docs",
     redoc_url="/api/redoc",
     lifespan=lifespan
@@ -523,6 +649,7 @@ app.include_router(scheduler_router)
 app.include_router(anime_router)
 app.include_router(download_router)
 app.include_router(nfo_router)
+app.include_router(setup_router)
 app.include_router(logging_router)
 app.include_router(websocket_router)
 

src/server/interfaces/callbacks.py

@@ -12,6 +12,8 @@ from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any, Dict, Optional
 
+logger = logging.getLogger(__name__)
+
 
 class OperationType(str, Enum):
     """Types of operations that can report progress."""
@@ -313,7 +315,7 @@ class CallbackManager:
                 callback.on_progress(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in progress callback %s: %s",
                     callback,
                     e,
@@ -332,7 +334,7 @@ class CallbackManager:
                 callback.on_error(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in error callback %s: %s",
                     callback,
                     e,
@@ -351,7 +353,7 @@ class CallbackManager:
                 callback.on_completion(context)
             except Exception as e:
                 # Log but don't let callback errors break the operation
-                logging.error(
+                logger.error(
                     "Error in completion callback %s: %s",
                     callback,
                     e,

src/server/middleware/error_handler.py

@@ -74,7 +74,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle authentication errors (401)."""
         logger.warning(
-            f"Authentication error: {exc.message}",
+            "Authentication error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -94,7 +95,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle authorization errors (403)."""
         logger.warning(
-            f"Authorization error: {exc.message}",
+            "Authorization error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -114,7 +116,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle validation errors (422)."""
         logger.info(
-            f"Validation error: {exc.message}",
+            "Validation error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -134,7 +137,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle bad request errors (400)."""
         logger.info(
-            f"Bad request error: {exc.message}",
+            "Bad request error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -154,7 +158,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle not found errors (404)."""
         logger.info(
-            f"Not found error: {exc.message}",
+            "Not found error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -174,7 +179,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle conflict errors (409)."""
         logger.info(
-            f"Conflict error: {exc.message}",
+            "Conflict error: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -194,7 +200,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle rate limit errors (429)."""
         logger.warning(
-            f"Rate limit exceeded: {exc.message}",
+            "Rate limit exceeded: %s",
+            exc.message,
             extra={"details": exc.details, "path": str(request.url.path)},
         )
         return JSONResponse(
@@ -214,7 +221,8 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle generic API exceptions."""
         logger.error(
-            f"API error: {exc.message}",
+            "API error: %s",
+            exc.message,
             extra={
                 "error_code": exc.error_code,
                 "details": exc.details,
@@ -238,12 +246,13 @@ def register_exception_handlers(app: FastAPI) -> None:
     ) -> JSONResponse:
         """Handle unexpected exceptions."""
         logger.exception(
-            f"Unexpected error: {str(exc)}",
+            "Unexpected error: %s",
+            str(exc),
             extra={"path": str(request.url.path)},
         )
 
         # Log full traceback for debugging
-        logger.debug(f"Traceback: {traceback.format_exc()}")
+        logger.debug("Traceback: %s", traceback.format_exc())
 
         # Return generic error response for security
         return JSONResponse(

src/server/middleware/security.py

@@ -315,11 +315,11 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             None if malicious content detected, sanitized value otherwise
         """
         if self.check_sql_injection and self._check_sql_injection(value):
-            logger.warning(f"Potential SQL injection detected: {value[:100]}")
+            logger.warning("Potential SQL injection detected: %s", value[:100])
             return None
 
         if self.check_xss and self._check_xss(value):
-            logger.warning(f"Potential XSS detected: {value[:100]}")
+            logger.warning("Potential XSS detected: %s", value[:100])
             return None
 
         return value
@@ -341,7 +341,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             content_type
             and not any(ct in content_type for ct in self.allowed_content_types)
         ):
-            logger.warning(f"Unsupported content type: {content_type}")
+            logger.warning("Unsupported content type: %s", content_type)
             return JSONResponse(
                 status_code=415,
                 content={"detail": "Unsupported Media Type"},
@@ -350,7 +350,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
         # Check request size
         content_length = request.headers.get("content-length")
         if content_length and int(content_length) > self.max_request_size:
-            logger.warning(f"Request too large: {content_length} bytes")
+            logger.warning("Request too large: %s bytes", content_length)
             return JSONResponse(
                 status_code=413,
                 content={"detail": "Request Entity Too Large"},
@@ -361,7 +361,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             if isinstance(value, str):
                 sanitized = self._sanitize_value(value)
                 if sanitized is None:
-                    logger.warning(f"Malicious query parameter detected: {key}")
+                    logger.warning("Malicious query parameter detected: %s", key)
                     return JSONResponse(
                         status_code=400,
                         content={"detail": "Malicious request detected"},
@@ -372,7 +372,7 @@ class RequestSanitizationMiddleware(BaseHTTPMiddleware):
             if isinstance(value, str):
                 sanitized = self._sanitize_value(value)
                 if sanitized is None:
-                    logger.warning(f"Malicious path parameter detected: {key}")
+                    logger.warning("Malicious path parameter detected: %s", key)
                     return JSONResponse(
                         status_code=400,
                         content={"detail": "Malicious request detected"},

src/server/models/anime.py

@@ -83,6 +83,30 @@ class AnimeSeriesResponse(BaseModel):
         return v
 
 
+class AnimeMetadataUpdate(BaseModel):
+    """Request model for updating anime metadata (key, tmdb_id, tvdb_id)."""
+
+    key: Optional[str] = Field(None, description="New series key (URL-safe, lowercase)")
+    tmdb_id: Optional[int] = Field(None, ge=1, description="TMDB ID (positive integer)")
+    tvdb_id: Optional[int] = Field(None, ge=1, description="TVDB ID (positive integer)")
+
+    @field_validator('key', mode='before')
+    @classmethod
+    def validate_key_format(cls, v: Optional[str]) -> Optional[str]:
+        """Validate key is URL-safe lowercase with hyphens only."""
+        if v is None:
+            return v
+        v = v.strip().lower()
+        if not v:
+            raise ValueError("Key cannot be empty")
+        if not KEY_PATTERN.match(v):
+            raise ValueError(
+                "Key must contain only lowercase letters, numbers, and hyphens. "
+                "Cannot start or end with a hyphen."
+            )
+        return v
+
+
 class SearchRequest(BaseModel):
     """Request payload for searching series."""
 

src/server/models/config.py

@@ -39,6 +39,21 @@ class SchedulerConfig(BaseModel):
         description="Automatically queue and start downloads for all missing "
                     "episodes after a scheduled rescan completes.",
     )
+    nfo_scan_after_rescan: bool = Field(
+        default=True,
+        description="Run NFO validation and creation after a scheduled rescan "
+                    "completes. Checks each series folder for tvshow.nfo and "
+                    "creates or fills missing properties.",
+    )
+    # Legacy alias fields — read via Pydantic alias
+    auto_download: Optional[bool] = Field(default=None, alias="auto_download")
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        # Map legacy keys to primary fields only when primary key absent from data.
+        # "key in data" checks for explicit presence (even False/None), not just truthiness.
+        if self.auto_download is not None and "auto_download_after_rescan" not in data:
+            object.__setattr__(self, "auto_download_after_rescan", self.auto_download)
 
     @field_validator("schedule_time")
     @classmethod
@@ -64,6 +79,22 @@ class SchedulerConfig(BaseModel):
             )
         return v
 
+    def model_dump(self, **kwargs) -> Dict[str, object]:
+        """Serialize, excluding legacy alias fields when they are None.
+
+        The alias fields (auto_download, folder_scan) must not be written to
+        config.json as null entries, otherwise a roundtrip load sees the key
+        present (哪怕 value is None) and skips the alias-to-primary mapping.
+        """
+        data = super().model_dump(**kwargs)
+        # Drop None alias fields so they don't pollute config.json.
+        # They are still settable via the constructor for backward compatibility.
+        if data.get("auto_download") is None:
+            data.pop("auto_download", None)
+        if data.get("folder_scan") is None:
+            data.pop("folder_scan", None)
+        return data
+
 
 class BackupConfig(BaseModel):
     """Configuration for automatic backups of application data."""
@@ -166,6 +197,12 @@ class AppConfig(BaseModel):
     logging: LoggingConfig = Field(default_factory=LoggingConfig)
     backup: BackupConfig = Field(default_factory=BackupConfig)
     nfo: NFOConfig = Field(default_factory=NFOConfig)
+    scan_key_overrides: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Map of folder names to provider keys for scan overrides. "
+                    "Used when auto-generated keys from folder names are incorrect. "
+                    "Format: {\"Folder Name\": \"actual-provider-key\"}"
+    )
     other: Dict[str, object] = Field(
         default_factory=dict, description="Arbitrary other settings"
     )
@@ -204,6 +241,7 @@ class ConfigUpdate(BaseModel):
     logging: Optional[LoggingConfig] = None
     backup: Optional[BackupConfig] = None
     nfo: Optional[NFOConfig] = None
+    scan_key_overrides: Optional[Dict[str, str]] = None
     other: Optional[Dict[str, object]] = None
 
     def apply_to(self, current: AppConfig) -> AppConfig:
@@ -220,6 +258,8 @@ class ConfigUpdate(BaseModel):
             data["backup"] = self.backup.model_dump()
         if self.nfo is not None:
             data["nfo"] = self.nfo.model_dump()
+        if self.scan_key_overrides is not None:
+            data["scan_key_overrides"] = self.scan_key_overrides
         if self.other is not None:
             merged = dict(current.other or {})
             merged.update(self.other)

src/server/models/download.py

@@ -22,6 +22,7 @@ class DownloadStatus(str, Enum):
     COMPLETED = "completed"
     FAILED = "failed"
     CANCELLED = "cancelled"
+    PERMANENTLY_FAILED = "permanently_failed"
 
 
 class DownloadPriority(str, Enum):

src/server/models/nfo.py

@@ -355,3 +355,29 @@ class NFOMissingResponse(BaseModel):
         ...,
         description="List of series missing NFO"
     )
+
+
+class NfoDiagnosticsResponse(BaseModel):
+    """Response for NFO diagnostics showing missing required tags."""
+
+    has_nfo: bool = Field(..., description="Whether tvshow.nfo exists")
+    nfo_path: Optional[str] = Field(None, description="Path to NFO file if exists")
+    missing_tags: List[str] = Field(
+        default_factory=list,
+        description="List of missing required tag names"
+    )
+    required_tags: List[str] = Field(
+        default_factory=list,
+        description="All required tag names for reference"
+    )
+
+
+class NfoRepairResponse(BaseModel):
+    """Response after NFO repair attempt."""
+
+    success: bool = Field(..., description="Whether repair succeeded")
+    message: str = Field(..., description="Human-readable result message")
+    repaired_tags: List[str] = Field(
+        default_factory=list,
+        description="Tags that were missing before repair"
+    )

src/server/nfo/__init__.py

@@ -0,0 +1,9 @@
+"""NFO package - TV show metadata generation for Kodi/XBMC.
+
+Re-exports the public API for the nfo package.
+"""
+
+from src.server.nfo.nfo_models import TVShowNFO
+from src.server.nfo.tmdb_client import TMDBClient, TMDBAPIError
+from src.server.nfo.nfo_generator import generate_tvshow_nfo
+from src.server.nfo.nfo_mapper import tmdb_to_nfo_model

src/server/nfo/nfo_generator.py

@@ -4,7 +4,7 @@ This module provides functions to generate tvshow.nfo XML files from
 TVShowNFO Pydantic models, adapted from the scraper project.
 
 Example:
-    >>> from src.core.entities.nfo_models import TVShowNFO
+    >>> from src.server.nfo.nfo_models import TVShowNFO
     >>> nfo = TVShowNFO(title="Test Show", year=2020, tmdbid=12345)
     >>> xml_string = generate_tvshow_nfo(nfo)
 """
@@ -15,7 +15,7 @@ from typing import Optional
 from lxml import etree
 
 from src.config.settings import settings
-from src.core.entities.nfo_models import TVShowNFO
+from src.server.nfo.nfo_models import TVShowNFO
 
 logger = logging.getLogger(__name__)
 
@@ -43,8 +43,10 @@ def generate_tvshow_nfo(tvshow: TVShowNFO, pretty_print: bool = True) -> str:
     _add_element(root, "sorttitle", tvshow.sorttitle)
     _add_element(root, "year", str(tvshow.year) if tvshow.year else None)
     
-    # Plot and description
-    _add_element(root, "plot", tvshow.plot)
+    # Plot and description – always write <plot> even when empty so that
+    # all NFO files have a consistent set of tags regardless of whether they
+    # were produced by create or update.
+    _add_element(root, "plot", tvshow.plot, always_write=True)
     _add_element(root, "outline", tvshow.outline)
     _add_element(root, "tagline", tvshow.tagline)
     
@@ -164,13 +166,23 @@ def generate_tvshow_nfo(tvshow: TVShowNFO, pretty_print: bool = True) -> str:
     return xml_declaration + xml_str
 
 
-def _add_element(parent: etree.Element, tag: str, text: Optional[str]) -> Optional[etree.Element]:
+def _add_element(
+    parent: etree.Element,
+    tag: str,
+    text: Optional[str],
+    always_write: bool = False,
+) -> Optional[etree.Element]:
     """Add a child element to parent if text is not None or empty.
     
     Args:
         parent: Parent XML element
         tag: Tag name for child element
-        text: Text content (None or empty strings are skipped)
+        text: Text content (None or empty strings are skipped
+              unless *always_write* is True)
+        always_write: When True the element is created even when
+                      *text* is None/empty (the element will have
+                      no text content).  Useful for tags like
+                      ``<plot>`` that should always be present.
         
     Returns:
         Created element or None if skipped
@@ -179,6 +191,8 @@ def _add_element(parent: etree.Element, tag: str, text: Optional[str]) -> Option
         elem = etree.SubElement(parent, tag)
         elem.text = text
         return elem
+    if always_write:
+        return etree.SubElement(parent, tag)
     return None
 
 
@@ -195,5 +209,5 @@ def validate_nfo_xml(xml_string: str) -> bool:
         etree.fromstring(xml_string.encode('utf-8'))
         return True
     except etree.XMLSyntaxError as e:
-        logger.error(f"Invalid NFO XML: {e}")
+        logger.error("Invalid NFO XML: %s", e)
         return False

src/server/nfo/nfo_mapper.py

@@ -11,9 +11,10 @@ import logging
 from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
-from src.core.entities.nfo_models import (
+from src.server.nfo.nfo_models import (
     ActorInfo,
     ImageInfo,
+    NamedSeason,
     RatingInfo,
     TVShowNFO,
     UniqueID,
@@ -167,6 +168,17 @@ def tmdb_to_nfo_model(
             tmdbid=member["id"],
         ))
 
+    # --- Named seasons ---
+    named_seasons: List[NamedSeason] = []
+    for season_info in tmdb_data.get("seasons", []):
+        season_name = season_info.get("name")
+        season_number = season_info.get("season_number")
+        if season_name and season_number is not None:
+            named_seasons.append(NamedSeason(
+                number=season_number,
+                name=season_name,
+            ))
+
     # --- Unique IDs ---
     unique_ids: List[UniqueID] = []
     if tmdb_data.get("id"):
@@ -194,6 +206,7 @@ def tmdb_to_nfo_model(
     return TVShowNFO(
         title=title,
         originaltitle=original_title,
+        showtitle=title,
         sorttitle=title,
         year=year,
         plot=tmdb_data.get("overview") or None,
@@ -215,6 +228,7 @@ def tmdb_to_nfo_model(
         thumb=thumb_images,
         fanart=fanart_images,
         actors=actors,
+        namedseason=named_seasons,
         watched=False,
         dateadded=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
     )

src/server/nfo/nfo_models.py

@@ -0,0 +1,335 @@
+"""Pydantic models for NFO metadata based on Kodi/XBMC standard.
+
+This module provides data models for tvshow.nfo files that are compatible
+with media center applications like Kodi, Plex, and Jellyfin.
+
+Example:
+    >>> nfo = TVShowNFO(
+    ...     title="Attack on Titan",
+    ...     year=2013,
+    ...     tmdbid=1429
+    ... )
+    >>> nfo.premiered = "2013-04-07"
+"""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field, HttpUrl, field_validator
+
+
+class RatingInfo(BaseModel):
+    """Rating information from various sources.
+    
+    Attributes:
+        name: Source of the rating (e.g., 'themoviedb', 'imdb')
+        value: Rating value (typically 0-10)
+        votes: Number of votes
+        max_rating: Maximum possible rating (default: 10)
+        default: Whether this is the default rating to display
+    """
+    
+    name: str = Field(..., description="Rating source name")
+    value: float = Field(..., ge=0, description="Rating value")
+    votes: Optional[int] = Field(None, ge=0, description="Number of votes")
+    max_rating: int = Field(10, ge=1, description="Maximum rating value")
+    default: bool = Field(False, description="Is this the default rating")
+    
+    @field_validator('value')
+    @classmethod
+    def validate_value(cls, v: float, info) -> float:
+        """Ensure rating value doesn't exceed max_rating."""
+        # Note: max_rating is not available yet during validation,
+        # so we use a reasonable default check
+        if v > 10:
+            raise ValueError("Rating value cannot exceed 10")
+        return v
+
+
+class ActorInfo(BaseModel):
+    """Actor/cast member information.
+    
+    Attributes:
+        name: Actor's name
+        role: Character name/role
+        thumb: URL to actor's photo
+        profile: URL to actor's profile page
+        tmdbid: TMDB ID for the actor
+    """
+    
+    name: str = Field(..., description="Actor's name")
+    role: Optional[str] = Field(None, description="Character role")
+    thumb: Optional[HttpUrl] = Field(None, description="Actor photo URL")
+    profile: Optional[HttpUrl] = Field(None, description="Actor profile URL")
+    tmdbid: Optional[int] = Field(None, description="TMDB actor ID")
+
+
+class ImageInfo(BaseModel):
+    """Image information for posters, fanart, and logos.
+    
+    Attributes:
+        url: URL to the image
+        aspect: Image aspect/type (e.g., 'poster', 'clearlogo', 'logo')
+        season: Season number for season-specific images
+        type: Image type (e.g., 'season')
+    """
+    
+    url: HttpUrl = Field(..., description="Image URL")
+    aspect: Optional[str] = Field(
+        None,
+        description="Image aspect (poster, clearlogo, logo)"
+    )
+    season: Optional[int] = Field(None, ge=-1, description="Season number")
+    type: Optional[str] = Field(None, description="Image type")
+
+
+class NamedSeason(BaseModel):
+    """Named season information.
+    
+    Attributes:
+        number: Season number
+        name: Season name/title
+    """
+    
+    number: int = Field(..., ge=0, description="Season number")
+    name: str = Field(..., description="Season name")
+
+
+class UniqueID(BaseModel):
+    """Unique identifier from various sources.
+    
+    Attributes:
+        type: ID source type (tmdb, imdb, tvdb)
+        value: The ID value
+        default: Whether this is the default ID
+    """
+    
+    type: str = Field(..., description="ID type (tmdb, imdb, tvdb)")
+    value: str = Field(..., description="ID value")
+    default: bool = Field(False, description="Is default ID")
+
+
+class TVShowNFO(BaseModel):
+    """Main tvshow.nfo structure following Kodi/XBMC standard.
+    
+    This model represents the complete metadata for a TV show that can be
+    serialized to XML for use with media center applications.
+    
+    Attributes:
+        title: Main title of the show
+        originaltitle: Original title (e.g., in original language)
+        showtitle: Show title (often same as title)
+        sorttitle: Title used for sorting
+        year: Release year
+        plot: Full plot description
+        outline: Short plot summary
+        tagline: Show tagline/slogan
+        runtime: Episode runtime in minutes
+        mpaa: Content rating (e.g., TV-14, TV-MA)
+        certification: Additional certification info
+        premiered: Premiere date (YYYY-MM-DD format)
+        status: Show status (e.g., 'Continuing', 'Ended')
+        studio: List of production studios
+        genre: List of genres
+        country: List of countries
+        tag: List of tags/keywords
+        ratings: List of ratings from various sources
+        userrating: User's personal rating
+        watched: Whether the show has been watched
+        playcount: Number of times watched
+        tmdbid: TMDB ID
+        imdbid: IMDB ID
+        tvdbid: TVDB ID
+        uniqueid: List of unique IDs
+        thumb: List of thumbnail/poster images
+        fanart: List of fanart/backdrop images
+        actors: List of cast members
+        namedseason: List of named seasons
+        trailer: Trailer URL
+        dateadded: Date when added to library
+    """
+    
+    # Required fields
+    title: str = Field(..., description="Show title", min_length=1)
+    
+    # Basic information (optional)
+    originaltitle: Optional[str] = Field(None, description="Original title")
+    showtitle: Optional[str] = Field(None, description="Show title")
+    sorttitle: Optional[str] = Field(None, description="Sort title")
+    year: Optional[int] = Field(
+        None,
+        ge=1900,
+        le=2100,
+        description="Release year"
+    )
+    
+    # Plot and description
+    plot: Optional[str] = Field(None, description="Full plot description")
+    outline: Optional[str] = Field(None, description="Short plot summary")
+    tagline: Optional[str] = Field(None, description="Show tagline")
+    
+    # Technical details
+    runtime: Optional[int] = Field(
+        None,
+        ge=0,
+        description="Episode runtime in minutes"
+    )
+    mpaa: Optional[str] = Field(None, description="Content rating")
+    fsk: Optional[str] = Field(
+        None,
+        description="German FSK rating (e.g., 'FSK 12', 'FSK 16')"
+    )
+    certification: Optional[str] = Field(
+        None,
+        description="Certification info"
+    )
+    
+    # Status and dates
+    premiered: Optional[str] = Field(
+        None,
+        description="Premiere date (YYYY-MM-DD)"
+    )
+    status: Optional[str] = Field(None, description="Show status")
+    dateadded: Optional[str] = Field(
+        None,
+        description="Date added to library"
+    )
+    
+    # Multi-value fields
+    studio: List[str] = Field(
+        default_factory=list,
+        description="Production studios"
+    )
+    genre: List[str] = Field(
+        default_factory=list,
+        description="Genres"
+    )
+    country: List[str] = Field(
+        default_factory=list,
+        description="Countries"
+    )
+    tag: List[str] = Field(
+        default_factory=list,
+        description="Tags/keywords"
+    )
+    
+    # IDs
+    tmdbid: Optional[int] = Field(None, description="TMDB ID")
+    imdbid: Optional[str] = Field(None, description="IMDB ID")
+    tvdbid: Optional[int] = Field(None, description="TVDB ID")
+    uniqueid: List[UniqueID] = Field(
+        default_factory=list,
+        description="Unique IDs"
+    )
+    
+    # Ratings and viewing info
+    ratings: List[RatingInfo] = Field(
+        default_factory=list,
+        description="Ratings"
+    )
+    userrating: Optional[float] = Field(
+        None,
+        ge=0,
+        le=10,
+        description="User rating"
+    )
+    watched: bool = Field(False, description="Watched status")
+    playcount: Optional[int] = Field(
+        None,
+        ge=0,
+        description="Play count"
+    )
+    
+    # Media
+    thumb: List[ImageInfo] = Field(
+        default_factory=list,
+        description="Thumbnail images"
+    )
+    fanart: List[ImageInfo] = Field(
+        default_factory=list,
+        description="Fanart images"
+    )
+    
+    # Cast and crew
+    actors: List[ActorInfo] = Field(
+        default_factory=list,
+        description="Cast members"
+    )
+    
+    # Seasons
+    namedseason: List[NamedSeason] = Field(
+        default_factory=list,
+        description="Named seasons"
+    )
+    
+    # Additional
+    trailer: Optional[HttpUrl] = Field(None, description="Trailer URL")
+    
+    @field_validator('premiered')
+    @classmethod
+    def validate_premiered_date(cls, v: Optional[str]) -> Optional[str]:
+        """Validate premiered date format (YYYY-MM-DD)."""
+        if v is None:
+            return v
+        
+        # Check format strictly: YYYY-MM-DD
+        if len(v) != 10 or v[4] != '-' or v[7] != '-':
+            raise ValueError(
+                "Premiered date must be in YYYY-MM-DD format"
+            )
+        
+        try:
+            datetime.strptime(v, '%Y-%m-%d')
+        except ValueError as exc:
+            raise ValueError(
+                "Premiered date must be in YYYY-MM-DD format"
+            ) from exc
+        
+        return v
+    
+    @field_validator('dateadded')
+    @classmethod
+    def validate_dateadded(cls, v: Optional[str]) -> Optional[str]:
+        """Validate dateadded format (YYYY-MM-DD HH:MM:SS)."""
+        if v is None:
+            return v
+        
+        # Check format strictly: YYYY-MM-DD HH:MM:SS
+        if len(v) != 19 or v[4] != '-' or v[7] != '-' or v[10] != ' ' or v[13] != ':' or v[16] != ':':
+            raise ValueError(
+                "Dateadded must be in YYYY-MM-DD HH:MM:SS format"
+            )
+        
+        try:
+            datetime.strptime(v, '%Y-%m-%d %H:%M:%S')
+        except ValueError as exc:
+            raise ValueError(
+                "Dateadded must be in YYYY-MM-DD HH:MM:SS format"
+            ) from exc
+        
+        return v
+    
+    @field_validator('imdbid')
+    @classmethod
+    def validate_imdbid(cls, v: Optional[str]) -> Optional[str]:
+        """Validate IMDB ID format (should start with 'tt')."""
+        if v is None:
+            return v
+        
+        if not v.startswith('tt'):
+            raise ValueError("IMDB ID must start with 'tt'")
+        
+        if not v[2:].isdigit():
+            raise ValueError("IMDB ID must be 'tt' followed by digits")
+        
+        return v
+    
+    def model_post_init(self, __context) -> None:
+        """Set default values after initialization."""
+        # Set showtitle to title if not provided
+        if self.showtitle is None:
+            self.showtitle = self.title
+        
+        # Set originaltitle to title if not provided
+        if self.originaltitle is None:
+            self.originaltitle = self.title

src/server/nfo/tmdb_client.py

@@ -12,6 +12,7 @@ Example:
 
 import asyncio
 import logging
+import time
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
@@ -38,6 +39,7 @@ class TMDBClient:
     
     DEFAULT_BASE_URL = "https://api.themoviedb.org/3"
     DEFAULT_IMAGE_BASE_URL = "https://image.tmdb.org/t/p"
+    NEGATIVE_CACHE_TTL = 86400  # 24 hours
     
     def __init__(
         self,
@@ -63,6 +65,12 @@ class TMDBClient:
         self.max_connections = max_connections
         self.session: Optional[aiohttp.ClientSession] = None
         self._cache: Dict[str, Any] = {}
+        self._negative_cache: Dict[str, float] = {}  # query -> timestamp when cached
+        # TMDB allows ~40 req/s; use 30 concurrent + per-second throttle to stay safe
+        self._semaphore = asyncio.Semaphore(30)
+        self._rate_limit_lock = asyncio.Lock()
+        self._request_timestamps: List[float] = []
+        self._max_requests_per_second = 35  # Stay under TMDB's ~40/s limit
     
     async def __aenter__(self):
         """Async context manager entry."""
@@ -83,7 +91,7 @@ class TMDBClient:
         self,
         endpoint: str,
         params: Optional[Dict[str, Any]] = None,
-        max_retries: int = 3
+        max_retries: int = 5
     ) -> Dict[str, Any]:
         """Make an async request to TMDB API with retries.
         
@@ -107,61 +115,103 @@ class TMDBClient:
         # Cache key for deduplication
         cache_key = f"{endpoint}:{str(sorted(params.items()))}"
         if cache_key in self._cache:
-            logger.debug(f"Cache hit for {endpoint}")
+            logger.debug("Cache hit for %s", endpoint)
             return self._cache[cache_key]
         
+        # Check negative cache (cached empty results)
+        negative_cache_key = f"{endpoint}:{str(sorted(params.items()))}"
+        if negative_cache_key in self._negative_cache:
+            if time.monotonic() - self._negative_cache[negative_cache_key] < self.NEGATIVE_CACHE_TTL:
+                logger.debug("Negative cache hit for %s (cached empty result)", endpoint)
+                return {"results": []}
+            else:
+                # Expired negative cache entry
+                del self._negative_cache[negative_cache_key]
+        
         delay = 1
         last_error = None
         
-        for attempt in range(max_retries):
-            try:
-                # Re-ensure session before each attempt in case it was closed
-                await self._ensure_session()
-                
-                if self.session is None:
-                    raise TMDBAPIError("Session is not available")
-                
-                logger.debug(f"TMDB API request: {endpoint} (attempt {attempt + 1})")
-                async with self.session.get(url, params=params, timeout=aiohttp.ClientTimeout(total=60)) as resp:
-                    if resp.status == 401:
-                        raise TMDBAPIError("Invalid TMDB API key")
-                    elif resp.status == 404:
-                        raise TMDBAPIError(f"Resource not found: {endpoint}")
-                    elif resp.status == 429:
-                        # Rate limit - wait longer
-                        retry_after = int(resp.headers.get('Retry-After', delay * 2))
-                        logger.warning(f"Rate limited, waiting {retry_after}s")
-                        await asyncio.sleep(retry_after)
-                        continue
-                    
-                    resp.raise_for_status()
-                    data = await resp.json()
-                    self._cache[cache_key] = data
-                    return data
-                    
-            except asyncio.TimeoutError as e:
-                last_error = e
-                if attempt < max_retries - 1:
-                    logger.warning(f"Request timeout (attempt {attempt + 1}), retrying in {delay}s")
-                    await asyncio.sleep(delay)
-                    delay *= 2
-                else:
-                    logger.error(f"Request timed out after {max_retries} attempts")
-                    
-            except (aiohttp.ClientError, AttributeError) as e:
-                last_error = e
-                # If connector/session was closed, try to recreate it
-                if "Connector is closed" in str(e) or isinstance(e, AttributeError):
-                    logger.warning(f"Session issue detected, recreating session: {e}")
-                    self.session = None
+        # Rate limiting: ensure we don't exceed ~35 requests/second
+        async with self._rate_limit_lock:
+            now = time.monotonic()
+            # Remove timestamps older than 1 second
+            self._request_timestamps = [
+                ts for ts in self._request_timestamps if now - ts < 1.0
+            ]
+            if len(self._request_timestamps) >= self._max_requests_per_second:
+                sleep_time = 1.0 - (now - self._request_timestamps[0])
+                if sleep_time > 0:
+                    logger.debug("Rate throttling: waiting %.2fs", sleep_time)
+                    await asyncio.sleep(sleep_time)
+            self._request_timestamps.append(time.monotonic())
+        
+        async with self._semaphore:
+            for attempt in range(max_retries):
+                try:
+                    # Re-ensure session before each attempt in case it was closed
                     await self._ensure_session()
-                
-                if attempt < max_retries - 1:
-                    logger.warning(f"Request failed (attempt {attempt + 1}): {e}, retrying in {delay}s")
-                    await asyncio.sleep(delay)
-                    delay *= 2
-                else:
-                    logger.error(f"Request failed after {max_retries} attempts: {e}")
+                    
+                    if self.session is None:
+                        raise TMDBAPIError("Session is not available")
+                    
+                    logger.debug("TMDB API request: %s (attempt %s)", endpoint, attempt + 1)
+                    async with self.session.get(url, params=params, timeout=aiohttp.ClientTimeout(total=60)) as resp:
+                        if resp.status == 401:
+                            raise TMDBAPIError("Invalid TMDB API key")
+                        elif resp.status == 404:
+                            raise TMDBAPIError(f"Resource not found: {endpoint}")
+                        elif resp.status == 429:
+                            # Rate limit - wait longer with exponential backoff
+                            retry_after = int(resp.headers.get('Retry-After', max(delay * 2, 2)))
+                            logger.warning("Rate limited, waiting %ss", retry_after)
+                            await asyncio.sleep(retry_after)
+                            continue
+                        
+                        resp.raise_for_status()
+                        data = await resp.json()
+                        self._cache[cache_key] = data
+                        # Cache negative result if empty
+                        if endpoint.startswith("search/") and not data.get("results"):
+                            self._negative_cache[negative_cache_key] = time.monotonic()
+                            logger.debug("Cached negative result for %s", endpoint)
+                        return data
+                        
+                except asyncio.TimeoutError as e:
+                    last_error = e
+                    if attempt < max_retries - 1:
+                        logger.warning("Request timeout (attempt %s), retrying in %ss", attempt + 1, delay)
+                        await asyncio.sleep(delay)
+                        delay *= 2
+                    else:
+                        logger.error("Request timed out after %s attempts", max_retries)
+                        
+                except (aiohttp.ClientError, AttributeError) as e:
+                    last_error = e
+                    # If connector/session was closed, try to recreate it
+                    if "Connector is closed" in str(e) or isinstance(e, AttributeError):
+                        logger.warning(
+                            "Session issue detected, recreating session: %s",
+                            e,
+                            exc_info=True,
+                        )
+                        self.session = None
+                        await self._ensure_session()
+
+                    # DNS / host-unreachable errors are not transient — abort immediately
+                    error_str = str(e)
+                    if "name resolution" in error_str.lower() or (
+                        isinstance(e, aiohttp.ClientConnectorError) and
+                        "Cannot connect to host" in error_str
+                    ):
+                        logger.error("Non-transient connection error, aborting retries: %s", e)
+                        raise TMDBAPIError(f"Request failed after {attempt + 1} attempts: {e}") from e
+
+                    if attempt < max_retries - 1:
+                        logger.warning("Request failed (attempt %s): %s, retrying in %ss", attempt + 1, e, delay)
+                        await asyncio.sleep(delay)
+                        delay *= 2
+                    else:
+                        logger.error("Request failed after %s attempts: %s", max_retries, e)
         
         raise TMDBAPIError(f"Request failed after {max_retries} attempts: {last_error}")
     
@@ -190,6 +240,34 @@ class TMDBClient:
             {"query": query, "language": language, "page": page}
         )
     
+    async def search_multi(
+        self,
+        query: str,
+        language: str = "en-US",
+        page: int = 1
+    ) -> Dict[str, Any]:
+        """Search for movies and TV shows by name using TMDB multi search.
+        
+        Multi search returns both movies and TV shows, useful for anime
+        that might be indexed as movies on TMDB.
+        
+        Args:
+            query: Search query (show name)
+            language: Language for results (default: English)
+            page: Page number for pagination
+            
+        Returns:
+            Search results with list of movies and TV shows
+            
+        Example:
+            >>> results = await client.search_multi("Suzume no Tojimari")
+            >>> shows = [r for r in results["results"] if r["media_type"] == "tv"]
+        """
+        return await self._request(
+            "search/multi",
+            {"query": query, "language": language, "page": page}
+        )
+    
     async def get_tv_show_details(
         self,
         tv_id: int,
@@ -275,7 +353,7 @@ class TMDBClient:
         url = f"{self.image_base_url}/{size}{image_path}"
         
         try:
-            logger.debug(f"Downloading image from {url}")
+            logger.debug("Downloading image from %s", url)
             async with self.session.get(url, timeout=aiohttp.ClientTimeout(total=60)) as resp:
                 resp.raise_for_status()
                 
@@ -286,7 +364,7 @@ class TMDBClient:
                 with open(local_path, "wb") as f:
                     f.write(await resp.read())
                 
-                logger.info(f"Downloaded image to {local_path}")
+                logger.info("Downloaded image to %s", local_path)
                 
         except aiohttp.ClientError as e:
             raise TMDBAPIError(f"Failed to download image: {e}")
@@ -309,8 +387,38 @@ class TMDBClient:
             await self.session.close()
             self.session = None
             logger.debug("TMDB client session closed")
+
+    def __del__(self):
+        """Warn if session is unclosed during garbage collection."""
+        if self.session is not None and not self.session.closed:
+            logger.warning(
+                "TMDBClient: unclosed session detected. "
+                "Use 'async with TMDBClient(...)' or call close() explicitly."
+            )
     
     def clear_cache(self):
         """Clear the request cache."""
         self._cache.clear()
         logger.debug("TMDB client cache cleared")
+    
+    def clear_negative_cache(self):
+        """Clear the negative result cache."""
+        self._negative_cache.clear()
+        logger.debug("TMDB negative cache cleared")
+    
+    def cleanup_expired_negative_cache(self) -> int:
+        """Remove expired entries from negative cache.
+        
+        Returns:
+            Number of entries removed
+        """
+        now = time.monotonic()
+        expired_keys = [
+            key for key, timestamp in self._negative_cache.items()
+            if now - timestamp >= self.NEGATIVE_CACHE_TTL
+        ]
+        for key in expired_keys:
+            del self._negative_cache[key]
+        if expired_keys:
+            logger.debug("Removed %d expired negative cache entries", len(expired_keys))
+        return len(expired_keys)

src/server/providers/base_provider.py

@@ -91,6 +91,17 @@ class Loader(ABC):
             Series title string
         """
 
+    @abstractmethod
+    def get_year(self, key: str) -> int | None:
+        """Get the release year of a series.
+
+        Args:
+            key: Unique series identifier/key
+
+        Returns:
+            Release year as integer, or None if year cannot be determined
+        """
+
     @abstractmethod
     def get_season_episode_count(self, slug: str) -> Dict[int, int]:
         """Get season and episode counts for a series.

src/server/providers/config_manager.py

@@ -87,7 +87,7 @@ class ProviderConfigManager:
             settings: Provider settings to apply.
         """
         self._provider_settings[provider_name] = settings
-        logger.info(f"Updated settings for provider: {provider_name}")
+        logger.info("Updated settings for provider: %s", provider_name)
 
     def update_provider_settings(
         self, provider_name: str, **kwargs
@@ -106,7 +106,7 @@ class ProviderConfigManager:
             self._provider_settings[provider_name] = ProviderSettings(
                 name=provider_name, **kwargs
             )
-            logger.info(f"Created new settings for provider: {provider_name}")  # noqa: E501
+            logger.info("Created new settings for provider: %s", provider_name)  # noqa: E501
             return True
 
         settings = self._provider_settings[provider_name]
@@ -152,7 +152,7 @@ class ProviderConfigManager:
         """
         if provider_name in self._provider_settings:
             self._provider_settings[provider_name].enabled = True
-            logger.info(f"Enabled provider: {provider_name}")
+            logger.info("Enabled provider: %s", provider_name)
             return True
         return False
 
@@ -167,7 +167,7 @@ class ProviderConfigManager:
         """
         if provider_name in self._provider_settings:
             self._provider_settings[provider_name].enabled = False
-            logger.info(f"Disabled provider: {provider_name}")
+            logger.info("Disabled provider: %s", provider_name)
             return True
         return False
 
@@ -224,7 +224,7 @@ class ProviderConfigManager:
             value: Setting value.
         """
         self._global_settings[key] = value
-        logger.info(f"Updated global setting {key}: {value}")
+        logger.info("Updated global setting %s: %s", key, value)
 
     def get_all_global_settings(self) -> Dict[str, Any]:
         """Get all global settings.
@@ -307,7 +307,7 @@ class ProviderConfigManager:
             with open(config_path, "w", encoding="utf-8") as f:
                 json.dump(data, f, indent=2)
 
-            logger.info(f"Saved configuration to {config_path}")
+            logger.info("Saved configuration to %s", config_path)
             return True
 
         except Exception as e:

src/server/providers/failover.py

@@ -8,8 +8,8 @@ import asyncio
 import logging
 from typing import Any, Callable, Dict, List, Optional, TypeVar
 
-from src.core.providers.health_monitor import get_health_monitor
-from src.core.providers.provider_config import DEFAULT_PROVIDERS
+from src.server.providers.health_monitor import get_health_monitor
+from src.server.providers.provider_config import DEFAULT_PROVIDERS
 
 logger = logging.getLogger(__name__)
 
@@ -207,7 +207,7 @@ class ProviderFailover:
         """
         if provider_name not in self._providers:
             self._providers.append(provider_name)
-            logger.info(f"Added provider to failover chain: {provider_name}")
+            logger.info("Added provider to failover chain: %s", provider_name)
 
     def remove_provider(self, provider_name: str) -> bool:
         """Remove a provider from the failover chain.

src/server/providers/health_monitor.py

@@ -151,7 +151,7 @@ class ProviderHealthMonitor:
             except asyncio.CancelledError:
                 break
             except Exception as e:
-                logger.error(f"Error in health check loop: {e}", exc_info=True)
+                logger.exception("Error in health check loop: %s", e)
                 await asyncio.sleep(self._health_check_interval)
 
     async def _perform_health_checks(self) -> None:
@@ -314,7 +314,7 @@ class ProviderHealthMonitor:
         )
 
         best_provider = available[0][0]
-        logger.debug(f"Best provider selected: {best_provider}")
+        logger.debug("Best provider selected: %s", best_provider)
         return best_provider
 
     def _get_recent_metrics(
@@ -355,7 +355,7 @@ class ProviderHealthMonitor:
             provider_name=provider_name
         )
         self._request_history[provider_name].clear()
-        logger.info(f"Reset metrics for provider: {provider_name}")
+        logger.info("Reset metrics for provider: %s", provider_name)
         return True
 
     def get_health_summary(self) -> Dict[str, Any]:

src/server/providers/monitored_provider.py

@@ -7,8 +7,8 @@ import logging
 import time
 from typing import Any, Callable, Dict, List, Optional
 
-from src.core.providers.base_provider import Loader
-from src.core.providers.health_monitor import get_health_monitor
+from src.server.providers.base_provider import Loader
+from src.server.providers.health_monitor import get_health_monitor
 
 logger = logging.getLogger(__name__)