chore: bump version

- Add /setup/unresolved to EXEMPT_PATHS to allow access after initial setup
- Handle 401 Unauthorized response in loading page (clear invalid token)
- Add console.log statements for debugging setup flow issues

.dockerignore

@@ -0,0 +1,37 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+.git/
+.github/
+.gitignore
+.vscode/
+.vs/
+.idea/
+.mypy_cache/
+.pytest_cache/
+.coverage
+.env
+*.log
+
+# Docker files (not needed inside the image)
+Docker/
+
+# Exception: VERSION is needed by Dockerfile.app
+!Docker/VERSION
+
+# Test and dev files
+tests/
+Temp/
+test_data/
+docs/
+diagrams/
+
+# Runtime data (mounted as volumes)
+data/aniworld.db
+data/config_backups/
+logs/
+
+# Frontend tooling
+node_modules/
+package.json

.gitignore

@@ -4,6 +4,7 @@
 /src/__pycache__/*
 /src/__pycache__/
 /.vs/*
+/.venv/*
 /src/Temp/*
 /src/Loaders/__pycache__/*
 /src/Loaders/provider/__pycache__/*
@@ -18,3 +19,68 @@
 /src/server/__pycache__/*
 /src/NoKeyFound.log
 /download_errors.log
+
+# Environment and secrets
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+secrets/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Database files (including SQLite journal/WAL files)
+*.db
+*.db-shm
+*.db-wal
+*.db-journal
+*.sqlite
+*.sqlite3
+*.sqlite-shm
+*.sqlite-wal
+*.sqlite-journal
+data/*.db*
+data/aniworld.db*
+
+# Configuration files (exclude from git, keep backups local)
+data/config.json
+data/config_backups/
+config.json
+*.config
+
+# Logs
+*.log
+logs/
+src/cli/logs/
+*.log.*
+
+# Temp folders
+Temp/
+temp/
+tmp/
+*.tmp
+.coverage
+.venv/bin/dotenv

.gitmodules

@@ -1,4 +0,0 @@
-[submodule "src/AniWorld-Downloader"]
-	path = src/AniWorld-Downloader
-	url = https://github.com/lukaspupkalipinski/AniWorld-Downloader.git
-	branch = next

.vscode/launch.json

@@ -8,7 +8,7 @@
             "program": "${workspaceFolder}/src/server/fastapi_app.py",
             "console": "integratedTerminal",
             "justMyCode": true,
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "env": {
                 "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
                 "JWT_SECRET_KEY": "your-secret-key-here-debug",
@@ -30,7 +30,7 @@
             "type": "debugpy",
             "request": "launch",
             "module": "uvicorn",
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "args": [
                 "src.server.fastapi_app:app",
                 "--host",
@@ -61,7 +61,7 @@
             "program": "${workspaceFolder}/src/cli/Main.py",
             "console": "integratedTerminal",
             "justMyCode": true,
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "env": {
                 "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
                 "LOG_LEVEL": "DEBUG",
@@ -79,7 +79,7 @@
             "type": "debugpy",
             "request": "launch",
             "module": "pytest",
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "args": [
                 "${workspaceFolder}/tests",
                 "-v",
@@ -105,7 +105,7 @@
             "type": "debugpy",
             "request": "launch",
             "module": "pytest",
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "args": [
                 "${workspaceFolder}/tests/unit",
                 "-v",
@@ -126,7 +126,7 @@
             "type": "debugpy",
             "request": "launch",
             "module": "pytest",
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "args": [
                 "${workspaceFolder}/tests/integration",
                 "-v",
@@ -150,7 +150,7 @@
             "type": "debugpy",
             "request": "launch",
             "module": "uvicorn",
-            "python": "C:\\Users\\lukas\\anaconda3\\envs\\AniWorld\\python.exe",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
             "args": [
                 "src.server.fastapi_app:app",
                 "--host",

.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

@@ -0,0 +1,25 @@
+FROM alpine:3.19
+
+RUN apk add --no-cache \
+    wireguard-tools \
+    iptables \
+    ip6tables \
+    bash \
+    curl \
+    iputils-ping \
+    iproute2 \
+    openresolv
+
+# Create wireguard config directory (config is mounted at runtime)
+RUN mkdir -p /etc/wireguard
+
+# 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=5 \
+    CMD curl -sf --max-time 5 http://1.1.1.1 || exit 1
+
+ENTRYPOINT ["/entrypoint.sh"]

Docker/Dockerfile.app

@@ -0,0 +1,35 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# 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)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the full application
+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
+
+EXPOSE 8000
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONPATH=/app
+
+# Bind to 0.0.0.0 so the app is reachable from the VPN container's network
+CMD ["python", "-m", "uvicorn", "src.server.fastapi_app:app", \
+     "--host", "0.0.0.0", "--port", "8000"]

Docker/VERSION

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

Docker/dispatcher.d-99-wg-routes.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+
+# === Configuration ===
+LOGFILE="/tmp/dispatcher.log"
+BACKUP="/tmp/dispatcher.log.1"
+MAXSIZE=$((1024 * 1024))  # 1 MB
+VPN_IFACE="nl"
+GATEWAY="192.168.178.1"
+LOCAL_IFACE="wlp4s0f0"
+ROUTE1="185.183.34.149"
+ROUTE2="192.168.178.0/24"
+
+# === Log Rotation ===
+if [ -f "$LOGFILE" ] && [ "$(stat -c%s "$LOGFILE")" -ge "$MAXSIZE" ]; then
+  echo "[$(date)] Log file exceeded 1MB, rotating..." >> "$LOGFILE"
+  mv "$LOGFILE" "$BACKUP"
+  touch "$LOGFILE"
+fi
+
+# === Logging Setup ===
+exec >> "$LOGFILE" 2>&1
+echo "[$(date)] Running dispatcher for $1 with status $2"
+
+IFACE="$1"
+STATUS="$2"
+
+log_and_run() {
+  echo "[$(date)] Executing: $*"
+  if ! output=$("$@" 2>&1); then
+    echo "[$(date)] ERROR: Command failed: $*"
+    echo "[$(date)] Output: $output"
+  else
+    echo "[$(date)] Success: $*"
+  fi
+}
+
+# === VPN Routing Logic ===
+if [ "$IFACE" = "$VPN_IFACE" ]; then
+  case "$STATUS" in
+    up)
+      echo "[$(date)] VPN interface is up. Preparing routes..."
+
+      # === Wait for local interface and gateway ===
+      echo "[$(date)] Waiting for $LOCAL_IFACE (state UP) and gateway $GATEWAY (reachable)..."
+      until ip link show "$LOCAL_IFACE" | grep -q "state UP" && ip route get "$GATEWAY" &>/dev/null; do
+        echo "[$(date)] Waiting for $LOCAL_IFACE and $GATEWAY..."
+        sleep 1
+      done
+      echo "[$(date)] Local interface and gateway are ready."
+      # === End Wait ===
+
+      # === APPLY ROUTES (Corrected Order) ===
+      
+      # 1. Add the route for the local network FIRST
+      log_and_run /sbin/ip route replace "$ROUTE2" dev "$LOCAL_IFACE"
+      
+      # 2. Add the route to the VPN endpoint via the gateway SECOND
+      log_and_run /sbin/ip route replace "$ROUTE1" via "$GATEWAY" dev "$LOCAL_IFACE"
+      
+      # === END APPLY ROUTES ===
+
+      # Log interface and WireGuard status
+      echo "[$(date)] --- ip addr show $VPN_IFACE ---"
+      ip addr show "$VPN_IFACE"
+      echo "[$(date)] --- wg show $VPN_IFACE ---"
+      wg show "$VPN_IFACE"
+
+      ;;
+
+    down)
+      echo "[$(date)] VPN interface is down. Verifying before removing routes..."
+
+      # Log interface and WireGuard status
+      echo "[$(date)] --- ip addr show $VPN_IFACE ---"
+      ip addr show "$VPN_IFACE"
+      echo "[$(date)] --- wg show $VPN_IFACE ---"
+      wg show "$VPN_IFACE"
+
+      # Delay and confirm interface is still down
+      sleep 5
+      if ip link show "$VPN_IFACE" | grep -q "state UP"; then
+        echo "[$(date)] VPN interface is still up. Skipping route removal."
+      else
+        echo "[$(date)] Confirmed VPN is down. Removing routes..."
+        # It's good practice to remove them in reverse order, too.
+        log_and_run /sbin/ip route del "$ROUTE1" via "$GATEWAY" dev "$LOCAL_IFACE"
+        log_and_run /sbin/ip route del "$ROUTE2" dev "$LOCAL_IFACE"
+      fi
+      ;;
+  esac
+fi

Docker/entrypoint.sh

@@ -0,0 +1,387 @@
+#!/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"
+CONFIG_FILE="${CONFIG_DIR}/${INTERFACE}.conf"
+CHECK_INTERVAL="${HEALTH_CHECK_INTERVAL:-10}"
+CHECK_HOST="${HEALTH_CHECK_HOST:-1.1.1.1}"
+
+# ──────────────────────────────────────────────
+# Validate config exists, copy to writable location
+# ──────────────────────────────────────────────
+if [ ! -f "$MOUNT_CONFIG" ]; then
+    echo "[error] WireGuard config not found at ${MOUNT_CONFIG}"
+    echo "[error] Mount your config file: -v /path/to/your.conf:/etc/wireguard/wg0.conf:ro"
+    exit 1
+fi
+
+mkdir -p "$CONFIG_DIR"
+cp "$MOUNT_CONFIG" "$CONFIG_FILE"
+chmod 600 "$CONFIG_FILE"
+
+# Extract endpoint IP and port from the config
+VPN_ENDPOINT=$(grep -i '^Endpoint' "$CONFIG_FILE" | head -1 | sed 's/.*= *//;s/:.*//;s/ //g')
+VPN_PORT=$(grep -i '^Endpoint' "$CONFIG_FILE" | head -1 | sed 's/.*://;s/ //g')
+# Extract address
+VPN_ADDRESS=$(grep -i '^Address' "$CONFIG_FILE" | head -1 | sed 's/.*= *//;s/ //g')
+
+if [ -z "$VPN_ENDPOINT" ] || [ -z "$VPN_PORT" ]; then
+    echo "[error] Could not parse Endpoint from ${CONFIG_FILE}"
+    exit 1
+fi
+
+echo "[init] Config: ${CONFIG_FILE}"
+echo "[init] Endpoint: ${VPN_ENDPOINT}:${VPN_PORT}"
+echo "[init] Address: ${VPN_ADDRESS}"
+
+# ──────────────────────────────────────────────
+# Kill switch: only allow traffic through wg0
+# ──────────────────────────────────────────────
+setup_killswitch() {
+    echo "[killswitch] Setting up iptables kill switch..."
+
+    # Flush existing rules
+    iptables -F
+    iptables -X
+    iptables -t nat -F
+
+    # Default policy: DROP everything
+    iptables -P INPUT DROP
+    iptables -P FORWARD DROP
+    iptables -P OUTPUT DROP
+
+    # Allow loopback
+    iptables -A INPUT  -i lo -j ACCEPT
+    iptables -A OUTPUT -o lo -j ACCEPT
+
+    # Allow traffic to/from VPN endpoint (needed to establish tunnel)
+    iptables -A OUTPUT -d "$VPN_ENDPOINT" -p udp --dport "$VPN_PORT" -j ACCEPT
+    iptables -A INPUT  -s "$VPN_ENDPOINT" -p udp --sport "$VPN_PORT" -j ACCEPT
+
+    # Allow all traffic through the WireGuard interface
+    iptables -A INPUT  -i "$INTERFACE" -j ACCEPT
+    iptables -A OUTPUT -o "$INTERFACE" -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
+    iptables -A INPUT  -p udp --sport 67:68 -j ACCEPT
+
+    # Allow established/related connections
+    iptables -A INPUT  -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+    iptables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+
+    # ── Allow incoming connections to exposed service ports (e.g. app on 8000) ──
+    # LOCAL_PORTS can be set as env var, e.g. "8000,8080,3000"
+    if [ -n "${LOCAL_PORTS:-}" ]; then
+        for port in $(echo "$LOCAL_PORTS" | tr ',' ' '); do
+            echo "[killswitch] Allowing incoming traffic on port ${port}"
+            iptables -A INPUT  -p tcp --dport "$port" -j ACCEPT
+            iptables -A OUTPUT -p tcp --sport "$port" -j ACCEPT
+        done
+    fi
+
+    # ── FORWARDING (so other containers can use this VPN) ──
+    iptables -A FORWARD -i eth0 -o "$INTERFACE" -j ACCEPT
+    iptables -A FORWARD -i "$INTERFACE" -o eth0 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
+
+    # NAT: masquerade traffic from other containers going out through wg0
+    iptables -t nat -A POSTROUTING -o "$INTERFACE" -j MASQUERADE
+
+    echo "[killswitch] Kill switch active. Traffic blocked if VPN drops."
+}
+
+# ──────────────────────────────────────────────
+# Enable IP forwarding so other containers can route through us
+# ──────────────────────────────────────────────
+enable_forwarding() {
+    echo "[init] Enabling IP forwarding..."
+    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"
+    fi
+}
+
+# ──────────────────────────────────────────────
+# Start WireGuard manually (no wg-quick, avoids sysctl issues)
+# ──────────────────────────────────────────────
+start_vpn() {
+    echo "[vpn] Starting WireGuard interface ${INTERFACE}..."
+
+    # Create the interface
+    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 and bring up
+    ip link set mtu 1420 up dev "$INTERFACE"
+
+    # ── 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}')
+
+    # ── Policy routing: ensure responses to incoming LAN traffic go back via eth0 ──
+    if [ -n "$DEFAULT_GW" ] && [ -n "$DEFAULT_IF" ]; then
+        # 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
+
+    # 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
+        # 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]   /'
+}
+
+# ──────────────────────────────────────────────
+# Stop WireGuard manually
+# ──────────────────────────────────────────────
+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
+}
+
+# ──────────────────────────────────────────────
+# Health check loop — restarts VPN if tunnel dies
+# ──────────────────────────────────────────────
+health_loop() {
+    local failures=0
+    local max_failures=3
+
+    echo "[health] Starting health check (every ${CHECK_INTERVAL}s, target ${CHECK_HOST})..."
+
+    while true; do
+        sleep "$CHECK_INTERVAL"
+
+        if ping -c 1 -W 5 "$CHECK_HOST" > /dev/null 2>&1; then
+            if [ "$failures" -gt 0 ]; then
+                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] 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..."
+                stop_vpn
+                sleep 2
+                start_vpn
+                failures=0
+                echo "[health] WireGuard restarted."
+            fi
+        fi
+    done
+}
+
+# ──────────────────────────────────────────────
+# Graceful shutdown
+# ──────────────────────────────────────────────
+cleanup() {
+    echo "[shutdown] Stopping WireGuard..."
+    stop_vpn
+    echo "[shutdown] Flushing iptables..."
+    iptables -F
+    iptables -t nat -F
+    echo "[shutdown] Done."
+    exit 0
+}
+
+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

@@ -0,0 +1,16 @@
+[Interface]
+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 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 = 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

@@ -0,0 +1,49 @@
+services:
+  vpn:
+    build:
+      context: .
+      dockerfile: Containerfile
+    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:
+      - ./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
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "ping", "-c", "1", "-W", "5", "1.1.1.1"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  app:
+    build:
+      context: ..
+      dockerfile: Docker/Dockerfile.app
+    container_name: aniworld-app
+    network_mode: "service:vpn"
+    depends_on:
+      vpn:
+        condition: service_healthy
+    environment:
+      - PYTHONUNBUFFERED=1
+      - LOG_LEVEL=DEBUG
+    volumes:
+      - app-data:/app/data
+      - app-logs:/app/logs
+    restart: unless-stopped
+
+volumes:
+  app-data:
+  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

@@ -0,0 +1,253 @@
+"""
+Integration test for the WireGuard VPN Podman image.
+
+Verifies:
+1. The image builds successfully.
+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) 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
+
+logger = logging.getLogger(__name__)
+
+IMAGE_NAME = "vpn-wireguard-test"
+CONTAINER_NAME = "vpn-test-container"
+CONFIG_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "wg0.conf")
+BUILD_DIR = os.path.dirname(os.path.abspath(__file__))
+IP_CHECK_URL = "https://ifconfig.me"
+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)
+
+
+def get_host_ip() -> str:
+    """Get the public IP of the host machine."""
+    result = run(["curl", "-s", "--max-time", "10", IP_CHECK_URL])
+    return result.stdout.strip()
+
+
+def podman_exec(container: str, cmd: list[str], timeout: int = 15) -> subprocess.CompletedProcess:
+    """Execute a command inside a running container."""
+    return run(["podman", "exec", container] + cmd, timeout=timeout, check=False)
+
+
+class TestVPNImage(unittest.TestCase):
+    """Test suite for the WireGuard VPN container."""
+
+    host_ip: str = ""
+    container_id: str = ""
+
+    @classmethod
+    def setUpClass(cls):
+        """Build image, get host IP, start container, wait for VPN."""
+        # Clean up any leftover container from a previous run
+        subprocess.run(
+            ["podman", "rm", "-f", CONTAINER_NAME],
+            capture_output=True, check=False,
+        )
+
+        # ── 1. Get host public IP before VPN ──
+        logger.info("Fetching host public IP...")
+        cls.host_ip = get_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 ──
+        logger.info("Building image '%s'...", IMAGE_NAME)
+        result = run(
+            ["podman", "build", "-t", IMAGE_NAME, BUILD_DIR],
+            timeout=180,
+        )
+        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}"
+        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 ──
+        logger.info("Starting container '%s'...", CONTAINER_NAME)
+        result = run(
+            [
+                "podman", "run", "-d",
+                "--name", CONTAINER_NAME,
+                "--cap-add=NET_ADMIN",
+                "--cap-add=SYS_MODULE",
+                "--sysctl", "net.ipv4.ip_forward=1",
+                "-v", f"{CONFIG_FILE}:/etc/wireguard/wg0.conf:ro",
+                "-v", "/lib/modules:/lib/modules:ro",
+                IMAGE_NAME,
+            ],
+            timeout=30,
+            check=False,
+        )
+        assert result.returncode == 0, f"Container failed to start:\n{result.stderr}"
+        cls.container_id = result.stdout.strip()
+        logger.info("Container started: %s", cls.container_id[:12])
+
+        # Verify it's running
+        inspect = run(
+            ["podman", "inspect", "-f", "{{.State.Running}}", CONTAINER_NAME],
+            check=False,
+        )
+        assert inspect.stdout.strip() == "true", "Container is not running"
+
+        # ── 4. Wait for VPN to come up ──
+        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"
+        logger.info("VPN tunnel is up. Running tests.")
+
+    @classmethod
+    def tearDownClass(cls):
+        """Stop and remove the container."""
+        if not is_root():
+            return
+        logger.info("Cleaning up test container...")
+        subprocess.run(["podman", "rm", "-f", CONTAINER_NAME], capture_output=True, check=False)
+        logger.info("Cleanup complete.")
+
+    @classmethod
+    def _wait_for_vpn_cls(cls, timeout: int = STARTUP_TIMEOUT) -> bool:
+        """Wait until the VPN tunnel is up (can reach the internet)."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            result = podman_exec(CONTAINER_NAME, ["ping", "-c", "1", "-W", "3", "1.1.1.1"])
+            if result.returncode == 0:
+                return True
+            time.sleep(HEALTH_POLL_INTERVAL)
+        return False
+
+    def _get_vpn_ip(self) -> str:
+        """Get the public IP as seen from inside the container."""
+        result = podman_exec(
+            CONTAINER_NAME,
+            ["curl", "-s", "--max-time", "10", IP_CHECK_URL],
+            timeout=20,
+        )
+        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()
+        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(
+            vpn_ip,
+            self.host_ip,
+            f"VPN IP ({vpn_ip}) is the same as host IP — VPN is not working!",
+        )
+
+    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_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}")
+
+        # Give iptables a moment
+        time.sleep(2)
+
+        # Try to reach the internet — should fail due to kill switch
+        result = podman_exec(
+            CONTAINER_NAME,
+            ["curl", "-s", "--max-time", "5", IP_CHECK_URL],
+            timeout=10,
+        )
+        self.assertNotEqual(
+            result.returncode, 0,
+            "Traffic went through even with WireGuard down — kill switch is NOT working!",
+        )
+        logger.info("Kill switch confirmed: traffic blocked with VPN down")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

Docker/wg0.conf

@@ -0,0 +1,18 @@
+[Interface]
+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 = KgTUh3KLijVluDvNpzDCJJfrJ7EyLzYLmdHCksG4sRg=
+AllowedIPs = 0.0.0.0/0
+Endpoint = 91.148.236.64:51820
+PersistentKeepalive = 25
+

FRONTEND_INTEGRATION.md

@@ -1,338 +0,0 @@
-# Frontend Integration Changes
-
-## Overview
-
-This document details the changes made to integrate the existing frontend JavaScript with the new FastAPI backend and native WebSocket implementation.
-
-## Key Changes
-
-### 1. WebSocket Migration (Socket.IO → Native WebSocket)
-
-**Files Created:**
-
--   `src/server/web/static/js/websocket_client.js` - Native WebSocket wrapper with Socket.IO-compatible interface
-
-**Files Modified:**
-
--   `src/server/web/templates/index.html` - Replace Socket.IO CDN with websocket_client.js
--   `src/server/web/templates/queue.html` - Replace Socket.IO CDN with websocket_client.js
-
-**Migration Details:**
-
--   Created `WebSocketClient` class that provides Socket.IO-style `.on()` and `.emit()` methods
--   Automatic reconnection with exponential backoff
--   Room-based subscriptions (join/leave rooms for topic filtering)
--   Message queueing during disconnection
--   Native WebSocket URL: `ws://host:port/ws/connect` (or `wss://` for HTTPS)
-
-### 2. WebSocket Message Format Changes
-
-**Old Format (Socket.IO custom events):**
-
-```javascript
-socket.on('download_progress', (data) => { ... });
-// data was sent directly
-```
-
-**New Format (Structured messages):**
-
-```javascript
-{
-    "type": "download_progress",
-    "timestamp": "2025-10-17T12:34:56.789Z",
-    "data": {
-        // Message payload
-    }
-}
-```
-
-**Event Mapping:**
-
-| Old Socket.IO Event     | New WebSocket Type  | Room                | Notes                      |
-| ----------------------- | ------------------- | ------------------- | -------------------------- |
-| `scan_progress`         | `scan_progress`     | `scan_progress`     | Scan updates               |
-| `scan_completed`        | `scan_complete`     | `scan_progress`     | Scan finished              |
-| `scan_error`            | `scan_failed`       | `scan_progress`     | Scan error                 |
-| `download_progress`     | `download_progress` | `download_progress` | Real-time download updates |
-| `download_completed`    | `download_complete` | `downloads`         | Single download finished   |
-| `download_error`        | `download_failed`   | `downloads`         | Download failed            |
-| `download_queue_update` | `queue_status`      | `downloads`         | Queue state changes        |
-| `queue_started`         | `queue_started`     | `downloads`         | Queue processing started   |
-| `queue_stopped`         | `queue_stopped`     | `downloads`         | Queue processing stopped   |
-| `queue_paused`          | `queue_paused`      | `downloads`         | Queue paused               |
-| `queue_resumed`         | `queue_resumed`     | `downloads`         | Queue resumed              |
-
-### 3. API Endpoint Changes
-
-**Authentication Endpoints:**
-
--   ✅ `/api/auth/status` - Check auth status (GET)
--   ✅ `/api/auth/login` - Login (POST)
--   ✅ `/api/auth/logout` - Logout (POST)
--   ✅ `/api/auth/setup` - Initial setup (POST)
-
-**Anime Endpoints:**
-
--   ✅ `/api/v1/anime` - List anime with missing episodes (GET)
--   ✅ `/api/v1/anime/rescan` - Trigger rescan (POST)
--   ✅ `/api/v1/anime/search` - Search for anime (POST)
--   ✅ `/api/v1/anime/{anime_id}` - Get anime details (GET)
-
-**Download Queue Endpoints:**
-
--   ✅ `/api/queue/status` - Get queue status (GET)
--   ✅ `/api/queue/add` - Add to queue (POST)
--   ✅ `/api/queue/{item_id}` - Remove single item (DELETE)
--   ✅ `/api/queue/` - Remove multiple items (DELETE)
--   ✅ `/api/queue/start` - Start queue (POST)
--   ✅ `/api/queue/stop` - Stop queue (POST)
--   ✅ `/api/queue/pause` - Pause queue (POST)
--   ✅ `/api/queue/resume` - Resume queue (POST)
--   ✅ `/api/queue/reorder` - Reorder queue (POST)
--   ✅ `/api/queue/completed` - Clear completed (DELETE)
--   ✅ `/api/queue/retry` - Retry failed (POST)
-
-**WebSocket Endpoint:**
-
--   ✅ `/ws/connect` - WebSocket connection (WebSocket)
--   ✅ `/ws/status` - WebSocket status (GET)
-
-### 4. Required JavaScript Updates
-
-**app.js Changes Needed:**
-
-1. **WebSocket Initialization** - Add room subscriptions:
-
-```javascript
-initSocket() {
-    this.socket = io();
-
-    // Subscribe to relevant rooms after connection
-    this.socket.on('connected', () => {
-        this.socket.join('scan_progress');
-        this.socket.join('download_progress');
-        this.socket.join('downloads');
-        this.isConnected = true;
-        // ... rest of connect handler
-    });
-
-    // ... rest of event handlers
-}
-```
-
-2. **Event Handler Updates** - Map new message types:
-
--   `scan_completed` → `scan_complete`
--   `scan_error` → `scan_failed`
--   Legacy events that are no longer sent need to be handled differently or removed
-
-3. **API Call Updates** - Already correct:
-
--   `/api/v1/anime` for anime list ✅
--   `/api/auth/*` for authentication ✅
-
-**queue.js Changes Needed:**
-
-1. **WebSocket Initialization** - Add room subscriptions:
-
-```javascript
-initSocket() {
-    this.socket = io();
-
-    this.socket.on('connected', () => {
-        this.socket.join('downloads');
-        this.socket.join('download_progress');
-        // ... rest of connect handler
-    });
-
-    // ... rest of event handlers
-}
-```
-
-2. **API Calls** - Already mostly correct:
-
--   `/api/queue/status` ✅
--   `/api/queue/*` operations ✅
-
-3. **Event Handlers** - Map to new types:
-
--   `queue_updated` → `queue_status`
--   `download_progress_update` → `download_progress`
-
-### 5. Authentication Flow
-
-**Current Implementation:**
-
--   JWT tokens stored in localStorage (via auth service)
--   Tokens included in Authorization header for API requests
--   WebSocket connections can optionally authenticate (user_id in session)
-
-**JavaScript Implementation Needed:**
-Add helper for authenticated requests:
-
-```javascript
-async makeAuthenticatedRequest(url, options = {}) {
-    const token = localStorage.getItem('auth_token');
-
-    if (!token) {
-        window.location.href = '/login';
-        return null;
-    }
-
-    const headers = {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${token}`,
-        ...options.headers
-    };
-
-    const response = await fetch(url, { ...options, headers });
-
-    if (response.status === 401) {
-        // Token expired or invalid
-        localStorage.removeItem('auth_token');
-        window.location.href = '/login';
-        return null;
-    }
-
-    return response;
-}
-```
-
-### 6. Backend Router Registration
-
-**Fixed in fastapi_app.py:**
-
--   ✅ Added `anime_router` import
--   ✅ Registered `app.include_router(anime_router)`
-
-All routers now properly registered:
-
--   health_router
--   page_router
--   auth_router
--   anime_router ⭐ (newly added)
--   download_router
--   websocket_router
-
-## Implementation Status
-
-### ✅ Completed
-
-1. Created native WebSocket client wrapper
-2. Updated HTML templates to use new WebSocket client
-3. Registered anime router in FastAPI app
-4. Documented API endpoint mappings
-5. Documented WebSocket message format changes
-
-### 🔄 In Progress
-
-1. Update app.js WebSocket initialization and room subscriptions
-2. Update app.js event handlers for new message types
-3. Update queue.js WebSocket initialization and room subscriptions
-4. Update queue.js event handlers for new message types
-
-### ⏳ Pending
-
-1. Add authentication token handling to all API requests
-2. Test complete workflow (auth → scan → download)
-3. Update other JavaScript modules if they use WebSocket/API
-4. Integration tests for frontend-backend communication
-5. Update infrastructure.md documentation
-
-## Testing Plan
-
-1. **Authentication Flow:**
-
-    - Test setup page → creates master password
-    - Test login page → authenticates with master password
-    - Test logout → clears session
-    - Test protected pages redirect to login
-
-2. **Anime Management:**
-
-    - Test loading anime list
-    - Test rescan functionality with progress updates
-    - Test search functionality
-
-3. **Download Queue:**
-
-    - Test adding items to queue
-    - Test queue operations (start, stop, pause, resume)
-    - Test progress updates via WebSocket
-    - Test retry and clear operations
-
-4. **WebSocket Communication:**
-    - Test connection/reconnection
-    - Test room subscriptions
-    - Test message routing to correct handlers
-    - Test disconnect handling
-
-## Known Issues & Limitations
-
-1. **Legacy Events:** Some Socket.IO events in app.js don't have backend equivalents:
-
-    - `scheduled_rescan_*` events
-    - `auto_download_*` events
-    - `download_episode_update` event
-    - `download_series_completed` event
-
-    **Solution:** Either remove these handlers or implement corresponding backend events
-
-2. **Configuration Endpoints:** Many config-related API calls in app.js don't have backend implementations:
-
-    - Scheduler configuration
-    - Logging configuration
-    - Advanced configuration
-    - Config backups
-
-    **Solution:** Implement these endpoints or remove the UI features
-
-3. **Process Status Monitoring:** `checkProcessLocks()` method may not work with new backend
-
-    **Solution:** Implement equivalent status endpoint or remove feature
-
-## Migration Guide for Developers
-
-### Adding New WebSocket Events
-
-1. Define message type in `src/server/models/websocket.py`:
-
-```python
-class WebSocketMessageType(str, Enum):
-    MY_NEW_EVENT = "my_new_event"
-```
-
-2. Broadcast from service:
-
-```python
-await ws_service.broadcast_to_room(
-    {"type": "my_new_event", "data": {...}},
-    "my_room"
-)
-```
-
-3. Subscribe and handle in JavaScript:
-
-```javascript
-this.socket.join("my_room");
-this.socket.on("my_new_event", (data) => {
-    // Handle event
-});
-```
-
-### Adding New API Endpoints
-
-1. Define Pydantic models in `src/server/models/`
-2. Create endpoint in appropriate router file in `src/server/api/`
-3. Add endpoint to this documentation
-4. Update JavaScript to call new endpoint
-
-## References
-
--   FastAPI Application: `src/server/fastapi_app.py`
--   WebSocket Service: `src/server/services/websocket_service.py`
--   WebSocket Models: `src/server/models/websocket.py`
--   Download Service: `src/server/services/download_service.py`
--   Anime Service: `src/server/services/anime_service.py`
--   Progress Service: `src/server/services/progress_service.py`
--   Infrastructure Doc: `infrastructure.md`

README.md

@@ -0,0 +1,202 @@
+# Aniworld Download Manager
+
+A web-based anime download manager with REST API, WebSocket real-time updates, and a modern web interface.
+
+## Features
+
+- Web interface for managing anime library
+- REST API for programmatic access
+- WebSocket real-time progress updates
+- Download queue with priority management
+- Automatic library scanning for missing episodes
+- **NFO metadata management with TMDB integration**
+- **Automatic poster/fanart/logo downloads**
+- JWT-based authentication
+- SQLite database for persistence
+- **Comprehensive test coverage** (1,070+ tests, 91.3% coverage)
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- Conda (recommended) or virtualenv
+
+### Installation
+
+1. Clone the repository:
+
+```bash
+git clone https://github.com/your-repo/aniworld.git
+cd aniworld
+```
+
+2. Create and activate conda environment:
+
+```bash
+conda create -n AniWorld python=3.10
+conda activate AniWorld
+```
+
+3. Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+4. Start the server:
+
+```bash
+python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000
+```
+
+5. Open http://127.0.0.1:8000 in your browser
+
+### First-Time Setup
+
+1. Navigate to http://127.0.0.1:8000/setup
+2. Set a master password (minimum 8 characters, mixed case, number, special character)
+3. Configure your anime directory path
+4. **(Optional)** Configure NFO settings with your TMDB API key
+5. Login with your master password
+
+### NFO Metadata Setup (Optional)
+
+For automatic NFO file generation with metadata and images:
+
+1. Get a free TMDB API key from https://www.themoviedb.org/settings/api
+2. Go to Configuration → NFO Settings in the web interface
+3. Enter your TMDB API key and click "Test Connection"
+4. Enable auto-creation and select which images to download
+5. NFO files will be created automatically during downloads
+
+## Documentation
+
+| Document                                       | Description                      |
+| ---------------------------------------------- | -------------------------------- |
+| [docs/API.md](docs/API.md)                     | REST API and WebSocket reference |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)   | System architecture and design   |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Configuration options            |
+| [docs/DATABASE.md](docs/DATABASE.md)           | Database schema                  |
+| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)     | Developer setup guide            |
+| [docs/TESTING.md](docs/TESTING.md)             | Testing guidelines               |
+
+## Project Structure
+
+```
+src/
++-- cli/                # CLI interface (legacy)
++-- config/             # Application settings
++-- core/               # Domain logic
+|   +-- SeriesApp.py    # Main application facade
+|   +-- SerieScanner.py # Directory scanning
+|   +-- entities/       # Domain entities
+|   +-- providers/      # External provider adapters
++-- server/             # FastAPI web server
+    +-- api/            # REST API endpoints
+    +-- services/       # Business logic
+    +-- models/         # Pydantic models
+    +-- database/       # SQLAlchemy ORM
+    +-- middleware/     # Auth, rate limiting
+```
+
+## API Endpoints
+
+| Endpoint                       | Description                      |
+| ------------------------------ | -------------------------------- |
+| `POST /api/auth/login`         | Authenticate and get JWT token   |
+| `GET /api/anime`               | List anime with missing episodes |
+| `GET /api/anime/search?query=` | Search for anime                 |
+| `POST /api/queue/add`          | Add episodes to download queue   |
+| `POST /api/queue/start`        | Start queue processing           |
+| `GET /api/queue/status`        | Get queue status                 |
+| `GET /api/nfo/check`           | Check NFO status for anime       |
+| `POST /api/nfo/create`         | Create NFO files                 |
+| `WS /ws/connect`               | WebSocket for real-time updates  |
+
+See [docs/API.md](docs/API.md) for complete API reference.
+
+## Configuration
+
+Environment variables (via `.env` file):
+
+| Variable          | Default                        | Description               |
+| ----------------- | ------------------------------ | ------------------------- |
+| `JWT_SECRET_KEY`  | (random)                       | Secret for JWT signing    |
+| `DATABASE_URL`    | `sqlite:///./data/aniworld.db` | Database connection       |
+| `ANIME_DIRECTORY` | (empty)                        | Path to anime library     |
+| `TMDB_API_KEY`    | (empty)                        | TMDB API key for metadata |
+| `LOG_LEVEL`       | `INFO`                         | Logging level             |
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all options.
+
+## Running Tests
+
+The project includes a comprehensive test suite with **1,070+ tests** and **91.3% coverage** across all critical systems:
+
+```bash
+# Run all Python tests
+conda run -n AniWorld python -m pytest tests/ -v
+
+# Run unit tests only
+conda run -n AniWorld python -m pytest tests/unit/ -v
+
+# Run integration tests
+conda run -n AniWorld python -m pytest tests/integration/ -v
+
+# Run with coverage report
+conda run -n AniWorld python -m pytest tests/ --cov --cov-report=html
+
+# Run JavaScript/E2E tests (requires Node.js)
+npm test                    # Unit tests (Vitest)
+npm run test:e2e           # E2E tests (Playwright)
+```
+
+**Test Coverage:**
+
+- ✅ 1,070+ tests across 4 priority tiers (644 Python tests passing, 426 JavaScript/E2E tests)
+- ✅ 91.3% code coverage
+- ✅ **TIER 1 Critical**: 159/159 tests - Scheduler, NFO batch, download queue, persistence
+- ✅ **TIER 2 High Priority**: 390/390 tests - Frontend UI, WebSocket, dark mode, settings
+- ✅ **TIER 3 Medium Priority**: 95/156 tests - Performance, edge cases (core scenarios complete)
+- ✅ **TIER 4 Polish**: 426 tests - Internationalization, accessibility, media server compatibility
+- ✅ Security: Complete coverage (authentication, authorization, CSRF, XSS, SQL injection)
+- ✅ Performance: Validated (200+ concurrent WebSocket clients, batch operations)
+
+See [docs/TESTING_COMPLETE.md](docs/TESTING_COMPLETE.md) for comprehensive testing documentation.
+
+## Technology Stack
+
+- **Web Framework**: FastAPI 0.104.1
+- **Database**: SQLite + SQLAlchemy 2.0
+- **Auth**: JWT (python-jose) + passlib
+- **Validation**: Pydantic 2.5
+- **Logging**: structlog
+- **Testing**: pytest + pytest-asyncio
+
+## Application Lifecycle
+
+### Initialization
+
+On first startup, the application performs a one-time sync of series from data files to the database:
+
+1. FastAPI lifespan starts
+2. Database is initialized
+3. `sync_series_from_data_files()` reads all data files from the anime directory (creates temporary SeriesApp)
+4. Series metadata is synced to the database
+5. DownloadService initializes (triggers main `SeriesApp` creation)
+6. `SeriesApp` loads series from database via service layer (not from files)
+
+On subsequent startups, the same flow applies but the sync finds no new series. `SeriesApp` always initializes with an empty series list (`skip_load=True`) and loads data from the database on demand, avoiding redundant file system scans.
+
+### Adding New Series
+
+When adding a new series:
+
+1. Series is added to the database via `AnimeService`
+2. Data file is created in the anime directory
+3. In-memory `SerieList` is updated via `load_series_from_list()`
+
+## License
+
+MIT License

docs/ARCHITECTURE.md

@@ -0,0 +1,817 @@
+# Architecture Documentation
+
+## Document Purpose
+
+This document describes the system architecture of the Aniworld anime download manager.
+
+---
+
+## 1. System Overview
+
+Aniworld is a web-based anime download manager built with Python, FastAPI, and SQLite. It provides a REST API and WebSocket interface for managing anime libraries, downloading episodes, and tracking progress.
+
+### High-Level Architecture
+
+```
++------------------+     +------------------+     +------------------+
+|   Web Browser    |     |   CLI Client     |     |   External       |
+|   (Frontend)     |     |   (Main.py)      |     |   Providers      |
++--------+---------+     +--------+---------+     +--------+---------+
+         |                        |                        |
+         | HTTP/WebSocket         | Direct                 | HTTP
+         |                        |                        |
++--------v---------+     +--------v---------+     +--------v---------+
+|                  |     |                  |     |                  |
+|   FastAPI        <----->   Core Layer    <----->   Provider       |
+|   Server Layer   |     |   (SeriesApp)    |     |   Adapters       |
+|                  |     |                  |     |                  |
++--------+---------+     +--------+---------+     +------------------+
+         |                        |
+         |                        |
++--------v---------+     +--------v---------+
+|                  |     |                  |
+|   SQLite DB      |     |   File System    |
+|   (aniworld.db)  |     |   (anime/*/)     |
+|  - Series data   |     |   - Video files  |
+|  - Episodes      |     |   - NFO files    |
+|  - Queue state   |     |   - Media files  |
++------------------+     +------------------+
+```
+
+Source: [src/server/fastapi_app.py](../src/server/fastapi_app.py#L1-L252)
+
+---
+
+## 2. Architectural Layers
+
+### 2.1 CLI Layer (`src/cli/`)
+
+Legacy command-line interface for direct interaction with the core layer.
+
+| Component | File                          | Purpose         |
+| --------- | ----------------------------- | --------------- |
+| Main      | [Main.py](../src/cli/Main.py) | CLI entry point |
+
+### 2.2 Server Layer (`src/server/`)
+
+FastAPI-based REST API and WebSocket server.
+
+```
+src/server/
++-- fastapi_app.py          # Application entry point, lifespan management
++-- api/                    # API route handlers
+|   +-- anime.py            # /api/anime/* endpoints
+|   +-- auth.py             # /api/auth/* endpoints
+|   +-- config.py           # /api/config/* endpoints
+|   +-- download.py         # /api/queue/* endpoints
+|   +-- scheduler.py        # /api/scheduler/* endpoints
+|   +-- nfo.py              # /api/nfo/* endpoints
+|   +-- websocket.py        # /ws/* WebSocket handlers
+|   +-- health.py           # /health/* endpoints
++-- controllers/            # Page controllers for HTML rendering
+|   +-- page_controller.py  # UI page routes
+|   +-- health_controller.py# Health check route
+|   +-- error_controller.py # Error pages (404, 500)
++-- services/               # Business logic
+|   +-- anime_service.py    # Anime operations
+|   +-- auth_service.py     # Authentication
+|   +-- config_service.py   # Configuration management
+|   +-- download_service.py # Download queue management
+|   +-- progress_service.py # Progress tracking
+|   +-- 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
+|   +-- download.py         # Download queue models
+|   +-- websocket.py        # WebSocket message models
++-- middleware/             # Request processing
+|   +-- auth.py             # JWT validation, rate limiting
+|   +-- error_handler.py    # Exception handlers
+|   +-- setup_redirect.py   # Setup flow redirect
++-- database/               # SQLAlchemy ORM
+|   +-- connection.py       # Database connection
+|   +-- models.py           # ORM models
+|   +-- service.py          # Database service
++-- utils/                  # Utility modules
+|   +-- filesystem.py       # Folder sanitization, path safety
+|   +-- validators.py       # Input validation utilities
+|   +-- dependencies.py     # FastAPI dependency injection
++-- web/                    # Static files and templates
+    +-- static/             # CSS, JS, images
+    +-- templates/          # Jinja2 templates
+```
+
+Source: [src/server/](../src/server/)
+
+### 2.2.1 Frontend Architecture (`src/server/web/static/`)
+
+The frontend uses a modular architecture with no build step required. CSS and JavaScript files are organized by responsibility.
+
+#### CSS Structure
+
+```
+src/server/web/static/css/
++-- styles.css              # Entry point with @import statements
++-- base/
+|   +-- variables.css       # CSS custom properties (colors, fonts, spacing)
+|   +-- reset.css           # CSS reset and normalize styles
+|   +-- typography.css      # Font styles, headings, text utilities
++-- components/
+|   +-- buttons.css         # All button styles
+|   +-- cards.css           # Card and panel components
+|   +-- forms.css           # Form inputs, labels, validation styles
+|   +-- modals.css          # Modal and overlay styles
+|   +-- navigation.css      # Header, nav, sidebar styles
+|   +-- progress.css        # Progress bars, loading indicators
+|   +-- notifications.css   # Toast, alerts, messages
+|   +-- tables.css          # Table and list styles
+|   +-- status.css          # Status badges and indicators
++-- pages/
+|   +-- login.css           # Login page specific styles
+|   +-- index.css           # Index/library page specific styles
+|   +-- queue.css           # Queue page specific styles
++-- utilities/
+    +-- animations.css      # Keyframes and animation classes
+    +-- responsive.css      # Media queries and breakpoints
+    +-- helpers.css         # Utility classes (hidden, flex, spacing)
+```
+
+#### JavaScript Structure
+
+JavaScript uses the IIFE pattern with a shared `AniWorld` namespace for browser compatibility without build tools.
+
+```
+src/server/web/static/js/
++-- shared/                 # Shared utilities used by all pages
+|   +-- constants.js        # API endpoints, localStorage keys, defaults
+|   +-- auth.js             # Token management (getToken, setToken, checkAuth)
+|   +-- api-client.js       # Fetch wrapper with auto-auth headers
+|   +-- theme.js            # Dark/light theme toggle
+|   +-- ui-utils.js         # Toast notifications, format helpers
+|   +-- websocket-client.js # Socket.IO wrapper
++-- index/                  # Index page modules
+|   +-- series-manager.js   # Series list rendering and filtering
+|   +-- selection-manager.js# Multi-select and bulk download
+|   +-- search.js           # Series search functionality
+|   +-- scan-manager.js     # Library rescan operations
+|   +-- scheduler-config.js # Scheduler configuration
+|   +-- logging-config.js   # Logging configuration
+|   +-- advanced-config.js  # Advanced settings
+|   +-- main-config.js      # Main configuration and backup
+|   +-- config-manager.js   # Config modal orchestrator
+|   +-- socket-handler.js   # WebSocket event handlers
+|   +-- app-init.js         # Application initialization
++-- queue/                  # Queue page modules
+    +-- queue-api.js        # Queue API interactions
+    +-- queue-renderer.js   # Queue list rendering
+    +-- progress-handler.js # Download progress updates
+    +-- queue-socket-handler.js # WebSocket events for queue
+    +-- queue-init.js       # Queue page initialization
+```
+
+#### Module Pattern
+
+All JavaScript modules follow the IIFE pattern with namespace:
+
+```javascript
+var AniWorld = window.AniWorld || {};
+
+AniWorld.ModuleName = (function () {
+    "use strict";
+
+    // Private variables and functions
+
+    // Public API
+    return {
+        init: init,
+        publicMethod: publicMethod,
+    };
+})();
+```
+
+Source: [src/server/web/static/](../src/server/web/static/)
+
+### 2.3 Core Layer (`src/core/`)
+
+Domain logic for anime series management.
+
+```
+src/core/
++-- SeriesApp.py            # Main application facade
++-- SerieScanner.py         # Directory scanning, targeted single-series scan
++-- entities/               # Domain entities
+|   +-- series.py           # Serie class with sanitized_folder property
+|   +-- SerieList.py        # SerieList collection with sanitized folder support
+|   +-- nfo_models.py       # Pydantic models for tvshow.nfo (TVShowNFO, ActorInfo…)
++-- services/               # Domain services
+|   +-- nfo_service.py      # NFO lifecycle: create / update tvshow.nfo
+|   +-- nfo_repair_service.py # Detect & repair incomplete tvshow.nfo files
+|   |                       #   (parse_nfo_tags, find_missing_tags, NfoRepairService)
+|   +-- tmdb_client.py      # Async TMDB API client
++-- utils/                  # Utility helpers (no side-effects)
+|   +-- nfo_generator.py    # TVShowNFO → XML serialiser
+|   +-- nfo_mapper.py       # TMDB API dict → TVShowNFO (tmdb_to_nfo_model,
+|   |                       #   _extract_rating_by_country, _extract_fsk_rating)
+|   +-- image_downloader.py # TMDB image downloader
++-- providers/              # External provider adapters
+|   +-- base_provider.py    # Loader interface
+|   +-- provider_factory.py # Provider registry
++-- interfaces/             # Abstract interfaces
+|   +-- callbacks.py        # Progress callback system
++-- exceptions/             # Domain exceptions
+    +-- Exceptions.py       # Custom exceptions
+```
+
+**Key Components:**
+
+| Component      | Purpose                                                                    |
+| -------------- | -------------------------------------------------------------------------- |
+| `SeriesApp`    | Main application facade for anime operations                               |
+| `SerieScanner` | Scans directories for anime; `scan_single_series()` for targeted scans     |
+| `Serie`        | Domain entity with `sanitized_folder` property for filesystem-safe names   |
+| `SerieList`    | Collection management with automatic folder creation using sanitized names |
+
+**Initialization:**
+
+`SeriesApp` is initialized with `skip_load=True` passed to `SerieList`, preventing automatic loading of series from data files on every instantiation. Series data is loaded once during application setup via `sync_series_from_data_files()` in the FastAPI lifespan, which reads data files and syncs them to the database. Subsequent operations load series from the database through the service layer.
+
+Source: [src/core/](../src/core/)
+
+### 2.4 Infrastructure Layer (`src/infrastructure/`)
+
+Cross-cutting concerns.
+
+```
+src/infrastructure/
++-- logging/                # Structured logging setup
++-- security/               # Security utilities
+```
+
+### 2.5 Configuration Layer (`src/config/`)
+
+Application settings management.
+
+| Component | File                                     | Purpose                         |
+| --------- | ---------------------------------------- | ------------------------------- |
+| Settings  | [settings.py](../src/config/settings.py) | Environment-based configuration |
+
+Source: [src/config/settings.py](../src/config/settings.py#L1-L96)
+
+---
+
+## 12. Startup Sequence
+
+The FastAPI lifespan function (`src/server/fastapi_app.py`) runs the following steps on every server start.
+
+### 12.1 Startup Order
+
+```
+1. Logging configured
+
+2. Temp folder purged  ← cleans leftover partial download files
+   +-- Iterate ./Temp/ and delete every file and sub-directory
+   +-- Create ./Temp/ if it does not exist
+   +-- Errors are logged as warnings; startup continues regardless
+
+3. Database initialised (required – abort on failure)
+   +-- SQLite file created / migrated via init_db()
+
+4. Configuration loaded from data/config.json
+   +-- Synced to settings (ENV vars take precedence)
+
+5. Progress & WebSocket services wired up
+
+6. Series loaded from database into memory
+
+7. Download service initialised (queue restored from DB)
+
+8. Background loader service started
+
+9. Scheduler service started
+   +-- 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
+
+Every server start begins with a clean `./Temp/` directory. This ensures that partial `.part` files or stale temp videos from a crashed or force-killed previous session are never left behind before new downloads start.
+
+Source: [src/server/fastapi_app.py](../src/server/fastapi_app.py)
+
+---
+
+## 11. Graceful Shutdown
+
+The application implements a comprehensive graceful shutdown mechanism that ensures data integrity and proper cleanup when the server is stopped via Ctrl+C (SIGINT) or SIGTERM.
+
+### 11.1 Shutdown Sequence
+
+```
+1. SIGINT/SIGTERM received
+   +-- Uvicorn catches signal
+   +-- Stops accepting new requests
+
+2. FastAPI lifespan shutdown triggered
+   +-- 30 second total timeout
+
+3. WebSocket shutdown (5s timeout)
+   +-- Broadcast {"type": "server_shutdown"} to all clients
+   +-- Close each connection with code 1001 (Going Away)
+   +-- Clear connection tracking data
+
+4. Download service stop (10s timeout)
+   +-- Set shutdown flag
+   +-- Persist active download as "pending" in database
+   +-- Cancel active download task
+   +-- Shutdown ThreadPoolExecutor with wait
+
+5. Progress service cleanup
+   +-- Clear event subscribers
+   +-- Clear active progress tracking
+
+6. Database cleanup (10s timeout)
+   +-- SQLite: Run PRAGMA wal_checkpoint(TRUNCATE)
+   +-- Dispose async engine
+   +-- Dispose sync engine
+
+7. Process exits cleanly
+```
+
+Source: [src/server/fastapi_app.py](../src/server/fastapi_app.py#L142-L210)
+
+### 11.2 Key Components
+
+| Component           | File                                                                | Shutdown Method                |
+| ------------------- | ------------------------------------------------------------------- | ------------------------------ |
+| WebSocket Service   | [websocket_service.py](../src/server/services/websocket_service.py) | `shutdown(timeout=5.0)`        |
+| Download Service    | [download_service.py](../src/server/services/download_service.py)   | `stop(timeout=10.0)`           |
+| Database Connection | [connection.py](../src/server/database/connection.py)               | `close_db()`                   |
+| Uvicorn Config      | [run_server.py](../run_server.py)                                   | `timeout_graceful_shutdown=30` |
+| Stop Script         | [stop_server.sh](../stop_server.sh)                                 | SIGTERM with fallback          |
+
+### 11.3 Data Integrity Guarantees
+
+1. **Active downloads preserved**: In-progress downloads are saved as "pending" and can resume on restart.
+
+2. **Database WAL flushed**: SQLite WAL checkpoint ensures all writes are in the main database file.
+
+3. **WebSocket clients notified**: Clients receive shutdown message before connection closes.
+
+4. **Thread pool cleanup**: Background threads complete or are gracefully cancelled.
+
+### 11.4 Manual Stop
+
+```bash
+# Graceful stop via script (sends SIGTERM, waits up to 30s)
+./stop_server.sh
+
+# Or press Ctrl+C in terminal running the server
+```
+
+Source: [stop_server.sh](../stop_server.sh#L1-L80)
+
+---
+
+## 3. Component Interactions
+
+### 3.1 Request Flow (REST API)
+
+```
+1. Client sends HTTP request
+2. AuthMiddleware validates JWT token (if required)
+3. Rate limiter checks request frequency
+4. FastAPI router dispatches to endpoint handler
+5. Endpoint calls service layer
+6. Service layer uses core layer or database
+7. Response returned as JSON
+```
+
+Source: [src/server/middleware/auth.py](../src/server/middleware/auth.py#L1-L209)
+
+### 3.2 Download Flow
+
+```
+1. POST /api/queue/add
+   +-- DownloadService.add_to_queue()
+       +-- QueueRepository.save_item() -> SQLite
+
+2. POST /api/queue/start
+   +-- DownloadService.start_queue_processing()
+       +-- Process pending items sequentially
+       +-- ProgressService emits events
+       +-- WebSocketService broadcasts to clients
+
+3. During download:
+   +-- Provider writes to ./Temp/<filename>  (+ ./Temp/<filename>.part fragments)
+   +-- ProgressService.emit("progress_updated")
+   +-- WebSocketService.broadcast_to_room()
+   +-- Client receives WebSocket message
+
+4. After download attempt (success OR failure):
+   +-- _cleanup_temp_file() removes ./Temp/<filename> and all .part fragments
+   +-- On success: file was already moved to final destination before cleanup
+   +-- On failure / exception: no partial files remain in ./Temp/
+```
+
+#### Temp Directory Contract
+
+| Situation                        | Outcome                                                             |
+| -------------------------------- | ------------------------------------------------------------------- |
+| Server start                     | Entire `./Temp/` directory is purged before any service initialises |
+| Successful download              | Temp file moved to destination, then removed from `./Temp/`         |
+| Failed download (provider error) | Temp + `.part` fragments removed by `_cleanup_temp_file()`          |
+| Exception / cancellation         | Temp + `.part` fragments removed in `except` block                  |
+
+Source: [src/server/services/download_service.py](../src/server/services/download_service.py#L1-L150),
+[src/core/providers/aniworld_provider.py](../src/core/providers/aniworld_provider.py),
+[src/core/providers/enhanced_provider.py](../src/core/providers/enhanced_provider.py)
+
+### 3.3 WebSocket Event Flow
+
+```
+1. Client connects to /ws/connect
+2. Server sends "connected" message
+3. Client joins room: {"action": "join", "data": {"room": "downloads"}}
+4. ProgressService emits events
+5. WebSocketService broadcasts to room subscribers
+6. Client receives real-time updates
+```
+
+Source: [src/server/api/websocket.py](../src/server/api/websocket.py#L1-L260)
+
+---
+
+## 4. Design Patterns
+
+### 4.1 Repository Pattern (Service Layer as Repository)
+
+**Architecture Decision**: The Service Layer serves as the Repository layer for database access.
+
+Database access is abstracted through service classes in `src/server/database/service.py` that provide CRUD operations and act as the repository layer. This eliminates the need for a separate repository layer while maintaining clean separation of concerns.
+
+**Service Layer Classes** (acting as repositories):
+
+- `AnimeSeriesService` - CRUD operations for anime series
+- `EpisodeService` - CRUD operations for episodes
+- `DownloadQueueService` - CRUD operations for download queue
+- `UserSessionService` - CRUD operations for user sessions
+- `SystemSettingsService` - CRUD operations for system settings
+
+**Key Principles**:
+
+1. **No Direct Database Queries**: Controllers and business logic services MUST use service layer methods
+2. **Service Layer Encapsulation**: All SQLAlchemy queries are encapsulated in service methods
+3. **Consistent Interface**: Services provide consistent async methods for all database operations
+4. **Single Responsibility**: Each service manages one entity type
+
+**Example Usage**:
+
+```python
+# CORRECT: Use service layer
+from src.server.database.service import AnimeSeriesService
+
+async with get_db_session() as db:
+    series = await AnimeSeriesService.get_by_key(db, "attack-on-titan")
+    await AnimeSeriesService.update(db, series.id, has_nfo=True)
+
+# INCORRECT: Direct database query
+result = await db.execute(select(AnimeSeries).filter(...))  # ❌ Never do this
+```
+
+**Special Case - Queue Repository Adapter**:
+
+The `QueueRepository` in `src/server/services/queue_repository.py` is an adapter that wraps `DownloadQueueService` to provide domain model conversion between Pydantic models and SQLAlchemy models:
+
+```python
+# QueueRepository provides CRUD with model conversion
+class QueueRepository:
+    async def save_item(self, item: DownloadItem) -> None: ...  # Converts Pydantic → SQLAlchemy
+    async def get_all_items(self) -> List[DownloadItem]: ...    # Converts SQLAlchemy → Pydantic
+    async def delete_item(self, item_id: str) -> bool: ...
+```
+
+Source: [src/server/database/service.py](../src/server/database/service.py), [src/server/services/queue_repository.py](../src/server/services/queue_repository.py)
+
+### 4.2 Dependency Injection
+
+FastAPI's `Depends()` provides constructor injection.
+
+```python
+@router.get("/status")
+async def get_status(
+    download_service: DownloadService = Depends(get_download_service),
+):
+    ...
+```
+
+Source: [src/server/utils/dependencies.py](../src/server/utils/dependencies.py)
+
+### 4.3 Event-Driven Architecture
+
+Progress updates use an event subscription model.
+
+```python
+# ProgressService publishes events
+progress_service.emit("progress_updated", event)
+
+# WebSocketService subscribes
+progress_service.subscribe("progress_updated", ws_handler)
+```
+
+Source: [src/server/fastapi_app.py](../src/server/fastapi_app.py#L98-L108)
+
+### 4.4 Singleton Pattern
+
+Services use module-level singletons for shared state.
+
+```python
+# In download_service.py
+_download_service_instance: Optional[DownloadService] = None
+
+def get_download_service() -> DownloadService:
+    global _download_service_instance
+    if _download_service_instance is None:
+        _download_service_instance = DownloadService(...)
+    return _download_service_instance
+```
+
+### 4.5 Error Handling Pattern
+
+**Architecture Decision**: Dual error handling approach based on exception source.
+
+The application uses two complementary error handling mechanisms:
+
+1. **FastAPI HTTPException** - For simple validation and HTTP-level errors
+2. **Custom Exception Hierarchy** - For business logic and service-level errors with rich context
+
+#### Exception Hierarchy
+
+```python
+# Base exception with HTTP status mapping
+AniWorldAPIException(message, status_code, error_code, details)
+├── AuthenticationError (401)
+├── AuthorizationError (403)
+├── ValidationError (422)
+├── NotFoundError (404)
+├── ConflictError (409)
+├── BadRequestError (400)
+├── RateLimitError (429)
+└── ServerError (500)
+    ├── DownloadError
+    ├── ConfigurationError
+    ├── ProviderError
+    └── DatabaseError
+```
+
+#### When to Use Each
+
+**Use HTTPException for:**
+
+- Simple parameter validation (missing fields, wrong type)
+- Direct HTTP-level errors (401, 403, 404 without business context)
+- Quick endpoint-specific failures
+
+**Use Custom Exceptions for:**
+
+- Service-layer business logic errors (AnimeServiceError, ConfigServiceError)
+- Errors needing rich context (details dict, error codes)
+- Errors that should be logged with specific categorization
+- Cross-cutting concerns (authentication, authorization, rate limiting)
+
+**Example:**
+
+```python
+# Simple validation - Use HTTPException
+if not series_key:
+    raise HTTPException(status_code=400, detail="series_key required")
+
+# Business logic error - Use custom exception
+try:
+    await anime_service.add_series(series_key)
+except AnimeServiceError as e:
+    raise ServerError(
+        message=f"Failed to add series: {e}",
+        error_code="ANIME_ADD_FAILED",
+        details={"series_key": series_key}
+    )
+```
+
+#### Global Exception Handlers
+
+All custom exceptions are automatically handled by global middleware that:
+
+- Converts exceptions to structured JSON responses
+- Logs errors with appropriate severity
+- Includes request ID for tracking
+- Provides consistent error format
+
+**Source**: [src/server/exceptions/\_\_init\_\_.py](../src/server/exceptions/__init__.py), [src/server/middleware/error_handler.py](../src/server/middleware/error_handler.py)
+
+Source: [src/server/services/download_service.py](../src/server/services/download_service.py)
+
+---
+
+## 5. Data Flow
+
+### 5.1 Series Identifier Convention
+
+The system uses two identifier fields:
+
+| Field    | Type     | Purpose                                | Example                    |
+| -------- | -------- | -------------------------------------- | -------------------------- |
+| `key`    | Primary  | Provider-assigned, URL-safe identifier | `"attack-on-titan"`        |
+| `folder` | Metadata | Filesystem folder name (display only)  | `"Attack on Titan (2013)"` |
+
+All API operations use `key`. The `folder` is for filesystem operations only.
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L26-L50)
+
+### 5.2 Database Schema
+
+```
++----------------+       +----------------+       +--------------------+
+|  anime_series  |       |    episodes    |       | download_queue_item|
++----------------+       +----------------+       +--------------------+
+| id (PK)        |<--+   | id (PK)        |   +-->| id (PK)            |
+| key (unique)   |   |   | series_id (FK) |---+   | series_id (FK)     |
+| name           |   +---| season         |       | status             |
+| site           |       | episode_number |       | priority           |
+| folder         |       | title          |       | progress_percent   |
+| created_at     |       | is_downloaded  |       | added_at           |
+| updated_at     |       | file_path      |       | started_at         |
++----------------+       +----------------+       +--------------------+
+```
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L1-L200)
+
+### 5.3 Configuration Storage
+
+Configuration is stored in `data/config.json`:
+
+```json
+{
+    "name": "Aniworld",
+    "data_dir": "data",
+    "scheduler": {
+        "enabled": true,
+        "schedule_time": "03:00",
+        "schedule_days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"],
+        "auto_download_after_rescan": false
+    },
+    "logging": { "level": "INFO" },
+    "backup": { "enabled": false, "path": "data/backups" },
+    "other": {
+        "master_password_hash": "$pbkdf2-sha256$...",
+        "anime_directory": "/path/to/anime"
+    }
+}
+```
+
+Source: [data/config.json](../data/config.json)
+
+---
+
+## 6. Technology Stack
+
+| Layer         | Technology          | Version | Purpose                |
+| ------------- | ------------------- | ------- | ---------------------- |
+| Web Framework | FastAPI             | 0.104.1 | REST API, WebSocket    |
+| ASGI Server   | Uvicorn             | 0.24.0  | HTTP server            |
+| Database      | SQLite + SQLAlchemy | 2.0.35  | Persistence            |
+| Auth          | python-jose         | 3.3.0   | JWT tokens             |
+| Password      | passlib             | 1.7.4   | bcrypt hashing         |
+| Validation    | Pydantic            | 2.5.0   | Data models            |
+| Templates     | Jinja2              | 3.1.2   | HTML rendering         |
+| Logging       | structlog           | 24.1.0  | Structured logging     |
+| Testing       | pytest              | 7.4.3   | Unit/integration tests |
+
+Source: [requirements.txt](../requirements.txt)
+
+---
+
+## 7. Scalability Considerations
+
+### Current Limitations
+
+1. **Single-process deployment**: In-memory rate limiting and session state are not shared across processes.
+
+2. **SQLite database**: Not suitable for high concurrency. Consider PostgreSQL for production.
+
+3. **Sequential downloads**: Only one download processes at a time by design.
+
+### Recommended Improvements for Scale
+
+| Concern        | Current         | Recommended       |
+| -------------- | --------------- | ----------------- |
+| Rate limiting  | In-memory dict  | Redis             |
+| Session store  | In-memory       | Redis or database |
+| Database       | SQLite          | PostgreSQL        |
+| Task queue     | In-memory deque | Celery + Redis    |
+| Load balancing | None            | Nginx/HAProxy     |
+
+---
+
+## 8. Integration Points
+
+### 8.1 External Providers
+
+The system integrates with anime streaming providers via the Loader interface.
+
+```python
+class Loader(ABC):
+    @abstractmethod
+    def search(self, query: str) -> List[Serie]: ...
+
+    @abstractmethod
+    def get_episodes(self, serie: Serie) -> Dict[int, List[int]]: ...
+```
+
+Source: [src/core/providers/base_provider.py](../src/core/providers/base_provider.py)
+
+### 8.2 Filesystem Integration
+
+The scanner reads anime directories to detect downloaded episodes.
+
+```python
+SerieScanner(
+    basePath="/path/to/anime",  # Anime library directory
+    loader=provider,             # Provider for metadata
+    db_session=session           # Optional database
+)
+```
+
+Source: [src/core/SerieScanner.py](../src/core/SerieScanner.py#L59-L96)
+
+---
+
+## 9. Security Architecture
+
+### 9.1 Authentication Flow
+
+```
+1. User sets master password via POST /api/auth/setup
+2. Password hashed with pbkdf2_sha256 (via passlib)
+3. Hash stored in config.json
+4. Login validates password, returns JWT token
+5. JWT contains: session_id, user, created_at, expires_at
+6. Subsequent requests include: Authorization: Bearer <token>
+```
+
+Source: [src/server/services/auth_service.py](../src/server/services/auth_service.py#L1-L150)
+
+### 9.2 Password Requirements
+
+- Minimum 8 characters
+- Mixed case (upper and lower)
+- At least one number
+- At least one special character
+
+Source: [src/server/services/auth_service.py](../src/server/services/auth_service.py#L97-L125)
+
+### 9.3 Rate Limiting
+
+| Endpoint          | Limit       | Window     |
+| ----------------- | ----------- | ---------- |
+| `/api/auth/login` | 5 requests  | 60 seconds |
+| `/api/auth/setup` | 5 requests  | 60 seconds |
+| All origins       | 60 requests | 60 seconds |
+
+Source: [src/server/middleware/auth.py](../src/server/middleware/auth.py#L54-L68)
+
+---
+
+## 10. Deployment Modes
+
+### 10.1 Development
+
+```bash
+# Run with hot reload
+python -m uvicorn src.server.fastapi_app:app --reload
+```
+
+### 10.2 Production
+
+```bash
+# Via conda environment
+conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app \
+    --host 127.0.0.1 --port 8000
+```
+
+### 10.3 Configuration
+
+Environment variables (via `.env` or shell):
+
+| Variable          | Default                        | Description            |
+| ----------------- | ------------------------------ | ---------------------- |
+| `JWT_SECRET_KEY`  | Random                         | Secret for JWT signing |
+| `DATABASE_URL`    | `sqlite:///./data/aniworld.db` | Database connection    |
+| `ANIME_DIRECTORY` | (empty)                        | Path to anime library  |
+| `LOG_LEVEL`       | `INFO`                         | Logging level          |
+| `CORS_ORIGINS`    | `localhost:3000,8000`          | Allowed CORS origins   |
+
+Source: [src/config/settings.py](../src/config/settings.py#L1-L96)

docs/CHANGELOG.md

@@ -0,0 +1,243 @@
+# Changelog
+
+## Document Purpose
+
+This document tracks all notable changes to the Aniworld project.
+
+### What This Document Contains
+
+- **Version History**: All released versions with dates
+- **Added Features**: New functionality in each release
+- **Changed Features**: Modifications to existing features
+- **Deprecated Features**: Features marked for removal
+- **Removed Features**: Features removed from the codebase
+- **Fixed Bugs**: Bug fixes with issue references
+- **Security Fixes**: Security-related changes
+- **Breaking Changes**: Changes requiring user action
+
+### What This Document Does NOT Contain
+
+- Internal refactoring details (unless user-facing)
+- Commit-level changes
+- Work-in-progress features
+- Roadmap or planned features
+
+### Target Audience
+
+- All users and stakeholders
+- Operators planning upgrades
+- Developers tracking changes
+- Support personnel
+
+---
+
+## Format
+
+This changelog follows [Keep a Changelog](https://keepachangelog.com/) principles and adheres to [Semantic Versioning](https://semver.org/).
+
+---
+
+## [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`
+  fragments after each download attempt — on success, on failure, and on
+  exceptions (including `BrokenPipeError` and cancellation). Ensures that no
+  partial files accumulate in `./Temp/` across multiple runs.
+- **Temp folder purge on server start** (`src/server/fastapi_app.py`): The
+  FastAPI lifespan startup now iterates `./Temp/` and deletes every file and
+  sub-directory before the rest of the initialisation sequence runs. If the
+  folder does not exist it is created. Errors are caught and logged as warnings
+  so that they never abort startup.
+
+---
+
+## [1.3.0] - 2026-02-22
+
+### Added
+
+- **NFO tag completeness (`nfo_mapper.py`)**: All 17 required NFO tags are now
+  explicitly populated during creation: `originaltitle`, `sorttitle`, `year`,
+  `plot`, `outline`, `tagline`, `runtime`, `premiered`, `status`, `imdbid`,
+  `genre`, `studio`, `country`, `actor`, `watched`, `dateadded`, `mpaa`.
+- **`src/core/utils/nfo_mapper.py`**: New module containing
+  `tmdb_to_nfo_model()`, `_extract_rating_by_country()`, and
+  `_extract_fsk_rating()`. Extracted from `NFOService` to keep files under
+  500 lines and isolate pure mapping logic.
+- **US MPAA rating**: `_extract_rating_by_country(ratings, "US")` now maps the
+  US TMDB content rating to the `<mpaa>` NFO tag.
+- **`NfoRepairService` (`src/core/services/nfo_repair_service.py`)**: New service
+  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()`
+  (`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
+
+- `NFOService._tmdb_to_nfo_model()` and `NFOService._extract_fsk_rating()` moved
+  to `src/core/utils/nfo_mapper.py` as module-level functions
+  `tmdb_to_nfo_model()` and `_extract_fsk_rating()`.
+- `src/core/services/nfo_service.py` reduced from 640 → 471 lines.
+
+---
+
+## [Unreleased] - 2026-01-18
+
+### Added
+
+- **Cron-based Scheduler**: Replaced the asyncio sleep-loop with APScheduler's `AsyncIOScheduler + CronTrigger`
+    - Schedule rescans at a specific **time of day** (`HH:MM`) on selected **days of the week**
+    - New `SchedulerConfig` fields: `schedule_time` (default `"03:00"`), `schedule_days` (default all 7), `auto_download_after_rescan` (default `false`)
+    - Old `interval_minutes` field retained for backward compatibility
+- **Auto-download after rescan**: When `auto_download_after_rescan` is enabled, missing episodes are automatically queued for download after each scheduled rescan
+- **Day-of-week UI**: New day-of-week pill toggles (Mon–Sun) in the Settings → Scheduler section
+- **Live config reload**: POST `/api/scheduler/config` reschedules the APScheduler job without restarting the application
+- **Enriched API response**: GET/POST `/api/scheduler/config` now returns `{"success", "config", "status"}` envelope including `next_run`, `last_run`, and `scan_in_progress`
+
+### Changed
+
+- Scheduler API response format: previously returned flat config; now returns `{"success": true, "config": {...}, "status": {...}}`
+- `reload_config()` is now a synchronous method accepting a `SchedulerConfig` argument (previously async, no arguments)
+- Dependencies: added `APScheduler>=3.10.4` to `requirements.txt`
+
+### Fixed
+
+- **Series Visibility**: Fixed issue where series added to the database weren't appearing in the API/UI
+    - Series are now loaded from database into SeriesApp's in-memory cache on startup
+    - Added `_load_series_from_db()` call after initial database sync in FastAPI lifespan
+- **Episode Tracking**: Fixed missing episodes not being saved to database when adding new series
+    - Missing episodes are now persisted to the `episodes` table after the targeted scan
+    - Episodes are properly synced during rescan operations (added/removed based on filesystem state)
+- **Database Synchronization**: Improved data consistency between database and in-memory cache
+    - Rescan process properly updates episodes: adds new missing episodes, removes downloaded ones
+    - All series operations now maintain database and cache synchronization
+
+### Technical Details
+
+- Modified `src/server/fastapi_app.py` to load series from database after sync
+- 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
+
+```markdown
+## [Version] - YYYY-MM-DD
+
+### Added
+
+- New features
+
+### Changed
+
+- Changes to existing functionality
+
+### Deprecated
+
+- Features that will be removed in future versions
+
+### Removed
+
+- Features removed in this release
+
+### Fixed
+
+- Bug fixes
+
+### Security
+
+- Security-related fixes
+```
+
+---
+
+## Unreleased
+
+_Changes that are in development but not yet released._
+
+### Added
+
+- **Comprehensive Test Suite**: Created 1,070+ tests across 4 priority tiers
+    - **TIER 1 (Critical)**: 159 tests - Scheduler, NFO batch operations, download queue, persistence
+    - **TIER 2 (High Priority)**: 390 tests - JavaScript framework, dark mode, setup page, settings modal, WebSocket, queue UI
+    - **TIER 3 (Medium Priority)**: 156 tests - WebSocket load, concurrent operations, retry logic, NFO performance, series parsing, TMDB integration
+    - **TIER 4 (Polish)**: 426 tests - Internationalization (89), user preferences (68), accessibility (250+), media server compatibility (19)
+- **Frontend Testing Infrastructure**: Vitest for unit tests, Playwright for E2E tests
+- **Security Test Coverage**: Complete testing for authentication, authorization, CSRF, XSS, SQL injection
+- **Performance Validation**: WebSocket load (200+ concurrent clients), batch operations, concurrent access
+- **Accessibility Tests**: WCAG 2.1 AA compliance testing (keyboard navigation, ARIA labels, screen readers)
+- **Media Server Compatibility**: NFO format validation for Kodi, Plex, Jellyfin, and Emby
+
+### Changed
+
+- Updated testing documentation (TESTING_COMPLETE.md, instructions.md) to reflect 100% completion of all test tiers
+
+### Fixed
+
+- **Enhanced Anime Add Flow**: Automatic database persistence, targeted episode scanning, and folder creation with sanitized names
+- Filesystem utility module (`src/server/utils/filesystem.py`) with `sanitize_folder_name()`, `is_safe_path()`, and `create_safe_folder()` functions
+- `Serie.sanitized_folder` property for generating filesystem-safe folder names from display names
+- `SerieScanner.scan_single_series()` method for targeted scanning of individual anime without full library rescan
+- Add series API response now includes `missing_episodes` list and `total_missing` count
+- Database transaction support with `@transactional` decorator and `atomic()` context manager
+- Transaction propagation modes (REQUIRED, REQUIRES_NEW, NESTED) for fine-grained control
+- Savepoint support for nested transactions with partial rollback capability
+- `TransactionManager` helper class for manual transaction control
+- Bulk operations: `bulk_mark_downloaded`, `bulk_delete`, `clear_all` for batch processing
+- `rotate_session` atomic operation for secure session rotation
+- Transaction utilities: `is_session_in_transaction`, `get_session_transaction_depth`
+- `get_transactional_session` for sessions without auto-commit
+
+### Changed
+
+- `QueueRepository.save_item()` now uses atomic transactions for data consistency
+- `QueueRepository.clear_all()` now uses atomic transactions for all-or-nothing behavior
+- Service layer documentation updated to reflect transaction-aware design
+
+### Fixed
+
+- Scan status indicator now correctly shows running state after page reload during active scan
+- Improved reliability of process status updates in the UI header
+
+---
+
+## Version History
+
+_To be documented as versions are released._

docs/CONFIGURATION.md

@@ -0,0 +1,374 @@
+# Configuration Reference
+
+## Document Purpose
+
+This document provides a comprehensive reference for all configuration options in the Aniworld application.
+
+---
+
+## 1. Configuration Overview
+
+### Configuration Sources
+
+Aniworld uses a layered configuration system with **explicit precedence rules**:
+
+1. **Environment Variables** (highest priority) - Takes precedence over all other sources
+2. **`.env` file** in project root - Loaded as environment variables
+3. **`data/config.json`** file - Persistent file-based configuration
+4. **Default values** (lowest priority) - Built-in fallback values
+
+### Precedence Rules
+
+**Critical Principle**: `ENV VARS > config.json > defaults`
+
+- **Environment variables always win**: If a value is set via environment variable, it will NOT be overridden by config.json
+- **config.json as fallback**: If an ENV var is not set (or is empty/default), the value from config.json is used
+- **Defaults as last resort**: Built-in default values are used only if neither ENV var nor config.json provide a value
+
+### Loading Mechanism
+
+Configuration is loaded at application startup in `src/server/fastapi_app.py`:
+
+1. **Pydantic Settings** loads ENV vars and .env file with defaults
+2. **config.json** is loaded via `ConfigService`
+3. **Selective sync**: config.json values sync to settings **only if** ENV var not set
+4. **Runtime access**: Code uses `settings` object (which has final merged values)
+
+**Example**:
+
+```bash
+# If ENV var is set:
+ANIME_DIRECTORY=/env/path  # This takes precedence
+
+# config.json has:
+{"other": {"anime_directory": "/config/path"}}  # This is ignored
+
+# Result: settings.anime_directory = "/env/path"
+```
+
+**Source**: [src/config/settings.py](../src/config/settings.py#L1-L96), [src/server/fastapi_app.py](../src/server/fastapi_app.py#L139-L185)
+
+---
+
+## 2. Environment Variables
+
+### Authentication Settings
+
+| Variable                | Type   | Default          | Description                                                         |
+| ----------------------- | ------ | ---------------- | ------------------------------------------------------------------- |
+| `JWT_SECRET_KEY`        | string | (random)         | Secret key for JWT token signing. Auto-generated if not set.        |
+| `PASSWORD_SALT`         | string | `"default-salt"` | Salt for password hashing.                                          |
+| `MASTER_PASSWORD_HASH`  | string | (none)           | Pre-hashed master password. Loaded from config.json if not set.     |
+| `MASTER_PASSWORD`       | string | (none)           | **DEVELOPMENT ONLY** - Plaintext password. Never use in production. |
+| `SESSION_TIMEOUT_HOURS` | int    | `24`             | JWT token expiry time in hours.                                     |
+
+Source: [src/config/settings.py](../src/config/settings.py#L13-L42)
+
+### Server Settings
+
+| Variable          | Type   | Default                          | Description                                                           |
+| ----------------- | ------ | -------------------------------- | --------------------------------------------------------------------- |
+| `ANIME_DIRECTORY` | string | `""`                             | Path to anime library directory.                                      |
+| `LOG_LEVEL`       | string | `"INFO"`                         | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL.                 |
+| `DATABASE_URL`    | string | `"sqlite:///./data/aniworld.db"` | Database connection string.                                           |
+| `CORS_ORIGINS`    | string | `"http://localhost:3000"`        | Comma-separated allowed CORS origins. Use `*` for localhost defaults. |
+| `API_RATE_LIMIT`  | int    | `100`                            | Maximum API requests per minute.                                      |
+
+Source: [src/config/settings.py](../src/config/settings.py#L43-L68)
+
+### Provider Settings
+
+| Variable           | Type   | Default         | Description                                   |
+| ------------------ | ------ | --------------- | --------------------------------------------- |
+| `DEFAULT_PROVIDER` | string | `"aniworld.to"` | Default anime provider.                       |
+| `PROVIDER_TIMEOUT` | int    | `30`            | HTTP timeout for provider requests (seconds). |
+| `RETRY_ATTEMPTS`   | int    | `3`             | Number of retry attempts for failed requests. |
+
+Source: [src/config/settings.py](../src/config/settings.py#L69-L79)
+
+### NFO Settings
+
+| Variable              | Type   | Default  | Description                                        |
+| --------------------- | ------ | -------- | -------------------------------------------------- |
+| `TMDB_API_KEY`        | string | `""`     | The Movie Database (TMDB) API key for metadata.    |
+| `NFO_AUTO_CREATE`     | bool   | `true`   | Automatically create NFO files during downloads.   |
+| `NFO_UPDATE_ON_SCAN`  | bool   | `false`  | Update existing NFO files when scanning library.   |
+| `NFO_DOWNLOAD_POSTER` | bool   | `true`   | Download poster images along with NFO files.       |
+| `NFO_DOWNLOAD_LOGO`   | bool   | `false`  | Download logo images along with NFO files.         |
+| `NFO_DOWNLOAD_FANART` | bool   | `false`  | Download fanart images along with NFO files.       |
+| `NFO_IMAGE_SIZE`      | string | `"w500"` | Image size for TMDB images (w500, w780, original). |
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L109-L132)
+
+---
+
+## 3. Configuration File (config.json)
+
+Location: `data/config.json`
+
+### File Structure
+
+```json
+{
+    "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": false,
+        "folder_scan_enabled": false
+    },
+    "logging": {
+        "level": "INFO",
+        "file": null,
+        "max_bytes": null,
+        "backup_count": 3
+    },
+    "backup": {
+        "enabled": false,
+        "path": "data/backups",
+        "keep_days": 30
+    },
+    "nfo": {
+        "tmdb_api_key": "",
+        "auto_create": true,
+        "update_on_scan": false,
+        "download_poster": true,
+        "download_logo": false,
+        "download_fanart": false,
+        "image_size": "w500"
+    },
+    "other": {
+        "master_password_hash": "$pbkdf2-sha256$...",
+        "anime_directory": "/path/to/anime"
+    },
+    "version": "1.0.1"
+}
+```
+
+Source: [data/config.json](../data/config.json)
+
+---
+
+## 4. Configuration Sections
+
+### 4.1 General Settings
+
+| Field      | Type   | Default      | Description                    |
+| ---------- | ------ | ------------ | ------------------------------ |
+| `name`     | string | `"Aniworld"` | Application name.              |
+| `data_dir` | string | `"data"`     | Base directory for data files. |
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L62-L66)
+
+### 4.2 Scheduler Settings
+
+Controls automatic cron-based library rescanning (powered by APScheduler).
+
+| Field                                  | Type         | Default                                       | Description                                                          |
+| -------------------------------------- | ------------ | --------------------------------------------- | -------------------------------------------------------------------- |
+| `scheduler.enabled`                    | bool         | `true`                                        | Enable/disable automatic scans.                                      |
+| `scheduler.interval_minutes`           | int          | `60`                                          | Legacy field kept for backward compatibility. Minimum: 1.            |
+| `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`.
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L5-L12)
+
+### 4.3 Logging Settings
+
+| Field                  | Type   | Default  | Description                                       |
+| ---------------------- | ------ | -------- | ------------------------------------------------- |
+| `logging.level`        | string | `"INFO"` | Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL. |
+| `logging.file`         | string | `null`   | Optional log file path.                           |
+| `logging.max_bytes`    | int    | `null`   | Maximum log file size for rotation.               |
+| `logging.backup_count` | int    | `3`      | Number of rotated log files to keep.              |
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L27-L46)
+
+### 4.4 Backup Settings
+
+| Field              | Type   | Default          | Description                      |
+| ------------------ | ------ | ---------------- | -------------------------------- |
+| `backup.enabled`   | bool   | `false`          | Enable automatic config backups. |
+| `backup.path`      | string | `"data/backups"` | Directory for backup files.      |
+| `backup.keep_days` | int    | `30`             | Days to retain backups.          |
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L15-L24)
+
+### 4.5 NFO Settings
+
+| Field                 | Type   | Default  | Description                                                   |
+| --------------------- | ------ | -------- | ------------------------------------------------------------- |
+| `nfo.tmdb_api_key`    | string | `""`     | The Movie Database (TMDB) API key for fetching metadata.      |
+| `nfo.auto_create`     | bool   | `true`   | Automatically create NFO files when downloading episodes.     |
+| `nfo.update_on_scan`  | bool   | `false`  | Update existing NFO files during library scan operations.     |
+| `nfo.download_poster` | bool   | `true`   | Download poster images (poster.jpg) along with NFO files.     |
+| `nfo.download_logo`   | bool   | `false`  | Download logo images (logo.png) along with NFO files.         |
+| `nfo.download_fanart` | bool   | `false`  | Download fanart images (fanart.jpg) along with NFO files.     |
+| `nfo.image_size`      | string | `"w500"` | TMDB image size: `w500` (recommended), `w780`, or `original`. |
+
+**Notes:**
+
+- 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)
+
+### 4.6 Other Settings (Dynamic)
+
+The `other` field stores arbitrary settings.
+
+| Key                    | Type   | Description                             |
+| ---------------------- | ------ | --------------------------------------- |
+| `master_password_hash` | string | Hashed master password (pbkdf2-sha256). |
+| `anime_directory`      | string | Path to anime library.                  |
+| `advanced`             | object | Advanced configuration options.         |
+
+---
+
+## 5. Configuration Precedence
+
+Settings are resolved in this order (first match wins):
+
+1. Environment variable (e.g., `ANIME_DIRECTORY`)
+2. `.env` file in project root
+3. `data/config.json` (for dynamic settings)
+4. Code defaults in `Settings` class
+
+---
+
+## 6. Validation Rules
+
+### Password Requirements
+
+Master password must meet all criteria:
+
+- Minimum 8 characters
+- At least one uppercase letter
+- At least one lowercase letter
+- At least one digit
+- At least one special character
+
+Source: [src/server/services/auth_service.py](../src/server/services/auth_service.py#L97-L125)
+
+### Logging Level Validation
+
+Must be one of: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L43-L47)
+
+### Backup Path Validation
+
+If `backup.enabled` is `true`, `backup.path` must be set.
+
+Source: [src/server/models/config.py](../src/server/models/config.py#L87-L91)
+
+---
+
+## 7. Example Configurations
+
+### Minimal Development Setup
+
+**.env file:**
+
+```
+LOG_LEVEL=DEBUG
+ANIME_DIRECTORY=/home/user/anime
+```
+
+### Production Setup
+
+**.env file:**
+
+```
+JWT_SECRET_KEY=your-secure-random-key-here
+DATABASE_URL=postgresql+asyncpg://user:pass@localhost/aniworld
+LOG_LEVEL=WARNING
+CORS_ORIGINS=https://your-domain.com
+API_RATE_LIMIT=60
+```
+
+### Docker Setup
+
+```yaml
+# docker-compose.yml
+environment:
+    - JWT_SECRET_KEY=${JWT_SECRET_KEY}
+    - DATABASE_URL=sqlite:///./data/aniworld.db
+    - ANIME_DIRECTORY=/media/anime
+    - LOG_LEVEL=INFO
+volumes:
+    - ./data:/app/data
+    - /media/anime:/media/anime:ro
+```
+
+---
+
+## 8. Configuration Backup Management
+
+### Automatic Backups
+
+Backups are created automatically before config changes when `backup.enabled` is `true`.
+
+Location: `data/config_backups/`
+
+Naming: `config_backup_YYYYMMDD_HHMMSS.json`
+
+### Manual Backup via API
+
+```bash
+# Create backup
+curl -X POST http://localhost:8000/api/config/backups \
+  -H "Authorization: Bearer $TOKEN"
+
+# List backups
+curl http://localhost:8000/api/config/backups \
+  -H "Authorization: Bearer $TOKEN"
+
+# Restore backup
+curl -X POST http://localhost:8000/api/config/backups/config_backup_20251213.json/restore \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Source: [src/server/api/config.py](../src/server/api/config.py#L67-L142)
+
+---
+
+## 9. Troubleshooting
+
+### Configuration Not Loading
+
+1. Check file permissions on `data/config.json`
+2. Verify JSON syntax with a validator
+3. Check logs for Pydantic validation errors
+
+### Environment Variable Not Working
+
+1. Ensure variable name matches exactly (case-sensitive)
+2. Check `.env` file location (project root)
+3. Restart application after changes
+
+### Master Password Issues
+
+1. Password hash is stored in `config.json` under `other.master_password_hash`
+2. Delete this field to reset (requires re-setup)
+3. Check hash format starts with `$pbkdf2-sha256$`
+
+---
+
+## 10. Related Documentation
+
+- [API.md](API.md) - Configuration API endpoints
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Development environment setup
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Configuration service architecture

docs/DATABASE.md

@@ -0,0 +1,642 @@
+# Database Documentation
+
+## Document Purpose
+
+This document describes the database schema, models, and data layer of the Aniworld application.
+
+---
+
+## 1. Database Overview
+
+### Technology
+
+- **Database Engine**: SQLite 3 (default), PostgreSQL supported
+- **ORM**: SQLAlchemy 2.0 with async support (aiosqlite)
+- **Location**: `data/aniworld.db` (configurable via `DATABASE_URL`)
+
+Source: [src/config/settings.py](../src/config/settings.py#L53-L55)
+
+### Connection Configuration
+
+```python
+# Default connection string
+DATABASE_URL = "sqlite+aiosqlite:///./data/aniworld.db"
+
+# PostgreSQL alternative
+DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/aniworld"
+```
+
+Source: [src/server/database/connection.py](../src/server/database/connection.py)
+
+---
+
+## 2. Entity Relationship Diagram
+
+```
++---------------------+       +-------------------+       +-------------------+       +------------------------+
+| system_settings     |       |   anime_series    |       |     episodes      |       |  download_queue_item   |
++---------------------+       +-------------------+       +-------------------+       +------------------------+
+| id (PK)             |       | id (PK)           |<--+   | id (PK)           |   +-->| id (PK, VARCHAR)       |
+| initial_scan_...    |       | key (UNIQUE)      |   |   | series_id (FK)----+---+   | series_id (FK)---------+
+| initial_nfo_scan... |       | name              |   +---|                   |       | status                 |
+| initial_media_...   |       | site              |       | season            |       | priority               |
+| last_scan_timestamp |       | folder            |       | episode_number    |       | season                 |
+| created_at          |       | created_at        |       | title             |       | episode                |
+| updated_at          |       | updated_at        |       | file_path         |       | progress_percent       |
++---------------------+       +-------------------+       | is_downloaded     |       | error_message          |
+                                                          | created_at        |       | retry_count            |
+                                                          | updated_at        |       | added_at               |
+                                                          +-------------------+       | started_at             |
+                                                                                      | completed_at           |
+                                                                                      | created_at             |
+                                                                                      | updated_at             |
+                                                                                      +------------------------+
+```
+
+---
+
+## 3. Table Schemas
+
+### 3.1 system_settings
+
+Stores application-wide system settings and initialization state.
+
+| Column                         | Type     | Constraints                | Description                                   |
+| ------------------------------ | -------- | -------------------------- | --------------------------------------------- |
+| `id`                           | INTEGER  | PRIMARY KEY, AUTOINCREMENT | Internal database ID (only one row)           |
+| `initial_scan_completed`       | BOOLEAN  | NOT NULL, DEFAULT FALSE    | Whether initial anime folder scan is complete |
+| `initial_nfo_scan_completed`   | BOOLEAN  | NOT NULL, DEFAULT FALSE    | Whether initial NFO scan is complete          |
+| `initial_media_scan_completed` | BOOLEAN  | NOT NULL, DEFAULT FALSE    | Whether initial media scan is complete        |
+| `last_scan_timestamp`          | DATETIME | NULLABLE                   | Timestamp of last completed scan              |
+| `created_at`                   | DATETIME | NOT NULL, DEFAULT NOW      | Record creation timestamp                     |
+| `updated_at`                   | DATETIME | NOT NULL, ON UPDATE NOW    | Last update timestamp                         |
+
+**Purpose:**
+
+This table tracks the initialization status of the application to ensure that expensive one-time setup operations (like scanning the entire anime directory) only run on the first startup, not on every restart.
+
+- Only one row exists in this table
+- The `initial_scan_completed` flag prevents redundant full directory scans on each startup
+- The NFO and media scan flags similarly track completion of those setup tasks
+
+Source: [src/server/database/models.py](../src/server/database/models.py), [src/server/database/system_settings_service.py](../src/server/database/system_settings_service.py)
+
+### 3.2 anime_series
+
+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)                  |
+| `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:**
+
+- `key` is the **primary identifier** for all operations (e.g., `"attack-on-titan"`)
+- `folder` is **metadata only** for filesystem operations (e.g., `"Attack on Titan (2013)"`)
+- `id` is used only for database relationships
+
+**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
+
+Stores **missing episodes** that need to be downloaded. Episodes are automatically managed during scans:
+
+- New missing episodes are added to the database
+- Episodes that are no longer missing (files now exist) are removed from the database
+- When an episode is downloaded, it can be marked with `is_downloaded=True` or removed from tracking
+
+| Column           | Type          | Constraints                  | Description                   |
+| ---------------- | ------------- | ---------------------------- | ----------------------------- |
+| `id`             | INTEGER       | PRIMARY KEY, AUTOINCREMENT   | Internal database ID          |
+| `series_id`      | INTEGER       | FOREIGN KEY, NOT NULL, INDEX | Reference to anime_series.id  |
+| `season`         | INTEGER       | NOT NULL                     | Season number (1-based)       |
+| `episode_number` | INTEGER       | NOT NULL                     | Episode number within season  |
+| `title`          | VARCHAR(500)  | NULLABLE                     | Episode title if known        |
+| `file_path`      | VARCHAR(1000) | NULLABLE                     | Local file path if downloaded |
+| `is_downloaded`  | BOOLEAN       | NOT NULL, DEFAULT FALSE      | Download status flag          |
+| `created_at`     | DATETIME      | NOT NULL, DEFAULT NOW        | Record creation timestamp     |
+| `updated_at`     | DATETIME      | NOT NULL, ON UPDATE NOW      | Last update timestamp         |
+
+**Foreign Key:**
+
+- `series_id` -> `anime_series.id` (ON DELETE CASCADE)
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L122-L181)
+
+### 3.4 download_queue_item
+
+Stores download queue items with status tracking.
+
+| Column             | Type          | Constraints                 | Description                    |
+| ------------------ | ------------- | --------------------------- | ------------------------------ |
+| `id`               | VARCHAR(36)   | PRIMARY KEY                 | UUID identifier                |
+| `series_id`        | INTEGER       | FOREIGN KEY, NOT NULL       | Reference to anime_series.id   |
+| `season`           | INTEGER       | NOT NULL                    | Season number                  |
+| `episode`          | INTEGER       | NOT NULL                    | Episode number                 |
+| `status`           | VARCHAR(20)   | NOT NULL, DEFAULT 'pending' | Download status                |
+| `priority`         | VARCHAR(10)   | NOT NULL, DEFAULT 'NORMAL'  | Queue priority                 |
+| `progress_percent` | FLOAT         | NULLABLE                    | Download progress (0-100)      |
+| `error_message`    | TEXT          | NULLABLE                    | Error description if failed    |
+| `retry_count`      | INTEGER       | NOT NULL, DEFAULT 0         | Number of retry attempts       |
+| `source_url`       | VARCHAR(2000) | NULLABLE                    | Download source URL            |
+| `added_at`         | DATETIME      | NOT NULL, DEFAULT NOW       | When added to queue            |
+| `started_at`       | DATETIME      | NULLABLE                    | When download started          |
+| `completed_at`     | DATETIME      | NULLABLE                    | When download completed/failed |
+| `created_at`       | DATETIME      | NOT NULL, DEFAULT NOW       | Record creation timestamp      |
+| `updated_at`       | DATETIME      | NOT NULL, ON UPDATE NOW     | Last update timestamp          |
+
+**Status Values:** `pending`, `downloading`, `paused`, `completed`, `failed`, `cancelled`
+
+**Priority Values:** `LOW`, `NORMAL`, `HIGH`
+
+**Foreign Key:**
+
+- `series_id` -> `anime_series.id` (ON DELETE CASCADE)
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L200-L300)
+
+---
+
+## 4. Indexes
+
+| Table                 | Index Name              | Columns     | Purpose                           |
+| --------------------- | ----------------------- | ----------- | --------------------------------- |
+| `system_settings`     | N/A (single row)        | N/A         | Only one row, no indexes needed   |
+| `anime_series`        | `ix_anime_series_key`   | `key`       | Fast lookup by primary identifier |
+| `anime_series`        | `ix_anime_series_name`  | `name`      | Search by name                    |
+| `episodes`            | `ix_episodes_series_id` | `series_id` | Join with series                  |
+| `download_queue_item` | `ix_download_series_id` | `series_id` | Filter by series                  |
+| `download_queue_item` | `ix_download_status`    | `status`    | Filter by status                  |
+
+---
+
+## 5. Model Layer
+
+### 5.1 SQLAlchemy ORM Models
+
+```python
+# src/server/database/models.py
+
+class AnimeSeries(Base, TimestampMixin):
+    __tablename__ = "anime_series"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    key: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(500), index=True)
+    site: Mapped[str] = mapped_column(String(500))
+    folder: Mapped[str] = mapped_column(String(1000))
+
+    episodes: Mapped[List["Episode"]] = relationship(
+        "Episode", back_populates="series", cascade="all, delete-orphan"
+    )
+```
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L23-L87)
+
+### 5.2 Pydantic API Models
+
+```python
+# src/server/models/download.py
+
+class DownloadItem(BaseModel):
+    id: str
+    serie_id: str      # Maps to anime_series.key
+    serie_folder: str  # Metadata only
+    serie_name: str
+    episode: EpisodeIdentifier
+    status: DownloadStatus
+    priority: DownloadPriority
+```
+
+Source: [src/server/models/download.py](../src/server/models/download.py#L63-L118)
+
+### 5.3 Model Mapping
+
+| API Field      | Database Column       | Notes              |
+| -------------- | --------------------- | ------------------ |
+| `serie_id`     | `anime_series.key`    | Primary identifier |
+| `serie_folder` | `anime_series.folder` | Metadata only      |
+| `serie_name`   | `anime_series.name`   | Display name       |
+
+---
+
+## 6. Transaction Support
+
+### 6.1 Overview
+
+The database layer provides comprehensive transaction support to ensure data consistency across compound operations. All write operations can be wrapped in explicit transactions.
+
+Source: [src/server/database/transaction.py](../src/server/database/transaction.py)
+
+### 6.2 Transaction Utilities
+
+| Component                 | Type              | Description                              |
+| ------------------------- | ----------------- | ---------------------------------------- |
+| `@transactional`          | Decorator         | Wraps function in transaction boundary   |
+| `atomic()`                | Async context mgr | Provides atomic operation block          |
+| `atomic_sync()`           | Sync context mgr  | Sync version of atomic()                 |
+| `TransactionContext`      | Class             | Explicit sync transaction control        |
+| `AsyncTransactionContext` | Class             | Explicit async transaction control       |
+| `TransactionManager`      | Class             | Helper for manual transaction management |
+
+### 6.3 Transaction Propagation Modes
+
+| Mode           | Behavior                                         |
+| -------------- | ------------------------------------------------ |
+| `REQUIRED`     | Use existing transaction or create new (default) |
+| `REQUIRES_NEW` | Always create new transaction                    |
+| `NESTED`       | Create savepoint within existing transaction     |
+
+### 6.4 Usage Examples
+
+**Using @transactional decorator:**
+
+```python
+from src.server.database.transaction import transactional
+
+@transactional()
+async def compound_operation(db: AsyncSession, data: dict):
+    # All operations commit together or rollback on error
+    series = await AnimeSeriesService.create(db, ...)
+    episode = await EpisodeService.create(db, series_id=series.id, ...)
+    return series, episode
+```
+
+**Using atomic() context manager:**
+
+```python
+from src.server.database.transaction import atomic
+
+async def some_function(db: AsyncSession):
+    async with atomic(db) as tx:
+        await operation1(db)
+        await operation2(db)
+        # Auto-commits on success, rolls back on exception
+```
+
+**Using savepoints for partial rollback:**
+
+```python
+async with atomic(db) as tx:
+    await outer_operation(db)
+
+    async with tx.savepoint() as sp:
+        await risky_operation(db)
+        if error_condition:
+            await sp.rollback()  # Only rollback nested ops
+
+    await final_operation(db)  # Still executes
+```
+
+Source: [src/server/database/transaction.py](../src/server/database/transaction.py)
+
+### 6.5 Connection Module Additions
+
+| Function                        | Description                                  |
+| ------------------------------- | -------------------------------------------- |
+| `get_transactional_session`     | Session without auto-commit for transactions |
+| `TransactionManager`            | Helper class for manual transaction control  |
+| `is_session_in_transaction`     | Check if session is in active transaction    |
+| `get_session_transaction_depth` | Get nesting depth of transactions            |
+
+Source: [src/server/database/connection.py](../src/server/database/connection.py)
+
+---
+
+## 7. Repository Pattern
+
+The `QueueRepository` class provides data access abstraction.
+
+```python
+class QueueRepository:
+    async def save_item(self, item: DownloadItem) -> None:
+        """Save or update a download item (atomic operation)."""
+
+    async def get_all_items(self) -> List[DownloadItem]:
+        """Get all items from database."""
+
+    async def delete_item(self, item_id: str) -> bool:
+        """Delete item by ID."""
+
+    async def clear_all(self) -> int:
+        """Clear all items (atomic operation)."""
+```
+
+Note: Compound operations (`save_item`, `clear_all`) are wrapped in `atomic()` transactions.
+
+Source: [src/server/services/queue_repository.py](../src/server/services/queue_repository.py)
+
+---
+
+## 8. Database Service
+
+The `AnimeSeriesService` provides async CRUD operations.
+
+```python
+class AnimeSeriesService:
+    @staticmethod
+    async def create(
+        db: AsyncSession,
+        key: str,
+        name: str,
+        site: str,
+        folder: str
+    ) -> AnimeSeries:
+        """Create a new anime series."""
+
+    @staticmethod
+    async def get_by_key(
+        db: AsyncSession,
+        key: str
+    ) -> Optional[AnimeSeries]:
+        """Get series by primary key identifier."""
+```
+
+### Bulk Operations
+
+Services provide bulk operations for transaction-safe batch processing:
+
+| Service                | Method                 | Description                    |
+| ---------------------- | ---------------------- | ------------------------------ |
+| `EpisodeService`       | `bulk_mark_downloaded` | Mark multiple episodes at once |
+| `DownloadQueueService` | `bulk_delete`          | Delete multiple queue items    |
+| `DownloadQueueService` | `clear_all`            | Clear entire queue             |
+| `UserSessionService`   | `rotate_session`       | Revoke old + create new atomic |
+| `UserSessionService`   | `cleanup_expired`      | Bulk delete expired sessions   |
+
+Source: [src/server/database/service.py](../src/server/database/service.py)
+
+---
+
+## 9. Data Integrity Rules
+
+### Validation Constraints
+
+| Field                     | Rule                     | Error Message                         |
+| ------------------------- | ------------------------ | ------------------------------------- |
+| `anime_series.key`        | Non-empty, max 255 chars | "Series key cannot be empty"          |
+| `anime_series.name`       | Non-empty, max 500 chars | "Series name cannot be empty"         |
+| `episodes.season`         | 0-1000                   | "Season number must be non-negative"  |
+| `episodes.episode_number` | 0-10000                  | "Episode number must be non-negative" |
+
+Source: [src/server/database/models.py](../src/server/database/models.py#L89-L119)
+
+### Cascade Rules
+
+- Deleting `anime_series` deletes all related `episodes` and `download_queue_item`
+
+---
+
+## 10. Migration Strategy
+
+Currently, SQLAlchemy's `create_all()` is used for schema creation.
+
+```python
+# src/server/database/connection.py
+async def init_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+```
+
+For production migrations, Alembic is recommended but not yet implemented.
+
+Source: [src/server/database/connection.py](../src/server/database/connection.py)
+
+---
+
+## 11. Common Query Patterns
+
+### Get all series with missing episodes
+
+```python
+series = await db.execute(
+    select(AnimeSeries).options(selectinload(AnimeSeries.episodes))
+)
+for serie in series.scalars():
+    downloaded = [e for e in serie.episodes if e.is_downloaded]
+```
+
+### Get pending downloads ordered by priority
+
+```python
+items = await db.execute(
+    select(DownloadQueueItem)
+    .where(DownloadQueueItem.status == "pending")
+    .order_by(
+        case(
+            (DownloadQueueItem.priority == "HIGH", 1),
+            (DownloadQueueItem.priority == "NORMAL", 2),
+            (DownloadQueueItem.priority == "LOW", 3),
+        ),
+        DownloadQueueItem.added_at
+    )
+)
+```
+
+---
+
+## 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                                  |
+| ----------- | ------------------------------------------------- |
+| Development | `./data/aniworld.db`                              |
+| Production  | Via `DATABASE_URL` environment variable           |
+| Testing     | In-memory SQLite (`sqlite+aiosqlite:///:memory:`) |

docs/DEVELOPMENT.md

@@ -0,0 +1,436 @@
+# Development Guide
+
+## Document Purpose
+
+This document provides guidance for developers working on the Aniworld project.
+
+### What This Document Contains
+
+-   **Prerequisites**: Required software and tools
+-   **Environment Setup**: Step-by-step local development setup
+-   **Project Structure**: Source code organization explanation
+-   **Development Workflow**: Branch strategy, commit conventions
+-   **Coding Standards**: Style guide, linting, formatting
+-   **Running the Application**: Development server, CLI usage
+-   **Debugging Tips**: Common debugging approaches
+-   **IDE Configuration**: VS Code settings, recommended extensions
+-   **Contributing Guidelines**: How to submit changes
+-   **Code Review Process**: Review checklist and expectations
+
+### What This Document Does NOT Contain
+
+-   Production deployment (see [DEPLOYMENT.md](DEPLOYMENT.md))
+-   API reference (see [API.md](API.md))
+-   Architecture decisions (see [ARCHITECTURE.md](ARCHITECTURE.md))
+-   Test writing guides (see [TESTING.md](TESTING.md))
+-   Security guidelines (see [SECURITY.md](SECURITY.md))
+
+### Target Audience
+
+-   New Developers joining the project
+-   Contributors (internal and external)
+-   Anyone setting up a development environment
+
+---
+
+## Sections to Document
+
+1. Prerequisites
+    - Python version
+    - Conda environment
+    - Node.js (if applicable)
+    - Git
+2. Getting Started
+    - Clone repository
+    - Setup conda environment
+    - Install dependencies
+    - Configuration setup
+3. Project Structure Overview
+4. Development Server
+    - Starting FastAPI server
+    - Hot reload configuration
+    - Debug mode
+5. CLI Development
+6. Code Style
+    - PEP 8 compliance
+    - Type hints requirements
+    - Docstring format
+    - Import organization
+7. Git Workflow
+    - Branch naming
+    - 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

@@ -0,0 +1,905 @@
+# NFO Metadata Guide
+
+## Document Purpose
+
+This guide explains how to use the NFO metadata feature to enrich your anime library with TMDB metadata and artwork for Plex, Jellyfin, Emby, and Kodi.
+
+---
+
+## 1. Overview
+
+### What are NFO Files?
+
+NFO files are XML documents that contain metadata about TV shows and episodes. Media servers like Plex, Jellyfin, Emby, and Kodi use these files to display information about your library without needing to scrape external sources.
+
+### Features
+
+- **Automatic NFO Creation**: Generate NFO files during downloads
+- **TMDB Integration**: Fetch metadata from The Movie Database
+- **Image Downloads**: Poster, fanart, and logo images
+- **Batch Operations**: Create/update NFO files for multiple anime
+- **Web UI**: Manage NFO settings and operations
+- **API Access**: Programmatic NFO management
+
+---
+
+## 2. Getting Started
+
+### 2.1 Obtain TMDB API Key
+
+1. Create a free account at https://www.themoviedb.org
+2. Navigate to https://www.themoviedb.org/settings/api
+3. Request an API key (select "Developer" option)
+4. Copy your API key (v3 auth)
+
+### 2.2 Configure NFO Settings
+
+#### Via Web Interface
+
+1. Open http://127.0.0.1:8000
+2. Click **Configuration** button
+3. Scroll to **NFO Settings** section
+4. Enter your TMDB API key
+5. Click **Test Connection** to verify
+6. Configure options:
+    - **Auto-create during downloads**: Enable to create NFO files automatically
+    - **Update on library scan**: Enable to refresh existing NFO files
+    - **Download poster**: Episode and show poster images (poster.jpg)
+    - **Download logo**: Show logo images (logo.png)
+    - **Download fanart**: Background artwork (fanart.jpg)
+    - **Image size**: Select w500 (recommended), w780, or original
+7. Click **Save**
+
+#### Via Environment Variables
+
+Add to your `.env` file:
+
+```bash
+TMDB_API_KEY=your_api_key_here
+NFO_AUTO_CREATE=true
+NFO_UPDATE_ON_SCAN=false
+NFO_DOWNLOAD_POSTER=true
+NFO_DOWNLOAD_LOGO=false
+NFO_DOWNLOAD_FANART=false
+NFO_IMAGE_SIZE=w500
+```
+
+#### Via config.json
+
+Edit `data/config.json`:
+
+```json
+{
+    "nfo": {
+        "tmdb_api_key": "your_api_key_here",
+        "auto_create": true,
+        "update_on_scan": false,
+        "download_poster": true,
+        "download_logo": false,
+        "download_fanart": false,
+        "image_size": "w500"
+    }
+}
+```
+
+---
+
+## 3. Using NFO Features
+
+### 3.1 Automatic NFO Creation
+
+With `auto_create` enabled, NFO files are created automatically when downloading episodes:
+
+1. Add episodes to download queue
+2. Start queue processing
+3. NFO files are created after successful downloads
+4. Images are downloaded based on configuration
+
+### 3.2 Manual NFO Creation
+
+#### Via Web Interface
+
+1. Navigate to the main page
+2. Click **Create NFO** button next to an anime
+3. Wait for completion notification
+
+#### Via API
+
+```bash
+curl -X POST "http://127.0.0.1:8000/api/nfo/create" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "anime_id": 123,
+    "folder_path": "/path/to/anime/Attack on Titan"
+  }'
+```
+
+### 3.3 Batch NFO Creation
+
+Create NFO files for multiple anime at once:
+
+```bash
+curl -X POST "http://127.0.0.1:8000/api/nfo/batch/create" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "anime_ids": [123, 456, 789]
+  }'
+```
+
+### 3.4 Update Existing NFO Files
+
+Update NFO files with latest TMDB metadata:
+
+```bash
+curl -X POST "http://127.0.0.1:8000/api/nfo/update" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "anime_id": 123,
+    "folder_path": "/path/to/anime/Attack on Titan",
+    "force": true
+  }'
+```
+
+### 3.5 Check NFO Status
+
+Check which anime have NFO files:
+
+```bash
+curl -X GET "http://127.0.0.1:8000/api/nfo/check?folder_path=/path/to/anime" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+Response:
+
+```json
+{
+    "has_tvshow_nfo": true,
+    "episode_nfos": [
+        {
+            "season": 1,
+            "episode": 1,
+            "has_nfo": true,
+            "file_path": "/path/to/anime/Season 1/S01E01.nfo"
+        }
+    ],
+    "missing_episodes": [],
+    "total_episodes": 25,
+    "nfo_count": 25
+}
+```
+
+### 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
+
+### 4.1 NFO File Locations
+
+NFO files are created in the anime directory:
+
+```
+/path/to/anime/Attack on Titan/
+├── tvshow.nfo              # Show metadata
+├── poster.jpg              # Show poster (optional)
+├── logo.png                # Show logo (optional)
+├── fanart.jpg              # Show fanart (optional)
+├── Season 1/
+│   ├── S01E01.mkv
+│   ├── S01E01.nfo          # Episode metadata
+│   ├── S01E01-thumb.jpg    # Episode thumbnail (optional)
+│   ├── S01E02.mkv
+│   └── S01E02.nfo
+└── Season 2/
+    ├── S02E01.mkv
+    └── S02E01.nfo
+```
+
+### 4.2 tvshow.nfo Format
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<tvshow>
+    <title>Attack on Titan</title>
+    <originaltitle>進撃の巨人</originaltitle>
+    <showtitle>Attack on Titan</showtitle>
+    <sorttitle>Attack on Titan</sorttitle>
+    <rating>8.5</rating>
+    <year>2013</year>
+    <plot>Humans are nearly exterminated by giant creatures...</plot>
+    <runtime>24</runtime>
+    <mpaa>TV-MA</mpaa>
+    <premiered>2013-04-07</premiered>
+    <status>Ended</status>
+    <studio>Wit Studio</studio>
+    <genre>Animation</genre>
+    <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>
+    </fanart>
+</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
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<episodedetails>
+    <title>To You, in 2000 Years: The Fall of Shiganshina, Part 1</title>
+    <showtitle>Attack on Titan</showtitle>
+    <season>1</season>
+    <episode>1</episode>
+    <displayseason>1</displayseason>
+    <displayepisode>1</displayepisode>
+    <plot>After a hundred years of peace...</plot>
+    <runtime>24</runtime>
+    <aired>2013-04-07</aired>
+    <rating>8.2</rating>
+    <uniqueid type="tmdb">63056</uniqueid>
+    <thumb>https://image.tmdb.org/t/p/w500/...</thumb>
+</episodedetails>
+```
+
+---
+
+## 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
+
+**Endpoint**: `GET /api/nfo/check`
+
+**Query Parameters**:
+
+- `folder_path` (required): Absolute path to anime directory
+
+**Response**:
+
+```json
+{
+    "has_tvshow_nfo": true,
+    "episode_nfos": [
+        {
+            "season": 1,
+            "episode": 1,
+            "has_nfo": true,
+            "file_path": "/path/to/S01E01.nfo"
+        }
+    ],
+    "missing_episodes": [],
+    "total_episodes": 25,
+    "nfo_count": 25
+}
+```
+
+### 5.2 Create NFO Files
+
+**Endpoint**: `POST /api/nfo/create`
+
+**Request Body**:
+
+```json
+{
+    "anime_id": 123,
+    "folder_path": "/path/to/anime/Attack on Titan"
+}
+```
+
+**Response**:
+
+```json
+{
+    "success": true,
+    "message": "NFO files created successfully",
+    "files_created": ["tvshow.nfo", "S01E01.nfo", "S01E02.nfo"],
+    "images_downloaded": ["poster.jpg", "S01E01-thumb.jpg"]
+}
+```
+
+### 5.3 Update NFO Files
+
+**Endpoint**: `POST /api/nfo/update`
+
+**Request Body**:
+
+```json
+{
+    "anime_id": 123,
+    "folder_path": "/path/to/anime",
+    "force": false
+}
+```
+
+**Response**:
+
+```json
+{
+    "success": true,
+    "message": "NFO files updated successfully",
+    "files_updated": ["tvshow.nfo", "S01E01.nfo"]
+}
+```
+
+### 5.4 View NFO Content
+
+**Endpoint**: `GET /api/nfo/view`
+
+**Query Parameters**:
+
+- `file_path` (required): Absolute path to NFO file
+
+**Response**:
+
+```json
+{
+    "content": "<?xml version=\"1.0\"...?>",
+    "file_path": "/path/to/tvshow.nfo",
+    "exists": true
+}
+```
+
+### 5.5 Get Media Status
+
+**Endpoint**: `GET /api/nfo/media/status`
+
+**Query Parameters**:
+
+- `folder_path` (required): Absolute path to anime directory
+
+**Response**:
+
+```json
+{
+    "poster_exists": true,
+    "poster_path": "/path/to/poster.jpg",
+    "logo_exists": false,
+    "logo_path": null,
+    "fanart_exists": true,
+    "fanart_path": "/path/to/fanart.jpg",
+    "episode_thumbs": [
+        {
+            "season": 1,
+            "episode": 1,
+            "exists": true,
+            "path": "/path/to/S01E01-thumb.jpg"
+        }
+    ]
+}
+```
+
+### 5.6 Download Media
+
+**Endpoint**: `POST /api/nfo/media/download`
+
+**Request Body**:
+
+```json
+{
+    "folder_path": "/path/to/anime",
+    "anime_id": 123,
+    "download_poster": true,
+    "download_logo": false,
+    "download_fanart": false,
+    "image_size": "w500"
+}
+```
+
+**Response**:
+
+```json
+{
+    "success": true,
+    "message": "Media downloaded successfully",
+    "downloaded": ["poster.jpg", "S01E01-thumb.jpg"]
+}
+```
+
+### 5.7 Batch Create NFO
+
+**Endpoint**: `POST /api/nfo/batch/create`
+
+**Request Body**:
+
+```json
+{
+    "anime_ids": [123, 456, 789]
+}
+```
+
+**Response**:
+
+```json
+{
+    "success": true,
+    "results": [
+        {
+            "anime_id": 123,
+            "success": true,
+            "message": "Created successfully"
+        },
+        {
+            "anime_id": 456,
+            "success": false,
+            "error": "Folder not found"
+        }
+    ]
+}
+```
+
+### 5.8 Find Missing NFOs
+
+**Endpoint**: `GET /api/nfo/missing`
+
+**Response**:
+
+```json
+{
+    "anime_list": [
+        {
+            "anime_id": 123,
+            "title": "Attack on Titan",
+            "folder_path": "/path/to/anime/Attack on Titan",
+            "missing_tvshow_nfo": false,
+            "missing_episode_count": 3,
+            "total_episodes": 25
+        }
+    ]
+}
+```
+
+---
+
+## 6. Troubleshooting
+
+### 6.1 NFO Files Not Created
+
+**Problem**: NFO files are not being created during downloads.
+
+**Solutions**:
+
+1. Verify TMDB API key is configured correctly
+2. Check `auto_create` is enabled in settings
+3. Ensure anime directory has write permissions
+4. Check logs for error messages
+5. Test TMDB connection using "Test Connection" button
+
+### 6.2 Invalid TMDB API Key
+
+**Problem**: TMDB validation fails with "Invalid API key".
+
+**Solutions**:
+
+1. Verify API key is copied correctly (no extra spaces)
+2. Ensure you're using the v3 API key (not v4)
+3. Check API key is active on TMDB website
+4. Try regenerating API key on TMDB
+
+### 6.3 Images Not Downloading
+
+**Problem**: NFO files are created but images are missing.
+
+**Solutions**:
+
+1. Enable image downloads in settings (poster/logo/fanart)
+2. Verify TMDB API key is valid
+3. Check network connectivity to TMDB servers
+4. Ensure sufficient disk space
+5. Check file permissions in anime directory
+
+### 6.4 Incorrect Metadata
+
+**Problem**: NFO contains wrong show information.
+
+**Solutions**:
+
+1. Verify anime title matches TMDB exactly
+2. Use TMDB ID if available for accurate matching
+3. Update NFO files with `force=true` to refresh metadata
+4. Check TMDB website for correct show information
+
+### 6.5 Permission Errors
+
+**Problem**: "Permission denied" when creating NFO files.
+
+**Solutions**:
+
+1. Check anime directory permissions: `chmod 755 /path/to/anime`
+2. Ensure application user has write access
+3. Verify directory ownership: `chown -R user:group /path/to/anime`
+4. Check parent directories are accessible
+
+### 6.6 Slow NFO Creation
+
+**Problem**: NFO creation takes a long time.
+
+**Solutions**:
+
+1. Reduce image size (use w500 instead of original)
+2. Disable unnecessary images (logo, fanart)
+3. Create NFOs in batches during off-peak hours
+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
+
+### 7.1 Configuration Recommendations
+
+- **Image Size**: Use `w500` for optimal balance of quality and storage
+- **Auto-create**: Enable for new downloads
+- **Update on scan**: Disable to avoid unnecessary TMDB API calls
+- **Poster**: Always enable for show and episode thumbnails
+- **Logo/Fanart**: Enable only if your media server supports them
+
+### 7.2 Maintenance
+
+- **Regular Updates**: Update NFO files quarterly to get latest metadata
+- **Backup**: Include NFO files in your backup strategy
+- **Validation**: Periodically check missing NFOs using `/api/nfo/missing`
+- **API Rate Limits**: Be mindful of TMDB API rate limits when batch processing
+
+### 7.3 Performance
+
+- **Batch Operations**: Use batch endpoints for multiple anime
+- **Off-Peak Processing**: Create NFOs during low-activity periods
+- **Image Optimization**: Use smaller image sizes for large libraries
+- **Selective Updates**: Only update NFOs when metadata changes
+
+### 7.4 Media Server Integration
+
+#### Plex
+
+- Use "Personal Media Shows" agent
+- Enable "Local Media Assets" scanner
+- Place NFO files in anime directories
+- Refresh metadata after creating NFOs
+
+#### Jellyfin
+
+- Use "NFO" metadata provider
+- Enable in Library settings
+- Order providers: NFO first, then online sources
+- Scan library after NFO creation
+
+#### Emby
+
+- Enable "NFO" metadata reader
+- Configure in Library advanced settings
+- Use "Prefer embedded metadata" option
+- Refresh metadata after updates
+
+#### Kodi
+
+- NFO files are automatically detected
+- No additional configuration needed
+- Update library to see changes
+
+---
+
+## 8. Advanced Usage
+
+### 8.1 Custom NFO Templates
+
+You can customize NFO generation by modifying the NFO service:
+
+```python
+# src/core/services/nfo_creator.py
+def generate_tvshow_nfo(self, metadata: dict) -> str:
+    # Add custom fields or modify structure
+    pass
+```
+
+### 8.2 Bulk Operations
+
+Create NFOs for entire library:
+
+```bash
+# Get all anime without NFOs
+curl -X GET "http://127.0.0.1:8000/api/nfo/missing" \
+  -H "Authorization: Bearer $TOKEN" \
+  | jq -r '.anime_list[].anime_id' \
+  | xargs -I{} curl -X POST "http://127.0.0.1:8000/api/nfo/batch/create" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"anime_ids": [{}]}'
+```
+
+### 8.3 Scheduled Updates
+
+Use the scheduler API to refresh NFOs automatically:
+
+```bash
+# Schedule weekly NFO updates (rescan runs Sunday at 03:00)
+curl -X POST "http://127.0.0.1:8000/api/scheduler/config" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "schedule_time": "03:00",
+    "schedule_days": ["sun"],
+    "auto_download_after_rescan": false
+  }'
+```
+
+---
+
+## 9. Related Documentation
+
+- [API.md](API.md) - Complete API reference
+- [CONFIGURATION.md](CONFIGURATION.md) - All configuration options
+- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture
+- [DEVELOPMENT.md](DEVELOPMENT.md) - Development guide
+
+---
+
+## 10. Tag Reference
+
+The table below lists every XML tag written to `tvshow.nfo` and its source in
+the TMDB API response. All tags are written whenever the NFO is created or
+updated via `create_tvshow_nfo()` / `update_tvshow_nfo()`.
+
+| NFO tag         | TMDB source field                                     | Required |
+| --------------- | ----------------------------------------------------- | -------- |
+| `title`         | `name`                                                | ✅       |
+| `originaltitle` | `original_name`                                       | ✅       |
+| `showtitle`     | `name` (same as `title`)                              | ✅       |
+| `sorttitle`     | `name` (same as `title`)                              | ✅       |
+| `year`          | First 4 chars of `first_air_date`                     | ✅       |
+| `plot`          | `overview`                                            | ✅       |
+| `outline`       | `overview` (same as `plot`)                           | ✅       |
+| `tagline`       | `tagline`                                             | optional |
+| `runtime`       | `episode_run_time[0]`                                 | ✅       |
+| `premiered`     | `first_air_date`                                      | ✅       |
+| `status`        | `status`                                              | ✅       |
+| `mpaa`          | US content rating from `content_ratings.results`      | optional |
+| `fsk`           | DE content rating (written as `mpaa` when preferred)  | optional |
+| `imdbid`        | `external_ids.imdb_id`                                | ✅       |
+| `tmdbid`        | `id`                                                  | ✅       |
+| `tvdbid`        | `external_ids.tvdb_id`                                | optional |
+| `genre`         | `genres[].name` (one element per genre)               | ✅       |
+| `studio`        | `networks[].name` (one element per network)           | ✅       |
+| `country`       | `origin_country[]` or `production_countries[].name`   | ✅       |
+| `actor`         | `credits.cast[]` (top 10, with name/role/thumb)       | ✅       |
+| `watched`       | Always `false` on creation                            | ✅       |
+| `dateadded`     | System clock at creation time (`YYYY-MM-DD HH:MM:SS`) | ✅       |
+
+The mapping logic lives in `src/core/utils/nfo_mapper.py` (`tmdb_to_nfo_model`).
+The XML serialisation lives in `src/core/utils/nfo_generator.py`
+(`generate_tvshow_nfo`).
+
+---
+
+## 11. Automatic NFO Repair
+
+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
+   `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 `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)
+
+| XPath             | Tag name        |
+| ----------------- | --------------- |
+| `./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`       |
+
+### Log Messages
+
+| Message                                                     | Meaning                                           |
+| ----------------------------------------------------------- | ------------------------------------------------- |
+| `NFO repair scan complete: 0 of N series queued for repair` | All NFOs are complete — no action needed          |
+| `NFO repair scan complete: X of N series queued for repair` | X series had incomplete NFOs and have been queued |
+| `NFO repair scan skipped: TMDB API key not configured`      | Set `tmdb_api_key` in `data/config.json`          |
+| `NFO repair scan skipped: anime directory not configured`   | Set `anime_directory` in `data/config.json`       |
+
+### Triggering a Manual Repair
+
+You can also repair a single series on demand via the API:
+
+```http
+POST /api/nfo/update/{series_key}
+```
+
+This calls `NFOService.update_tvshow_nfo()` directly and overwrites the existing
+`tvshow.nfo` with fresh data from TMDB.
+
+### Source Files
+
+| File                                            | Purpose                                                                                        |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `src/core/services/nfo_repair_service.py`       | `REQUIRED_TAGS`, `parse_nfo_tags`, `find_missing_tags`, `nfo_needs_repair`, `NfoRepairService` |
+| `src/server/services/folder_scan_service.py`    | `perform_nfo_repair_scan` — invoked during the scheduled daily folder scan                     |
+
+---
+
+## 12. Support
+
+### Getting Help
+
+- Check logs in `logs/` directory for error details
+- Review [TESTING.md](TESTING.md) for test coverage
+- Consult [DATABASE.md](DATABASE.md) for NFO status schema
+
+### Common Issues
+
+See section 6 (Troubleshooting) for solutions to common problems.
+
+### TMDB Resources
+
+- TMDB API Documentation: https://developers.themoviedb.org/3
+- TMDB Support: https://www.themoviedb.org/talk
+- TMDB API Status: https://status.themoviedb.org/

docs/README.md

@@ -0,0 +1,39 @@
+# Aniworld Documentation
+
+## Overview
+
+This directory contains all documentation for the Aniworld anime download manager project.
+
+## Documentation Structure
+
+| Document                                 | Purpose                                        | Target Audience                    |
+| ---------------------------------------- | ---------------------------------------------- | ---------------------------------- |
+| [ARCHITECTURE.md](ARCHITECTURE.md)       | System architecture and design decisions       | Architects, Senior Developers      |
+| [API.md](API.md)                         | REST API reference and WebSocket documentation | Frontend Developers, API Consumers |
+| [DEVELOPMENT.md](DEVELOPMENT.md)         | Developer setup and contribution guide         | All Developers                     |
+| [DEPLOYMENT.md](DEPLOYMENT.md)           | Deployment and operations guide                | DevOps, System Administrators      |
+| [DATABASE.md](DATABASE.md)               | Database schema and data models                | Backend Developers                 |
+| [TESTING.md](TESTING.md)                 | Testing strategy and guidelines                | QA Engineers, Developers           |
+| [SECURITY.md](SECURITY.md)               | Security considerations and guidelines         | Security Engineers, All Developers |
+| [CONFIGURATION.md](CONFIGURATION.md)     | Configuration options reference                | Operators, Developers              |
+| [CHANGELOG.md](CHANGELOG.md)             | Version history and changes                    | All Stakeholders                   |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues and solutions                    | Support, Operators                 |
+| [features.md](features.md)               | Feature list and capabilities                  | Product Owners, Users              |
+| [instructions.md](instructions.md)       | AI agent development instructions              | AI Agents, Developers              |
+
+## Documentation Standards
+
+-   All documentation uses Markdown format
+-   Keep documentation up-to-date with code changes
+-   Include code examples where applicable
+-   Use clear, concise language
+-   Include diagrams for complex concepts (use Mermaid syntax)
+
+## Contributing to Documentation
+
+When adding or updating documentation:
+
+1. Follow the established format in each document
+2. Update the README.md if adding new documents
+3. Ensure cross-references are valid
+4. Review for spelling and grammar

docs/TESTING.md

@@ -0,0 +1,146 @@
+# Testing Documentation
+
+## Document Purpose
+
+This document describes the testing strategy, guidelines, and practices for the Aniworld project.
+
+### What This Document Contains
+
+-   **Testing Strategy**: Overall approach to quality assurance
+-   **Test Categories**: Unit, integration, API, performance, security tests
+-   **Test Structure**: Organization of test files and directories
+-   **Writing Tests**: Guidelines for writing effective tests
+-   **Fixtures and Mocking**: Shared test utilities and mock patterns
+-   **Running Tests**: Commands and configurations
+-   **Coverage Requirements**: Minimum coverage thresholds
+-   **CI/CD Integration**: How tests run in automation
+-   **Test Data Management**: Managing test fixtures and data
+-   **Best Practices**: Do's and don'ts for testing
+
+### What This Document Does NOT Contain
+
+-   Production deployment (see [DEPLOYMENT.md](DEPLOYMENT.md))
+-   Security audit procedures (see [SECURITY.md](SECURITY.md))
+-   Bug tracking and issue management
+-   Performance benchmarking results
+
+### Target Audience
+
+-   Developers writing tests
+-   QA Engineers
+-   CI/CD Engineers
+-   Code reviewers
+
+---
+
+## Sections to Document
+
+1. Testing Philosophy
+    - Test pyramid approach
+    - Quality gates
+2. Test Categories
+    - Unit Tests (`tests/unit/`)
+    - Integration Tests (`tests/integration/`)
+    - API Tests (`tests/api/`)
+    - Frontend Tests (`tests/frontend/`)
+    - Performance Tests (`tests/performance/`)
+    - Security Tests (`tests/security/`)
+3. Test Structure and Naming
+    - File naming conventions
+    - Test function naming
+    - Test class organization
+4. Running Tests
+    - pytest commands
+    - Running specific tests
+    - Verbose output
+    - Coverage reports
+5. Fixtures and Conftest
+    - Shared fixtures
+    - Database fixtures
+    - Mock services
+6. Mocking Guidelines
+    - 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
+    - Arrange-Act-Assert pattern
+    - Test isolation
+    - Edge cases
+10. Common Pitfalls to Avoid

docs/diagrams/README.md

@@ -0,0 +1,23 @@
+# Architecture Diagrams
+
+This directory contains architecture diagram source files for the Aniworld documentation.
+
+## Diagrams
+
+### System Architecture (Mermaid)
+
+See [system-architecture.mmd](system-architecture.mmd) for the system overview diagram.
+
+### Rendering
+
+Diagrams can be rendered using:
+
+-   Mermaid Live Editor: https://mermaid.live/
+-   VS Code Mermaid extension
+-   GitHub/GitLab native Mermaid support
+
+## Formats
+
+-   `.mmd` - Mermaid diagram source files
+-   `.svg` - Exported vector graphics (add when needed)
+-   `.png` - Exported raster graphics (add when needed)

docs/diagrams/download-flow.mmd

@@ -0,0 +1,44 @@
+%%{init: {'theme': 'base'}}%%
+sequenceDiagram
+    participant Client
+    participant FastAPI
+    participant AuthMiddleware
+    participant DownloadService
+    participant ProgressService
+    participant WebSocketService
+    participant SeriesApp
+    participant Database
+
+    Note over Client,Database: Download Flow
+
+    %% Add to queue
+    Client->>FastAPI: POST /api/queue/add
+    FastAPI->>AuthMiddleware: Validate JWT
+    AuthMiddleware-->>FastAPI: OK
+    FastAPI->>DownloadService: add_to_queue()
+    DownloadService->>Database: save_item()
+    Database-->>DownloadService: item_id
+    DownloadService-->>FastAPI: [item_ids]
+    FastAPI-->>Client: 201 Created
+
+    %% Start queue
+    Client->>FastAPI: POST /api/queue/start
+    FastAPI->>AuthMiddleware: Validate JWT
+    AuthMiddleware-->>FastAPI: OK
+    FastAPI->>DownloadService: start_queue_processing()
+    
+    loop For each pending item
+        DownloadService->>SeriesApp: download_episode()
+        
+        loop Progress updates
+            SeriesApp->>ProgressService: emit("progress_updated")
+            ProgressService->>WebSocketService: broadcast_to_room()
+            WebSocketService-->>Client: WebSocket message
+        end
+        
+        SeriesApp-->>DownloadService: completed
+        DownloadService->>Database: update_status()
+    end
+    
+    DownloadService-->>FastAPI: OK
+    FastAPI-->>Client: 200 OK

docs/diagrams/system-architecture.mmd

@@ -0,0 +1,88 @@
+%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#4a90d9'}}}%%
+flowchart TB
+    subgraph Clients["Client Layer"]
+        Browser["Web Browser<br/>(HTML/CSS/JS)"]
+        CLI["CLI Client<br/>(Main.py)"]
+    end
+
+    subgraph Server["Server Layer (FastAPI)"]
+        direction TB
+        Middleware["Middleware<br/>Auth, Rate Limit, Error Handler"]
+        
+        subgraph API["API Routers"]
+            AuthAPI["/api/auth"]
+            AnimeAPI["/api/anime"]
+            QueueAPI["/api/queue"]
+            ConfigAPI["/api/config"]
+            SchedulerAPI["/api/scheduler"]
+            HealthAPI["/health"]
+            WebSocketAPI["/ws"]
+        end
+        
+        subgraph Services["Services"]
+            AuthService["AuthService"]
+            AnimeService["AnimeService"]
+            DownloadService["DownloadService"]
+            ConfigService["ConfigService"]
+            ProgressService["ProgressService"]
+            WebSocketService["WebSocketService"]
+        end
+    end
+
+    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")]
+        ConfigJSON[(config.json)]
+        FileSystem[(File System<br/>Anime Episodes)]
+        LegacyFiles[("Legacy Files<br/>key/data<br/>(Deprecated)")]
+    end
+
+    subgraph External["External"]
+        Provider["Anime Provider<br/>(aniworld.to)"]
+    end
+
+    %% Client connections
+    Browser -->|HTTP/WebSocket| Middleware
+    CLI -->|Direct| SeriesApp
+
+    %% Middleware to API
+    Middleware --> API
+
+    %% API to Services
+    AuthAPI --> AuthService
+    AnimeAPI --> AnimeService
+    QueueAPI --> DownloadService
+    ConfigAPI --> ConfigService
+    SchedulerAPI --> AnimeService
+    WebSocketAPI --> WebSocketService
+
+    %% Services to Core
+    AnimeService --> SeriesApp
+    DownloadService --> SeriesApp
+
+    %% Services to Data
+    AuthService --> ConfigJSON
+    ConfigService --> ConfigJSON
+    DownloadService --> SQLite
+    AnimeService --> SQLite
+
+    %% Core to Data
+    SeriesApp --> SeriesCache
+    SeriesCache -.->|Cached Series| SQLite
+    SeriesApp --> SerieScanner
+    SeriesApp --> SerieList
+    SerieScanner -->|Scan Episodes| FileSystem
+    SerieScanner -->|Detect Series| SQLite
+    SerieScanner -->|Migrate Legacy| LegacyFiles
+    SerieScanner --> Provider
+
+    %% Event flow
+    ProgressService -.->|Events| WebSocketService
+    DownloadService -.->|Progress| ProgressService
+    WebSocketService -.->|Broadcast| Browser

docs/features.md

@@ -0,0 +1,118 @@
+# Aniworld Web Application Features
+
+## Recent Updates
+
+### Enhanced Setup and Settings Pages (Latest)
+
+The application now features a comprehensive configuration system that allows users to configure all settings during initial setup or modify them later through the settings modal:
+
+**Setup Page Enhancements:**
+
+- Single-page setup with all configuration options organized into clear sections
+- Real-time password strength indicator for security
+- Form validation with helpful error messages
+- Comprehensive settings including: general, security, scheduler, logging, backup, and NFO metadata
+
+**Settings Modal Enhancements:**
+
+- All configuration fields are now editable through the main application's config modal
+- Organized into logical sections with clear labels and help text
+- Real-time saving with immediate feedback
+- Configuration validation to prevent invalid settings
+- Full control over cron-based scheduler (time, days of week, auto-download), logging options, and backup settings
+
+---
+
+## Authentication & Security
+
+- **Master Password Login**: Secure access to the application with a master password system
+- **JWT Token Sessions**: Stateless authentication with JSON Web Tokens
+- **Rate Limiting**: Built-in protection against brute force attacks
+
+## Configuration Management
+
+- **Enhanced Setup Page**: Comprehensive initial configuration interface with all settings in one place:
+    - General Settings: Application name and data directory configuration
+    - Security Settings: Master password setup with strength indicator
+    - Anime Directory: Primary directory path for anime storage
+    - Scheduler Settings: Enable/disable scheduler, configure daily run time, select days of week, and optionally auto-download missing episodes after rescan
+    - Logging Settings: Configure log level, file path, file size limits, and backup count
+    - Backup Settings: Enable automatic backups with configurable path and retention period
+    - NFO Settings: TMDB API key, auto-creation options, and media file download preferences
+- **Enhanced Settings/Config Modal**: Comprehensive configuration interface accessible from main page:
+    - General Settings: Edit application name and data directory
+    - Anime Directory: Modify anime storage location with browse functionality
+    - Scheduler Configuration: Enable/disable, set cron run time (`HH:MM`), select active days of the week, and toggle auto-download after rescan
+    - Logging Configuration: Full control over logging level, file rotation, and backup count
+    - Backup Configuration: Configure automatic backup settings including path and retention
+    - NFO Settings: Complete control over TMDB integration and media file downloads
+    - Configuration Validation: Validate configuration for errors before saving
+    - Backup Management: Create, restore, and manage configuration backups
+    - Export/Import: Export configuration for backup or transfer to another instance
+
+## User Interface
+
+- **Dark Mode**: Toggle between light and dark themes for better user experience
+- **Responsive Design**: Mobile-friendly interface with touch support
+- **Real-time Updates**: WebSocket-based live notifications and progress tracking
+
+## 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
+- **Anime Search**: Search for anime series using integrated providers
+- **Library Scanning**: Automated scanning for missing episodes with database persistence
+- **Episode Tracking**: Missing episodes tracked in database, automatically updated during scans
+- **NFO Status Indicators**: Visual badges showing NFO and media file status for each series
+
+## NFO Metadata Management
+
+- **TMDB Integration**: Automatic metadata fetching from The Movie Database (TMDB)
+- **Auto-Create NFO Files**: Automatically generate tvshow.nfo files during downloads
+- **Media File Downloads**: Automatic download of poster.jpg, logo.png, and fanart.jpg
+- **NFO Status Tracking**: Database tracking of NFO creation and update timestamps
+- **Manual NFO Creation**: Create NFO files and download media for existing anime
+- **NFO Updates**: Update existing NFO files with latest TMDB metadata
+- **Batch Operations**: Create NFO files for multiple anime at once
+- **NFO Content Viewing**: View generated NFO file content in the UI
+- **Media Server Compatibility**: Kodi, Plex, Jellyfin, and Emby compatible format
+- **Configuration Options**: Customize which media files to download and image quality
+
+## Download Management
+
+- **Download Queue Page**: View and manage the current download queue with organized sections
+- **Queue Organization**: Displays downloads organized by status (pending, active, completed, failed)
+- **NFO Integration**: Automatic NFO and media file creation before episode downloads
+- **Manual Start/Stop Control**: User manually starts downloads one at a time with Start/Stop buttons
+- **FIFO Queue Processing**: First-in, first-out queue order (no priority or reordering)
+- **Single Download Mode**: Only one download active at a time, new downloads must be manually started
+- **Download Status Display**: Real-time status updates and progress of current download
+- **Queue Operations**: Add and remove items from the pending queue
+- **Completed Downloads List**: Separate section for completed downloads with clear button
+- **Failed Downloads List**: Separate section for failed downloads with retry and clear options
+- **Retry Failed Downloads**: Automatically retry failed downloads with configurable limits
+- **Clear Completed**: Remove completed downloads from the queue
+- **Clear Failed**: Remove failed downloads from the queue
+- **Queue Statistics**: Real-time counters for pending, active, completed, and failed items
+
+## Real-time Communication
+
+- **WebSocket Support**: Real-time notifications for download progress and queue updates
+- **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.
+
+**NFO Metadata Features**: The application now includes full support for generating Kodi/Plex/Jellyfin/Emby compatible metadata files (tvshow.nfo) with automatic TMDB integration. NFO files are created automatically during downloads or can be managed manually through the UI. The system tracks NFO status in the database and provides comprehensive API endpoints for programmatic access. Media files (poster, logo, fanart) are automatically downloaded based on configuration settings.

docs/instructions.md

@@ -0,0 +1,119 @@
+# Aniworld Web Application Development Instructions
+
+This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.
+
+## Project Overview
+
+The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.
+
+## Architecture Principles
+
+- **Single Responsibility**: Each file/class has one clear purpose
+- **Dependency Injection**: Use FastAPI's dependency system
+- **Clean Separation**: Web layer calls core logic, never the reverse
+- **File Size Limit**: Maximum 500 lines per file
+- **Type Hints**: Use comprehensive type annotations
+- **Error Handling**: Proper exception handling and logging
+
+## Additional Implementation Guidelines
+
+### Code Style and Standards
+
+- **Type Hints**: Use comprehensive type annotations throughout all modules
+- **Docstrings**: Follow PEP 257 for function and class documentation
+- **Error Handling**: Implement custom exception classes with meaningful messages
+- **Logging**: Use structured logging with appropriate log levels
+- **Security**: Validate all inputs and sanitize outputs
+- **Performance**: Use async/await patterns for I/O operations
+
+## 📞 Escalation
+
+If you encounter:
+
+- Architecture issues requiring design decisions
+- Tests that conflict with documented requirements
+- Breaking changes needed
+- Unclear requirements or expectations
+
+**Document the issue and escalate rather than guessing.**
+
+---
+
+## <20> Credentials
+
+**Admin Login:**
+
+- Username: `admin`
+- Password: `Hallo123!`
+
+---
+
+## <20>📚 Helpful Commands
+
+```bash
+# Run all tests
+conda run -n AniWorld python -m pytest tests/ -v --tb=short
+
+# Run specific test file
+conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py -v
+
+# Run specific test class
+conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService -v
+
+# Run specific test
+conda run -n AniWorld python -m pytest tests/unit/test_websocket_service.py::TestWebSocketService::test_broadcast_download_progress -v
+
+# Run with extra verbosity
+conda run -n AniWorld python -m pytest tests/ -vv
+
+# Run with full traceback
+conda run -n AniWorld python -m pytest tests/ -v --tb=long
+
+# Run and stop at first failure
+conda run -n AniWorld python -m pytest tests/ -v -x
+
+# Run tests matching pattern
+conda run -n AniWorld python -m pytest tests/ -v -k "auth"
+
+# Show all print statements
+conda run -n AniWorld python -m pytest tests/ -v -s
+
+#Run app
+conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
+```
+
+---
+
+## Implementation Notes
+
+1. **Incremental Development**: Implement features incrementally, testing each component thoroughly before moving to the next
+2. **Code Review**: Review all generated code for adherence to project standards
+3. **Documentation**: Document all public APIs and complex logic
+4. **Testing**: Maintain test coverage above 80% for all new code
+5. **Performance**: Profile and optimize critical paths, especially download and streaming operations
+6. **Security**: Regular security audits and dependency updates
+7. **Monitoring**: Implement comprehensive monitoring and alerting
+8. **Maintenance**: Plan for regular maintenance and updates
+
+---
+
+## Task Completion Checklist
+
+For each task completed:
+
+- [ ] Implementation follows coding standards
+- [ ] Unit tests written and passing
+- [ ] Integration tests passing
+- [ ] Documentation updated
+- [ ] Error handling implemented
+- [ ] Logging added
+- [ ] Security considerations addressed
+- [ ] Performance validated
+- [ ] Code reviewed
+- [ ] Task marked as complete in instructions.md
+- [ ] Infrastructure.md updated and other docs
+- [ ] Changes committed to git; keep your messages in git short and clear
+- [ ] Take the next task
+
+---
+

docs/key

@@ -0,0 +1,51 @@
+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.

features.md

@@ -1,24 +0,0 @@
-# Aniworld Web Application Features
-
-## Authentication & Security
-- **Master Password Login**: Secure access to the application with a master password system
-
-## Configuration Management
-- **Setup Page**: Initial configuration interface for server setup and basic settings
-- **Config Page**: View and modify application configuration settings
-
-## User Interface
-- **Dark Mode**: Toggle between light and dark themes for better user experience
-
-## Anime Management
-- **Anime Library Page**: Display list of anime series with missing episodes
-- **Series Selection**: Select individual anime series and add episodes to download queue
-- **Anime Search Page**: Search functionality to find and add new anime series to the library
-
-## Download Management
-- **Download Queue Page**: View and manage the current download queue
-- **Download Status Display**: Real-time status updates and progress of current downloads
-- **Queue Operations**: Add, remove, and prioritize items in the download queue
-
-## 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.

instructions.md

@@ -1,601 +0,0 @@
-# Aniworld Web Application Development Instructions
-
-This document provides detailed tasks for AI agents to implement a modern web application for the Aniworld anime download manager. All tasks should follow the coding guidelines specified in the project's copilot instructions.
-
-## Project Overview
-
-The goal is to create a FastAPI-based web application that provides a modern interface for the existing Aniworld anime download functionality. The core anime logic should remain in `SeriesApp.py` while the web layer provides REST API endpoints and a responsive UI.
-
-## Architecture Principles
-
--   **Single Responsibility**: Each file/class has one clear purpose
--   **Dependency Injection**: Use FastAPI's dependency system
--   **Clean Separation**: Web layer calls core logic, never the reverse
--   **File Size Limit**: Maximum 500 lines per file
--   **Type Hints**: Use comprehensive type annotations
--   **Error Handling**: Proper exception handling and logging
-
-## Implementation Order
-
-The tasks should be completed in the following order to ensure proper dependencies and logical progression:
-
-1. **Project Structure Setup** - Foundation and dependencies
-2. **Authentication System** - Security layer implementation
-3. **Configuration Management** - Settings and config handling
-4. **Anime Management Integration** - Core functionality wrapper
-5. **Download Queue Management** - Queue handling and persistence
-6. **WebSocket Real-time Updates** - Real-time communication
-7. **Frontend Integration** - Integrate existing frontend assets
-8. **Core Logic Integration** - Enhance existing core functionality
-9. **Database Layer** - Data persistence and management
-10. **Testing** - Comprehensive test coverage
-11. **Deployment and Configuration** - Production setup
-12. **Documentation and Error Handling** - Final documentation and error handling
-
-# make the following steps for each task or subtask. make sure you do not miss one
-
-1.  Task the next task
-2.  Process the task
-3.  Make Tests.
-4.  Remove task from instructions.md.
-5.  Update infrastructure.md, but only add text that belongs to a infrastructure doc. make sure to summarize text or delete text that do not belog to infrastructure.md. Keep it clear and short.
-6.  Commit in git
-
-## Core Tasks
-
-### 7. Frontend Integration
-
-#### [] Integrate existing CSS styling
-
--   []Review and integrate existing CSS files in `src/server/web/static/css/`
--   []Ensure styling works with FastAPI static file serving
--   []Maintain existing responsive design and theme support
--   []Update any hardcoded paths if necessary
-
-#### [] Update frontend-backend integration
-
--   []Ensure existing JavaScript calls match new API endpoints
--   []Update authentication flow to work with new auth system
--   []Verify WebSocket events match new service implementations
--   []Test all existing UI functionality with new backend
-
-### 8. Core Logic Integration
-
-#### [] Enhance SeriesApp for web integration
-
--   []Update `src/core/SeriesApp.py`
--   []Add async callback support
--   []Implement progress reporting
--   []Include better error handling
--   []Add cancellation support
-
-#### [] Create progress callback system
-
--   []Add progress callback interface
--   []Implement scan progress reporting
--   []Add download progress tracking
--   []Include error/completion callbacks
-
-#### [] Add configuration persistence
-
--   []Implement configuration file management
--   []Add settings validation
--   []Include backup/restore functionality
--   []Add migration support for config updates
-
-### 9. Database Layer
-
-#### [] Implement database models
-
--   []Create `src/server/database/models.py`
--   []Add SQLAlchemy models for anime series
--   []Implement download queue persistence
--   []Include user session storage
-
-#### [] Create database service
-
--   []Create `src/server/database/service.py`
--   []Add CRUD operations for anime data
--   []Implement queue persistence
--   []Include database migration support
-
-#### [] Add database initialization
-
--   []Create `src/server/database/init.py`
--   []Implement database setup
--   []Add initial data migration
--   []Include schema validation
-
-### 10. Testing
-
-#### [] Create unit tests for services
-
--   []Create `tests/unit/test_auth_service.py`
--   []Create `tests/unit/test_anime_service.py`
--   []Create `tests/unit/test_download_service.py`
--   []Create `tests/unit/test_config_service.py`
-
-#### [] Create API endpoint tests
-
--   []Create `tests/api/test_auth_endpoints.py`
--   []Create `tests/api/test_anime_endpoints.py`
--   []Create `tests/api/test_download_endpoints.py`
--   []Create `tests/api/test_config_endpoints.py`
-
-#### [] Create integration tests
-
--   []Create `tests/integration/test_download_flow.py`
--   []Create `tests/integration/test_auth_flow.py`
--   []Create `tests/integration/test_websocket.py`
-
-#### [] Create frontend integration tests
-
--   []Create `tests/frontend/test_existing_ui_integration.py`
--   []Test existing JavaScript functionality with new backend
--   []Verify WebSocket connections and real-time updates
--   []Test authentication flow with existing frontend
-
-### 11. Deployment and Configuration
-
-#### [] Create production configuration
-
--   []Create `src/server/config/production.py`
--   []Add environment variable handling
--   []Include security settings
--   []Add performance optimizations
-
-#### [] Create startup scripts
-
--   []Create `scripts/start.sh`
--   []Create `scripts/setup.py`
--   []Add dependency installation
--   []Include database initialization
-
-### 12. Documentation and Error Handling
-
-#### [] Create API documentation
-
--   []Add OpenAPI/Swagger documentation
--   []Include endpoint descriptions
--   []Add request/response examples
--   []Include authentication details
-
-#### [] Implement comprehensive error handling
-
--   []Create custom exception classes
--   []Add error logging and tracking
--   []Implement user-friendly error messages
--   []Include error recovery mechanisms
-
-#### [] Create user documentation
-
--   []Create `docs/user_guide.md`
--   []Add installation instructions
--   []Include configuration guide
--   []Add troubleshooting section
-
-## File Size Guidelines
-
--   []**Models**: Max 200 lines each
--   []**Services**: Max 450 lines each
--   []**API Endpoints**: Max 350 lines each
--   []**Templates**: Max 400 lines each
--   []**JavaScript**: Max 500 lines each
--   []**CSS**: Max 500 lines each
--   []**Tests**: Max 400 lines each
-
-## Existing Frontend Assets
-
-The following frontend assets already exist and should be integrated:
-
--   []**Templates**: Located in `src/server/web/templates/`
--   []**JavaScript**: Located in `src/server/web/static/js/` (app.js, queue.js, etc.)
--   []**CSS**: Located in `src/server/web/static/css/`
--   []**Static Assets**: Images and other assets in `src/server/web/static/`
-
-When working with these files:
-
--   []Review existing functionality before making changes
--   []Maintain existing UI/UX patterns and design
--   []Update API calls to match new FastAPI endpoints
--   []Preserve existing WebSocket event handling
--   []Keep existing theme and responsive design features
-
-## Quality Assurance
-
-#### [] Code quality checks
-
--   []Run linting with flake8/pylint
--   []Check type hints with mypy
--   []Validate formatting with black
--   []Run security checks with bandit
-
-#### [] Performance testing
-
--   []Load test API endpoints
--   []Test WebSocket connection limits
--   []Validate download performance
--   []Check memory usage patterns
-
-#### [] Security validation
-
--   []Test authentication bypass attempts
--   []Validate input sanitization
--   []Check for injection vulnerabilities
--   []Test session management security
-
-Each task should be implemented with proper error handling, logging, and type hints according to the project's coding standards.
-
-## Additional Implementation Guidelines
-
-### Code Style and Standards
-
--   **Type Hints**: Use comprehensive type annotations throughout all modules
--   **Docstrings**: Follow PEP 257 for function and class documentation
--   **Error Handling**: Implement custom exception classes with meaningful messages
--   **Logging**: Use structured logging with appropriate log levels
--   **Security**: Validate all inputs and sanitize outputs
--   **Performance**: Use async/await patterns for I/O operations
-
-### Monitoring and Health Checks
-
-#### [] Implement health check endpoints
-
--   []Create `src/server/api/health.py`
--   []Add GET `/health` - basic health check
--   []Add GET `/health/detailed` - comprehensive system status
--   []Include dependency checks (database, file system)
--   []Add performance metrics
-
-#### [] Create monitoring service
-
--   []Create `src/server/services/monitoring_service.py`
--   []Implement system resource monitoring
--   []Add download queue metrics
--   []Include error rate tracking
--   []Add performance benchmarking
-
-#### [] Add metrics collection
-
--   []Create `src/server/utils/metrics.py`
--   []Implement Prometheus metrics export
--   []Add custom business metrics
--   []Include request timing and counts
--   []Add download success/failure rates
-
-### Advanced Features
-
-#### [] Implement backup and restore
-
--   []Create `src/server/services/backup_service.py`
--   []Add configuration backup/restore
--   []Implement anime data export/import
--   []Include download history preservation
--   []Add scheduled backup functionality
-
-#### [] Create notification system
-
--   []Create `src/server/services/notification_service.py`
--   []Implement email notifications for completed downloads
--   []Add webhook support for external integrations
--   []Include in-app notification system
--   []Add notification preference management
-
-#### [] Add analytics and reporting
-
--   []Create `src/server/services/analytics_service.py`
--   []Implement download statistics
--   []Add series popularity tracking
--   []Include storage usage analysis
--   []Add performance reports
-
-### Maintenance and Operations
-
-#### [] Create maintenance endpoints
-
--   []Create `src/server/api/maintenance.py`
--   []Add POST `/api/maintenance/cleanup` - cleanup temporary files
--   []Add POST `/api/maintenance/rebuild-index` - rebuild search index
--   []Add GET `/api/maintenance/stats` - system statistics
--   []Add POST `/api/maintenance/vacuum` - database maintenance
-
-#### [] Implement log management
-
--   []Create `src/server/utils/log_manager.py`
--   []Add log rotation and archival
--   []Implement log level management
--   []Include log search and filtering
--   []Add log export functionality
-
-#### [] Create system utilities
-
--   []Create `src/server/utils/system.py`
--   []Add disk space monitoring
--   []Implement file system cleanup
--   []Include process management utilities
--   []Add system information gathering
-
-### Security Enhancements
-
-#### [] Implement rate limiting
-
--   []Create `src/server/middleware/rate_limit.py`
--   []Add endpoint-specific rate limits
--   []Implement IP-based limiting
--   []Include user-based rate limiting
--   []Add bypass mechanisms for authenticated users
-
-#### [] Add security headers
-
--   []Create `src/server/middleware/security.py`
--   []Implement CORS headers
--   []Add CSP headers
--   []Include security headers (HSTS, X-Frame-Options)
--   []Add request sanitization
-
-#### [] Create audit logging
-
--   []Create `src/server/services/audit_service.py`
--   []Log all authentication attempts
--   []Track configuration changes
--   []Monitor download activities
--   []Include user action tracking
-
-### Data Management
-
-#### [] Implement data validation
-
--   []Create `src/server/utils/validators.py`
--   []Add Pydantic custom validators
--   []Implement business rule validation
--   []Include data integrity checks
--   []Add format validation utilities
-
-#### [] Create data migration tools
-
--   []Create `src/server/database/migrations/`
--   []Add database schema migration scripts
--   []Implement data transformation tools
--   []Include rollback mechanisms
--   []Add migration validation
-
-#### [] Add caching layer
-
--   []Create `src/server/services/cache_service.py`
--   []Implement Redis caching
--   []Add in-memory caching for frequent data
--   []Include cache invalidation strategies
--   []Add cache performance monitoring
-
-### Integration Enhancements
-
-#### [] Extend provider system
-
--   []Enhance `src/core/providers/` for better web integration
--   []Add provider health monitoring
--   []Implement provider failover mechanisms
--   []Include provider performance tracking
--   []Add dynamic provider configuration
-
-#### [] Create plugin system
-
--   []Create `src/server/plugins/`
--   []Add plugin loading and management
--   []Implement plugin API
--   []Include plugin configuration
--   []Add plugin security validation
-
-#### [] Add external API integrations
-
--   []Create `src/server/integrations/`
--   []Add anime database API connections
--   []Implement metadata enrichment services
--   []Include content recommendation systems
--   []Add external notification services
-
-### Advanced Testing
-
-#### [] Performance testing
-
--   []Create `tests/performance/`
--   []Add load testing for API endpoints
--   []Implement stress testing for download system
--   []Include memory leak detection
--   []Add concurrency testing
-
-#### [] Security testing
-
--   []Create `tests/security/`
--   []Add penetration testing scripts
--   []Implement vulnerability scanning
--   []Include authentication bypass testing
--   []Add input validation testing
-
-#### [] End-to-end testing
-
--   []Create `tests/e2e/`
--   []Add full workflow testing
--   []Implement UI automation tests
--   []Include cross-browser testing
--   []Add mobile responsiveness testing
-
-### Deployment Strategies
-
-#### [] Container orchestration
-
--   []Create `kubernetes/` directory
--   []Add Kubernetes deployment manifests
--   []Implement service discovery
--   []Include load balancing configuration
--   []Add auto-scaling policies
-
-#### [] CI/CD pipeline
-
--   []Create `.github/workflows/`
--   []Add automated testing pipeline
--   []Implement deployment automation
--   []Include security scanning
--   []Add performance benchmarking
-
-#### [] Environment management
-
--   []Create environment-specific configurations
--   []Add secrets management
--   []Implement feature flags
--   []Include environment validation
--   []Add rollback mechanisms
-
-## Implementation Best Practices
-
-### Error Handling Patterns
-
-```python
-# Custom exception hierarchy
-class AniWorldException(Exception):
-    """Base exception for AniWorld application"""
-    pass
-
-class AuthenticationError(AniWorldException):
-    """Authentication related errors"""
-    pass
-
-class DownloadError(AniWorldException):
-    """Download related errors"""
-    pass
-
-# Service-level error handling
-async def download_episode(episode_id: str) -> DownloadResult:
-    try:
-        result = await downloader.download(episode_id)
-        return result
-    except ProviderError as e:
-        logger.error(f"Provider error downloading {episode_id}: {e}")
-        raise DownloadError(f"Failed to download episode: {e}")
-    except Exception as e:
-        logger.exception(f"Unexpected error downloading {episode_id}")
-        raise DownloadError("Unexpected download error")
-```
-
-### Logging Standards
-
-```python
-import logging
-import structlog
-
-# Configure structured logging
-structlog.configure(
-    processors=[
-        structlog.stdlib.add_log_level,
-        structlog.stdlib.add_logger_name,
-        structlog.processors.TimeStamper(fmt="iso"),
-        structlog.processors.JSONRenderer()
-    ],
-    wrapper_class=structlog.stdlib.BoundLogger,
-    logger_factory=structlog.stdlib.LoggerFactory(),
-    cache_logger_on_first_use=True,
-)
-
-logger = structlog.get_logger(__name__)
-
-# Usage examples
-logger.info("Download started", episode_id=episode_id, user_id=user_id)
-logger.error("Download failed", episode_id=episode_id, error=str(e))
-```
-
-### API Response Patterns
-
-```python
-from pydantic import BaseModel
-from typing import Optional, List, Any
-
-class APIResponse(BaseModel):
-    success: bool
-    message: Optional[str] = None
-    data: Optional[Any] = None
-    errors: Optional[List[str]] = None
-
-class PaginatedResponse(APIResponse):
-    total: int
-    page: int
-    per_page: int
-    pages: int
-
-# Usage in endpoints
-@router.get("/anime", response_model=PaginatedResponse)
-async def list_anime(page: int = 1, per_page: int = 20):
-    try:
-        anime_list, total = await anime_service.list_anime(page, per_page)
-        return PaginatedResponse(
-            success=True,
-            data=anime_list,
-            total=total,
-            page=page,
-            per_page=per_page,
-            pages=(total + per_page - 1) // per_page
-        )
-    except Exception as e:
-        logger.exception("Failed to list anime")
-        return APIResponse(
-            success=False,
-            message="Failed to retrieve anime list",
-            errors=[str(e)]
-        )
-```
-
-### Dependency Injection Patterns
-
-```python
-from fastapi import Depends
-from typing import Annotated
-
-# Service dependencies
-def get_anime_service() -> AnimeService:
-    return AnimeService()
-
-def get_download_service() -> DownloadService:
-    return DownloadService()
-
-# Dependency annotations
-AnimeServiceDep = Annotated[AnimeService, Depends(get_anime_service)]
-DownloadServiceDep = Annotated[DownloadService, Depends(get_download_service)]
-
-# Usage in endpoints
-@router.post("/download")
-async def start_download(
-    request: DownloadRequest,
-    download_service: DownloadServiceDep,
-    anime_service: AnimeServiceDep
-):
-    # Implementation
-    pass
-```
-
-## Final Implementation Notes
-
-1. **Incremental Development**: Implement features incrementally, testing each component thoroughly before moving to the next
-2. **Code Review**: Review all generated code for adherence to project standards
-3. **Documentation**: Document all public APIs and complex logic
-4. **Testing**: Maintain test coverage above 80% for all new code
-5. **Performance**: Profile and optimize critical paths, especially download and streaming operations
-6. **Security**: Regular security audits and dependency updates
-7. **Monitoring**: Implement comprehensive monitoring and alerting
-8. **Maintenance**: Plan for regular maintenance and updates
-
-## Task Completion Checklist
-
-For each task completed:
-
--   [ ] Implementation follows coding standards
--   [ ] Unit tests written and passing
--   [ ] Integration tests passing
--   [ ] Documentation updated
--   [ ] Error handling implemented
--   [ ] Logging added
--   [ ] Security considerations addressed
--   [ ] Performance validated
--   [ ] Code reviewed
--   [ ] Task marked as complete in instructions.md
--   [ ] Infrastructure.md updated
--   [ ] Changes committed to git
-
-This comprehensive guide ensures a robust, maintainable, and scalable anime download management system with modern web capabilities.

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "aniworld-web",
+  "version": "1.4.7",
+  "description": "Aniworld Anime Download Manager - Web Frontend",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed",
+    "test:e2e:debug": "playwright test --debug",
+    "playwright:install": "playwright install --with-deps chromium"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.41.0",
+    "@vitest/coverage-v8": "^1.2.0",
+    "@vitest/ui": "^1.2.0",
+    "happy-dom": "^13.3.5",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

requirements.txt

@@ -9,6 +9,20 @@ passlib[bcrypt]==1.7.4
 aiofiles==23.2.1
 websockets==12.0
 structlog==24.1.0
+psutil==5.9.6
 pytest==7.4.3
 pytest-asyncio==0.21.1
-httpx==0.25.2
+httpx==0.25.2
+sqlalchemy>=2.0.35
+aiosqlite>=0.19.0
+aiohttp>=3.9.0
+lxml>=5.0.0
+pillow>=10.0.0
+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

run_server.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+Startup script for the Aniworld FastAPI application.
+
+This script starts the application with proper logging configuration
+and graceful shutdown support via Ctrl+C (SIGINT) or SIGTERM.
+"""
+import uvicorn
+
+from src.infrastructure.logging.uvicorn_config import get_uvicorn_log_config
+
+if __name__ == "__main__":
+    # Get logging configuration
+    log_config = get_uvicorn_log_config()
+    
+    # Run the application with logging.
+    # Only watch .py files in src/, explicitly exclude __pycache__.
+    # This prevents reload loops from .pyc compilation.
+    #
+    # Graceful shutdown:
+    # - Ctrl+C (SIGINT) or SIGTERM triggers graceful shutdown
+    # - timeout_graceful_shutdown ensures shutdown completes within 30s
+    # - The FastAPI lifespan handler orchestrates cleanup in proper order
+    uvicorn.run(
+        "src.server.fastapi_app:app",
+        host="127.0.0.1",
+        port=8000,
+        reload=True,
+        reload_dirs=["src"],
+        reload_includes=["*.py"],
+        reload_excludes=["*/__pycache__/*", "*.pyc"],
+        log_config=log_config,
+        timeout_graceful_shutdown=30,  # Allow 30s for graceful shutdown
+    )

server/__init__.py

@@ -1,14 +0,0 @@
-"""Package shim: expose `server` package from `src/server`.
-
-This file inserts the actual `src/server` directory into this package's
-`__path__` so imports like `import server.models.auth` will resolve to
-the code under `src/server` during tests.
-"""
-import os
-
-_HERE = os.path.dirname(__file__)
-_SRC_SERVER = os.path.normpath(os.path.join(_HERE, "..", "src", "server"))
-
-# Prepend the real src/server directory to the package __path__ so
-# normal imports resolve to the source tree.
-__path__.insert(0, _SRC_SERVER)

src/cli/Main.py

@@ -1,229 +0,0 @@
-import sys
-import os
-import logging
-from ..core.providers import aniworld_provider
-
-from rich.progress import Progress
-from ..core.entities import SerieList
-from ..core.SerieScanner import SerieScanner
-from ..core.providers.provider_factory import Loaders
-from ..core.entities.series import Serie
-import time
-
-# Configure logging
-logging.basicConfig(level=logging.FATAL, format='%(asctime)s - %(levelname)s - %(funcName)s - %(message)s')
-console_handler = logging.StreamHandler()
-console_handler.setLevel(logging.ERROR)
-console_handler.setFormatter(logging.Formatter(
-    "%(asctime)s - %(levelname)s - %(funcName)s - %(message)s")
-)
-for h in logging.root.handlers:
-    logging.root.removeHandler(h)
-
-logging.getLogger("urllib3.connectionpool").setLevel(logging.ERROR)
-logging.getLogger('charset_normalizer').setLevel(logging.ERROR)
-logging.getLogger().setLevel(logging.ERROR)
-for h in logging.getLogger().handlers:
-    logging.getLogger().removeHandler(h)
-
-
-class NoKeyFoundException(Exception):
-    """Exception raised when an anime key cannot be found."""
-    pass
-class MatchNotFoundError(Exception):
-    """Exception raised when an anime key cannot be found."""
-    pass
-
-
-class SeriesApp:
-    _initialization_count = 0  # Track how many times initialization has been called
-    
-    def __init__(self, directory_to_search: str):
-        SeriesApp._initialization_count += 1
-        
-        # Only show initialization message for the first instance
-        if SeriesApp._initialization_count <= 1:
-            print("Please wait while initializing...")
-        
-        self.progress = None
-        self.directory_to_search = directory_to_search
-        self.Loaders = Loaders()
-        loader = self.Loaders.GetLoader(key="aniworld.to")
-        self.SerieScanner = SerieScanner(directory_to_search, loader)
-
-        self.List = SerieList(self.directory_to_search)
-        self.__InitList__()
-
-    def __InitList__(self):
-        self.series_list = self.List.GetMissingEpisode()
-
-
-    def display_series(self):
-        """Print all series with assigned numbers."""
-        print("\nCurrent result:")
-        for i, serie in enumerate(self.series_list, 1):
-            name = serie.name  # Access the property on the instance
-            if name is None or str(name).strip() == "":
-                print(f"{i}. {serie.folder}")
-            else:
-                print(f"{i}. {serie.name}")
-
-    def search(self, words :str) -> list:
-        loader = self.Loaders.GetLoader(key="aniworld.to")
-        return loader.Search(words)
-
-    def get_user_selection(self):
-        """Handle user input for selecting series."""
-        self.display_series()
-        while True:
-            selection = input(
-                "\nSelect series by number (e.g. '1', '1,2' or 'all') or type 'exit' to return: ").strip().lower()
-
-            if selection == "exit":
-                return None
-
-            selected_series = []
-            if selection == "all":
-                selected_series = self.series_list
-            else:
-                try:
-                    indexes = [int(num) - 1 for num in selection.split(",")]
-                    selected_series = [self.series_list[i] for i in indexes if 0 <= i < len(self.series_list)]
-                except ValueError:
-                    print("Invalid selection. Going back to the result display.")
-                    self.display_series()
-                    continue
-
-            if selected_series:
-                return selected_series
-            else:
-                print("No valid series selected. Going back to the result display.")
-                return None
-
-
-    def retry(self, func, max_retries=3, delay=2, *args, **kwargs):
-        for attempt in range(1, max_retries + 1):
-            try:
-                func(*args, **kwargs)
-                return True
-            except Exception as e:
-
-                print(e)
-                time.sleep(delay)
-        return False
-
-    def download_series(self, series):
-        """Simulate the downloading process with a progress bar."""
-        total_downloaded = 0
-        total_episodes = sum(sum(len(ep) for ep in serie.episodeDict.values()) for serie in series)
-        self.progress = Progress()
-        task1 = self.progress.add_task("[red]Processing...", total=total_episodes)
-        task2 = self.progress.add_task(f"[green]...", total=0)
-        self.task3 = self.progress.add_task(f"[Gray]...", total=100)  # Setze total auf 100 für Prozentanzeige
-        self.progress.start()
-
-        for serie in series:
-            serie_episodes = sum(len(ep) for ep in serie.episodeDict.values())
-            self.progress.update(task2, description=f"[green]{serie.folder}", total=serie_episodes)
-            downloaded = 0
-            for season, episodes in serie.episodeDict.items():
-                for episode in episodes:
-                    loader = self.Loaders.GetLoader(key="aniworld.to")
-                    if loader.IsLanguage(season, episode, serie.key):
-                        self.retry(loader.Download, 3, 1, self.directory_to_search,  serie.folder, season, episode, serie.key, "German Dub",self.print_Download_Progress)
-
-                    downloaded += 1
-                    total_downloaded += 1
-
-                    self.progress.update(task1, advance=1)
-                    self.progress.update(task2, advance=1)
-                    time.sleep(0.02)
-
-        self.progress.stop()
-        self.progress = None
-
-    def print_Download_Progress(self, d):
-        # Nutze self.progress und self.task3 für Fortschrittsanzeige
-        if self.progress is None or not hasattr(self, 'task3'):
-            return
-
-        if d['status'] == 'downloading':
-            total = d.get('total_bytes') or d.get('total_bytes_estimate')
-            downloaded = d.get('downloaded_bytes', 0)
-            if total:
-                percent = downloaded / total * 100
-                self.progress.update(self.task3, completed=percent, description=f"[gray]Download: {percent:.1f}%")
-            else:
-                self.progress.update(self.task3, description=f"[gray]{downloaded/1024/1024:.2f}MB geladen")
-        elif d['status'] == 'finished':
-            self.progress.update(self.task3, completed=100, description="[gray]Download abgeschlossen.")
-
-    def search_mode(self):
-        """Search for a series and allow user to select an option."""
-        search_string = input("Enter search string: ").strip()
-        results = self.search(search_string)
-
-        if not results:
-            print("No results found. Returning to start.")
-            return
-
-        print("\nSearch results:")
-        for i, result in enumerate(results, 1):
-            print(f"{i}. {result.get('name')}")
-
-        while True:
-            selection = input("\nSelect an option by number or type '<enter>' to return: ").strip().lower()
-
-            if selection == "":
-                return
-
-            try:
-                index = int(selection) - 1
-                if 0 <= index < len(results):
-                    chosen_name = results[index]
-                    self.List.add(Serie(chosen_name["link"], chosen_name["name"], "aniworld.to", chosen_name["link"], {}))
-                    return
-                else:
-                    print("Invalid selection. Try again.")
-            except ValueError:
-                print("Invalid input. Try again.")
-
-    def updateFromReinit(self, folder, counter):
-        self.progress.update(self.task1, advance=1)
-
-    def run(self):
-        """Main function to run the app."""
-        while True:
-            action = input("\nChoose action ('s' for search, 'i' for init or 'd' for download): ").strip().lower()
-
-            if action == "s":
-                self.search_mode()
-            if action == "i":
-
-                print("\nRescanning series...\n")
-
-                self.progress = Progress()
-                self.task1 = self.progress.add_task("[red]items processed...", total=300)
-                self.progress.start()
-
-                self.SerieScanner.Reinit()
-                self.SerieScanner.Scan(self.updateFromReinit)
-
-                self.List = SerieList(self.directory_to_search)
-                self.__InitList__()
-
-                self.progress.stop()
-                self.progress = None
-
-            elif action == "d":
-                selected_series = self.get_user_selection()
-                if selected_series:
-                    self.download_series(selected_series)
-
-# Run the app
-if __name__ == "__main__":
-
-    # Read the base directory from an environment variable
-    directory_to_search = os.getenv("ANIME_DIRECTORY", "\\\\sshfs.r\\ubuntu@192.168.178.43\\media\\serien\\Serien")
-    app = SeriesApp(directory_to_search)
-    app.run()

src/cli/logs/aniworld.log

@@ -1,491 +0,0 @@
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Enhanced logging system initialized
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Starting Aniworld Flask server...
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Anime directory: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Log level: INFO
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Scheduled operations disabled
-2025-09-29 12:38:25 - INFO     - __main__        - <module>             - Server will be available at http://localhost:5000
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Enhanced logging system initialized
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Starting Aniworld Flask server...
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Anime directory: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Log level: INFO
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Scheduled operations disabled
-2025-09-29 12:38:30 - INFO     - __main__        - <module>             - Server will be available at http://localhost:5000
-2025-09-29 12:38:30 - WARNING  - werkzeug        - _log                 -  * Debugger is active!
-2025-09-29 12:38:40 - INFO     - root            - __init__             - Initialized Loader with base path: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Scanning anime folders in: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping .deletedByTMM - No data folder found
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\2.5 Dimensional Seduction (2024)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\2.5 Dimensional Seduction (2024)\data for 2.5 Dimensional Seduction (2024)
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping 25-dimensional-seduction - No data folder found
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping 25-sai no Joshikousei (2018) - No data folder found
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\7th Time Loop The Villainess Enjoys a Carefree Life Married to Her Worst Enemy! (2024)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\7th Time Loop The Villainess Enjoys a Carefree Life Married to Her Worst Enemy! (2024)\data for 7th Time Loop The Villainess Enjoys a Carefree Life Married to Her Worst Enemy! (2024)
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\9-nine-rulers-crown\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\9-nine-rulers-crown\data for 9-nine-rulers-crown
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\A Couple of Cuckoos (2022)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\A Couple of Cuckoos (2022)\data for A Couple of Cuckoos (2022)
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping A Time Called You (2023) - No data folder found
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\A.I.C.O. Incarnation (2018)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\A.I.C.O. Incarnation (2018)\data for A.I.C.O. Incarnation (2018)
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Aesthetica of a Rogue Hero (2012)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Aesthetica of a Rogue Hero (2012)\data for Aesthetica of a Rogue Hero (2012)
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Alya Sometimes Hides Her Feelings in Russian (2024)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Alya Sometimes Hides Her Feelings in Russian (2024)\data for Alya Sometimes Hides Her Feelings in Russian (2024)
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping American Horror Story (2011) - No data folder found
-2025-09-29 12:38:40 - WARNING  - root            - load_series          - Skipping Andor (2022) - No data folder found
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Angels of Death (2018)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Angels of Death (2018)\data for Angels of Death (2018)
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Aokana Four Rhythm Across the Blue (2016)\data
-2025-09-29 12:38:40 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Aokana Four Rhythm Across the Blue (2016)\data for Aokana Four Rhythm Across the Blue (2016)
-2025-09-29 12:38:40 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Arifureta (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Arifureta (2019)\data for Arifureta (2019)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\As a Reincarnated Aristocrat, I'll Use My Appraisal Skill to Rise in the World (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\As a Reincarnated Aristocrat, I'll Use My Appraisal Skill to Rise in the World (2024)\data for As a Reincarnated Aristocrat, I'll Use My Appraisal Skill to Rise in the World (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\BOFURI I Don't Want to Get Hurt, so I'll Max Out My Defense. (2020)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\BOFURI I Don't Want to Get Hurt, so I'll Max Out My Defense. (2020)\data for BOFURI I Don't Want to Get Hurt, so I'll Max Out My Defense. (2020)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Black Butler (2008)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Black Butler (2008)\data for Black Butler (2008)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Black Clover (2017)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Black Clover (2017)\data for Black Clover (2017)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blast of Tempest (2012)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blast of Tempest (2012)\data for Blast of Tempest (2012)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blood Lad (2013)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blood Lad (2013)\data for Blood Lad (2013)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blue Box (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blue Box (2024)\data for Blue Box (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blue Exorcist (2011)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Blue Exorcist (2011)\data for Blue Exorcist (2011)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Bogus Skill Fruitmaster About That Time I Became Able to Eat Unlimited Numbers of Skill Fruits (That Kill You) (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Bogus Skill Fruitmaster About That Time I Became Able to Eat Unlimited Numbers of Skill Fruits (That Kill You) (2025)\data for Bogus Skill Fruitmaster About That Time I Became Able to Eat Unlimited Numbers of Skill Fruits (That Kill You) (2025)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Boys Over Flowers (2009) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Burst Angel (2004)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Burst Angel (2004)\data for Burst Angel (2004)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\By the Grace of the Gods (2020)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\By the Grace of the Gods (2020)\data for By the Grace of the Gods (2020)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Call of the Night (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Call of the Night (2022)\data for Call of the Night (2022)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Campfire Cooking in Another World with My Absurd Skill (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Campfire Cooking in Another World with My Absurd Skill (2023)\data for Campfire Cooking in Another World with My Absurd Skill (2023)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Celebrity (2023) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Chainsaw Man (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Chainsaw Man (2022)\data for Chainsaw Man (2022)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Charlotte (2015)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Charlotte (2015)\data for Charlotte (2015)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Cherish the Day (2020) - No data folder found
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Chernobyl (2019) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Chillin’ in Another World with Level 2 Super Cheat Powers (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Chillin’ in Another World with Level 2 Super Cheat Powers (2024)\data for Chillin’ in Another World with Level 2 Super Cheat Powers (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Clannad (2007)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Clannad (2007)\data for Clannad (2007)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Classroom of the Elite (2017)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Classroom of the Elite (2017)\data for Classroom of the Elite (2017)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Clevatess (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Clevatess (2025)\data for Clevatess (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\DAN DA DAN (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\DAN DA DAN (2024)\data for DAN DA DAN (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Danmachi Is It Wrong to Try to Pick Up Girls in a Dungeon (2015)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Danmachi Is It Wrong to Try to Pick Up Girls in a Dungeon (2015)\data for Danmachi Is It Wrong to Try to Pick Up Girls in a Dungeon (2015)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Das Buch von Boba Fett (2021) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Date a Live (2013)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Date a Live (2013)\data for Date a Live (2013)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dead Mount Death Play (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dead Mount Death Play (2023)\data for Dead Mount Death Play (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Deadman Wonderland (2011)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Deadman Wonderland (2011)\data for Deadman Wonderland (2011)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dealing with Mikadono Sisters Is a Breeze (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dealing with Mikadono Sisters Is a Breeze (2025)\data for Dealing with Mikadono Sisters Is a Breeze (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Delicious in Dungeon (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Delicious in Dungeon (2024)\data for Delicious in Dungeon (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Lord, Retry! (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Lord, Retry! (2019)\data for Demon Lord, Retry! (2019)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Slave - The Chained Soldier (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Slave - The Chained Soldier (2024)\data for Demon Slave - The Chained Soldier (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Slayer Kimetsu no Yaiba (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Demon Slayer Kimetsu no Yaiba (2019)\data for Demon Slayer Kimetsu no Yaiba (2019)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Der Herr der Ringe Die Ringe der Macht (2022) - No data folder found
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Devil in Ohio (2022) - No data folder found
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Die Bibel (2013) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Die Tagebücher der Apothekerin (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Die Tagebücher der Apothekerin (2023)\data for Die Tagebücher der Apothekerin (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Domestic Girlfriend (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Domestic Girlfriend (2019)\data for Domestic Girlfriend (2019)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Doona! (2023) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dr. STONE (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dr. STONE (2019)\data for Dr. STONE (2019)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dragonball Super (2015)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Dragonball Super (2015)\data for Dragonball Super (2015)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Failure Frame I Became the Strongest and Annihilated Everything With Low-Level Spells (2024) - No data folder found
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Fallout (2024) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Farming Life in Another World (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Farming Life in Another World (2023)\data for Farming Life in Another World (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Frieren - Nach dem Ende der Reise (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Frieren - Nach dem Ende der Reise (2023)\data for Frieren - Nach dem Ende der Reise (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Fruits Basket (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Fruits Basket (2019)\data for Fruits Basket (2019)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gachiakuta (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gachiakuta (2025)\data for Gachiakuta (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gate (2015)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gate (2015)\data for Gate (2015)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Generation der Verdammten (2014) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Girls und Panzer (2012)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Girls und Panzer (2012)\data for Girls und Panzer (2012)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gleipnir (2020)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Gleipnir (2020)\data for Gleipnir (2020)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Golden Time (2013)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Golden Time (2013)\data for Golden Time (2013)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Grimgar, Ashes and Illusions (2016)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Grimgar, Ashes and Illusions (2016)\data for Grimgar, Ashes and Illusions (2016)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Harem in the Labyrinth of Another World (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Harem in the Labyrinth of Another World (2022)\data for Harem in the Labyrinth of Another World (2022)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Highschool D×D (2012) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Hinamatsuri (2018)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Hinamatsuri (2018)\data for Hinamatsuri (2018)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I Got a Cheat Skill in Another World and Became Unrivaled in The Real World Too (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I Got a Cheat Skill in Another World and Became Unrivaled in The Real World Too (2023)\data for I Got a Cheat Skill in Another World and Became Unrivaled in The Real World Too (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I Parry Everything What Do You Mean I’m the Strongest I’m Not Even an Adventurer Yet! (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I Parry Everything What Do You Mean I’m the Strongest I’m Not Even an Adventurer Yet! (2024)\data for I Parry Everything What Do You Mean I’m the Strongest I’m Not Even an Adventurer Yet! (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I'm the Evil Lord of an Intergalactic Empire! (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I'm the Evil Lord of an Intergalactic Empire! (2025)\data for I'm the Evil Lord of an Intergalactic Empire! (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I've Been Killing Slimes for 300 Years and Maxed Out My Level (2021)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I've Been Killing Slimes for 300 Years and Maxed Out My Level (2021)\data for I've Been Killing Slimes for 300 Years and Maxed Out My Level (2021)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\In the Land of Leadale (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\In the Land of Leadale (2022)\data for In the Land of Leadale (2022)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Ishura (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Ishura (2024)\data for Ishura (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I’ll Become a Villainess Who Goes Down in History (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\I’ll Become a Villainess Who Goes Down in History (2024)\data for I’ll Become a Villainess Who Goes Down in History (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\JUJUTSU KAISEN (2020)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\JUJUTSU KAISEN (2020)\data for JUJUTSU KAISEN (2020)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kaguya-sama Love is War (2019)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kaguya-sama Love is War (2019)\data for Kaguya-sama Love is War (2019)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kaiju No. 8 (20200)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kaiju No. 8 (20200)\data for Kaiju No. 8 (20200)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\KamiKatsu Meine Arbeit als Missionar in einer gottlosen Welt (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\KamiKatsu Meine Arbeit als Missionar in einer gottlosen Welt (2023)\data for KamiKatsu Meine Arbeit als Missionar in einer gottlosen Welt (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Knight's & Magic (2017)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Knight's & Magic (2017)\data for Knight's & Magic (2017)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kombattanten werden entsandt! (2021)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kombattanten werden entsandt! (2021)\data for Kombattanten werden entsandt! (2021)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\KonoSuba – An Explosion on This Wonderful World! (2023)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\KonoSuba – An Explosion on This Wonderful World! (2023)\data for KonoSuba – An Explosion on This Wonderful World! (2023)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Konosuba God's Blessing on This Wonderful World! (2016)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Konosuba God's Blessing on This Wonderful World! (2016)\data for Konosuba God's Blessing on This Wonderful World! (2016)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Krieg der Welten (2019) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kuma Kuma Kuma Bear (2020)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Kuma Kuma Kuma Bear (2020)\data for Kuma Kuma Kuma Bear (2020)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Log Horizon (2013)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Log Horizon (2013)\data for Log Horizon (2013)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Loki (2021) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Loner Life in Another World (2024)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Loner Life in Another World (2024)\data for Loner Life in Another World (2024)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Lord of Mysteries (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Lord of Mysteries (2025)\data for Lord of Mysteries (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Lycoris Recoil (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Lycoris Recoil (2022)\data for Lycoris Recoil (2022)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Magic Maker How to Make Magic in Another World (2025)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Magic Maker How to Make Magic in Another World (2025)\data for Magic Maker How to Make Magic in Another World (2025)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Magical Girl Site (2018)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Magical Girl Site (2018)\data for Magical Girl Site (2018)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Management of a Novice Alchemist (2022)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Management of a Novice Alchemist (2022)\data for Management of a Novice Alchemist (2022)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Marianne (2019) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Meine Wiedergeburt als Schleim in einer anderen Welt (2018)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Meine Wiedergeburt als Schleim in einer anderen Welt (2018)\data for Meine Wiedergeburt als Schleim in einer anderen Welt (2018)
-2025-09-29 12:38:41 - WARNING  - root            - load_series          - Skipping Midnight Mass (2021) - No data folder found
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mirai Nikki (2011)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mirai Nikki (2011)\data for Mirai Nikki (2011)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Miss Kobayashi's Dragon Maid (2017)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Miss Kobayashi's Dragon Maid (2017)\data for Miss Kobayashi's Dragon Maid (2017)
-2025-09-29 12:38:41 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mob Psycho 100 (2016)\data
-2025-09-29 12:38:41 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mob Psycho 100 (2016)\data for Mob Psycho 100 (2016)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\More than a Married Couple, but Not Lovers (2022)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\More than a Married Couple, but Not Lovers (2022)\data for More than a Married Couple, but Not Lovers (2022)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mushoku Tensei Jobless Reincarnation (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Mushoku Tensei Jobless Reincarnation (2021)\data for Mushoku Tensei Jobless Reincarnation (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Hero Academia Vigilantes (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Hero Academia Vigilantes (2025)\data for My Hero Academia Vigilantes (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Instant Death Ability Is So Overpowered, No One in This Other World Stands a Chance Against Me! (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Instant Death Ability Is So Overpowered, No One in This Other World Stands a Chance Against Me! (2024)\data for My Instant Death Ability Is So Overpowered, No One in This Other World Stands a Chance Against Me! (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Isekai Life (2022)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Isekai Life (2022)\data for My Isekai Life (2022)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Life as Inukai-san's Dog (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Life as Inukai-san's Dog (2023)\data for My Life as Inukai-san's Dog (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Unique Skill Makes Me OP even at Level 1 (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\My Unique Skill Makes Me OP even at Level 1 (2023)\data for My Unique Skill Makes Me OP even at Level 1 (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\New Saga (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\New Saga (2025)\data for New Saga (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Nina the Starry Bride (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Nina the Starry Bride (2024)\data for Nina the Starry Bride (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Nisekoi Liebe, Lügen & Yakuza (2014)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Nisekoi Liebe, Lügen & Yakuza (2014)\data for Nisekoi Liebe, Lügen & Yakuza (2014)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\No Game No Life (2014)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\No Game No Life (2014)\data for No Game No Life (2014)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Obi-Wan Kenobi (2022) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Orange (2016)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Orange (2016)\data for Orange (2016)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Peach Boy Riverside (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Peach Boy Riverside (2021)\data for Peach Boy Riverside (2021)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Penny Dreadful (2014) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Planet Erde II Eine Erde - viele Welten (2016) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Plastic Memories (2015)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Plastic Memories (2015)\data for Plastic Memories (2015)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Ragna Crimson (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Ragna Crimson (2023)\data for Ragna Crimson (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Rascal Does Not Dream of Bunny Girl Senpai (2018)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Rascal Does Not Dream of Bunny Girl Senpai (2018)\data for Rascal Does Not Dream of Bunny Girl Senpai (2018)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\ReMonster (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\ReMonster (2024)\data for ReMonster (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\ReZERO - Starting Life in Another World (2016)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\ReZERO - Starting Life in Another World (2016)\data for ReZERO - Starting Life in Another World (2016)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Reborn as a Vending Machine, I Now Wander the Dungeon (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Reborn as a Vending Machine, I Now Wander the Dungeon (2023)\data for Reborn as a Vending Machine, I Now Wander the Dungeon (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Redo of Healer (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Redo of Healer (2021)\data for Redo of Healer (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Rick and Morty (2013)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Rick and Morty (2013)\data for Rick and Morty (2013)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Rocket & Groot (2017) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Romulus (2020) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Saga of Tanya the Evil (2017)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Saga of Tanya the Evil (2017)\data for Saga of Tanya the Evil (2017)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Seirei Gensouki Spirit Chronicles (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Seirei Gensouki Spirit Chronicles (2021)\data for Seirei Gensouki Spirit Chronicles (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Shangri-La Frontier (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Shangri-La Frontier (2023)\data for Shangri-La Frontier (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\She Professed Herself Pupil of the Wise Man (2022)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\She Professed Herself Pupil of the Wise Man (2022)\data for She Professed Herself Pupil of the Wise Man (2022)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping She-Hulk Die Anwältin (2022) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Solo Leveling (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Solo Leveling (2024)\data for Solo Leveling (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Spice and Wolf (2008)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Spice and Wolf (2008)\data for Spice and Wolf (2008)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Star Trek Discovery (2017) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Stargate (1997) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Stargate Atlantis (2004) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Steins;Gate (2011)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Steins;Gate (2011)\data for Steins;Gate (2011)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Sweet Tooth (2021) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Sword of the Demon Hunter Kijin Gen (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Sword of the Demon Hunter Kijin Gen (2025)\data for Sword of the Demon Hunter Kijin Gen (2025)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Tales from the Loop (2020) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tamako Market (2013)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tamako Market (2013)\data for Tamako Market (2013)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Ancient Magus' Bride (2017)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Ancient Magus' Bride (2017)\data for The Ancient Magus' Bride (2017)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Demon Sword Master of Excalibur Academy (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Demon Sword Master of Excalibur Academy (2023)\data for The Demon Sword Master of Excalibur Academy (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Devil is a Part-Timer! (2013)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Devil is a Part-Timer! (2013)\data for The Devil is a Part-Timer! (2013)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Dreaming Boy is a Realist (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Dreaming Boy is a Realist (2023)\data for The Dreaming Boy is a Realist (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Dungeon of Black Company (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Dungeon of Black Company (2021)\data for The Dungeon of Black Company (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Eminence in Shadow (2022)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Eminence in Shadow (2022)\data for The Eminence in Shadow (2022)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Familiar of Zero (2006)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Familiar of Zero (2006)\data for The Familiar of Zero (2006)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Faraway Paladin (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Faraway Paladin (2021)\data for The Faraway Paladin (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Gorilla God’s Go-To Girl (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Gorilla God’s Go-To Girl (2025)\data for The Gorilla God’s Go-To Girl (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Hidden Dungeon Only I Can Enter (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Hidden Dungeon Only I Can Enter (2021)\data for The Hidden Dungeon Only I Can Enter (2021)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping The Last of Us (2023) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping The Man in the High Castle (2015) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping The Mandalorian (2019) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Quintessential Quintuplets (2019)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Quintessential Quintuplets (2019)\data for The Quintessential Quintuplets (2019)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Saint’s Magic Power is Omnipotent (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Saint’s Magic Power is Omnipotent (2021)\data for The Saint’s Magic Power is Omnipotent (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Too-Perfect Saint Tossed Aside by My Fiance and Sold to Another Kingdom (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Too-Perfect Saint Tossed Aside by My Fiance and Sold to Another Kingdom (2025)\data for The Too-Perfect Saint Tossed Aside by My Fiance and Sold to Another Kingdom (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Unaware Atelier Meister (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Unaware Atelier Meister (2025)\data for The Unaware Atelier Meister (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Weakest Tamer Began a Journey to Pick Up Trash (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\The Weakest Tamer Began a Journey to Pick Up Trash (2024)\data for The Weakest Tamer Began a Journey to Pick Up Trash (2024)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping The Witcher (2019) - No data folder found
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping The World's Finest Assassin Gets Reincarnated in Another World as an Aristocrat (2021) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\To Your Eternity (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\To Your Eternity (2021)\data for To Your Eternity (2021)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tomo-chan Is a Girl! (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tomo-chan Is a Girl! (2023)\data for Tomo-chan Is a Girl! (2023)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tonikawa Over the Moon for You (2020)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tonikawa Over the Moon for You (2020)\data for Tonikawa Over the Moon for You (2020)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tsukimichi Moonlit Fantasy (2021)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Tsukimichi Moonlit Fantasy (2021)\data for Tsukimichi Moonlit Fantasy (2021)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping Unidentified - Die wahren X-Akten (2019) - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Unnamed Memory (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Unnamed Memory (2024)\data for Unnamed Memory (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Vom Landei zum Schwertheiligen (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Vom Landei zum Schwertheiligen (2025)\data for Vom Landei zum Schwertheiligen (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\WIND BREAKER (2024)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\WIND BREAKER (2024)\data for WIND BREAKER (2024)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\WITCH WATCH (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\WITCH WATCH (2025)\data for WITCH WATCH (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Wolf Girl & Black Prince (2014)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Wolf Girl & Black Prince (2014)\data for Wolf Girl & Black Prince (2014)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\World’s End Harem (2022)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\World’s End Harem (2022)\data for World’s End Harem (2022)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Zom 100 Bucket List of the Dead (2023)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Zom 100 Bucket List of the Dead (2023)\data for Zom 100 Bucket List of the Dead (2023)
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping a-couple-of-cuckoos - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\a-ninja-and-an-assassin-under-one-roof\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\a-ninja-and-an-assassin-under-one-roof\data for a-ninja-and-an-assassin-under-one-roof
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\a-nobodys-way-up-to-an-exploration-hero\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\a-nobodys-way-up-to-an-exploration-hero\data for a-nobodys-way-up-to-an-exploration-hero
-2025-09-29 12:38:42 - WARNING  - root            - load_series          - Skipping a-silent-voice - No data folder found
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\am-i-actually-the-strongest\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\am-i-actually-the-strongest\data for am-i-actually-the-strongest
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\anne-shirley\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\anne-shirley\data for anne-shirley
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\apocalypse-bringer-mynoghra\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\apocalypse-bringer-mynoghra\data for apocalypse-bringer-mynoghra
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\banished-from-the-heros-party-i-decided-to-live-a-quiet-life-in-the-countryside\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\banished-from-the-heros-party-i-decided-to-live-a-quiet-life-in-the-countryside\data for banished-from-the-heros-party-i-decided-to-live-a-quiet-life-in-the-countryside
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\beheneko the elf girls cat is secretly an s ranked monster (2025) (2025)\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\beheneko the elf girls cat is secretly an s ranked monster (2025) (2025)\data for beheneko the elf girls cat is secretly an s ranked monster (2025) (2025)
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\berserk-of-gluttony\data
-2025-09-29 12:38:42 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\berserk-of-gluttony\data for berserk-of-gluttony
-2025-09-29 12:38:42 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\black-summoner\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\black-summoner\data for black-summoner
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\boarding-school-juliet\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\boarding-school-juliet\data for boarding-school-juliet
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\buddy-daddies\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\buddy-daddies\data for buddy-daddies
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\can-a-boy-girl-friendship-survive\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\can-a-boy-girl-friendship-survive\data for can-a-boy-girl-friendship-survive
-2025-09-29 12:38:43 - WARNING  - root            - load_series          - Skipping chillin-in-another-world-with-level-2-super-cheat-powers - No data folder found
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\chillin-in-my-30s-after-getting-fired-from-the-demon-kings-army\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\chillin-in-my-30s-after-getting-fired-from-the-demon-kings-army\data for chillin-in-my-30s-after-getting-fired-from-the-demon-kings-army
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\choujin koukousei tachi wa isekai de mo yoyuu de ikinuku you desu\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\choujin koukousei tachi wa isekai de mo yoyuu de ikinuku you desu\data for choujin koukousei tachi wa isekai de mo yoyuu de ikinuku you desu
-2025-09-29 12:38:43 - WARNING  - root            - load_series          - Skipping clevatess - No data folder found
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\compass-20-animation-project\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\compass-20-animation-project\data for compass-20-animation-project
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\dragon-raja-the-blazing-dawn\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\dragon-raja-the-blazing-dawn\data for dragon-raja-the-blazing-dawn
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\dragonar-academy\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\dragonar-academy\data for dragonar-academy
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\drugstore-in-another-world-the-slow-life-of-a-cheat-pharmacist\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\drugstore-in-another-world-the-slow-life-of-a-cheat-pharmacist\data for drugstore-in-another-world-the-slow-life-of-a-cheat-pharmacist
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\fluffy-paradise\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\fluffy-paradise\data for fluffy-paradise
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\food-for-the-soul\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\food-for-the-soul\data for food-for-the-soul
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\handyman-saitou-in-another-world\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\handyman-saitou-in-another-world\data for handyman-saitou-in-another-world
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\i-shall-survive-using-potions\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\i-shall-survive-using-potions\data for i-shall-survive-using-potions
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\im-giving-the-disgraced-noble-lady-i-rescued-a-crash-course-in-naughtiness\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\im-giving-the-disgraced-noble-lady-i-rescued-a-crash-course-in-naughtiness\data for im-giving-the-disgraced-noble-lady-i-rescued-a-crash-course-in-naughtiness
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\killing-bites\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\killing-bites\data for killing-bites
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\love-flops\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\love-flops\data for love-flops
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\magic-maker-how-to-make-magic-in-another-world\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\magic-maker-how-to-make-magic-in-another-world\data for magic-maker-how-to-make-magic-in-another-world
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\muhyo-rojis-bureau-of-supernatural-investigation\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\muhyo-rojis-bureau-of-supernatural-investigation\data for muhyo-rojis-bureau-of-supernatural-investigation
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\my-roommate-is-a-cat\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\my-roommate-is-a-cat\data for my-roommate-is-a-cat
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\nukitashi-the-animation\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\nukitashi-the-animation\data for nukitashi-the-animation
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\outbreak-company\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\outbreak-company\data for outbreak-company
-2025-09-29 12:38:43 - WARNING  - root            - load_series          - Skipping plastic-memories - No data folder found
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\pseudo-harem\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\pseudo-harem\data for pseudo-harem
-2025-09-29 12:38:43 - WARNING  - root            - load_series          - Skipping rent-a-girlfriend - No data folder found
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\sasaki-and-peeps\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\sasaki-and-peeps\data for sasaki-and-peeps
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\scooped-up-by-an-s-rank-adventurer\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\scooped-up-by-an-s-rank-adventurer\data for scooped-up-by-an-s-rank-adventurer
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\secrets-of-the-silent-witch\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\secrets-of-the-silent-witch\data for secrets-of-the-silent-witch
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\seton-academy-join-the-pack\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\seton-academy-join-the-pack\data for seton-academy-join-the-pack
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\shachibato-president-its-time-for-battle\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\shachibato-president-its-time-for-battle\data for shachibato-president-its-time-for-battle
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\skeleton-knight-in-another-world\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\skeleton-knight-in-another-world\data for skeleton-knight-in-another-world
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\sugar-apple-fairy-tale\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\sugar-apple-fairy-tale\data for sugar-apple-fairy-tale
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\summer-pockets\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\summer-pockets\data for summer-pockets
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\suppose-a-kid-from-the-last-dungeon-boonies-moved-to-a-starter-town\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\suppose-a-kid-from-the-last-dungeon-boonies-moved-to-a-starter-town\data for suppose-a-kid-from-the-last-dungeon-boonies-moved-to-a-starter-town
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-beginning-after-the-end\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-beginning-after-the-end\data for the-beginning-after-the-end
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-brilliant-healers-new-life-in-the-shadows\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-brilliant-healers-new-life-in-the-shadows\data for the-brilliant-healers-new-life-in-the-shadows
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-daily-life-of-a-middle-aged-online-shopper-in-another-world\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-daily-life-of-a-middle-aged-online-shopper-in-another-world\data for the-daily-life-of-a-middle-aged-online-shopper-in-another-world
-2025-09-29 12:38:43 - WARNING  - root            - load_series          - Skipping the-familiar-of-zero - No data folder found
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-fragrant-flower-blooms-with-dignity\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-fragrant-flower-blooms-with-dignity\data for the-fragrant-flower-blooms-with-dignity
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-great-cleric\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-great-cleric\data for the-great-cleric
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-new-chronicles-of-extraordinary-beings-preface\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-new-chronicles-of-extraordinary-beings-preface\data for the-new-chronicles-of-extraordinary-beings-preface
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-shiunji-family-children\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-shiunji-family-children\data for the-shiunji-family-children
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-shy-hero-and-the-assassin-princesses\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-shy-hero-and-the-assassin-princesses\data for the-shy-hero-and-the-assassin-princesses
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-testament-of-sister-new-devil\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-testament-of-sister-new-devil\data for the-testament-of-sister-new-devil
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-unwanted-undead-adventurer\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-unwanted-undead-adventurer\data for the-unwanted-undead-adventurer
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-water-magician\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-water-magician\data for the-water-magician
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-worlds-finest-assassin-gets-reincarnated-in-another-world-as-an-aristocrat\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-worlds-finest-assassin-gets-reincarnated-in-another-world-as-an-aristocrat\data for the-worlds-finest-assassin-gets-reincarnated-in-another-world-as-an-aristocrat
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-wrong-way-to-use-healing-magic\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\the-wrong-way-to-use-healing-magic\data for the-wrong-way-to-use-healing-magic
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\theres-no-freaking-way-ill-be-your-lover-unless\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\theres-no-freaking-way-ill-be-your-lover-unless\data for theres-no-freaking-way-ill-be-your-lover-unless
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\to-be-hero-x\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\to-be-hero-x\data for to-be-hero-x
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\tougen-anki\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\tougen-anki\data for tougen-anki
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\uglymug-epicfighter\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\uglymug-epicfighter\data for uglymug-epicfighter
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\valkyrie-drive-mermaid\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\valkyrie-drive-mermaid\data for valkyrie-drive-mermaid
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\wandering-witch-the-journey-of-elaina\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\wandering-witch-the-journey-of-elaina\data for wandering-witch-the-journey-of-elaina
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\war-god-system-im-counting-on-you\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\war-god-system-im-counting-on-you\data for war-god-system-im-counting-on-you
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\welcome-to-japan-ms-elf\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\welcome-to-japan-ms-elf\data for welcome-to-japan-ms-elf
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\welcome-to-the-outcasts-restaurant\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\welcome-to-the-outcasts-restaurant\data for welcome-to-the-outcasts-restaurant
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\yandere-dark-elf-she-chased-me-all-the-way-from-another-world\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\yandere-dark-elf-she-chased-me-all-the-way-from-another-world\data for yandere-dark-elf-she-chased-me-all-the-way-from-another-world
-2025-09-29 12:38:43 - INFO     - root            - load_series          - Found data folder: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Übel Blatt (2025)\data
-2025-09-29 12:38:43 - INFO     - root            - load_data            - Successfully loaded \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien\Übel Blatt (2025)\data for Übel Blatt (2025)
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Enhanced logging system initialized
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Starting Aniworld Flask server...
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Anime directory: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Log level: INFO
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Scheduled operations disabled
-2025-09-29 20:23:13 - INFO     - __main__        - <module>             - Server will be available at http://localhost:5000
-2025-09-29 20:23:16 - INFO     - __main__        - <module>             - Enhanced logging system initialized
-2025-09-29 20:23:16 - INFO     - root            - __init__             - Initialized Loader with base path: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 20:23:16 - INFO     - root            - load_series          - Scanning anime folders in: \\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien
-2025-09-29 20:23:16 - ERROR    - root            - init_series_app      - Error initializing SeriesApp:
-Traceback (most recent call last):
-  File "D:\repo\Aniworld/src/server/app.py", line 145, in init_series_app
-    series_app = SeriesApp(directory_to_search)
-                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File "D:\repo\Aniworld\src\Main.py", line 54, in __init__
-    self.List = SerieList(self.directory_to_search)
-                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  File "D:\repo\Aniworld\src\server\core\entities\SerieList.py", line 9, in __init__
-    self.load_series()
-  File "D:\repo\Aniworld\src\server\core\entities\SerieList.py", line 29, in load_series
-    for anime_folder in os.listdir(self.directory):
-                        ^^^^^^^^^^^^^^^^^^^^^^^^^^
-FileNotFoundError: [WinError 53] Der Netzwerkpfad wurde nicht gefunden: '\\\\sshfs.r\\ubuntu@192.168.178.43\\media\\serien\\Serien'
-2025-09-29 20:23:16 - WARNING  - werkzeug        - _log                 -  * Debugger is active!
-2025-09-29 20:33:06 - DEBUG    - schedule        - clear                - Deleting *all* jobs
-2025-09-29 20:33:06 - INFO     - application.services.scheduler_service - stop_scheduler       - Scheduled operations stopped
-2025-09-29 20:33:06 - INFO     - __main__        - <module>             - Scheduler stopped

src/cli/nfo_cli.py

@@ -0,0 +1,205 @@
+"""CLI command for NFO management.
+
+Note: NFO service has been removed. This CLI is no longer functional.
+"""
+
+import logging
+import sys
+from pathlib import Path
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+logger = logging.getLogger(__name__)
+
+
+async def scan_and_create_nfo():
+    """Scan all series and create missing NFO files."""
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Auto-Creation Tool")
+    logger.info("%s", "=" * 70)
+
+    if not settings.tmdb_api_key:
+        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:
+        logger.error("ANIME_DIRECTORY not configured")
+        return 1
+
+    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:
+        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
+    
+    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()
+
+    logger.info("Found %d series in directory", len(all_series))
+
+    if not all_series:
+        logger.warning("No series found. Add some anime series first.")
+        return 0
+    
+    # Show series without NFO
+    series_without_nfo = []
+    for serie in all_series:
+        if not serie.has_nfo():
+            series_without_nfo.append(serie)
+    
+    if series_without_nfo:
+        logger.info("Series without NFO: %d", len(series_without_nfo))
+        for serie in series_without_nfo[:5]:  # Show first 5
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
+        if len(series_without_nfo) > 5:
+            logger.info("... and %d more", len(series_without_nfo) - 5)
+    else:
+        logger.info("All series already have NFO files")
+
+        if not settings.nfo_update_on_scan:
+            logger.info("Nothing to do. Enable NFO_UPDATE_ON_SCAN to update existing NFOs.")
+            return 0
+    
+    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()
+        logger.info("NFO processing complete")
+
+        # Show updated stats
+        serie_list.load_series()  # Reload to get updated stats
+        all_series = serie_list.get_all()
+        series_with_nfo = [s for s in all_series if s.has_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()]
+
+        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()
+    
+    return 0
+
+
+async def check_nfo_status():
+    """Check NFO status for all series."""
+    logger.info("%s", "=" * 70)
+    logger.info("NFO Status Check")
+    logger.info("%s", "=" * 70)
+
+    if not settings.anime_directory:
+        logger.error("ANIME_DIRECTORY not configured")
+        return 1
+
+    logger.info("Anime Directory: %s", settings.anime_directory)
+
+    # Create series list (no NFO service needed for status check)
+    from src.server.database.SerieList import SerieList
+    serie_list = SerieList(settings.anime_directory)
+    all_series = serie_list.get_all()
+
+    if not all_series:
+        logger.warning("No series found")
+        return 0
+
+    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)
+
+    logger.info(
+        "Series NFO coverage",
+        extra={
+            "with_nfo": len(with_nfo),
+            "without_nfo": len(without_nfo),
+            "total": len(all_series),
+        },
+    )
+
+    if without_nfo:
+        logger.info("Series missing NFO: %d", len(without_nfo))
+        for serie in without_nfo[:10]:
+            logger.debug("Missing NFO: %s (%s)", serie.name, serie.folder)
+        if len(without_nfo) > 10:
+            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())
+
+    logger.info(
+        "Media file coverage",
+        extra={
+            "posters": with_poster,
+            "logos": with_logo,
+            "fanart": with_fanart,
+            "total": len(all_series),
+        },
+    )
+
+    return 0
+
+
+def main():
+    """Main CLI entry point."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    if len(sys.argv) < 2:
+        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())
+    else:
+        logger.error("Unknown command: %s", command)
+        logger.info("Use 'scan' or 'status'")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/config/settings.py

@@ -1,30 +1,191 @@
+import re
+import secrets
 from typing import Optional
 
 from pydantic import Field
-from pydantic_settings import BaseSettings
+from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 class Settings(BaseSettings):
     """Application settings from environment variables."""
-    jwt_secret_key: str = Field(default="your-secret-key-here", env="JWT_SECRET_KEY")
-    password_salt: str = Field(default="default-salt", env="PASSWORD_SALT")
-    master_password_hash: Optional[str] = Field(default=None, env="MASTER_PASSWORD_HASH")
-    master_password: Optional[str] = Field(default=None, env="MASTER_PASSWORD")  # For development
-    token_expiry_hours: int = Field(default=24, env="SESSION_TIMEOUT_HOURS")
-    anime_directory: str = Field(default="", env="ANIME_DIRECTORY")
-    log_level: str = Field(default="INFO", env="LOG_LEVEL")
+    
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+    
+    jwt_secret_key: str = Field(
+        default_factory=lambda: secrets.token_urlsafe(32),
+        validation_alias="JWT_SECRET_KEY",
+    )
+    password_salt: str = Field(
+        default="default-salt",
+        validation_alias="PASSWORD_SALT"
+    )
+    master_password_hash: Optional[str] = Field(
+        default=None,
+        validation_alias="MASTER_PASSWORD_HASH"
+    )
+    # ⚠️ WARNING: DEVELOPMENT ONLY - NEVER USE IN PRODUCTION ⚠️
+    # This field allows setting a plaintext master password via environment
+    # variable for development/testing purposes only. In production
+    # deployments, use MASTER_PASSWORD_HASH instead and NEVER set this field.
+    master_password: Optional[str] = Field(
+        default=None,
+        validation_alias="MASTER_PASSWORD",
+        description=(
+            "**DEVELOPMENT ONLY** - Plaintext master password. "
+            "NEVER enable in production. Use MASTER_PASSWORD_HASH instead."
+        ),
+    )
+    token_expiry_hours: int = Field(
+        default=24,
+        validation_alias="SESSION_TIMEOUT_HOURS"
+    )
+    anime_directory: str = Field(
+        default="",
+        validation_alias="ANIME_DIRECTORY"
+    )
+    log_level: str = Field(
+        default="INFO",
+        validation_alias="LOG_LEVEL"
+    )
 
     # Additional settings from .env
-    database_url: str = Field(default="sqlite:///./data/aniworld.db", env="DATABASE_URL")
-    cors_origins: str = Field(default="*", env="CORS_ORIGINS")
-    api_rate_limit: int = Field(default=100, env="API_RATE_LIMIT")
-    default_provider: str = Field(default="aniworld.to", env="DEFAULT_PROVIDER")
-    provider_timeout: int = Field(default=30, env="PROVIDER_TIMEOUT")
-    retry_attempts: int = Field(default=3, env="RETRY_ATTEMPTS")
+    database_url: str = Field(
+        default="sqlite:///./data/aniworld.db",
+        validation_alias="DATABASE_URL"
+    )
+    cors_origins: str = Field(
+        default="http://localhost:3000",
+        validation_alias="CORS_ORIGINS",
+    )
+    api_rate_limit: int = Field(
+        default=100,
+        validation_alias="API_RATE_LIMIT"
+    )
+    default_provider: str = Field(
+        default="aniworld.to",
+        validation_alias="DEFAULT_PROVIDER"
+    )
+    provider_timeout: int = Field(
+        default=30,
+        validation_alias="PROVIDER_TIMEOUT"
+    )
+    retry_attempts: int = Field(
+        default=3,
+        validation_alias="RETRY_ATTEMPTS"
+    )
+    
+    # NFO / TMDB Settings
+    tmdb_api_key: Optional[str] = Field(
+        default=None,
+        validation_alias="TMDB_API_KEY",
+        description="TMDB API key for scraping TV show metadata"
+    )
+    nfo_auto_create: bool = Field(
+        default=False,
+        validation_alias="NFO_AUTO_CREATE",
+        description="Automatically create NFO files when scanning series"
+    )
+    nfo_update_on_scan: bool = Field(
+        default=False,
+        validation_alias="NFO_UPDATE_ON_SCAN",
+        description="Update existing NFO files when scanning series"
+    )
+    nfo_download_poster: bool = Field(
+        default=True,
+        validation_alias="NFO_DOWNLOAD_POSTER",
+        description="Download poster.jpg when creating NFO"
+    )
+    nfo_download_logo: bool = Field(
+        default=True,
+        validation_alias="NFO_DOWNLOAD_LOGO",
+        description="Download logo.png when creating NFO"
+    )
+    nfo_download_fanart: bool = Field(
+        default=True,
+        validation_alias="NFO_DOWNLOAD_FANART",
+        description="Download fanart.jpg when creating NFO"
+    )
+    nfo_image_size: str = Field(
+        default="original",
+        validation_alias="NFO_IMAGE_SIZE",
+        description="Image size to download (original, w500, etc.)"
+    )
+    nfo_prefer_fsk_rating: bool = Field(
+        default=True,
+        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)"
+    )
 
-    class Config:
-        env_file = ".env"
-        extra = "ignore"
+    @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]:
+        """Return the list of allowed CORS origins.
+
+        The environment variable should contain a comma-separated list.
+        When ``*`` is provided we fall back to a safe local development
+        default instead of allowing every origin in production.
+        """
+
+        raw = (self.cors_origins or "").strip()
+        if not raw:
+            return []
+        if raw == "*":
+            return [
+                "http://localhost:3000",
+                "http://localhost:8000",
+            ]
+        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/SerieScanner.py

@@ -1,131 +0,0 @@
-import os
-import re
-import logging
-from .entities.series import Serie
-import traceback
-from ..infrastructure.logging.GlobalLogger import error_logger, noKeyFound_logger
-from .exceptions.Exceptions import NoKeyFoundException, MatchNotFoundError
-from .providers.base_provider import Loader
-
-
-class SerieScanner:
-    def __init__(self, basePath: str, loader: Loader):
-        self.directory = basePath
-        self.folderDict: dict[str, Serie] = {}  # Proper initialization
-        self.loader = loader
-        logging.info(f"Initialized Loader with base path: {self.directory}")
-
-    def Reinit(self):
-        self.folderDict: dict[str, Serie] = {}  # Proper initialization
-
-
-    def is_null_or_whitespace(self, s):
-        return s is None or s.strip() == ""
-
-    def GetTotalToScan(self):
-        result = self.__find_mp4_files()
-        return sum(1 for _ in result)
-
-    def Scan(self, callback):
-        logging.info("Starting process to load missing episodes")
-        result = self.__find_mp4_files()
-        counter = 0
-        for folder, mp4_files in result:
-            try:
-                counter += 1
-                callback(folder, counter)
-                serie = self.__ReadDataFromFile(folder)
-                if (serie != None and not self.is_null_or_whitespace(serie.key)):
-                    missings, site = self.__GetMissingEpisodesAndSeason(serie.key, mp4_files)
-                    serie.episodeDict = missings
-                    serie.folder = folder
-                    serie.save_to_file(os.path.join(os.path.join(self.directory, folder), 'data'))
-                    if (serie.key in self.folderDict):
-                        logging.ERROR(f"dublication found: {serie.key}");
-                        pass
-                    self.folderDict[serie.key] = serie
-                    noKeyFound_logger.info(f"Saved Serie: '{str(serie)}'")
-            except NoKeyFoundException as nkfe:
-                NoKeyFoundException.error(f"Error processing folder '{folder}': {nkfe}")
-            except Exception as e:
-                error_logger.error(f"Folder: '{folder}' - Unexpected error processing folder '{folder}': {e} \n {traceback.format_exc()}")
-                continue
-
-
-    def __find_mp4_files(self):
-        logging.info("Scanning for .mp4 files")
-        for anime_name in os.listdir(self.directory):
-            anime_path = os.path.join(self.directory, anime_name)
-            if os.path.isdir(anime_path):
-                mp4_files = []
-                has_files = False
-                for root, _, files in os.walk(anime_path):
-                    for file in files:
-                        if file.endswith(".mp4"):
-                            mp4_files.append(os.path.join(root, file))
-                            has_files = True
-                yield anime_name, mp4_files if has_files else []
-
-    def __remove_year(self, input_string: str):
-        cleaned_string = re.sub(r'\(\d{4}\)', '', input_string).strip()
-        logging.debug(f"Removed year from '{input_string}' -> '{cleaned_string}'")
-        return cleaned_string
-
-    def __ReadDataFromFile(self, folder_name: str):
-        folder_path = os.path.join(self.directory, folder_name)
-        key = None
-        key_file = os.path.join(folder_path, 'key')
-        serie_file = os.path.join(folder_path, 'data')
-
-        if os.path.exists(key_file):
-            with open(key_file, 'r') as file:
-                key = file.read().strip()
-                logging.info(f"Key found for folder '{folder_name}': {key}")
-                return Serie(key, "", "aniworld.to", folder_name, dict())
-
-        if os.path.exists(serie_file):
-            with open(serie_file, "rb") as file:
-                logging.info(f"load serie_file from '{folder_name}': {serie_file}")
-                return Serie.load_from_file(serie_file)
-
-        return None
-
-
-    def __GetEpisodeAndSeason(self, filename: str):
-        pattern = r'S(\d+)E(\d+)'
-        match = re.search(pattern, filename)
-        if match:
-            season = match.group(1)
-            episode = match.group(2)
-            logging.debug(f"Extracted season {season}, episode {episode} from '{filename}'")
-            return int(season), int(episode)
-        else:
-            logging.error(f"Failed to find season/episode pattern in '{filename}'")
-            raise MatchNotFoundError("Season and episode pattern not found in the filename.")
-
-    def __GetEpisodesAndSeasons(self, mp4_files: []):
-        episodes_dict = {}
-
-        for file in mp4_files:
-            season, episode = self.__GetEpisodeAndSeason(file)
-
-            if season in episodes_dict:
-                episodes_dict[season].append(episode)
-            else:
-                episodes_dict[season] = [episode]
-        return episodes_dict
-
-    def __GetMissingEpisodesAndSeason(self, key: str, mp4_files: []):
-        expected_dict = self.loader.get_season_episode_count(key) # key season , value count of episodes
-        filedict = self.__GetEpisodesAndSeasons(mp4_files)
-        episodes_dict = {}
-        for season, expected_count in expected_dict.items():
-            existing_episodes = filedict.get(season, [])
-            missing_episodes = [ep for ep in range(1, expected_count + 1) if ep not in existing_episodes and self.loader.IsLanguage(season, ep, key)]
-
-            if missing_episodes:
-                episodes_dict[season] = missing_episodes
-
-        return episodes_dict, "aniworld.to"
-
-

src/core/SeriesApp.py

@@ -1,38 +0,0 @@
-from src.core.entities.SerieList import SerieList
-from src.core.providers.provider_factory import Loaders
-from src.core.SerieScanner import SerieScanner
-
-
-class SeriesApp:
-    _initialization_count = 0
-
-    def __init__(self, directory_to_search: str):
-        SeriesApp._initialization_count += 1        # Only show initialization message for the first instance
-        if SeriesApp._initialization_count <= 1:
-            print("Please wait while initializing...")
-        
-        self.progress = None
-        self.directory_to_search = directory_to_search
-        self.Loaders = Loaders()
-        self.loader = self.Loaders.GetLoader(key="aniworld.to")
-        self.SerieScanner = SerieScanner(directory_to_search, self.loader)
-
-        self.List = SerieList(self.directory_to_search)
-        self.__InitList__()
-
-    def __InitList__(self):
-        self.series_list = self.List.GetMissingEpisode()
-
-    def search(self, words: str) -> list:
-        return self.loader.Search(words)
-
-    def download(self, serieFolder: str, season: int, episode: int, key: str, callback) -> bool:
-        self.loader.Download(self.directory_to_search, serieFolder, season, episode, key, "German Dub", callback)
-
-    def ReScan(self, callback):
-
-        self.SerieScanner.Reinit()
-        self.SerieScanner.Scan(callback)
-
-        self.List = SerieList(self.directory_to_search)
-        self.__InitList__()

src/core/entities/SerieList.py

@@ -1,56 +0,0 @@
-import os
-import json
-import logging
-from .series import Serie
-class SerieList:
-    def __init__(self, basePath: str):
-        self.directory = basePath
-        self.folderDict: dict[str, Serie] = {}  # Proper initialization
-        self.load_series()
-
-    def add(self, serie: Serie):
-        if (not self.contains(serie.key)):
-            dataPath = os.path.join(self.directory, serie.folder, "data")
-            animePath = os.path.join(self.directory, serie.folder)
-            os.makedirs(animePath, exist_ok=True)
-            if not os.path.isfile(dataPath):
-                serie.save_to_file(dataPath)
-                self.folderDict[serie.folder] = serie;
-
-    def contains(self, key: str) -> bool:
-        for k, value in self.folderDict.items():
-            if value.key == key:
-                return True
-        return False
-
-    def load_series(self):
-        """ Scan folders and load data files """
-        logging.info(f"Scanning anime folders in: {self.directory}")
-        for anime_folder in os.listdir(self.directory):
-            anime_path = os.path.join(self.directory, anime_folder, "data")
-            if os.path.isfile(anime_path):
-                logging.debug(f"Found data folder: {anime_path}")
-                self.load_data(anime_folder, anime_path)
-            else:
-                logging.warning(f"Skipping {anime_folder} - No data folder found")
-
-    def load_data(self, anime_folder, data_path):
-        """ Load pickle files from the data folder """
-        try:
-            self.folderDict[anime_folder] = Serie.load_from_file(data_path)
-            logging.debug(f"Successfully loaded {data_path} for {anime_folder}")
-        except Exception as e:
-            logging.error(f"Failed to load {data_path} in {anime_folder}: {e}")
-
-    def GetMissingEpisode(self):
-        """Find all series with a non-empty episodeDict"""
-        return [serie for serie in self.folderDict.values() if len(serie.episodeDict) > 0]
-    
-    def GetList(self):
-        """Get all series in the list"""
-        return list(self.folderDict.values())
-
-
-#k = AnimeList("\\\\sshfs.r\\ubuntu@192.168.178.43\\media\\serien\\Serien")
-#bbabab = k.GetMissingEpisode()
-#print(bbabab)

src/core/entities/series.py

@@ -1,82 +0,0 @@
-import json
-
-class Serie:
-    def __init__(self, key: str, name: str, site: str, folder: str, episodeDict: dict[int, list[int]]):
-        self._key = key
-        self._name = name
-        self._site = site
-        self._folder = folder
-        self._episodeDict = episodeDict
-    def __str__(self):
-        """String representation of Serie object"""
-        return f"Serie(key='{self.key}', name='{self.name}', site='{self.site}', folder='{self.folder}', episodeDict={self.episodeDict})"
-
-    @property
-    def key(self) -> str:
-        return self._key
-
-    @key.setter
-    def key(self, value: str):
-        self._key = value
-
-    @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:
-        return self._folder
-
-    @folder.setter
-    def folder(self, value: str):
-        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
-
-    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()}
-        }
-
-    @staticmethod
-    def from_dict(data: dict):
-        """Create a Serie object from dictionary."""
-        episode_dict = {int(k): v for k, v in data["episodeDict"].items()}  # Convert keys to int
-        return Serie(data["key"], data["name"], data["site"], data["folder"], episode_dict)
-
-
-    def save_to_file(self, filename: str):
-        """Save Serie object to JSON file."""
-        with open(filename, "w") 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."""
-        with open(filename, "r") as file:
-            data = json.load(file)
-        return cls.from_dict(data)

src/core/providers/aniworld_provider.py

@@ -1,343 +0,0 @@
-import os
-import re
-import logging
-import json
-import requests
-import html
-from urllib.parse import quote
-
-from bs4 import BeautifulSoup
-
-from fake_useragent import UserAgent
-from requests.adapters import HTTPAdapter
-from urllib3.util.retry import Retry
-
-from .base_provider import Loader
-from ..interfaces.providers import Providers
-from yt_dlp import YoutubeDL
-import shutil
-
-# Read timeout from environment variable, default to 600 seconds (10 minutes)
-timeout = int(os.getenv("DOWNLOAD_TIMEOUT", 600))
-
-download_error_logger = logging.getLogger("DownloadErrors")
-download_error_handler = logging.FileHandler("../../download_errors.log")
-download_error_handler.setLevel(logging.ERROR)
-
-noKeyFound_logger = logging.getLogger("NoKeyFound")
-noKeyFound_handler = logging.FileHandler("../../NoKeyFound.log")
-noKeyFound_handler.setLevel(logging.ERROR)
-
-class AniworldLoader(Loader):
-    def __init__(self):
-        self.SUPPORTED_PROVIDERS = ["VOE", "Doodstream", "Vidmoly", "Vidoza", "SpeedFiles", "Streamtape", "Luluvdo"]
-        self.AniworldHeaders = {
-                                    "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
-                                    "accept-encoding": "gzip, deflate, br, zstd",
-                                    "accept-language": "de,de-DE;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6",
-                                    "cache-control": "max-age=0",
-                                    "priority": "u=0, i",
-                                    "sec-ch-ua": '"Chromium";v="136", "Microsoft Edge";v="136", "Not.A/Brand";v="99"',
-                                    "sec-ch-ua-mobile": "?0",
-                                    "sec-ch-ua-platform": '"Windows"',
-                                    "sec-fetch-dest": "document",
-                                    "sec-fetch-mode": "navigate",
-                                    "sec-fetch-site": "none",
-                                    "sec-fetch-user": "?1",
-                                    "upgrade-insecure-requests": "1",
-                                    "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36 Edg/136.0.0.0"
-                                }
-        self.INVALID_PATH_CHARS = ['<', '>', ':', '"', '/', '\\', '|', '?', '*', '&']
-        self.RANDOM_USER_AGENT = UserAgent().random
-        self.LULUVDO_USER_AGENT = "Mozilla/5.0 (Android 15; Mobile; rv:132.0) Gecko/132.0 Firefox/132.0"
-        self.PROVIDER_HEADERS = {
-                                "Vidmoly": ['Referer: "https://vidmoly.to"'],
-                                "Doodstream": ['Referer: "https://dood.li/"'],
-                                "VOE": [f'User-Agent: {self.RANDOM_USER_AGENT}'],
-                                "Luluvdo": [
-                                    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()
-
-        # 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],  # Retry for specific HTTP errors
-            allowed_methods=["GET"]
-        )
-
-        adapter = HTTPAdapter(max_retries=retries)
-        self.session.mount("https://", adapter)
-        self.DEFAULT_REQUEST_TIMEOUT = 30
-
-        self._KeyHTMLDict = {}
-        self._EpisodeHTMLDict = {}
-        self.Providers = Providers()
-
-    def ClearCache(self):
-        self._KeyHTMLDict = {}
-        self._EpisodeHTMLDict = {}
-
-    def RemoveFromCache(self):
-        self._EpisodeHTMLDict = {}
-
-    def Search(self, word: str) -> list:
-        search_url = f"{self.ANIWORLD_TO}/ajax/seriesSearch?keyword={quote(word)}"
-        anime_list = self.fetch_anime_list(search_url)
-
-        return anime_list
-
-
-    def fetch_anime_list(self, url: str) -> list:
-        response = self.session.get(url, timeout=self.DEFAULT_REQUEST_TIMEOUT)
-        response.raise_for_status()
-
-        clean_text = response.text.strip()
-
-        try:
-            decoded_data = json.loads(html.unescape(clean_text))
-            return decoded_data if isinstance(decoded_data, list) else []
-        except json.JSONDecodeError:
-            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)
-                return decoded_data if isinstance(decoded_data, list) else []
-            except (requests.RequestException, json.JSONDecodeError) as exc:
-                raise ValueError("Could not get valid anime: ") from exc
-
-    def _GetLanguageKey(self, language: str) -> int:
-        languageCode = 0
-        if (language == "German Dub"):
-            languageCode = 1
-        if (language == "English Sub"):
-            languageCode = 2
-        if (language == "German Sub"):
-            languageCode = 3
-        return languageCode
-    def IsLanguage(self, season: int, episode: int, key: str, language: str = "German Dub") -> bool:
-        """
-               Language Codes:
-                   1: German Dub
-                   2: English Sub
-                   3: German Sub
-               """
-        languageCode = self._GetLanguageKey(language)
-
-        episode_soup = BeautifulSoup(self._GetEpisodeHTML(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))
-
-        return languageCode in languages
-
-    def Download(self, baseDirectory: str, serieFolder: str, season: int, episode: int, key: str, language: str = "German Dub", progress_callback: callable = None) -> bool:
-        sanitized_anime_title = ''.join(
-            char for char in self.GetTitle(key) if char not in self.INVALID_PATH_CHARS
-        )
-
-        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"
-            )
-
-        folderPath = os.path.join(os.path.join(baseDirectory, serieFolder), f"Season {season}")
-        output_path = os.path.join(folderPath, output_file)
-        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)
-
-        for provider in self.SUPPORTED_PROVIDERS:
-            link, header = self._get_direct_link_from_provider(season, episode, key, language)
-            ydl_opts = {
-                'fragment_retries': float('inf'),
-                'outtmpl': temp_Path,
-                'quiet': True,
-                'no_warnings': True,
-                'progress_with_newline': False,
-                'nocheckcertificate': True,
-            }
-
-            if header:
-                ydl_opts['http_headers'] = header
-            if progress_callback:
-                ydl_opts['progress_hooks'] = [progress_callback]
-
-            with YoutubeDL(ydl_opts) as ydl:
-                ydl.download([link])
-
-            if (os.path.exists(temp_Path)):
-                shutil.copy(temp_Path, output_path)
-                os.remove(temp_Path)
-            break
-        self.ClearCache()
-
-
-    def GetSiteKey(self) -> str:
-        return "aniworld.to"
-
-    def GetTitle(self, key: str) -> str:
-        soup = BeautifulSoup(self._GetKeyHTML(key).content, 'html.parser')
-        title_div = soup.find('div', class_='series-title')
-
-        if title_div:
-            return title_div.find('h1').find('span').text
-
-        return ""
-
-    def _GetKeyHTML(self, key: str):
-        if key in self._KeyHTMLDict:
-         return self._KeyHTMLDict[key]
-
-
-        self._KeyHTMLDict[key] = self.session.get(
-            f"{self.ANIWORLD_TO}/anime/stream/{key}",
-            timeout=self.DEFAULT_REQUEST_TIMEOUT
-        )
-        return self._KeyHTMLDict[key]
-    def _GetEpisodeHTML(self, season: int, episode: int, key: str):
-        if key in self._EpisodeHTMLDict:
-         return self._EpisodeHTMLDict[(key, season, episode)]
-
-
-        link = (
-            f"{self.ANIWORLD_TO}/anime/stream/{key}/"
-            f"staffel-{season}/episode-{episode}"
-        )
-        html = self.session.get(link, timeout=self.DEFAULT_REQUEST_TIMEOUT)
-        self._EpisodeHTMLDict[(key, season, episode)] = html
-        return self._EpisodeHTMLDict[(key, season, episode)]
-
-    def _get_provider_from_html(self, season: int, episode: int, key: str) -> dict:
-        """
-            Parses the HTML content to extract streaming providers,
-            their language keys, and redirect links.
-
-            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'},
-                'Doodstream': {1: 'https://aniworld.to/redirect/1987922',
-                               2: 'https://aniworld.to/redirect/2700342'},
-                ...
-            }
-
-            Access redirect link with:
-            print(self.provider["VOE"][2])
-        """
-
-        soup = BeautifulSoup(self._GetEpisodeHTML(season, episode, key).content, 'html.parser')
-        providers = {}
-
-        episode_links = soup.find_all(
-            'li', class_=lambda x: x and x.startswith('episodeLink')
-        )
-
-        if not episode_links:
-            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['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}"
-
-
-        return providers
-    def _get_redirect_link(self, season: int, episode: int, key: str, language: str = "German Dub") -> str:
-        languageCode = self._GetLanguageKey(language)
-        if (self.IsLanguage(season, episode, key, language)):
-            for provider_name, lang_dict in self._get_provider_from_html(season, episode, key).items():
-                if languageCode in lang_dict:
-                    return(lang_dict[languageCode], provider_name)
-                    break
-        return None
-    def _get_embeded_link(self, season: int, episode: int, key: str, language: str = "German Dub"):
-        redirect_link, provider_name = self._get_redirect_link(season, episode, key, language)
-
-        embeded_link = self.session.get(
-            redirect_link, timeout=self.DEFAULT_REQUEST_TIMEOUT,
-            headers={'User-Agent': self.RANDOM_USER_AGENT}).url
-        return embeded_link
-    def _get_direct_link_from_provider(self, season: int, episode: int, key: str, language: str = "German Dub") -> str:
-        """
-            providers = {
-                "Vidmoly": get_direct_link_from_vidmoly,
-                "Vidoza": get_direct_link_from_vidoza,
-                "VOE": get_direct_link_from_voe,
-                "Doodstream": get_direct_link_from_doodstream,
-                "SpeedFiles": get_direct_link_from_speedfiles,
-                "Luluvdo": get_direct_link_from_luluvdo
-            }
-
-        """
-        embeded_link = self._get_embeded_link(season, episode, key, language)
-        if embeded_link is None:
-            return None
-
-        return self.Providers.GetProvider("VOE").GetLink(embeded_link, self.DEFAULT_REQUEST_TIMEOUT)
-
-    def get_season_episode_count(self, slug : str) -> dict:
-        base_url = f"{self.ANIWORLD_TO}/anime/stream/{slug}/"
-        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
-
-        episode_counts = {}
-
-        for season in range(1, number_of_seasons + 1):
-            season_url = f"{base_url}staffel-{season}"
-            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)
-
-        return episode_counts

src/core/providers/base_provider.py

@@ -1,27 +0,0 @@
-from abc import ABC, abstractmethod
-
-
-class Loader(ABC):
-    @abstractmethod
-    def Search(self, word: str) -> list:
-        pass
-
-    @abstractmethod
-    def IsLanguage(self, season: int, episode: int, key: str, language: str = "German Dub") -> bool:
-        pass
-
-    @abstractmethod
-    def Download(self, baseDirectory: str, serieFolder: str, season: int, episode: int, key: str, progress_callback: callable = None) -> bool:
-        pass
-
-    @abstractmethod
-    def GetSiteKey(self) -> str:
-        pass
-
-    @abstractmethod
-    def GetTitle(self) -> str:
-        pass
-
-    @abstractmethod
-    def get_season_episode_count(self, slug: str) -> dict:
-        pass

src/core/providers/enhanced_provider.py

@@ -1,671 +0,0 @@
-"""
-Enhanced AniWorld Loader with Error Handling and Recovery
-
-This module extends the original AniWorldLoader with comprehensive
-error handling, retry mechanisms, and recovery strategies.
-"""
-
-import os
-import re
-import logging
-import json
-import requests
-import html
-from urllib.parse import quote
-import time
-import hashlib
-from typing import Optional, Dict, Any, Callable
-
-from bs4 import BeautifulSoup
-from fake_useragent import UserAgent
-from requests.adapters import HTTPAdapter
-from urllib3.util.retry import Retry
-from yt_dlp import YoutubeDL
-import shutil
-
-from .base_provider import Loader
-from ..interfaces.providers import Providers
-from error_handler import (
-    with_error_recovery, 
-    recovery_strategies,
-    NetworkError,
-    DownloadError,
-    RetryableError,
-    NonRetryableError,
-    file_corruption_detector
-)
-
-
-class EnhancedAniWorldLoader(Loader):
-    """Enhanced AniWorld loader with comprehensive error handling."""
-    
-    def __init__(self):
-        super().__init__()
-        self.logger = logging.getLogger(__name__)
-        self.SUPPORTED_PROVIDERS = ["VOE", "Doodstream", "Vidmoly", "Vidoza", "SpeedFiles", "Streamtape", "Luluvdo"]
-        
-        self.AniworldHeaders = {
-            "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8",
-            "accept-encoding": "gzip, deflate, br, zstd",
-            "accept-language": "de,de-DE;q=0.9,en;q=0.8,en-GB;q=0.7,en-US;q=0.6",
-            "cache-control": "max-age=0",
-            "priority": "u=0, i",
-            "sec-ch-ua": '"Chromium";v="136", "Microsoft Edge";v="136", "Not.A/Brand";v="99"',
-            "sec-ch-ua-mobile": "?0",
-            "sec-ch-ua-platform": '"Windows"',
-            "sec-fetch-dest": "document",
-            "sec-fetch-mode": "navigate",
-            "sec-fetch-site": "none",
-            "sec-fetch-user": "?1",
-            "upgrade-insecure-requests": "1",
-            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36 Edg/136.0.0.0"
-        }
-        
-        self.INVALID_PATH_CHARS = ['<', '>', ':', '"', '/', '\\', '|', '?', '*', '&']
-        self.RANDOM_USER_AGENT = UserAgent().random
-        self.LULUVDO_USER_AGENT = "Mozilla/5.0 (Android 15; Mobile; rv:132.0) Gecko/132.0 Firefox/132.0"
-        
-        self.PROVIDER_HEADERS = {
-            "Vidmoly": ['Referer: "https://vidmoly.to"'],
-            "Doodstream": ['Referer: "https://dood.li/"'],
-            "VOE": [f'User-Agent: {self.RANDOM_USER_AGENT}'],
-            "Luluvdo": [
-                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.DEFAULT_REQUEST_TIMEOUT = 30
-        
-        # Initialize session with enhanced retry configuration
-        self.session = self._create_robust_session()
-        
-        # Cache dictionaries
-        self._KeyHTMLDict = {}
-        self._EpisodeHTMLDict = {}
-        
-        # Provider manager
-        self.Providers = Providers()
-        
-        # Download statistics
-        self.download_stats = {
-            'total_downloads': 0,
-            'successful_downloads': 0,
-            'failed_downloads': 0,
-            'retried_downloads': 0
-        }
-        
-        # Read timeout from environment variable
-        self.download_timeout = int(os.getenv("DOWNLOAD_TIMEOUT", 600))
-        
-        # Setup logging
-        self._setup_logging()
-    
-    def _create_robust_session(self) -> requests.Session:
-        """Create a session with robust retry and error handling configuration."""
-        session = requests.Session()
-        
-        # Enhanced retry strategy
-        retries = Retry(
-            total=5,
-            backoff_factor=2,  # More aggressive backoff
-            status_forcelist=[408, 429, 500, 502, 503, 504, 520, 521, 522, 523, 524],
-            allowed_methods=["GET", "POST", "HEAD"],
-            raise_on_status=False  # Handle status errors manually
-        )
-        
-        adapter = HTTPAdapter(
-            max_retries=retries,
-            pool_connections=10,
-            pool_maxsize=20,
-            pool_block=True
-        )
-        
-        session.mount("https://", adapter)
-        session.mount("http://", adapter)
-        
-        # Set default headers
-        session.headers.update(self.AniworldHeaders)
-        
-        return session
-    
-    def _setup_logging(self):
-        """Setup specialized logging for download errors and missing keys."""
-        # Download error logger
-        self.download_error_logger = logging.getLogger("DownloadErrors")
-        download_error_handler = logging.FileHandler("../../download_errors.log")
-        download_error_handler.setLevel(logging.ERROR)
-        download_error_formatter = logging.Formatter(
-            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-        )
-        download_error_handler.setFormatter(download_error_formatter)
-        
-        if not self.download_error_logger.handlers:
-            self.download_error_logger.addHandler(download_error_handler)
-        self.download_error_logger.setLevel(logging.ERROR)
-        
-        # No key found logger
-        self.nokey_logger = logging.getLogger("NoKeyFound")
-        nokey_handler = logging.FileHandler("../../NoKeyFound.log")
-        nokey_handler.setLevel(logging.ERROR)
-        nokey_handler.setFormatter(download_error_formatter)
-        
-        if not self.nokey_logger.handlers:
-            self.nokey_logger.addHandler(nokey_handler)
-        self.nokey_logger.setLevel(logging.ERROR)
-    
-    def ClearCache(self):
-        """Clear all cached data."""
-        self._KeyHTMLDict.clear()
-        self._EpisodeHTMLDict.clear()
-        self.logger.debug("Cache cleared")
-    
-    def RemoveFromCache(self):
-        """Remove episode HTML cache."""
-        self._EpisodeHTMLDict.clear()
-        self.logger.debug("Episode cache cleared")
-    
-    @with_error_recovery(max_retries=3, context="anime_search")
-    def Search(self, word: str) -> list:
-        """Search for anime with error handling."""
-        if not word or not word.strip():
-            raise ValueError("Search term cannot be empty")
-        
-        search_url = f"{self.ANIWORLD_TO}/ajax/seriesSearch?keyword={quote(word)}"
-        
-        try:
-            return self._fetch_anime_list_with_recovery(search_url)
-        except Exception as e:
-            self.logger.error(f"Search failed for term '{word}': {e}")
-            raise RetryableError(f"Search failed: {e}") from e
-    
-    def _fetch_anime_list_with_recovery(self, url: str) -> list:
-        """Fetch anime list with comprehensive error handling."""
-        try:
-            response = recovery_strategies.handle_network_failure(
-                self.session.get,
-                url,
-                timeout=self.DEFAULT_REQUEST_TIMEOUT
-            )
-            
-            if not response.ok:
-                if response.status_code == 404:
-                    raise NonRetryableError(f"URL not found: {url}")
-                elif response.status_code == 403:
-                    raise NonRetryableError(f"Access forbidden: {url}")
-                elif response.status_code >= 500:
-                    raise RetryableError(f"Server error {response.status_code}")
-                else:
-                    raise RetryableError(f"HTTP error {response.status_code}")
-            
-            return self._parse_anime_response(response.text)
-            
-        except (requests.RequestException, ConnectionError) as e:
-            raise NetworkError(f"Network error during anime search: {e}") from e
-    
-    def _parse_anime_response(self, response_text: str) -> list:
-        """Parse anime search response with error handling."""
-        if not response_text or not response_text.strip():
-            raise ValueError("Empty response from server")
-        
-        clean_text = response_text.strip()
-        
-        # Try multiple parsing strategies
-        parsing_strategies = [
-            lambda text: json.loads(html.unescape(text)),
-            lambda text: json.loads(text.encode('utf-8').decode('utf-8-sig')),
-            lambda text: json.loads(re.sub(r'[\x00-\x1F\x7F-\x9F]', '', text))
-        ]
-        
-        for i, strategy in enumerate(parsing_strategies):
-            try:
-                decoded_data = strategy(clean_text)
-                if isinstance(decoded_data, list):
-                    self.logger.debug(f"Successfully parsed anime response with strategy {i + 1}")
-                    return decoded_data
-                else:
-                    self.logger.warning(f"Strategy {i + 1} returned non-list data: {type(decoded_data)}")
-            except json.JSONDecodeError as e:
-                self.logger.debug(f"Parsing strategy {i + 1} failed: {e}")
-                continue
-        
-        raise ValueError("Could not parse anime search response with any strategy")
-    
-    def _GetLanguageKey(self, language: str) -> int:
-        """Get numeric language code."""
-        language_map = {
-            "German Dub": 1,
-            "English Sub": 2, 
-            "German Sub": 3
-        }
-        return language_map.get(language, 0)
-    
-    @with_error_recovery(max_retries=2, context="language_check")
-    def IsLanguage(self, season: int, episode: int, key: str, language: str = "German Dub") -> bool:
-        """Check if episode is available in specified language with error handling."""
-        try:
-            languageCode = self._GetLanguageKey(language)
-            if languageCode == 0:
-                raise ValueError(f"Unknown language: {language}")
-            
-            episode_response = self._GetEpisodeHTML(season, episode, key)
-            soup = BeautifulSoup(episode_response.content, 'html.parser')
-            
-            change_language_box_div = soup.find('div', class_='changeLanguageBox')
-            if not change_language_box_div:
-                self.logger.debug(f"No language box found for {key} S{season}E{episode}")
-                return False
-            
-            img_tags = change_language_box_div.find_all('img')
-            available_languages = []
-            
-            for img in img_tags:
-                lang_key = img.get('data-lang-key')
-                if lang_key and lang_key.isdigit():
-                    available_languages.append(int(lang_key))
-            
-            is_available = languageCode in available_languages
-            self.logger.debug(f"Language check for {key} S{season}E{episode} - "
-                            f"Requested: {languageCode}, Available: {available_languages}, "
-                            f"Result: {is_available}")
-            
-            return is_available
-            
-        except Exception as e:
-            self.logger.error(f"Language check failed for {key} S{season}E{episode}: {e}")
-            raise RetryableError(f"Language check failed: {e}") from e
-    
-    def Download(self, baseDirectory: str, serieFolder: str, season: int, episode: int, 
-                key: str, language: str = "German Dub", progress_callback: Callable = None) -> bool:
-        """Download episode with comprehensive error handling and recovery."""
-        self.download_stats['total_downloads'] += 1
-        
-        try:
-            # Validate inputs
-            if not all([baseDirectory, serieFolder, key]):
-                raise ValueError("Missing required parameters for download")
-            
-            if season < 0 or episode < 0:
-                raise ValueError("Season and episode must be non-negative")
-            
-            # Prepare file paths
-            sanitized_anime_title = ''.join(
-                char for char in self.GetTitle(key) if char not in self.INVALID_PATH_CHARS
-            )
-            
-            if not sanitized_anime_title:
-                sanitized_anime_title = f"Unknown_{key}"
-            
-            # Generate output filename
-            if season == 0:
-                output_file = f"{sanitized_anime_title} - Movie {episode:02} - ({language}).mp4"
-            else:
-                output_file = f"{sanitized_anime_title} - S{season:02}E{episode:03} - ({language}).mp4"
-            
-            # Create directory structure
-            folder_path = os.path.join(baseDirectory, serieFolder, f"Season {season}")
-            output_path = os.path.join(folder_path, output_file)
-            
-            # Check if file already exists and is valid
-            if os.path.exists(output_path):
-                if file_corruption_detector.is_valid_video_file(output_path):
-                    self.logger.info(f"File already exists and is valid: {output_file}")
-                    self.download_stats['successful_downloads'] += 1
-                    return True
-                else:
-                    self.logger.warning(f"Existing file appears corrupted, removing: {output_path}")
-                    try:
-                        os.remove(output_path)
-                    except Exception as e:
-                        self.logger.error(f"Failed to remove corrupted file: {e}")
-            
-            os.makedirs(folder_path, exist_ok=True)
-            
-            # Create temp directory
-            temp_dir = "./Temp/"
-            os.makedirs(temp_dir, exist_ok=True)
-            temp_path = os.path.join(temp_dir, output_file)
-            
-            # Attempt download with recovery strategies
-            success = self._download_with_recovery(
-                season, episode, key, language, temp_path, output_path, progress_callback
-            )
-            
-            if success:
-                self.download_stats['successful_downloads'] += 1
-                self.logger.info(f"Successfully downloaded: {output_file}")
-            else:
-                self.download_stats['failed_downloads'] += 1
-                self.download_error_logger.error(
-                    f"Download failed for {key} S{season}E{episode} ({language})"
-                )
-            
-            return success
-            
-        except Exception as e:
-            self.download_stats['failed_downloads'] += 1
-            self.download_error_logger.error(
-                f"Download error for {key} S{season}E{episode}: {e}", exc_info=True
-            )
-            raise DownloadError(f"Download failed: {e}") from e
-        finally:
-            self.ClearCache()
-    
-    def _download_with_recovery(self, season: int, episode: int, key: str, language: str,
-                               temp_path: str, output_path: str, progress_callback: Callable) -> bool:
-        """Attempt download with multiple providers and recovery strategies."""
-        
-        for provider_name in self.SUPPORTED_PROVIDERS:
-            try:
-                self.logger.info(f"Attempting download with provider: {provider_name}")
-                
-                # Get download link and headers for provider
-                link, headers = recovery_strategies.handle_network_failure(
-                    self._get_direct_link_from_provider,
-                    season, episode, key, language
-                )
-                
-                if not link:
-                    self.logger.warning(f"No download link found for provider: {provider_name}")
-                    continue
-                
-                # Configure yt-dlp options
-                ydl_opts = {
-                    'fragment_retries': float('inf'),
-                    'outtmpl': temp_path,
-                    'quiet': True,
-                    'no_warnings': True,
-                    'progress_with_newline': False,
-                    'nocheckcertificate': True,
-                    'socket_timeout': self.download_timeout,
-                    'http_chunk_size': 1024 * 1024,  # 1MB chunks
-                }
-                
-                if headers:
-                    ydl_opts['http_headers'] = headers
-                
-                if progress_callback:
-                    ydl_opts['progress_hooks'] = [progress_callback]
-                
-                # Perform download with recovery
-                success = recovery_strategies.handle_download_failure(
-                    self._perform_ytdl_download,
-                    temp_path,
-                    ydl_opts,
-                    link
-                )
-                
-                if success and os.path.exists(temp_path):
-                    # Verify downloaded file
-                    if file_corruption_detector.is_valid_video_file(temp_path):
-                        # Move to final location
-                        shutil.copy2(temp_path, output_path)
-                        
-                        # Clean up temp file
-                        try:
-                            os.remove(temp_path)
-                        except Exception as e:
-                            self.logger.warning(f"Failed to remove temp file: {e}")
-                        
-                        return True
-                    else:
-                        self.logger.warning(f"Downloaded file failed validation: {temp_path}")
-                        try:
-                            os.remove(temp_path)
-                        except Exception:
-                            pass
-                
-            except Exception as e:
-                self.logger.warning(f"Provider {provider_name} failed: {e}")
-                self.download_stats['retried_downloads'] += 1
-                continue
-        
-        return False
-    
-    def _perform_ytdl_download(self, ydl_opts: Dict[str, Any], link: str) -> bool:
-        """Perform actual download using yt-dlp."""
-        try:
-            with YoutubeDL(ydl_opts) as ydl:
-                ydl.download([link])
-            return True
-        except Exception as e:
-            self.logger.error(f"yt-dlp download failed: {e}")
-            raise DownloadError(f"Download failed: {e}") from e
-    
-    @with_error_recovery(max_retries=2, context="get_title")
-    def GetTitle(self, key: str) -> str:
-        """Get anime title with error handling."""
-        try:
-            soup = BeautifulSoup(self._GetKeyHTML(key).content, 'html.parser')
-            title_div = soup.find('div', class_='series-title')
-            
-            if title_div:
-                title_span = title_div.find('h1')
-                if title_span:
-                    span = title_span.find('span')
-                    if span:
-                        return span.text.strip()
-            
-            self.logger.warning(f"Could not extract title for key: {key}")
-            return f"Unknown_Title_{key}"
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get title for key {key}: {e}")
-            raise RetryableError(f"Title extraction failed: {e}") from e
-    
-    def GetSiteKey(self) -> str:
-        """Get site identifier."""
-        return "aniworld.to"
-    
-    @with_error_recovery(max_retries=2, context="get_key_html")
-    def _GetKeyHTML(self, key: str):
-        """Get cached HTML for anime key."""
-        if key in self._KeyHTMLDict:
-            return self._KeyHTMLDict[key]
-        
-        try:
-            url = f"{self.ANIWORLD_TO}/anime/stream/{key}"
-            response = recovery_strategies.handle_network_failure(
-                self.session.get,
-                url,
-                timeout=self.DEFAULT_REQUEST_TIMEOUT
-            )
-            
-            if not response.ok:
-                if response.status_code == 404:
-                    self.nokey_logger.error(f"Anime key not found: {key}")
-                    raise NonRetryableError(f"Anime key not found: {key}")
-                else:
-                    raise RetryableError(f"HTTP error {response.status_code} for key {key}")
-            
-            self._KeyHTMLDict[key] = response
-            return self._KeyHTMLDict[key]
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get HTML for key {key}: {e}")
-            raise
-    
-    @with_error_recovery(max_retries=2, context="get_episode_html")
-    def _GetEpisodeHTML(self, season: int, episode: int, key: str):
-        """Get cached HTML for specific episode."""
-        cache_key = (key, season, episode)
-        if cache_key in self._EpisodeHTMLDict:
-            return self._EpisodeHTMLDict[cache_key]
-        
-        try:
-            url = f"{self.ANIWORLD_TO}/anime/stream/{key}/staffel-{season}/episode-{episode}"
-            response = recovery_strategies.handle_network_failure(
-                self.session.get,
-                url,
-                timeout=self.DEFAULT_REQUEST_TIMEOUT
-            )
-            
-            if not response.ok:
-                if response.status_code == 404:
-                    raise NonRetryableError(f"Episode not found: {key} S{season}E{episode}")
-                else:
-                    raise RetryableError(f"HTTP error {response.status_code} for episode")
-            
-            self._EpisodeHTMLDict[cache_key] = response
-            return self._EpisodeHTMLDict[cache_key]
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get episode HTML for {key} S{season}E{episode}: {e}")
-            raise
-    
-    def _get_provider_from_html(self, season: int, episode: int, key: str) -> dict:
-        """Extract providers from HTML with error handling."""
-        try:
-            soup = BeautifulSoup(self._GetEpisodeHTML(season, episode, key).content, 'html.parser')
-            providers = {}
-            
-            episode_links = soup.find_all(
-                'li', class_=lambda x: x and x.startswith('episodeLink')
-            )
-            
-            if not episode_links:
-                self.logger.warning(f"No episode links found for {key} S{season}E{episode}")
-                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['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}"
-            
-            self.logger.debug(f"Found {len(providers)} providers for {key} S{season}E{episode}")
-            return providers
-            
-        except Exception as e:
-            self.logger.error(f"Failed to parse providers from HTML: {e}")
-            raise RetryableError(f"Provider parsing failed: {e}") from e
-    
-    def _get_redirect_link(self, season: int, episode: int, key: str, language: str = "German Dub"):
-        """Get redirect link for episode with error handling."""
-        languageCode = self._GetLanguageKey(language)
-        
-        if not self.IsLanguage(season, episode, key, language):
-            raise NonRetryableError(f"Language {language} not available for {key} S{season}E{episode}")
-        
-        providers = self._get_provider_from_html(season, episode, key)
-        
-        for provider_name, lang_dict in providers.items():
-            if languageCode in lang_dict:
-                return lang_dict[languageCode], provider_name
-        
-        raise NonRetryableError(f"No provider found for {language} in {key} S{season}E{episode}")
-    
-    def _get_embeded_link(self, season: int, episode: int, key: str, language: str = "German Dub"):
-        """Get embedded link with error handling."""
-        try:
-            redirect_link, provider_name = self._get_redirect_link(season, episode, key, language)
-            
-            response = recovery_strategies.handle_network_failure(
-                self.session.get,
-                redirect_link,
-                timeout=self.DEFAULT_REQUEST_TIMEOUT,
-                headers={'User-Agent': self.RANDOM_USER_AGENT}
-            )
-            
-            return response.url
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get embedded link: {e}")
-            raise
-    
-    def _get_direct_link_from_provider(self, season: int, episode: int, key: str, language: str = "German Dub"):
-        """Get direct download link from provider with error handling."""
-        try:
-            embedded_link = self._get_embeded_link(season, episode, key, language)
-            if not embedded_link:
-                raise NonRetryableError("No embedded link found")
-            
-            # Use VOE provider as default (could be made configurable)
-            provider = self.Providers.GetProvider("VOE")
-            if not provider:
-                raise NonRetryableError("VOE provider not available")
-            
-            return provider.GetLink(embedded_link, self.DEFAULT_REQUEST_TIMEOUT)
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get direct link from provider: {e}")
-            raise
-    
-    @with_error_recovery(max_retries=2, context="get_season_episode_count")
-    def get_season_episode_count(self, slug: str) -> dict:
-        """Get episode count per season with error handling."""
-        try:
-            base_url = f"{self.ANIWORLD_TO}/anime/stream/{slug}/"
-            response = recovery_strategies.handle_network_failure(
-                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
-            
-            episode_counts = {}
-            
-            for season in range(1, number_of_seasons + 1):
-                season_url = f"{base_url}staffel-{season}"
-                season_response = recovery_strategies.handle_network_failure(
-                    requests.get,
-                    season_url,
-                    timeout=self.DEFAULT_REQUEST_TIMEOUT
-                )
-                
-                season_soup = BeautifulSoup(season_response.content, 'html.parser')
-                
-                episode_links = season_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)
-            
-            return episode_counts
-            
-        except Exception as e:
-            self.logger.error(f"Failed to get episode counts for {slug}: {e}")
-            raise RetryableError(f"Episode count retrieval failed: {e}") from e
-    
-    def get_download_statistics(self) -> Dict[str, Any]:
-        """Get download statistics."""
-        stats = self.download_stats.copy()
-        stats['success_rate'] = (
-            (stats['successful_downloads'] / stats['total_downloads'] * 100)
-            if stats['total_downloads'] > 0 else 0
-        )
-        return stats
-    
-    def reset_statistics(self):
-        """Reset download statistics."""
-        self.download_stats = {
-            'total_downloads': 0,
-            'successful_downloads': 0,
-            'failed_downloads': 0,
-            'retried_downloads': 0
-        }
-
-
-# For backward compatibility, create wrapper that uses enhanced loader
-class AniworldLoader(EnhancedAniWorldLoader):
-    """Backward compatibility wrapper for the enhanced loader."""
-    pass

src/core/providers/provider_factory.py

@@ -1,10 +0,0 @@
-from .aniworld_provider import AniworldLoader
-from .base_provider import Loader
-
-class Loaders:
-
-    def __init__(self):
-        self.dict = {"aniworld.to": AniworldLoader()}
-
-    def GetLoader(self, key: str) -> Loader:
-        return self.dict[key]

src/core/providers/streaming/Provider.py

@@ -1,7 +0,0 @@
-from abc import ABC, abstractmethod
-
-
-class Provider(ABC):
-    @abstractmethod
-    def GetLink(self, embededLink: str, DEFAULT_REQUEST_TIMEOUT: int) -> (str, [str]):
-        pass

src/core/providers/streaming/doodstream.py

@@ -1,59 +0,0 @@
-import re
-import random
-import time
-
-from fake_useragent import UserAgent
-import requests
-from .Provider import Provider
-class Doodstream(Provider):
-
-    def __init__(self):
-        self.RANDOM_USER_AGENT = UserAgent().random
-
-    def GetLink(self, embededLink: str, DEFAULT_REQUEST_TIMEOUT: int) -> str:
-        headers = {
-            'User-Agent': self.RANDOM_USER_AGENT,
-            'Referer': 'https://dood.li/'
-        }
-
-        def extract_data(pattern, content):
-            match = re.search(pattern, content)
-            return match.group(1) if match else None
-
-        def generate_random_string(length=10):
-            characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'
-            return ''.join(random.choice(characters) for _ in range(length))
-
-        response = requests.get(
-            embededLink,
-            headers=headers,
-            timeout=DEFAULT_REQUEST_TIMEOUT,
-            verify=False
-        )
-        response.raise_for_status()
-
-        pass_md5_pattern = r"\$\.get\('([^']*\/pass_md5\/[^']*)'"
-        pass_md5_url = extract_data(pass_md5_pattern, response.text)
-        if not pass_md5_url:
-            raise ValueError(
-                f'pass_md5 URL not found using {embededLink}.')
-
-        full_md5_url = f"https://dood.li{pass_md5_url}"
-
-        token_pattern = r"token=([a-zA-Z0-9]+)"
-        token = extract_data(token_pattern, response.text)
-        if not token:
-            raise ValueError(f'Token not found using {embededLink}.')
-
-        md5_response = requests.get(
-            full_md5_url, headers=headers, timeout=DEFAULT_REQUEST_TIMEOUT, verify=False)
-        md5_response.raise_for_status()
-        video_base_url = md5_response.text.strip()
-
-        random_string = generate_random_string(10)
-        expiry = int(time.time())
-
-        direct_link = f"{video_base_url}{random_string}?token={token}&expiry={expiry}"
-        # print(direct_link)
-
-        return direct_link

src/core/providers/streaming/filemoon.py

@@ -1,51 +0,0 @@
-import re
-import requests
-# import jsbeautifier.unpackers.packer as packer
-
-from aniworld import config
-
-REDIRECT_REGEX = re.compile(
-    r'<iframe *(?:[^>]+ )?src=(?:\'([^\']+)\'|"([^"]+)")[^>]*>')
-SCRIPT_REGEX = re.compile(
-    r'(?s)<script\s+[^>]*?data-cfasync=["\']?false["\']?[^>]*>(.+?)</script>')
-VIDEO_URL_REGEX = re.compile(r'file:\s*"([^"]+\.m3u8[^"]*)"')
-
-# TODO Implement this script fully
-
-
-def get_direct_link_from_filemoon(embeded_filemoon_link: str):
-    session = requests.Session()
-    session.verify = False
-
-    headers = {
-        "User-Agent": config.RANDOM_USER_AGENT,
-        "Referer": embeded_filemoon_link,
-    }
-
-    response = session.get(embeded_filemoon_link, headers=headers)
-    source = response.text
-
-    match = REDIRECT_REGEX.search(source)
-    if match:
-        redirect_url = match.group(1) or match.group(2)
-        response = session.get(redirect_url, headers=headers)
-        source = response.text
-
-    for script_match in SCRIPT_REGEX.finditer(source):
-        script_content = script_match.group(1).strip()
-
-        if not script_content.startswith("eval("):
-            continue
-
-        if packer.detect(script_content):
-            unpacked = packer.unpack(script_content)
-            video_match = VIDEO_URL_REGEX.search(unpacked)
-            if video_match:
-                return video_match.group(1)
-
-    raise Exception("No Video link found!")
-
-
-if __name__ == '__main__':
-    url = input("Enter Filemoon Link: ")
-    print(get_direct_link_from_filemoon(url))

src/core/providers/streaming/hanime.py

@@ -1,90 +0,0 @@
-import re
-import json
-import sys
-import requests
-from aniworld.config import DEFAULT_REQUEST_TIMEOUT
-
-
-def fetch_page_content(url):
-    try:
-        response = requests.get(url, timeout=DEFAULT_REQUEST_TIMEOUT)
-        response.raise_for_status()
-        return response.text
-    except requests.exceptions.RequestException as e:
-        print(f"Failed to fetch the page content: {e}")
-        return None
-
-
-def extract_video_data(page_content):
-    match = re.search(r'^.*videos_manifest.*$', page_content, re.MULTILINE)
-    if not match:
-        raise ValueError("Failed to extract video manifest from the response.")
-
-    json_str = match.group(0)[match.group(0).find(
-        '{'):match.group(0).rfind('}') + 1]
-    return json.loads(json_str)
-
-
-def get_streams(url):
-    page_content = fetch_page_content(url)
-    data = extract_video_data(page_content)
-    video_info = data['state']['data']['video']
-    name = video_info['hentai_video']['name']
-    streams = video_info['videos_manifest']['servers'][0]['streams']
-
-    return {"name": name, "streams": streams}
-
-
-def display_streams(streams):
-    if not streams:
-        print("No streams available.")
-        return
-
-    print("Available qualities:")
-    for i, stream in enumerate(streams, 1):
-        premium_tag = "(Premium)" if not stream['is_guest_allowed'] else ""
-        print(
-            f"{i}. {stream['width']}x{stream['height']}\t"
-            f"({stream['filesize_mbs']}MB) {premium_tag}")
-
-
-def get_user_selection(streams):
-    try:
-        selected_index = int(input("Select a stream: ").strip()) - 1
-        if 0 <= selected_index < len(streams):
-            return selected_index
-
-        print("Invalid selection.")
-        return None
-    except ValueError:
-        print("Invalid input.")
-        return None
-
-
-def get_direct_link_from_hanime(url=None):
-    try:
-        if url is None:
-            if len(sys.argv) > 1:
-                url = sys.argv[1]
-            else:
-                url = input("Please enter the hanime.tv video URL: ").strip()
-
-        try:
-            video_data = get_streams(url)
-            print(f"Video: {video_data['name']}")
-            print('*' * 40)
-            display_streams(video_data['streams'])
-
-            selected_index = None
-            while selected_index is None:
-                selected_index = get_user_selection(video_data['streams'])
-
-            print(f"M3U8 URL: {video_data['streams'][selected_index]['url']}")
-        except ValueError as e:
-            print(f"Error: {e}")
-    except KeyboardInterrupt:
-        pass
-
-
-if __name__ == "__main__":
-    get_direct_link_from_hanime()

src/core/providers/streaming/loadx.py

@@ -1,35 +0,0 @@
-import requests
-import json
-from urllib.parse import urlparse
-
-# TODO Doesn't work on download yet and has to be implemented
-
-
-def get_direct_link_from_loadx(embeded_loadx_link: str):
-    response = requests.head(
-        embeded_loadx_link, allow_redirects=True, verify=False)
-
-    parsed_url = urlparse(response.url)
-    path_parts = parsed_url.path.split("/")
-    if len(path_parts) < 3:
-        raise ValueError("Invalid path!")
-
-    id_hash = path_parts[2]
-    host = parsed_url.netloc
-
-    post_url = f"https://{host}/player/index.php?data={id_hash}&do=getVideo"
-    headers = {"X-Requested-With": "XMLHttpRequest"}
-    response = requests.post(post_url, headers=headers, verify=False)
-
-    data = json.loads(response.text)
-    print(data)
-    video_url = data.get("videoSource")
-    if not video_url:
-        raise ValueError("No Video link found!")
-
-    return video_url
-
-
-if __name__ == '__main__':
-    url = input("Enter Loadx Link: ")
-    print(get_direct_link_from_loadx(url))

src/core/providers/streaming/luluvdo.py

@@ -1,39 +0,0 @@
-import re
-
-import requests
-
-from aniworld import config
-
-
-def get_direct_link_from_luluvdo(embeded_luluvdo_link, arguments=None):
-    luluvdo_id = embeded_luluvdo_link.split('/')[-1]
-    filelink = (
-        f"https://luluvdo.com/dl?op=embed&file_code={luluvdo_id}&embed=1&referer=luluvdo.com&adb=0"
-    )
-
-    # The User-Agent needs to be the same as the direct-link ones to work
-    headers = {
-        "Origin": "https://luluvdo.com",
-        "Referer": "https://luluvdo.com/",
-        "User-Agent": config.LULUVDO_USER_AGENT
-    }
-
-    if arguments.action == "Download":
-        headers["Accept-Language"] = "de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"
-
-    response = requests.get(filelink, headers=headers,
-                            timeout=config.DEFAULT_REQUEST_TIMEOUT)
-
-    if response.status_code == 200:
-        pattern = r'file:\s*"([^"]+)"'
-        matches = re.findall(pattern, str(response.text))
-
-        if matches:
-            return matches[0]
-
-    raise ValueError("No match found")
-
-
-if __name__ == '__main__':
-    url = input("Enter Luluvdo Link: ")
-    print(get_direct_link_from_luluvdo(url))

src/core/providers/streaming/speedfiles.py

@@ -1,43 +0,0 @@
-import re
-import base64
-import requests
-
-from aniworld.config import DEFAULT_REQUEST_TIMEOUT, RANDOM_USER_AGENT
-
-SPEEDFILES_PATTERN = re.compile(r'var _0x5opu234 = "(?P<encoded_data>.*?)";')
-
-
-def get_direct_link_from_speedfiles(embeded_speedfiles_link):
-    response = requests.get(
-        embeded_speedfiles_link,
-        timeout=DEFAULT_REQUEST_TIMEOUT,
-        headers={'User-Agent': RANDOM_USER_AGENT}
-    )
-
-    if "<span class=\"inline-block\">Web server is down</span>" in response.text:
-        raise ValueError(
-            "The SpeedFiles server is currently down.\n"
-            "Please try again later or choose a different hoster."
-        )
-
-    match = SPEEDFILES_PATTERN.search(response.text)
-
-    if not match:
-        raise ValueError("Pattern not found in the response.")
-
-    encoded_data = match.group("encoded_data")
-    decoded = base64.b64decode(encoded_data).decode()
-    decoded = decoded.swapcase()[::-1]
-    decoded = base64.b64decode(decoded).decode()[::-1]
-    decoded_hex = ''.join(chr(int(decoded[i:i + 2], 16))
-                          for i in range(0, len(decoded), 2))
-    shifted = ''.join(chr(ord(char) - 3) for char in decoded_hex)
-    result = base64.b64decode(shifted.swapcase()[::-1]).decode()
-
-    return result
-
-
-if __name__ == '__main__':
-    speedfiles_link = input("Enter Speedfiles Link: ")
-    print(get_direct_link_from_speedfiles(
-        embeded_speedfiles_link=speedfiles_link))

src/core/providers/streaming/streamtape.py

@@ -1,2 +0,0 @@
-def get_direct_link_from_streamtape(embeded_streamtape_link: str) -> str:
-    pass

src/core/providers/streaming/vidmoly.py

@@ -1,34 +0,0 @@
-import re
-
-import requests
-from bs4 import BeautifulSoup
-
-from aniworld.config import DEFAULT_REQUEST_TIMEOUT, RANDOM_USER_AGENT
-
-
-def get_direct_link_from_vidmoly(embeded_vidmoly_link: str):
-    response = requests.get(
-        embeded_vidmoly_link,
-        headers={'User-Agent': RANDOM_USER_AGENT},
-        timeout=DEFAULT_REQUEST_TIMEOUT
-    )
-    html_content = response.text
-    soup = BeautifulSoup(html_content, 'html.parser')
-    scripts = soup.find_all('script')
-
-    file_link_pattern = r'file:\s*"(https?://.*?)"'
-
-    for script in scripts:
-        if script.string:
-            match = re.search(file_link_pattern, script.string)
-            if match:
-                file_link = match.group(1)
-                return file_link
-
-    raise ValueError("No direct link found.")
-
-
-if __name__ == '__main__':
-    link = input("Enter Vidmoly Link: ")
-    print('Note: --referer "https://vidmoly.to"')
-    print(get_direct_link_from_vidmoly(embeded_vidmoly_link=link))

src/core/providers/streaming/vidoza.py

@@ -1,29 +0,0 @@
-import re
-
-import requests
-from bs4 import BeautifulSoup
-
-from aniworld.config import DEFAULT_REQUEST_TIMEOUT, RANDOM_USER_AGENT
-
-
-def get_direct_link_from_vidoza(embeded_vidoza_link: str) -> str:
-    response = requests.get(
-        embeded_vidoza_link,
-        headers={'User-Agent': RANDOM_USER_AGENT},
-        timeout=DEFAULT_REQUEST_TIMEOUT
-    )
-
-    soup = BeautifulSoup(response.content, "html.parser")
-
-    for tag in soup.find_all('script'):
-        if 'sourcesCode:' in tag.text:
-            match = re.search(r'src: "(.*?)"', tag.text)
-            if match:
-                return match.group(1)
-
-    raise ValueError("No direct link found.")
-
-
-if __name__ == '__main__':
-    link = input("Enter Vidoza Link: ")
-    print(get_direct_link_from_vidoza(embeded_vidoza_link=link))

src/infrastructure/logging/GlobalLogger.py

@@ -1,40 +0,0 @@
-import logging
-
-console_handler = None
-error_logger = None
-noKeyFound_logger = None
-noGerFound_logger = None
-def setupLogger():
-    global console_handler, error_logger, noKeyFound_logger, noGerFound_logger
-    # Configure logging
-    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(funcName)s - %(message)s')
-    if (console_handler is None):
-        console_handler = logging.StreamHandler()
-        console_handler.setLevel(logging.INFO)
-        console_handler.setFormatter(logging.Formatter(
-            "%(asctime)s - %(levelname)s - %(funcName)s - %(message)s")
-        )
-        logging.getLogger().addHandler(console_handler)
-        logging.getLogger("urllib3.connectionpool").setLevel(logging.INFO)
-        logging.getLogger('charset_normalizer').setLevel(logging.INFO)
-        logging.getLogger().setLevel(logging.INFO)
-
-    if (error_logger is None):
-        error_logger = logging.getLogger("ErrorLog")
-        error_handler = logging.FileHandler("../errors.log")
-        error_handler.setLevel(logging.ERROR)
-        error_logger.addHandler(error_handler)
-
-    if (noKeyFound_logger is None):
-        noKeyFound_logger = logging.getLogger("NoKeyFound")
-        noKeyFound_handler = logging.FileHandler("../NoKeyFound.log")
-        noKeyFound_handler.setLevel(logging.ERROR)
-        noKeyFound_logger.addHandler(noKeyFound_handler)
-
-    if (noGerFound_logger is None):
-        noGerFound_logger = logging.getLogger("noGerFound")
-        noGerFound_handler = logging.FileHandler("../noGerFound.log")
-        noGerFound_handler.setLevel(logging.ERROR)
-        noGerFound_logger.addHandler(noGerFound_handler)
-
-setupLogger()

src/infrastructure/logging/__init__.py

@@ -0,0 +1,7 @@
+"""
+Logging infrastructure for the Aniworld application.
+"""
+from src.infrastructure.logging.logger import get_logger, setup_logging
+from src.infrastructure.logging.uvicorn_config import get_uvicorn_log_config
+
+__all__ = ["setup_logging", "get_logger", "get_uvicorn_log_config"]

src/infrastructure/logging/logger.py

@@ -0,0 +1,100 @@
+"""
+Logging configuration for the Aniworld application.
+
+This module provides a centralized logging setup with both console and file
+logging, following Python logging best practices.
+"""
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+from src.config.settings import settings
+
+
+def setup_logging(
+    log_file: Optional[str] = None,
+    log_level: Optional[str] = None,
+    log_dir: Optional[Path] = None
+) -> logging.Logger:
+    """
+    Configure application logging with console and file handlers.
+    
+    Args:
+        log_file: Name of the log file (default: "fastapi_app.log")
+        log_level: Logging level (default: from settings or "INFO")
+        log_dir: Directory for log files (default: "logs" in project root)
+    
+    Returns:
+        Configured logger instance
+    """
+    # Determine log level
+    level_name = log_level or settings.log_level or "INFO"
+    level = getattr(logging, level_name.upper(), logging.INFO)
+    
+    # Determine log directory and file
+    if log_dir is None:
+        # Default to logs directory in project root
+        log_dir = Path(__file__).parent.parent.parent.parent / "logs"
+    
+    log_dir.mkdir(parents=True, exist_ok=True)
+    
+    if log_file is None:
+        log_file = "fastapi_app.log"
+    
+    log_path = log_dir / log_file
+    
+    # Create formatters
+    detailed_formatter = logging.Formatter(
+        fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S"
+    )
+    
+    console_formatter = logging.Formatter(
+        fmt="%(levelname)s:     %(message)s"
+    )
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+    
+    # Remove existing handlers to avoid duplicates
+    root_logger.handlers.clear()
+    
+    # Console handler (stdout)
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_handler.setFormatter(console_formatter)
+    root_logger.addHandler(console_handler)
+    
+    # File handler
+    file_handler = logging.FileHandler(log_path, mode='a', encoding='utf-8')
+    file_handler.setLevel(level)
+    file_handler.setFormatter(detailed_formatter)
+    root_logger.addHandler(file_handler)
+    
+    # Create application logger
+    logger = logging.getLogger("aniworld")
+    logger.setLevel(level)
+    
+    # Log startup information
+    logger.info("=" * 60)
+    logger.info("Logging configured successfully")
+    logger.info("Log level: %s", level_name.upper())
+    logger.info("Log file: %s", log_path)
+    logger.info("=" * 60)
+    
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance for a specific module.
+    
+    Args:
+        name: Name of the logger (typically __name__)
+    
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(name)

src/infrastructure/logging/uvicorn_config.py

@@ -0,0 +1,92 @@
+"""
+Uvicorn logging configuration for the Aniworld application.
+
+This configuration ensures that uvicorn logs are properly formatted and
+written to both console and file.
+"""
+from pathlib import Path
+
+# Get the logs directory
+LOGS_DIR = Path(__file__).parent.parent.parent.parent / "logs"
+LOGS_DIR.mkdir(parents=True, exist_ok=True)
+LOG_FILE = LOGS_DIR / "fastapi_app.log"
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "default": {
+            "()": "uvicorn.logging.DefaultFormatter",
+            "fmt": "%(levelprefix)s %(message)s",
+            "use_colors": None,
+        },
+        "access": {
+            "()": "uvicorn.logging.AccessFormatter",
+            "fmt": (
+                '%(levelprefix)s %(client_addr)s - '
+                '"%(request_line)s" %(status_code)s'
+            ),
+        },
+        "detailed": {
+            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        },
+    },
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "level": "INFO",
+            "formatter": "default",
+            "stream": "ext://sys.stdout",
+        },
+        "file": {
+            "class": "logging.FileHandler",
+            "level": "INFO",
+            "formatter": "detailed",
+            "filename": str(LOG_FILE),
+            "mode": "a",
+            "encoding": "utf-8",
+        },
+    },
+    "loggers": {
+        "uvicorn": {
+            "handlers": ["console", "file"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "uvicorn.error": {
+            "handlers": ["console", "file"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "uvicorn.access": {
+            "handlers": ["console", "file"],
+            "level": "INFO",
+            "propagate": False,
+        },
+        "watchfiles.main": {
+            "handlers": ["console"],
+            "level": "WARNING",
+            "propagate": False,
+        },
+        "aniworld": {
+            "handlers": ["console", "file"],
+            "level": "INFO",
+            "propagate": False,
+        },
+    },
+    "root": {
+        "handlers": ["console", "file"],
+        "level": "INFO",
+    },
+}
+
+
+def get_uvicorn_log_config() -> dict:
+    """
+    Get the uvicorn logging configuration dictionary.
+    
+    Returns:
+        Dictionary containing logging configuration
+    """
+    return LOGGING_CONFIG

src/infrastructure/security/__init__.py

@@ -0,0 +1,20 @@
+"""Security utilities for the Aniworld application.
+
+This module provides security-related utilities including:
+- File integrity verification with checksums
+- Database integrity checks
+- Configuration encryption
+"""
+
+from .config_encryption import ConfigEncryption, get_config_encryption
+from .database_integrity import DatabaseIntegrityChecker, check_database_integrity
+from .file_integrity import FileIntegrityManager, get_integrity_manager
+
+__all__ = [
+    "FileIntegrityManager",
+    "get_integrity_manager",
+    "DatabaseIntegrityChecker",
+    "check_database_integrity",
+    "ConfigEncryption",
+    "get_config_encryption",
+]

src/infrastructure/security/config_encryption.py

@@ -0,0 +1,274 @@
+"""Configuration encryption utilities.
+
+This module provides encryption/decryption for sensitive configuration
+values such as passwords, API keys, and tokens.
+"""
+
+import base64
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from cryptography.fernet import Fernet
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigEncryption:
+    """Handles encryption/decryption of sensitive configuration values."""
+
+    def __init__(self, key_file: Optional[Path] = None):
+        """Initialize the configuration encryption.
+
+        Args:
+            key_file: Path to store encryption key.
+                Defaults to data/encryption.key
+        """
+        if key_file is None:
+            project_root = Path(__file__).parent.parent.parent.parent
+            key_file = project_root / "data" / "encryption.key"
+
+        self.key_file = Path(key_file)
+        self._cipher: Optional[Fernet] = None
+        self._ensure_key_exists()
+
+    def _ensure_key_exists(self) -> None:
+        """Ensure encryption key exists or create one."""
+        if not self.key_file.exists():
+            logger.info("Creating new encryption key at %s", self.key_file)
+            self._generate_new_key()
+        else:
+            logger.info("Using existing encryption key from %s", self.key_file)
+
+    def _generate_new_key(self) -> None:
+        """Generate and store a new encryption key."""
+        try:
+            self.key_file.parent.mkdir(parents=True, exist_ok=True)
+
+            # Generate a secure random key
+            key = Fernet.generate_key()
+
+            # Write key with restrictive permissions (owner read/write only)
+            self.key_file.write_bytes(key)
+            os.chmod(self.key_file, 0o600)
+
+            logger.info("Generated new encryption key")
+
+        except IOError as e:
+            logger.error("Failed to generate encryption key: %s", e)
+            raise
+
+    def _load_key(self) -> bytes:
+        """Load encryption key from file.
+
+        Returns:
+            Encryption key bytes
+
+        Raises:
+            FileNotFoundError: If key file doesn't exist
+        """
+        if not self.key_file.exists():
+            raise FileNotFoundError(
+                f"Encryption key not found: {self.key_file}"
+            )
+
+        try:
+            key = self.key_file.read_bytes()
+            return key
+        except IOError as e:
+            logger.error("Failed to load encryption key: %s", e)
+            raise
+
+    def _get_cipher(self) -> Fernet:
+        """Get or create Fernet cipher instance.
+
+        Returns:
+            Fernet cipher instance
+        """
+        if self._cipher is None:
+            key = self._load_key()
+            self._cipher = Fernet(key)
+        return self._cipher
+
+    def encrypt_value(self, value: str) -> str:
+        """Encrypt a configuration value.
+
+        Args:
+            value: Plain text value to encrypt
+
+        Returns:
+            Base64-encoded encrypted value
+
+        Raises:
+            ValueError: If value is empty
+        """
+        if not value:
+            raise ValueError("Cannot encrypt empty value")
+
+        try:
+            cipher = self._get_cipher()
+            encrypted_bytes = cipher.encrypt(value.encode('utf-8'))
+
+            # Return as base64 string for easy storage
+            encrypted_str = base64.b64encode(encrypted_bytes).decode('utf-8')
+
+            logger.debug("Encrypted configuration value")
+            return encrypted_str
+
+        except Exception as e:
+            logger.error("Failed to encrypt value: %s", e)
+            raise
+
+    def decrypt_value(self, encrypted_value: str) -> str:
+        """Decrypt a configuration value.
+
+        Args:
+            encrypted_value: Base64-encoded encrypted value
+
+        Returns:
+            Decrypted plain text value
+
+        Raises:
+            ValueError: If encrypted value is invalid
+        """
+        if not encrypted_value:
+            raise ValueError("Cannot decrypt empty value")
+
+        try:
+            cipher = self._get_cipher()
+
+            # Decode from base64
+            encrypted_bytes = base64.b64decode(encrypted_value.encode('utf-8'))
+
+            # Decrypt
+            decrypted_bytes = cipher.decrypt(encrypted_bytes)
+            decrypted_str = decrypted_bytes.decode('utf-8')
+
+            logger.debug("Decrypted configuration value")
+            return decrypted_str
+
+        except Exception as e:
+            logger.error("Failed to decrypt value: %s", e)
+            raise
+
+    def encrypt_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Encrypt sensitive fields in configuration dictionary.
+
+        Args:
+            config: Configuration dictionary
+
+        Returns:
+            Dictionary with encrypted sensitive fields
+        """
+        # List of sensitive field names to encrypt
+        sensitive_fields = {
+            'password',
+            'passwd',
+            'secret',
+            'key',
+            'token',
+            'api_key',
+            'apikey',
+            'auth_token',
+            'jwt_secret',
+            'master_password',
+        }
+
+        encrypted_config = {}
+
+        for key, value in config.items():
+            key_lower = key.lower()
+
+            # Check if field name suggests sensitive data
+            is_sensitive = any(
+                field in key_lower for field in sensitive_fields
+            )
+
+            if is_sensitive and isinstance(value, str) and value:
+                try:
+                    encrypted_config[key] = {
+                        'encrypted': True,
+                        'value': self.encrypt_value(value)
+                    }
+                    logger.debug("Encrypted config field: %s", key)
+                except Exception as e:
+                    logger.warning("Failed to encrypt %s: %s", key, e)
+                    encrypted_config[key] = value
+            else:
+                encrypted_config[key] = value
+
+        return encrypted_config
+
+    def decrypt_config(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Decrypt sensitive fields in configuration dictionary.
+
+        Args:
+            config: Configuration dictionary with encrypted fields
+
+        Returns:
+            Dictionary with decrypted values
+        """
+        decrypted_config = {}
+
+        for key, value in config.items():
+            # Check if this is an encrypted field
+            if (
+                isinstance(value, dict) and
+                value.get('encrypted') is True and
+                'value' in value
+            ):
+                try:
+                    decrypted_config[key] = self.decrypt_value(
+                        value['value']
+                    )
+                    logger.debug("Decrypted config field: %s", key)
+                except Exception as e:
+                    logger.error("Failed to decrypt %s: %s", key, e)
+                    decrypted_config[key] = None
+            else:
+                decrypted_config[key] = value
+
+        return decrypted_config
+
+    def rotate_key(self, new_key_file: Optional[Path] = None) -> None:
+        """Rotate encryption key.
+
+        **Warning**: This will invalidate all previously encrypted data.
+
+        Args:
+            new_key_file: Path for new key file (optional)
+        """
+        logger.warning(
+            "Rotating encryption key - all encrypted data will "
+            "need re-encryption"
+        )
+
+        # Backup old key if it exists
+        if self.key_file.exists():
+            backup_path = self.key_file.with_suffix('.key.bak')
+            self.key_file.rename(backup_path)
+            logger.info("Backed up old key to %s", backup_path)
+
+        # Generate new key
+        if new_key_file:
+            self.key_file = new_key_file
+
+        self._generate_new_key()
+        self._cipher = None  # Reset cipher to use new key
+
+
+# Global instance
+_config_encryption: Optional[ConfigEncryption] = None
+
+
+def get_config_encryption() -> ConfigEncryption:
+    """Get the global configuration encryption instance.
+
+    Returns:
+        ConfigEncryption instance
+    """
+    global _config_encryption
+    if _config_encryption is None:
+        _config_encryption = ConfigEncryption()
+    return _config_encryption

src/infrastructure/security/database_integrity.py

@@ -0,0 +1,299 @@
+"""Database integrity verification utilities.
+
+This module provides database integrity checks including:
+- Foreign key constraint validation
+- Orphaned record detection
+- Data consistency checks
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from sqlalchemy import select, text
+from sqlalchemy.orm import Session
+
+from src.server.database.models import AnimeSeries, DownloadQueueItem, Episode
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseIntegrityChecker:
+    """Checks database integrity and consistency."""
+
+    def __init__(self, session: Optional[Session] = None):
+        """Initialize the database integrity checker.
+
+        Args:
+            session: SQLAlchemy session for database access
+        """
+        self.session = session
+        self.issues: List[str] = []
+
+    def check_all(self) -> Dict[str, Any]:
+        """Run all integrity checks.
+
+        Returns:
+            Dictionary with check results and issues found
+        """
+        if self.session is None:
+            raise ValueError("Session required for integrity checks")
+
+        self.issues = []
+        results = {
+            "orphaned_episodes": self._check_orphaned_episodes(),
+            "orphaned_queue_items": self._check_orphaned_queue_items(),
+            "invalid_references": self._check_invalid_references(),
+            "duplicate_keys": self._check_duplicate_keys(),
+            "data_consistency": self._check_data_consistency(),
+            "total_issues": len(self.issues),
+            "issues": self.issues,
+        }
+
+        return results
+
+    def _check_orphaned_episodes(self) -> int:
+        """Check for episodes without parent series.
+
+        Returns:
+            Number of orphaned episodes found
+        """
+        try:
+            # Find episodes with non-existent series_id
+            stmt = select(Episode).outerjoin(
+                AnimeSeries, Episode.series_id == AnimeSeries.id
+            ).where(AnimeSeries.id.is_(None))
+
+            orphaned = self.session.execute(stmt).scalars().all()
+
+            if orphaned:
+                count = len(orphaned)
+                msg = f"Found {count} orphaned episodes without parent series"
+                self.issues.append(msg)
+                logger.warning(msg)
+                return count
+
+            logger.info("No orphaned episodes found")
+            return 0
+
+        except Exception as e:
+            msg = f"Error checking orphaned episodes: {e}"
+            self.issues.append(msg)
+            logger.error(msg)
+            return -1
+
+    def _check_orphaned_queue_items(self) -> int:
+        """Check for queue items without parent series.
+
+        Returns:
+            Number of orphaned queue items found
+        """
+        try:
+            # Find queue items with non-existent series_id
+            stmt = select(DownloadQueueItem).outerjoin(
+                AnimeSeries,
+                DownloadQueueItem.series_id == AnimeSeries.id
+            ).where(AnimeSeries.id.is_(None))
+
+            orphaned = self.session.execute(stmt).scalars().all()
+
+            if orphaned:
+                count = len(orphaned)
+                msg = (
+                    f"Found {count} orphaned queue items "
+                    f"without parent series"
+                )
+                self.issues.append(msg)
+                logger.warning(msg)
+                return count
+
+            logger.info("No orphaned queue items found")
+            return 0
+
+        except Exception as e:
+            msg = f"Error checking orphaned queue items: {e}"
+            self.issues.append(msg)
+            logger.error(msg)
+            return -1
+
+    def _check_invalid_references(self) -> int:
+        """Check for invalid foreign key references.
+
+        Returns:
+            Number of invalid references found
+        """
+        issues_found = 0
+
+        try:
+            # Check Episode.series_id references
+            stmt = text("""
+                SELECT COUNT(*) as count
+                FROM episode e
+                LEFT JOIN anime_series s ON e.series_id = s.id
+                WHERE e.series_id IS NOT NULL AND s.id IS NULL
+            """)
+            result = self.session.execute(stmt).fetchone()
+            if result and result[0] > 0:
+                msg = f"Found {result[0]} episodes with invalid series_id"
+                self.issues.append(msg)
+                logger.warning(msg)
+                issues_found += result[0]
+
+            # Check DownloadQueueItem.series_id references
+            stmt = text("""
+                SELECT COUNT(*) as count
+                FROM download_queue_item d
+                LEFT JOIN anime_series s ON d.series_id = s.id
+                WHERE d.series_id IS NOT NULL AND s.id IS NULL
+            """)
+            result = self.session.execute(stmt).fetchone()
+            if result and result[0] > 0:
+                msg = (
+                    f"Found {result[0]} queue items with invalid series_id"
+                )
+                self.issues.append(msg)
+                logger.warning(msg)
+                issues_found += result[0]
+
+            if issues_found == 0:
+                logger.info("No invalid foreign key references found")
+
+            return issues_found
+
+        except Exception as e:
+            msg = f"Error checking invalid references: {e}"
+            self.issues.append(msg)
+            logger.error(msg)
+            return -1
+
+    def _check_duplicate_keys(self) -> int:
+        """Check for duplicate primary keys.
+
+        Returns:
+            Number of duplicate key issues found
+        """
+        issues_found = 0
+
+        try:
+            # Check for duplicate anime series keys
+            stmt = text("""
+                SELECT anime_key, COUNT(*) as count
+                FROM anime_series
+                GROUP BY anime_key
+                HAVING COUNT(*) > 1
+            """)
+            duplicates = self.session.execute(stmt).fetchall()
+
+            if duplicates:
+                for row in duplicates:
+                    msg = (
+                        f"Duplicate anime_key found: {row[0]} "
+                        f"({row[1]} times)"
+                    )
+                    self.issues.append(msg)
+                    logger.warning(msg)
+                    issues_found += 1
+
+            if issues_found == 0:
+                logger.info("No duplicate keys found")
+
+            return issues_found
+
+        except Exception as e:
+            msg = f"Error checking duplicate keys: {e}"
+            self.issues.append(msg)
+            logger.error(msg)
+            return -1
+
+    def _check_data_consistency(self) -> int:
+        """Check for data consistency issues.
+
+        Returns:
+            Number of consistency issues found
+        """
+        issues_found = 0
+
+        try:
+            # Check for invalid season/episode numbers
+            stmt = select(Episode).where(
+                (Episode.season < 0) | (Episode.episode_number < 0)
+            )
+            invalid_episodes = self.session.execute(stmt).scalars().all()
+
+            if invalid_episodes:
+                count = len(invalid_episodes)
+                msg = (
+                    f"Found {count} episodes with invalid "
+                    f"season/episode numbers"
+                )
+                self.issues.append(msg)
+                logger.warning(msg)
+                issues_found += count
+
+            if issues_found == 0:
+                logger.info("No data consistency issues found")
+
+            return issues_found
+
+        except Exception as e:
+            msg = f"Error checking data consistency: {e}"
+            self.issues.append(msg)
+            logger.error(msg)
+            return -1
+
+    def repair_orphaned_records(self) -> int:
+        """Remove orphaned records from database.
+
+        Returns:
+            Number of records removed
+        """
+        if self.session is None:
+            raise ValueError("Session required for repair operations")
+
+        removed = 0
+
+        try:
+            # Remove orphaned episodes
+            stmt = select(Episode).outerjoin(
+                AnimeSeries, Episode.series_id == AnimeSeries.id
+            ).where(AnimeSeries.id.is_(None))
+
+            orphaned_episodes = self.session.execute(stmt).scalars().all()
+
+            for episode in orphaned_episodes:
+                self.session.delete(episode)
+                removed += 1
+
+            # Remove orphaned queue items
+            stmt = select(DownloadQueueItem).outerjoin(
+                AnimeSeries,
+                DownloadQueueItem.series_id == AnimeSeries.id
+            ).where(AnimeSeries.id.is_(None))
+
+            orphaned_queue = self.session.execute(stmt).scalars().all()
+
+            for item in orphaned_queue:
+                self.session.delete(item)
+                removed += 1
+
+            self.session.commit()
+            logger.info("Removed %s orphaned records", removed)
+
+            return removed
+
+        except Exception as e:
+            self.session.rollback()
+            logger.error("Error removing orphaned records: %s", e)
+            raise
+
+
+def check_database_integrity(session: Session) -> Dict[str, Any]:
+    """Convenience function to check database integrity.
+
+    Args:
+        session: SQLAlchemy session
+
+    Returns:
+        Dictionary with check results
+    """
+    checker = DatabaseIntegrityChecker(session)
+    return checker.check_all()

src/infrastructure/security/file_integrity.py

@@ -0,0 +1,239 @@
+"""File integrity verification utilities.
+
+This module provides checksum calculation and verification for
+downloaded files. Supports SHA256 hashing for file integrity validation.
+"""
+
+import hashlib
+import json
+import logging
+from pathlib import Path
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class FileIntegrityManager:
+    """Manages file integrity checksums and verification."""
+
+    def __init__(self, checksum_file: Optional[Path] = None):
+        """Initialize the file integrity manager.
+
+        Args:
+            checksum_file: Path to store checksums.
+                Defaults to data/checksums.json
+        """
+        if checksum_file is None:
+            project_root = Path(__file__).parent.parent.parent.parent
+            checksum_file = project_root / "data" / "checksums.json"
+        
+        self.checksum_file = Path(checksum_file)
+        self.checksums: Dict[str, str] = {}
+        self._load_checksums()
+
+    def _load_checksums(self) -> None:
+        """Load checksums from file."""
+        if self.checksum_file.exists():
+            try:
+                with open(self.checksum_file, 'r', encoding='utf-8') as f:
+                    self.checksums = json.load(f)
+                count = len(self.checksums)
+                logger.info(
+                    "Loaded %d checksums from %s",
+                    count,
+                    self.checksum_file,
+                )
+            except (json.JSONDecodeError, IOError) as e:
+                logger.error("Failed to load checksums: %s", e)
+                self.checksums = {}
+        else:
+            logger.info("Checksum file does not exist: %s", self.checksum_file)
+            self.checksums = {}
+
+    def _save_checksums(self) -> None:
+        """Save checksums to file."""
+        try:
+            self.checksum_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.checksum_file, 'w', encoding='utf-8') as f:
+                json.dump(self.checksums, f, indent=2)
+            count = len(self.checksums)
+            logger.debug(
+                "Saved %d checksums to %s",
+                count,
+                self.checksum_file,
+            )
+        except IOError as e:
+            logger.error("Failed to save checksums: %s", e)
+
+    def calculate_checksum(
+        self, file_path: Path, algorithm: str = "sha256"
+    ) -> str:
+        """Calculate checksum for a file.
+
+        Args:
+            file_path: Path to the file
+            algorithm: Hash algorithm to use (default: sha256)
+
+        Returns:
+            Hexadecimal checksum string
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If algorithm is not supported
+        """
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        if algorithm not in hashlib.algorithms_available:
+            raise ValueError(f"Unsupported hash algorithm: {algorithm}")
+
+        hash_obj = hashlib.new(algorithm)
+        
+        try:
+            with open(file_path, 'rb') as f:
+                # Read file in chunks to handle large files
+                for chunk in iter(lambda: f.read(8192), b''):
+                    hash_obj.update(chunk)
+            
+            checksum = hash_obj.hexdigest()
+            filename = file_path.name
+            logger.debug(
+                "Calculated %s checksum for %s: %s",
+                algorithm,
+                filename,
+                checksum,
+            )
+            return checksum
+        
+        except IOError as e:
+            logger.error("Failed to read file %s: %s", file_path, e)
+            raise
+
+    def store_checksum(
+        self, file_path: Path, checksum: Optional[str] = None
+    ) -> str:
+        """Calculate and store checksum for a file.
+
+        Args:
+            file_path: Path to the file
+            checksum: Pre-calculated checksum (optional, will calculate
+                if not provided)
+
+        Returns:
+            The stored checksum
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        if checksum is None:
+            checksum = self.calculate_checksum(file_path)
+        
+        # Use relative path as key for portability
+        key = str(file_path.resolve())
+        self.checksums[key] = checksum
+        self._save_checksums()
+        
+        logger.info("Stored checksum for %s", file_path.name)
+        return checksum
+
+    def verify_checksum(
+        self, file_path: Path, expected_checksum: Optional[str] = None
+    ) -> bool:
+        """Verify file integrity by comparing checksums.
+
+        Args:
+            file_path: Path to the file
+            expected_checksum: Expected checksum (optional, will look up
+                stored checksum)
+
+        Returns:
+            True if checksum matches, False otherwise
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+        """
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+
+        # Get expected checksum from storage if not provided
+        if expected_checksum is None:
+            key = str(file_path.resolve())
+            expected_checksum = self.checksums.get(key)
+            
+            if expected_checksum is None:
+                filename = file_path.name
+                logger.warning(
+                    "No stored checksum found for %s", filename
+                )
+                return False
+
+        # Calculate current checksum
+        try:
+            current_checksum = self.calculate_checksum(file_path)
+            
+            if current_checksum == expected_checksum:
+                filename = file_path.name
+                logger.info("Checksum verification passed for %s", filename)
+                return True
+            else:
+                filename = file_path.name
+                logger.warning(
+                    "Checksum mismatch for %s: "
+                    "expected %s, got %s",
+                    filename,
+                    expected_checksum,
+                    current_checksum
+                )
+                return False
+        
+        except (IOError, OSError) as e:
+            logger.error("Failed to verify checksum for %s: %s", file_path, e)
+            return False
+
+    def remove_checksum(self, file_path: Path) -> bool:
+        """Remove checksum for a file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            True if checksum was removed, False if not found
+        """
+        key = str(file_path.resolve())
+        
+        if key in self.checksums:
+            del self.checksums[key]
+            self._save_checksums()
+            logger.info("Removed checksum for %s", file_path.name)
+            return True
+        else:
+            logger.debug("No checksum found to remove for %s", file_path.name)
+            return False
+
+    def has_checksum(self, file_path: Path) -> bool:
+        """Check if a checksum exists for a file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            True if checksum exists, False otherwise
+        """
+        key = str(file_path.resolve())
+        return key in self.checksums
+
+
+# Global instance
+_integrity_manager: Optional[FileIntegrityManager] = None
+
+
+def get_integrity_manager() -> FileIntegrityManager:
+    """Get the global file integrity manager instance.
+
+    Returns:
+        FileIntegrityManager instance
+    """
+    global _integrity_manager
+    if _integrity_manager is None:
+        _integrity_manager = FileIntegrityManager()
+    return _integrity_manager

src/server/SerieScanner.py

@@ -0,0 +1,870 @@
+"""
+SerieScanner - Scans directories for anime series and missing episodes.
+
+This module provides functionality to scan anime directories, identify
+missing episodes, and report progress through callback interfaces.
+
+Note:
+    This module is pure domain logic. Database operations are handled
+    by the service layer (AnimeService).
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import traceback
+import uuid
+from typing import Callable, Iterable, Iterator, Optional
+
+from events import Events
+
+from src.config.settings import settings
+from src.server.database.models import AnimeSeries
+from src.server.exceptions.exceptions.Exceptions import MatchNotFoundError
+from src.server.providers.base_provider import Loader
+from src.server.database.connection import get_sync_session
+from src.server.database.service import AnimeSeriesService, EpisodeService
+
+logger = logging.getLogger(__name__)
+error_logger = logging.getLogger("error")
+no_key_found_logger = logging.getLogger("series.nokey")
+
+
+class SerieScanner:
+    """
+    Scans directories for anime series and identifies missing episodes.
+
+    Supports progress callbacks for real-time scanning updates.
+    
+    Note:
+        This class is pure domain logic. Database operations are handled
+        by the service layer (AnimeService). Scan results are stored
+        in keyDict and can be retrieved after scanning.
+    
+    Example:
+        # Synchronous context (CLI):
+        scanner = SerieScanner("/path/to/anime", loader)
+        scanner.scan()  # asyncio.run() used internally when no event loop
+
+        # Asynchronous context (server/scheduler):
+        # scan() detects running event loop and uses create_task()
+        # internally, so no special handling needed by caller.
+        # Results are in scanner.keyDict
+    """
+
+    def __init__(
+        self,
+        basePath: str,
+        loader: Loader,
+    ) -> None:
+        """
+        Initialize the SerieScanner.
+
+        Args:
+            basePath: Base directory containing anime series
+            loader: Loader instance for fetching series information
+
+        Raises:
+            ValueError: If basePath is invalid or doesn't exist
+        """
+        # Validate basePath to prevent directory traversal attacks
+        if not basePath or not basePath.strip():
+            raise ValueError("Base path cannot be empty")
+        
+        # Resolve to absolute path and validate it exists
+        abs_path = os.path.abspath(basePath)
+        if not os.path.exists(abs_path):
+            raise ValueError(f"Base path does not exist: {abs_path}")
+        if not os.path.isdir(abs_path):
+            raise ValueError(f"Base path is not a directory: {abs_path}")
+        
+        self.directory: str = abs_path
+        self.keyDict: dict[str, AnimeSeries] = {}
+        self.loader: Loader = loader
+        self._current_operation_id: Optional[str] = None
+        self.events = Events()
+        
+        self.events.on_progress = []
+        self.events.on_error = []
+        self.events.on_warning = []
+        self.events.on_completion = []
+
+        logger.info("Initialized SerieScanner with base path: %s", abs_path)
+    
+    def _safe_call_event(self, event_handler, data: dict) -> None:
+        """Safely call an event handler if it exists.
+        
+        Args:
+            event_handler: Event handler attribute (e.g., self.events.on_progress)
+            data: Data dictionary to pass to the event handler
+        """
+        if event_handler:
+            try:
+                # Event handlers are stored as lists, iterate over them
+                for handler in event_handler:
+                    handler(data)
+            except Exception as e:
+                logger.error("Error calling event handler: %s", e, exc_info=True)
+
+    def subscribe_on_progress(self, handler):
+        """
+        Subscribe a handler to an event.
+        Args:
+            handler: Callable to handle the event
+        """
+        if handler not in self.events.on_progress:
+            self.events.on_progress.append(handler)
+
+    def unsubscribe_on_progress(self, handler):
+        """
+        Unsubscribe a handler from an event.
+        Args:
+            handler: Callable to remove
+        """
+        if handler in self.events.on_progress:
+            self.events.on_progress.remove(handler)
+        
+    def _extract_year_from_folder_name(self, folder_name: str) -> int | None:
+        """Extract year from folder name if present.
+        
+        Looks for year in format "(YYYY)" at the end of folder name.
+        
+        Args:
+            folder_name: The folder name to check
+            
+        Returns:
+            int or None: Year if found, None otherwise
+            
+        Example:
+            >>> _extract_year_from_folder_name("Dororo (2025)")
+            2025
+            >>> _extract_year_from_folder_name("Dororo")
+            None
+        """
+        if not folder_name:
+            return None
+        
+        # Look for year in format (YYYY) - typically at end of name
+        match = re.search(r'\((\d{4})\)', folder_name)
+        if match:
+            try:
+                year = int(match.group(1))
+                # Validate year is reasonable (between 1900 and 2100)
+                if 1900 <= year <= 2100:
+                    logger.debug(
+                        "Extracted year from folder name: %s -> %d",
+                        folder_name,
+                        year
+                    )
+                    return year
+            except ValueError:
+                pass
+        
+        return None
+    
+    def subscribe_on_error(self, handler):
+        """
+        Subscribe a handler to an event.
+        Args:
+            handler: Callable to handle the event
+        """
+        if handler not in self.events.on_error:
+            self.events.on_error.append(handler)
+
+    def unsubscribe_on_error(self, handler):
+        """
+        Unsubscribe a handler from an event.
+        Args:
+            handler: Callable to remove
+        """
+        if handler in self.events.on_error:
+            self.events.on_error.remove(handler)
+
+    def subscribe_on_warning(self, handler):
+        """
+        Subscribe a handler to an event.
+        Args:
+            handler: Callable to handle the event
+        """
+        if handler not in self.events.on_warning:
+            self.events.on_warning.append(handler)
+
+    def unsubscribe_on_warning(self, handler):
+        """
+        Unsubscribe a handler from an event.
+        Args:
+            handler: Callable to remove
+        """
+        if handler in self.events.on_warning:
+            self.events.on_warning.remove(handler)
+
+    def subscribe_on_completion(self, handler):
+        """
+        Subscribe a handler to an event.
+        Args:
+            handler: Callable to handle the event
+        """
+        if handler not in self.events.on_completion:
+            self.events.on_completion.append(handler)
+
+    def unsubscribe_on_completion(self, handler):
+        """
+        Unsubscribe a handler from an event.
+        Args:
+            handler: Callable to remove
+        """
+        if handler in self.events.on_completion:
+            self.events.on_completion.remove(handler)
+        
+    def reinit(self) -> None:
+        """Reinitialize the series dictionary (keyed by anime.key)."""
+        self.keyDict: dict[str, AnimeSeries] = {}
+
+    async def _persist_serie_to_db(self, anime: AnimeSeries) -> None:
+        """Persist anime to database (create or update).
+
+        Args:
+            anime: AnimeSeries model to persist
+        """
+        try:
+            from src.server.database.connection import get_async_session_factory
+
+            db = get_async_session_factory()
+            try:
+                existing = await AnimeSeriesService.get_by_key(db, anime.key)
+                if existing:
+                    await AnimeSeriesService.update(
+                        db, existing.id,
+                        name=anime.name,
+                        folder=anime.folder,
+                        year=anime.year
+                    )
+                    await self._sync_episodes_to_db(db, existing.id, anime.episodeDict)
+                else:
+                    db_anime = await AnimeSeriesService.create(
+                        db=db,
+                        key=anime.key,
+                        name=anime.name,
+                        site=anime.site,
+                        folder=anime.folder,
+                        year=anime.year
+                    )
+                    for ep in anime.episodes:
+                        await EpisodeService.create(
+                            db=db,
+                            series_id=db_anime.id,
+                            season=ep.season,
+                            episode_number=ep.episode_number
+                        )
+                await db.commit()
+                logger.debug(
+                    "Persisted anime '%s' (key=%s) to database",
+                    anime.name, anime.key
+                )
+            except Exception as e:
+                await db.rollback()
+                logger.error(
+                    "Failed to persist anime '%s' to DB: %s",
+                    anime.key, e, exc_info=True
+                )
+                raise
+            finally:
+                await db.close()
+        except Exception as e:
+            logger.error(
+                "Could not persist anime '%s' to DB (DB unavailable?): %s",
+                anime.key, e
+            )
+
+    async def _sync_episodes_to_db(
+        self, db, series_id: int, episode_dict: dict[int, list[int]]
+    ) -> None:
+        """Sync episodes to database, preserving downloaded flags.
+
+        Adds missing episodes, removes episodes no longer missing,
+        and preserves is_downloaded=True episodes.
+
+        Args:
+            db: Async database session
+            series_id: Database ID of the series
+            episode_dict: Dict mapping season -> list of episode numbers
+        """
+        existing_episodes = await EpisodeService.get_by_series(db, series_id)
+        existing_map = {
+            (ep.season, ep.episode_number): ep for ep in existing_episodes
+        }
+        new_keys = set()
+        for season, eps in episode_dict.items():
+            for ep_num in eps:
+                new_keys.add((season, ep_num))
+        for (season, ep_num), ep in existing_map.items():
+            if (season, ep_num) not in new_keys:
+                if ep.is_downloaded:
+                    logger.debug(
+                        "Preserving downloaded episode S%02dE%02d for series_id=%d",
+                        season, ep_num, series_id
+                    )
+                else:
+                    await EpisodeService.delete_by_series(
+                        db, series_id, season, ep_num
+                    )
+        for season, eps in episode_dict.items():
+            for ep_num in eps:
+                if (season, ep_num) not in existing_map:
+                    await EpisodeService.create(
+                        db=db,
+                        series_id=series_id,
+                        season=season,
+                        episode_number=ep_num
+                    )
+
+    def get_total_to_scan(self) -> int:
+        """Get the total number of folders to scan.
+        
+        Returns:
+            Total count of folders with MP4 files
+        """
+        result = self.__find_mp4_files()
+        return sum(1 for _ in result)
+
+    def scan(self) -> None:
+        """
+        Scan directories for anime series and missing episodes.
+
+        Results are stored in self.keyDict and can be retrieved after
+        scanning. Data files are also saved to disk for persistence.
+
+        Raises:
+            Exception: If scan fails critically
+        """
+        # Generate unique operation ID
+        self._current_operation_id = str(uuid.uuid4())
+
+        logger.info("Starting scan for missing episodes")
+
+        # Notify scan starting
+        self._safe_call_event(
+            self.events.on_progress,
+            {
+                "operation_id": self._current_operation_id,
+                "phase": "STARTING",
+                "current": 0,
+                "total": 0,
+                "percentage": 0.0,
+                "message": "Initializing scan"
+            }
+        )
+
+        try:
+            # Get total items to process
+            total_to_scan = self.get_total_to_scan()
+            logger.info("Total folders to scan: %d", total_to_scan)
+
+            # The scanner enumerates folders with mp4 files, loads existing
+            # metadata, calculates the missing episodes via the provider, and
+            # persists the refreshed metadata while emitting progress events.
+            result = self.__find_mp4_files()
+            counter = 0
+
+            for folder, mp4_files in result:
+                try:
+                    counter += 1
+
+                    # Calculate progress
+                    if total_to_scan > 0:
+                        percentage = (counter / total_to_scan) * 100
+                    else:
+                        percentage = 0.0
+
+                    # Notify progress
+                    self._safe_call_event(
+                        self.events.on_progress,
+                        {
+                            "operation_id": self._current_operation_id,
+                            "phase": "IN_PROGRESS",
+                            "current": counter,
+                            "total": total_to_scan,
+                            "percentage": percentage,
+                            "message": f"Scanning: {folder}",
+                            "details": f"Found {len(mp4_files)} episodes"
+                        }
+                    )
+
+                    serie = self.__read_data_from_file(folder)
+                    if serie is None or not serie.key or not serie.key.strip():
+                        logger.warning(
+                            "No series found in DB for folder '%s', skipping",
+                            folder,
+                        )
+                        continue
+                    if (
+                        serie is not None
+                        and serie.key
+                        and serie.key.strip()
+                    ):
+                        # Delegate the provider to compare local files with
+                        # remote metadata, yielding missing episodes per
+                        # season. Results are saved back to disk so that both
+                        # CLI and API consumers see consistent state.
+                        missing_episodes, _site = (
+                            self.__get_missing_episodes_and_season(
+                                serie.key, mp4_files
+                            )
+                        )
+                        serie.episodeDict = missing_episodes
+                        serie.folder = folder
+
+                        # Persist to database (async)
+                        try:
+                            try:
+                                loop = asyncio.get_running_loop()
+                            except RuntimeError:
+                                # No running loop — safe to use asyncio.run()
+                                asyncio.run(self._persist_serie_to_db(serie))
+                            else:
+                                # Already in async context — schedule as task
+                                asyncio.create_task(self._persist_serie_to_db(serie))
+                        except Exception as e:
+                            logger.warning(
+                                "DB persistence failed for '%s', "
+                                "continuing without DB: %s",
+                                serie.key, e
+                            )
+
+                        # Store by key (primary identifier), not folder
+                        if serie.key in self.keyDict:
+                            existing = self.keyDict[serie.key]
+                            logger.warning(
+                                "Duplicate series found with key '%s': "
+                                "folder '%s' maps to same key as existing folder '%s'. "
+                                "Skipping duplicate folder.",
+                                serie.key,
+                                folder,
+                                existing.folder
+                            )
+                            self._safe_call_event(
+                                self.events.on_warning,
+                                {
+                                    "operation_id": self._current_operation_id,
+                                    "warning": "duplicate_key",
+                                    "message": f"Duplicate series skipped: '{folder}' maps to key '{serie.key}' already used by '{existing.folder}'",
+                                    "metadata": {
+                                        "key": serie.key,
+                                        "duplicate_folder": folder,
+                                        "existing_folder": existing.folder,
+                                    }
+                                }
+                            )
+                        else:
+                            self.keyDict[serie.key] = serie
+                            logger.debug(
+                                "Stored series with key '%s' (folder: '%s')",
+                                serie.key,
+                                folder
+                            )
+                            no_key_found_logger.info(
+                                "Saved Serie: '%s'", str(serie)
+                            )
+
+                except Exception as e:
+                    # Log error and notify via callback
+                    error_msg = (
+                        f"Folder: '{folder}' - "
+                        f"Unexpected error: {e}"
+                    )
+                    error_logger.error(
+                        "%s\n%s",
+                        error_msg,
+                        traceback.format_exc()
+                    )
+
+                    self._safe_call_event(
+                        self.events.on_error,
+                        {
+                            "operation_id": self._current_operation_id,
+                            "error": e,
+                            "message": error_msg,
+                            "recoverable": True,
+                            "metadata": {"folder": folder, "key": None}
+                        }
+                    )
+                    continue
+
+            # Notify scan completion
+            self._safe_call_event(
+                self.events.on_completion,
+                {
+                    "operation_id": self._current_operation_id,
+                    "success": True,
+                    "message": f"Scan completed. Processed {counter} folders.",
+                    "statistics": {
+                        "total_folders": counter,
+                        "series_found": len(self.keyDict)
+                    }
+                }
+            )
+
+            logger.info(
+                "Scan completed. Processed %d folders, found %d series",
+                counter,
+                len(self.keyDict)
+            )
+
+        except Exception as e:
+            # Critical error - notify and re-raise
+            error_msg = f"Critical scan error: {e}"
+            logger.error("%s\n%s", error_msg, traceback.format_exc())
+
+            self._safe_call_event(
+                self.events.on_error,
+                {
+                    "operation_id": self._current_operation_id,
+                    "error": e,
+                    "message": error_msg,
+                    "recoverable": False
+                }
+            )
+
+            self._safe_call_event(
+                self.events.on_completion,
+                {
+                    "operation_id": self._current_operation_id,
+                    "success": False,
+                    "message": error_msg
+                }
+            )
+
+            raise
+
+    def __find_mp4_files(self) -> Iterator[tuple[str, list[str]]]:
+        """Find all .mp4 files in the directory structure."""
+        logger.info("Scanning for .mp4 files")
+        for anime_name in os.listdir(self.directory):
+            anime_path = os.path.join(self.directory, anime_name)
+            if os.path.isdir(anime_path):
+                if settings.should_ignore_folder(anime_name):
+                    logger.debug("Skipping ignored folder: %s", anime_name)
+                    continue
+                mp4_files: list[str] = []
+                has_files = False
+                for root, _, files in os.walk(anime_path):
+                    for file in files:
+                        if file.endswith(".mp4"):
+                            mp4_files.append(os.path.join(root, file))
+                            has_files = True
+                yield anime_name, mp4_files if has_files else []
+
+    def __read_data_from_file(self, folder_name: str) -> Optional[AnimeSeries]:
+        """Load or discover an AnimeSeries for the given folder.
+
+        Strategy:
+        1. Query DB by folder name
+        2. If not found in DB, return None (no file fallback)
+
+        Args:
+            folder_name: Filesystem folder name
+
+        Returns:
+            AnimeSeries object if found in DB, None otherwise
+        """
+        # Step 1: Try DB lookup by folder name
+        try:
+            session = get_sync_session()
+            try:
+                anime_series = AnimeSeriesService.get_by_folder_sync(session, folder_name)
+                return anime_series
+            finally:
+                session.close()
+        except Exception as exc:
+            logger.warning(
+                "DB lookup failed for folder '%s': %s",
+                folder_name,
+                exc
+            )
+
+        return None
+
+    def __get_episode_and_season(self, filename: str) -> tuple[int, int]:
+        """Extract season and episode numbers from filename.
+        
+        Args:
+            filename: Filename to parse
+            
+        Returns:
+            Tuple of (season, episode) as integers
+            
+        Raises:
+            MatchNotFoundError: If pattern not found
+        """
+        pattern = r'S(\d+)E(\d+)'
+        match = re.search(pattern, filename)
+        if match:
+            season = match.group(1)
+            episode = match.group(2)
+            logger.debug(
+                "Extracted season %s, episode %s from '%s'",
+                season,
+                episode,
+                filename
+            )
+            return int(season), int(episode)
+        else:
+            logger.error(
+                "Failed to find season/episode pattern in '%s'",
+                filename
+            )
+            raise MatchNotFoundError(
+                "Season and episode pattern not found in the filename."
+            )
+
+    def __get_episodes_and_seasons(
+        self,
+        mp4_files: Iterable[str]
+    ) -> dict[int, list[int]]:
+        """Get episodes grouped by season from mp4 files.
+        
+        Args:
+            mp4_files: List of MP4 filenames
+            
+        Returns:
+            Dictionary mapping season to list of episode numbers
+        """
+        episodes_dict: dict[int, list[int]] = {}
+
+        for file in mp4_files:
+            season, episode = self.__get_episode_and_season(file)
+
+            if season in episodes_dict:
+                episodes_dict[season].append(episode)
+            else:
+                episodes_dict[season] = [episode]
+        return episodes_dict
+
+    def __get_missing_episodes_and_season(
+        self,
+        key: str,
+        mp4_files: Iterable[str]
+    ) -> tuple[dict[int, list[int]], str]:
+        """Get missing episodes for a serie.
+        
+        Args:
+            key: Series key
+            mp4_files: List of MP4 filenames
+            
+        Returns:
+            Tuple of (episodes_dict, site_name)
+        """
+        # key season , value count of episodes
+        expected_dict = self.loader.get_season_episode_count(key)
+        filedict = self.__get_episodes_and_seasons(mp4_files)
+        episodes_dict: dict[int, list[int]] = {}
+        for season, expected_count in expected_dict.items():
+            existing_episodes = filedict.get(season, [])
+            missing_episodes = [
+                ep for ep in range(1, expected_count + 1)
+                if ep not in existing_episodes
+                and self.loader.is_language(season, ep, key)
+            ]
+
+            if missing_episodes:
+                episodes_dict[season] = missing_episodes
+
+        return episodes_dict, "aniworld.to"
+
+    def scan_single_series(
+        self,
+        key: str,
+        folder: str,
+    ) -> dict[int, list[int]]:
+        """
+        Scan a single series for missing episodes.
+        
+        This method performs a targeted scan for only the specified series,
+        without triggering a full library rescan. It fetches available
+        episodes from the provider and compares with local files.
+        
+        Args:
+            key: The unique provider key for the series
+            folder: The filesystem folder name where the series is stored
+            
+        Returns:
+            dict[int, list[int]]: Dictionary mapping season numbers to lists
+                of missing episode numbers. Empty dict if no missing episodes.
+                
+        Raises:
+            ValueError: If key or folder is empty
+            
+        Example:
+            >>> scanner = SerieScanner("/path/to/anime", loader)
+            >>> missing = scanner.scan_single_series(
+            ...     "attack-on-titan",
+            ...     "Attack on Titan"
+            ... )
+            >>> print(missing)
+            {1: [5, 6, 7], 2: [1, 2]}
+        """
+        if not key or not key.strip():
+            raise ValueError("Series key cannot be empty")
+        if not folder or not folder.strip():
+            raise ValueError("Series folder cannot be empty")
+        
+        logger.info(
+            "Starting targeted scan for series: %s (folder: %s)",
+            key,
+            folder
+        )
+        
+        # Generate unique operation ID for this targeted scan
+        operation_id = str(uuid.uuid4())
+        # Notify scan starting
+        self._safe_call_event(
+            self.events.on_progress,
+            {
+                "operation_id": operation_id,
+                "phase": "STARTING",
+                "current": 0,
+                "total": 1,
+                "percentage": 0.0,
+                "message": f"Scanning series: {folder}",
+                "details": f"Key: {key}"
+            }
+        )
+        
+        try:
+            # Get the folder path
+            folder_path = os.path.join(self.directory, folder)
+            
+            # Check if folder exists
+            if not os.path.isdir(folder_path):
+                logger.info(
+                    "Series folder does not exist yet: %s - "
+                    "will scan for available episodes from provider",
+                    folder_path
+                )
+                mp4_files: list[str] = []
+            else:
+                # Find existing MP4 files in the folder
+                mp4_files = []
+                for root, _, files in os.walk(folder_path):
+                    for file in files:
+                        if file.endswith(".mp4"):
+                            mp4_files.append(os.path.join(root, file))
+                
+                logger.debug(
+                    "Found %d existing MP4 files in folder %s",
+                    len(mp4_files),
+                    folder
+                )
+            
+            # Get missing episodes from provider
+            missing_episodes, site = self.__get_missing_episodes_and_season(
+                key, mp4_files
+            )
+            
+            # Update progress
+            self._safe_call_event(
+                self.events.on_progress,
+                {
+                    "operation_id": operation_id,
+                    "phase": "IN_PROGRESS",
+                    "current": 1,
+                    "total": 1,
+                    "percentage": 100.0,
+                    "message": f"Scanned: {folder}",
+                    "details": f"Found {sum(len(eps) for eps in missing_episodes.values())} missing episodes"
+                }
+            )
+            
+            # Create or update AnimeSeries in keyDict
+            if key in self.keyDict:
+                # Update existing anime - rebuild episodeDict from episodes
+                existing = self.keyDict[key]
+                existing_ep_dict = existing.episodeDict
+                # Merge missing episodes
+                for season, eps in missing_episodes.items():
+                    if season not in existing_ep_dict:
+                        existing_ep_dict[season] = []
+                    existing_ep_dict[season].extend(eps)
+                logger.debug(
+                    "Updated existing series %s with %d missing episodes",
+                    key,
+                    sum(len(eps) for eps in missing_episodes.values())
+                )
+            else:
+                # Extract year from folder name if present, otherwise leave as None
+                year = self._extract_year_from_folder_name(folder)
+
+                # Create new AnimeSeries entry (minimal, fields populated later)
+                from src.server.database.models import AnimeSeries
+                anime_series = AnimeSeries(
+                    key=key,
+                    name=folder,  # Use folder as fallback name since we don't have actual name
+                    site=site,
+                    folder=folder,
+                    year=year
+                )
+                # Set episodeDict cache directly since AnimeSeries doesn't persist missing episodes
+                # (they get synced to DB via _persist_serie_to_db later)
+                anime_series._episode_dict_cache = missing_episodes.copy()
+                self.keyDict[key] = anime_series
+                logger.debug(
+                    "Created new series entry for %s with %d missing episodes (year=%s)",
+                    key,
+                    sum(len(eps) for eps in missing_episodes.values()),
+                    year
+                )
+            
+            # Notify completion
+            self._safe_call_event(
+                self.events.on_completion,
+                {
+                    "operation_id": operation_id,
+                    "success": True,
+                    "message": f"Scan completed for {folder}",
+                    "statistics": {
+                        "missing_episodes": sum(
+                            len(eps) for eps in missing_episodes.values()
+                        ),
+                        "seasons_with_missing": len(missing_episodes)
+                    }
+                }
+            )
+            
+            logger.info(
+                "Targeted scan completed for %s: %d missing episodes across %d seasons",
+                key,
+                sum(len(eps) for eps in missing_episodes.values()),
+                len(missing_episodes)
+            )
+            
+            return missing_episodes
+            
+        except Exception as e:
+            error_msg = f"Failed to scan series {key}: {e}"
+            logger.error(error_msg, exc_info=True)
+            
+            # Notify error
+            self._safe_call_event(
+                self.events.on_error,
+                {
+                    "operation_id": operation_id,
+                    "error": e,
+                    "message": error_msg,
+                    "recoverable": True,
+                    "metadata": {"key": key, "folder": folder}
+                }
+            )
+            # Notify completion with failure
+            self._safe_call_event(
+                self.events.on_completion,
+                {
+                    "operation_id": operation_id,
+                    "success": False,
+                    "message": error_msg
+                }
+            )
+            # Return empty dict on error (scan failed but not critical)
+            return {}
+

src/server/SeriesApp.py

@@ -0,0 +1,817 @@
+"""
+SeriesApp - Core application logic for anime series management.
+
+This module provides the main application interface for searching,
+downloading, and managing anime series with support for async callbacks,
+progress reporting, and error handling.
+
+Note:
+    This module is pure domain logic with no database dependencies.
+    Database operations are handled by the service layer (AnimeService).
+"""
+
+import asyncio
+import logging
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, List, Optional
+
+from events import Events
+
+from src.config.settings import settings
+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__)
+
+
+class DownloadStatusEventArgs:
+    """Event arguments for download status events."""
+
+    def __init__(
+        self,
+        serie_folder: str,
+        season: int,
+        episode: int,
+        status: str,
+        key: Optional[str] = None,
+        progress: float = 0.0,
+        message: Optional[str] = None,
+        error: Optional[Exception] = None,
+        eta: Optional[int] = None,
+        mbper_sec: Optional[float] = None,
+        item_id: Optional[str] = None,
+    ):
+        """
+        Initialize download status event arguments.
+
+        Args:
+            serie_folder: Serie folder name (metadata only, used for
+                file paths)
+            season: Season number
+            episode: Episode number
+            status: Status message (e.g., "started", "progress",
+                "completed", "failed")
+            key: Serie unique identifier (provider key, primary
+                identifier)
+            progress: Download progress (0.0 to 1.0)
+            message: Optional status message
+            error: Optional error if status is "failed"
+            eta: Estimated time remaining in seconds
+            mbper_sec: Download speed in MB/s
+            item_id: Optional download queue item ID for tracking
+        """
+        self.serie_folder = serie_folder
+        self.key = key
+        self.season = season
+        self.episode = episode
+        self.status = status
+        self.progress = progress
+        self.message = message
+        self.error = error
+        self.eta = eta
+        self.mbper_sec = mbper_sec
+        self.item_id = item_id
+
+
+class ScanStatusEventArgs:
+    """Event arguments for scan status events."""
+
+    def __init__(
+        self,
+        current: int,
+        total: int,
+        folder: str,
+        status: str,
+        key: Optional[str] = None,
+        progress: float = 0.0,
+        message: Optional[str] = None,
+        error: Optional[Exception] = None,
+    ):
+        """
+        Initialize scan status event arguments.
+
+        Args:
+            current: Current item being scanned
+            total: Total items to scan
+            folder: Current folder being scanned (metadata only)
+            status: Status message (e.g., "started", "progress",
+                "completed", "failed", "cancelled")
+            key: Serie unique identifier if applicable (provider key,
+                primary identifier)
+            progress: Scan progress (0.0 to 1.0)
+            message: Optional status message
+            error: Optional error if status is "failed"
+        """
+        self.current = current
+        self.total = total
+        self.folder = folder
+        self.key = key
+        self.status = status
+        self.progress = progress
+        self.message = message
+        self.error = error
+
+
+class SeriesApp:
+    """
+    Main application class for anime series management.
+
+    Provides functionality for:
+    - Searching anime series
+    - Downloading episodes
+    - Scanning directories for missing episodes
+    - Managing series lists
+
+    Supports async callbacks for progress reporting.
+    
+    Note:
+        This class is now pure domain logic with no database dependencies.
+        Database operations are handled by the service layer (AnimeService).
+
+    Events:
+        download_status: Raised when download status changes.
+            Handler signature: def handler(args: DownloadStatusEventArgs)
+        scan_status: Raised when scan status changes.
+            Handler signature: def handler(args: ScanStatusEventArgs)
+    """
+
+    def __init__(
+        self,
+        directory_to_search: str,
+    ):
+        """
+        Initialize SeriesApp.
+
+        Args:
+            directory_to_search: Base directory for anime series
+        """
+
+        self.directory_to_search = directory_to_search
+
+        # Initialize thread pool executor
+        self.executor = ThreadPoolExecutor(max_workers=3)
+
+        # Initialize events
+        self._events = Events()
+
+        self.loaders = Loaders()
+        self.loader = self.loaders.GetLoader(key="aniworld.to")
+        self.serie_scanner = SerieScanner(
+            directory_to_search,
+            self.loader,
+        )
+        # 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
+        
+        # NFO service removed - metadata handling moved to server layer
+        self.nfo_service = None
+        
+        logger.info(
+            "SeriesApp initialized for directory: %s",
+            directory_to_search,
+        )
+
+    @property
+    def download_status(self):
+        """
+        Event raised when download status changes.
+
+        Subscribe using:
+            app.download_status += handler
+        """
+        return self._events.download_status
+
+    @download_status.setter
+    def download_status(self, value):
+        """Set download_status event handler."""
+        self._events.download_status = value
+
+    @property
+    def scan_status(self):
+        """
+        Event raised when scan status changes.
+
+        Subscribe using:
+            app.scan_status += handler
+        """
+        return self._events.scan_status
+
+    @scan_status.setter
+    def scan_status(self, value):
+        """Set scan_status event handler."""
+        self._events.scan_status = value
+    
+    def load_series_from_list(self, series: list) -> None:
+        """
+        Load series into the in-memory list.
+        
+        This method is called by the service layer after loading
+        series from the database.
+        
+        Args:
+            series: List of Serie objects to load
+        """
+        self.list.keyDict.clear()
+        for serie in series:
+            self.list.keyDict[serie.key] = serie
+        self.series_list = self.list.GetMissingEpisode()
+        logger.debug(
+            "Loaded %d series with %d having missing episodes",
+            len(series),
+            len(self.series_list)
+        )
+
+    async def search(self, words: str) -> List[Dict[str, Any]]:
+        """
+        Search for anime series (async).
+
+        Args:
+            words: Search query
+
+        Returns:
+            List of search results
+
+        Raises:
+            RuntimeError: If search fails
+        """
+        logger.info("Searching for: %s", words)
+        loop = asyncio.get_running_loop()
+        results = await loop.run_in_executor(
+            self.executor,
+            self.loader.search,
+            words
+        )
+        logger.info("Found %d results", len(results))
+        return results
+      
+    async def download(
+        self,
+        serie_folder: str,
+        season: int,
+        episode: int,
+        key: str,
+        language: str = "German Dub",
+        item_id: Optional[str] = None,
+    ) -> bool:
+        """
+        Download an episode (async).
+
+        Args:
+            serie_folder: Serie folder name (metadata only, used for
+                file path construction)
+            season: Season number
+            episode: Episode number
+            key: Serie unique identifier (provider key, primary
+                identifier for lookups)
+            language: Language preference
+            item_id: Optional download queue item ID for progress
+                tracking
+
+        Returns:
+            True if download succeeded, False otherwise
+            
+        Note:
+            The 'key' parameter is the primary identifier for series
+            lookups. The 'serie_folder' parameter is only used for
+            filesystem operations.
+        """
+        
+        logger.info(
+            "Starting download: %s (key: %s) S%02dE%02d",
+            serie_folder,
+            key,
+            season,
+            episode
+        )
+
+        # Fire download started event
+        self._events.download_status(
+            DownloadStatusEventArgs(
+                serie_folder=serie_folder,
+                key=key,
+                season=season,
+                episode=episode,
+                status="started",
+                message="Download started",
+                item_id=item_id,
+            )
+        )
+
+        # Create series folder if it doesn't exist
+        folder_path = os.path.join(self.directory_to_search, serie_folder)
+        if not os.path.exists(folder_path):
+            try:
+                os.makedirs(folder_path, exist_ok=True)
+                logger.info(
+                    "Created series folder: %s (key: %s)",
+                    folder_path,
+                    key
+                )
+            except OSError as e:
+                logger.error(
+                    "Failed to create series folder %s: %s",
+                    folder_path,
+                    str(e)
+                )
+                # Fire download failed event
+                self._events.download_status(
+                    DownloadStatusEventArgs(
+                        serie_folder=serie_folder,
+                        key=key,
+                        season=season,
+                        episode=episode,
+                        status="failed",
+                        message=f"Failed to create folder: {str(e)}",
+                        item_id=item_id,
+                    )
+                )
+                return False
+
+        try:
+            def download_progress_handler(progress_info):
+                """Handle download progress events from loader."""
+                # 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 = (
+                    progress_info.get('total_bytes')
+                    or progress_info.get('total_bytes_estimate', 0)
+                )
+
+                speed = progress_info.get('speed', 0)  # bytes/sec
+                eta = progress_info.get('eta')  # seconds
+                mbper_sec = speed / (1024 * 1024) if speed else None
+
+                self._events.download_status(
+                    DownloadStatusEventArgs(
+                        serie_folder=serie_folder,
+                        key=key,
+                        season=season,
+                        episode=episode,
+                        status="progress",
+                        message="Download progress",
+                        progress=(
+                            (downloaded / total_bytes) * 100
+                            if total_bytes else 0
+                        ),
+                        eta=eta,
+                        mbper_sec=mbper_sec,
+                        item_id=item_id,
+                    )
+                )
+            
+            # Subscribe to loader's download progress events
+            self.loader.subscribe_download_progress(download_progress_handler)
+            
+            try:
+                # Perform download in thread to avoid blocking event loop
+                loop = asyncio.get_running_loop()
+                download_success = await loop.run_in_executor(
+                    self.executor,
+                    self.loader.download,
+                    self.directory_to_search,
+                    serie_folder,
+                    season,
+                    episode,
+                    key,
+                    language
+                )
+            finally:
+                # Always unsubscribe after download completes or fails
+                self.loader.unsubscribe_download_progress(
+                    download_progress_handler
+                )
+
+            if download_success:
+                logger.info(
+                    "Download completed: %s (key: %s) S%02dE%02d",
+                    serie_folder,
+                    key,
+                    season,
+                    episode
+                )
+
+                # Fire download completed event
+                self._events.download_status(
+                    DownloadStatusEventArgs(
+                        serie_folder=serie_folder,
+                        key=key,
+                        season=season,
+                        episode=episode,
+                        status="completed",
+                        progress=1.0,
+                        message="Download completed successfully",
+                        item_id=item_id,
+                    )
+                )
+            else:
+                logger.warning(
+                    "Download failed: %s (key: %s) S%02dE%02d",
+                    serie_folder,
+                    key,
+                    season,
+                    episode
+                )
+
+                # Fire download failed event
+                self._events.download_status(
+                    DownloadStatusEventArgs(
+                        serie_folder=serie_folder,
+                        key=key,
+                        season=season,
+                        episode=episode,
+                        status="failed",
+                        message="Download failed",
+                        item_id=item_id,
+                    )
+                )
+
+            return download_success
+
+        except InterruptedError:
+            # Download was cancelled - propagate the cancellation
+            logger.info(
+                "Download cancelled: %s (key: %s) S%02dE%02d",
+                serie_folder,
+                key,
+                season,
+                episode,
+            )
+            # Fire download cancelled event
+            self._events.download_status(
+                DownloadStatusEventArgs(
+                    serie_folder=serie_folder,
+                    key=key,
+                    season=season,
+                    episode=episode,
+                    status="cancelled",
+                    message="Download cancelled by user",
+                    item_id=item_id,
+                )
+            )
+            raise  # Re-raise to propagate cancellation
+
+        except Exception as e:  # pylint: disable=broad-except
+            logger.error(
+                "Download error: %s (key: %s) S%02dE%02d - %s",
+                serie_folder,
+                key,
+                season,
+                episode,
+                str(e),
+                exc_info=True,
+            )
+
+            # Fire download error event
+            self._events.download_status(
+                DownloadStatusEventArgs(
+                    serie_folder=serie_folder,
+                    key=key,
+                    season=season,
+                    episode=episode,
+                    status="failed",
+                    error=e,
+                    message=f"Download error: {str(e)}",
+                    item_id=item_id,
+                )
+            )
+
+            return False
+
+    async def rescan(self) -> list:
+        """
+        Rescan directory for missing episodes (async).
+        
+        This method performs a file-based scan and returns the results.
+        Database persistence is handled by the service layer (AnimeService).
+
+        Returns:
+            List of Serie objects found during scan with their
+            missing episodes.
+            
+        Note:
+            This method no longer saves to database directly. The returned
+            list should be persisted by the caller (AnimeService).
+        """
+        logger.info("Starting directory rescan")
+
+        total_to_scan = 0
+
+        try:
+            # Get total items to scan
+            logger.info("Getting total items to scan...")
+            loop = asyncio.get_running_loop()
+            total_to_scan = await loop.run_in_executor(
+                self.executor,
+                self.serie_scanner.get_total_to_scan
+            )
+            logger.info("Total folders to scan: %d", total_to_scan)
+
+            # Fire scan started event
+            logger.info(
+                "Firing scan_status 'started' event, handler=%s",
+                self._events.scan_status
+            )
+            self._events.scan_status(
+                ScanStatusEventArgs(
+                    current=0,
+                    total=total_to_scan,
+                    folder="",
+                    status="started",
+                    progress=0.0,
+                    message="Scan started",
+                )
+            )
+
+            # Reinitialize scanner
+            await loop.run_in_executor(
+                self.executor,
+                self.serie_scanner.reinit
+            )
+
+            def scan_progress_handler(progress_data):
+                """Handle scan progress events from scanner."""
+                # Fire scan progress event
+                message = progress_data.get('message', '')
+                folder = message.replace('Scanning: ', '')
+                self._events.scan_status(
+                    ScanStatusEventArgs(
+                        current=progress_data.get('current', 0),
+                        total=progress_data.get('total', total_to_scan),
+                        folder=folder,
+                        status="progress",
+                        progress=(
+                            progress_data.get('percentage', 0.0) / 100.0
+                        ),
+                        message=message,
+                    )
+                )
+
+            # Subscribe to scanner's progress events
+            self.serie_scanner.subscribe_on_progress(scan_progress_handler)
+            
+            try:
+                # Perform scan (file-based, returns results in scanner.keyDict)
+                await loop.run_in_executor(
+                    self.executor,
+                    self.serie_scanner.scan
+                )
+            finally:
+                # Always unsubscribe after scan completes or fails
+                self.serie_scanner.unsubscribe_on_progress(
+                    scan_progress_handler
+                )
+            
+            # Get scanned series from scanner
+            scanned_series = list(self.serie_scanner.keyDict.values())
+
+            # Update in-memory list with scan results
+            self.list.keyDict.clear()
+            for serie in scanned_series:
+                self.list.keyDict[serie.key] = serie
+            self.series_list = self.list.GetMissingEpisode()
+
+            logger.info("Directory rescan completed successfully")
+
+            # Fire scan completed event
+            logger.info(
+                "Firing scan_status 'completed' event, handler=%s",
+                self._events.scan_status
+            )
+            self._events.scan_status(
+                ScanStatusEventArgs(
+                    current=total_to_scan,
+                    total=total_to_scan,
+                    folder="",
+                    status="completed",
+                    progress=1.0,
+                    message=(
+                        f"Scan completed. Found {len(self.series_list)} "
+                        "series with missing episodes."
+                    ),
+                )
+            )
+
+            return scanned_series
+
+        except InterruptedError:
+            logger.warning("Scan cancelled by user")
+
+            # Fire scan cancelled event
+            self._events.scan_status(
+                ScanStatusEventArgs(
+                    current=0,
+                    total=total_to_scan,
+                    folder="",
+                    status="cancelled",
+                    message="Scan cancelled by user",
+                )
+            )
+            raise
+
+        except Exception as e:
+            logger.error("Scan error: %s", str(e), exc_info=True)
+
+            # Fire scan failed event
+            self._events.scan_status(
+                ScanStatusEventArgs(
+                    current=0,
+                    total=total_to_scan,
+                    folder="",
+                    status="failed",
+                    error=e,
+                    message=f"Scan error: {str(e)}",
+                )
+            )
+            raise
+
+    async def get_series_list(self) -> List[Any]:
+        """
+        Get the current series list (async).
+
+        Returns:
+            List of series with missing episodes
+        """
+        return self.series_list
+
+    async def refresh_series_list(self) -> None:
+        """
+        Reload the cached series list from the underlying data store.
+        
+        This is an async operation.
+        """
+        await self._init_list()
+    
+    def _get_serie_by_key(self, key: str) -> Optional[AnimeSeries]:
+        """
+        Get a series by its unique provider key.
+        
+        This is the primary method for series lookups within SeriesApp.
+        
+        Args:
+            key: The unique provider identifier (e.g.,
+                "attack-on-titan")
+            
+        Returns:
+            The AnimeSeries instance if found, None otherwise
+            
+        Note:
+            This method uses the SerieList.get_by_key() method which
+            looks up series by their unique key, not by folder name.
+        """
+        return self.list.get_by_key(key)
+
+    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 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 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 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
+        )
+
+        all_series: List[AnimeSeries] = []
+
+        try:
+            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",
+                str(e),
+                exc_info=True
+            )
+            return []
+
+        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",
+            len(all_series),
+            self.directory_to_search
+        )
+
+        return all_series
+
+    def shutdown(self) -> None:
+        """
+        Shutdown the thread pool executor.
+        
+        Should be called when the SeriesApp instance is no longer needed
+        to properly clean up resources.
+        """
+        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/__init__.py

@@ -0,0 +1 @@
+"""API router modules for the FastAPI server."""

src/server/api/auth.py

@@ -1,84 +1,321 @@
+"""Authentication API endpoints for Aniworld."""
 from typing import Optional
 
-from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.security import HTTPAuthorizationCredentials
+import structlog
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi import status as http_status
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
-from src.server.models.auth import AuthStatus, LoginRequest, LoginResponse, SetupRequest
+from src.server.models.auth import (
+    AuthStatus,
+    LoginRequest,
+    LoginResponse,
+    RegisterRequest,
+    SetupRequest,
+)
+from src.server.models.config import AppConfig
 from src.server.services.auth_service import AuthError, LockedOutError, auth_service
+from src.server.services.config_service import get_config_service
+
+logger = structlog.get_logger(__name__)
 
 # NOTE: import dependencies (optional_auth, security) lazily inside handlers
 # to avoid importing heavyweight modules (e.g. sqlalchemy) at import time.
 
 router = APIRouter(prefix="/api/auth", tags=["auth"])
 
+# HTTPBearer for optional authentication
+optional_bearer = HTTPBearer(auto_error=False)
 
-@router.post("/setup", status_code=status.HTTP_201_CREATED)
-def setup_auth(req: SetupRequest):
-    """Initial setup endpoint to configure the master password."""
+
+@router.post("/setup", status_code=http_status.HTTP_201_CREATED)
+async def setup_auth(req: SetupRequest):
+    """Initial setup endpoint to configure the master password.
+    
+    This endpoint also initializes the configuration with all provided values
+    and saves them to config.json. It triggers background initialization
+    and redirects to a loading page that shows real-time progress.
+    """
     if auth_service.is_configured():
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
+            status_code=http_status.HTTP_400_BAD_REQUEST,
             detail="Master password already configured",
         )
 
     try:
-        auth_service.setup_master_password(req.master_password)
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        # Set up master password (this validates and hashes it)
+        password_hash = auth_service.setup_master_password(
+            req.master_password
+        )
+        
+        # Initialize or update config with all provided values
+        config_service = get_config_service()
+        try:
+            config = config_service.load_config()
+        except Exception:
+            # If config doesn't exist, create default
+            from src.server.models.config import (
+                BackupConfig,
+                LoggingConfig,
+                NFOConfig,
+                SchedulerConfig,
+            )
+            config = AppConfig()
+        
+        # Update basic settings
+        if req.name:
+            config.name = req.name
+        if req.data_dir:
+            config.data_dir = req.data_dir
+        
+        # Update scheduler configuration
+        if req.scheduler_enabled is not None:
+            config.scheduler.enabled = req.scheduler_enabled
+        if req.scheduler_interval_minutes is not None:
+            config.scheduler.interval_minutes = req.scheduler_interval_minutes
+        if req.scheduler_schedule_time is not None:
+            config.scheduler.schedule_time = req.scheduler_schedule_time
+        if req.scheduler_schedule_days is not None:
+            config.scheduler.schedule_days = req.scheduler_schedule_days
+        if req.scheduler_auto_download_after_rescan is not None:
+            config.scheduler.auto_download_after_rescan = req.scheduler_auto_download_after_rescan
+        
+        # Update logging configuration
+        if req.logging_level:
+            config.logging.level = req.logging_level.upper()
+        if req.logging_file is not None:
+            config.logging.file = req.logging_file
+        if req.logging_max_bytes is not None:
+            config.logging.max_bytes = req.logging_max_bytes
+        if req.logging_backup_count is not None:
+            config.logging.backup_count = req.logging_backup_count
+        
+        # Update backup configuration
+        if req.backup_enabled is not None:
+            config.backup.enabled = req.backup_enabled
+        if req.backup_path:
+            config.backup.path = req.backup_path
+        if req.backup_keep_days is not None:
+            config.backup.keep_days = req.backup_keep_days
+        
+        # Update NFO configuration
+        if req.nfo_tmdb_api_key is not None:
+            config.nfo.tmdb_api_key = req.nfo_tmdb_api_key
+        if req.nfo_auto_create is not None:
+            config.nfo.auto_create = req.nfo_auto_create
+        if req.nfo_update_on_scan is not None:
+            config.nfo.update_on_scan = req.nfo_update_on_scan
+        if req.nfo_download_poster is not None:
+            config.nfo.download_poster = req.nfo_download_poster
+        if req.nfo_download_logo is not None:
+            config.nfo.download_logo = req.nfo_download_logo
+        if req.nfo_download_fanart is not None:
+            config.nfo.download_fanart = req.nfo_download_fanart
+        if req.nfo_image_size:
+            config.nfo.image_size = req.nfo_image_size.lower()
+        
+        # Store master password hash in config's other field
+        config.other['master_password_hash'] = password_hash
+        
+        # Store anime directory in config's other field if provided
+        anime_directory = None
+        if req.anime_directory:
+            anime_directory = req.anime_directory.strip()
+            if anime_directory:
+                config.other['anime_directory'] = anime_directory
+        
+        # Save the config with all updates
+        config_service.save_config(config, create_backup=False)
+        
+        # Sync config.json values to settings object
+        # (mirroring the logic in fastapi_app.py lifespan)
+        from src.config.settings import settings
+        other_settings = dict(config.other) if config.other else {}
+        if other_settings.get("anime_directory"):
+            settings.anime_directory = str(other_settings["anime_directory"])
+        
+        if config.nfo:
+            if config.nfo.tmdb_api_key:
+                settings.tmdb_api_key = config.nfo.tmdb_api_key
+            settings.nfo_auto_create = config.nfo.auto_create
+            settings.nfo_update_on_scan = config.nfo.update_on_scan
+            settings.nfo_download_poster = config.nfo.download_poster
+            settings.nfo_download_logo = config.nfo.download_logo
+            settings.nfo_download_fanart = config.nfo.download_fanart
+            settings.nfo_image_size = config.nfo.image_size
+        
+        # Trigger initialization in background task
+        import asyncio
 
-    return {"status": "ok"}
+        from src.server.services.initialization_service import (
+            perform_initial_setup,
+            perform_nfo_scan_if_needed,
+        )
+        from src.server.services.progress_service import get_progress_service
+        
+        progress_service = get_progress_service()
+        
+        async def run_initialization():
+            """Run initialization steps with progress updates."""
+            try:
+                # Perform the initial series sync and mark as completed
+                await perform_initial_setup(progress_service)
+                
+                # 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(
+                    progress_id="initialization_complete",
+                    progress_type=ProgressType.SYSTEM,
+                    title="Initialization Complete",
+                    total=100,
+                    message="All initialization tasks completed successfully",
+                    metadata={"initialization_complete": True}
+                )
+                await progress_service.complete_progress(
+                    progress_id="initialization_complete",
+                    message="All initialization tasks completed successfully",
+                    metadata={"initialization_complete": True}
+                )
+            except Exception as e:
+                # Send error event
+                from src.server.services.progress_service import ProgressType
+                await progress_service.start_progress(
+                    progress_id="initialization_error",
+                    progress_type=ProgressType.ERROR,
+                    title="Initialization Failed",
+                    total=100,
+                    message=str(e),
+                    metadata={"initialization_complete": True, "error": str(e)}
+                )
+                await progress_service.fail_progress(
+                    progress_id="initialization_error",
+                    error_message=str(e),
+                    metadata={"initialization_complete": True, "error": str(e)}
+                )
+        
+        # Start initialization in background
+        asyncio.create_task(run_initialization())
+        
+        # Return redirect to loading page
+        return {"status": "ok", "redirect": "/loading"}
+        # Note: Media scan is skipped during setup as it requires
+        # background_loader service which is only available during
+        # application lifespan. It will run on first application startup.
+        
+        return {"status": "ok"}
+        
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
 
 
 @router.post("/login", response_model=LoginResponse)
 def login(req: LoginRequest):
     """Validate master password and return JWT token."""
-    # Use a simple identifier for failed attempts; prefer IP in a real app
+    # Use a simple identifier for failed attempts; prefer IP in real app
     identifier = "global"
 
     try:
-        valid = auth_service.validate_master_password(req.password, identifier=identifier)
-    except AuthError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        valid = auth_service.validate_master_password(
+            req.password, identifier=identifier
+        )
     except LockedOutError as e:
-        raise HTTPException(status_code=429, detail=str(e))
+        raise HTTPException(
+            status_code=http_status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=str(e),
+        ) from e
+    except AuthError as e:
+        # Return 401 for authentication errors (including not configured)
+        # This prevents information leakage about system configuration
+        raise HTTPException(
+            status_code=http_status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials"
+        ) from e
 
     if not valid:
-        raise HTTPException(status_code=401, detail="Invalid credentials")
+        raise HTTPException(
+            status_code=http_status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials"
+        )
 
-    token = auth_service.create_access_token(subject="master", remember=bool(req.remember))
+    token = auth_service.create_access_token(
+        subject="master", remember=bool(req.remember)
+    )
     return token
 
 
 @router.post("/logout")
-def logout(credentials: HTTPAuthorizationCredentials = None):
+def logout_endpoint(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(
+        optional_bearer
+    ),
+):
     """Logout by revoking token (no-op for stateless JWT)."""
-    # Import security dependency lazily to avoid heavy imports during test
-    if credentials is None:
-        from fastapi import Depends
-
-        from src.server.utils.dependencies import security as _security
-
-        # Trigger dependency resolution during normal request handling
-        credentials = Depends(_security)
-
     # If a plain credentials object was provided, extract token
     token = getattr(credentials, "credentials", None)
-    # Placeholder; auth_service.revoke_token can be expanded to persist revocations
-    auth_service.revoke_token(token)
-    return {"status": "ok"}
+    # Placeholder; auth_service.revoke_token can be expanded to persist
+    # revocations
+    if token:
+        auth_service.revoke_token(token)
+    return {"status": "ok", "message": "Logged out successfully"}
+
+
+async def get_optional_auth(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(
+        optional_bearer
+    ),
+) -> Optional[dict]:
+    """Get optional authentication from bearer token."""
+    if credentials is None:
+        return None
+
+    token = credentials.credentials
+    try:
+        # Validate and decode token using the auth service
+        session = auth_service.create_session_model(token)
+        return session.model_dump()
+    except AuthError:
+        return None
 
 
 @router.get("/status", response_model=AuthStatus)
-def status(auth: Optional[dict] = None):
-    """Return whether master password is configured and if caller is authenticated."""
-    # Lazy import to avoid pulling in database/sqlalchemy during module import
-    from fastapi import Depends
-    try:
-        from src.server.utils.dependencies import optional_auth as _optional_auth
-    except Exception:
-        _optional_auth = None
+async def auth_status(auth: Optional[dict] = Depends(get_optional_auth)):
+    """Return whether master password is configured and authenticated."""
+    return AuthStatus(
+        configured=auth_service.is_configured(), authenticated=bool(auth)
+    )
+
+
+@router.post("/register", status_code=http_status.HTTP_201_CREATED)
+def register(req: RegisterRequest):
+    """Register a new user (for testing/validation purposes).
+    
+    Note: This is primarily for input validation testing.
+    The actual Aniworld app uses a single master password.
+    """
+    # This endpoint is primarily for input validation testing
+    # In a real multi-user system, you'd create the user here
+    return {
+        "status": "ok",
+        "message": "User registration successful",
+        "username": req.username,
+    }
 
-    # If dependency injection didn't provide auth, attempt to resolve optionally
-    if auth is None and _optional_auth is not None:
-        auth = Depends(_optional_auth)
-    return AuthStatus(configured=auth_service.is_configured(), authenticated=bool(auth))

src/server/api/config.py

@@ -1,9 +1,17 @@
-from typing import Optional
+import logging
+from typing import Any, Dict, List, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, status
 
-from src.config.settings import settings
+logger = logging.getLogger(__name__)
+
 from src.server.models.config import AppConfig, ConfigUpdate, ValidationResult
+from src.server.services.config_service import (
+    ConfigBackupError,
+    ConfigServiceError,
+    ConfigValidationError,
+    get_config_service,
+)
 from src.server.utils.dependencies import require_auth
 
 router = APIRouter(prefix="/api/config", tags=["config"])
@@ -11,58 +19,451 @@ router = APIRouter(prefix="/api/config", tags=["config"])
 
 @router.get("", response_model=AppConfig)
 def get_config(auth: Optional[dict] = Depends(require_auth)) -> AppConfig:
-    """Return current application configuration (read-only)."""
-    # Construct AppConfig from pydantic-settings where possible
-    cfg_data = {
-        "name": getattr(settings, "app_name", "Aniworld"),
-        "data_dir": getattr(settings, "data_dir", "data"),
-        "scheduler": getattr(settings, "scheduler", {}),
-        "logging": getattr(settings, "logging", {}),
-        "backup": getattr(settings, "backup", {}),
-        "other": getattr(settings, "other", {}),
-    }
+    """Return current application configuration."""
     try:
-        return AppConfig(**cfg_data)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=f"Failed to read config: {e}")
+        config_service = get_config_service()
+        return config_service.load_config()
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to load config: {e}"
+        ) from e
 
 
 @router.put("", response_model=AppConfig)
-def update_config(update: ConfigUpdate, auth: dict = Depends(require_auth)) -> AppConfig:
-    """Apply an update to the configuration and return the new config.
+async def update_config(
+    update: ConfigUpdate, auth: dict = Depends(require_auth)
+) -> AppConfig:
+    """Apply an update to the configuration and persist it.
 
-    Note: persistence strategy for settings is out-of-scope for this task.
-    This endpoint updates the in-memory Settings where possible and returns
-    the merged result as an AppConfig.
+    Creates automatic backup before applying changes. If anime_directory
+    is configured, starts the scheduler service.
     """
-    # Build current AppConfig from settings then apply update
-    current = get_config(auth)
-    new_cfg = update.apply_to(current)
-
-    # Mirror some fields back into pydantic-settings 'settings' where safe.
-    # Avoid writing secrets or unsupported fields.
     try:
-        if new_cfg.data_dir:
-            setattr(settings, "data_dir", new_cfg.data_dir)
-        # scheduler/logging/backup/other kept in memory only for now
-        setattr(settings, "scheduler", new_cfg.scheduler.model_dump())
-        setattr(settings, "logging", new_cfg.logging.model_dump())
-        setattr(settings, "backup", new_cfg.backup.model_dump())
-        setattr(settings, "other", new_cfg.other)
-    except Exception:
-        # Best-effort; do not fail the request if persistence is not available
-        pass
+        config_service = get_config_service()
+        updated_config = config_service.update_config(update)
 
-    return new_cfg
+        # 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,
+            detail=f"Invalid configuration: {e}"
+        ) from e
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update config: {e}"
+        ) from e
 
 
 @router.post("/validate", response_model=ValidationResult)
-def validate_config(cfg: AppConfig, auth: dict = Depends(require_auth)) -> ValidationResult:
+def validate_config(
+    cfg: AppConfig, auth: dict = Depends(require_auth)  # noqa: ARG001
+) -> ValidationResult:
     """Validate a provided AppConfig without applying it.
 
     Returns ValidationResult with any validation errors.
     """
     try:
-        return cfg.validate()
+        config_service = get_config_service()
+        return config_service.validate_config(cfg)
     except Exception as e:
-        raise HTTPException(status_code=400, detail=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        ) from e
+
+
+@router.get("/backups", response_model=List[Dict[str, object]])
+def list_backups(
+    auth: dict = Depends(require_auth)
+) -> List[Dict[str, object]]:
+    """List all available configuration backups.
+
+    Returns list of backup metadata including name, size, and created time.
+    """
+    try:
+        config_service = get_config_service()
+        return config_service.list_backups()
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to list backups: {e}"
+        ) from e
+
+
+@router.post("/backups", response_model=Dict[str, str])
+def create_backup(
+    name: Optional[str] = None, auth: dict = Depends(require_auth)
+) -> Dict[str, str]:
+    """Create a backup of the current configuration.
+
+    Args:
+        name: Optional custom backup name (timestamp used if not provided)
+
+    Returns:
+        Dictionary with backup name and message
+    """
+    try:
+        config_service = get_config_service()
+        backup_path = config_service.create_backup(name)
+        return {
+            "name": backup_path.name,
+            "message": "Backup created successfully"
+        }
+    except ConfigBackupError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Failed to create backup: {e}"
+        ) from e
+
+
+@router.post("/backups/{backup_name}/restore", response_model=AppConfig)
+def restore_backup(
+    backup_name: str, auth: dict = Depends(require_auth)
+) -> AppConfig:
+    """Restore configuration from a backup.
+
+    Creates backup of current config before restoring.
+
+    Args:
+        backup_name: Name of backup file to restore
+
+    Returns:
+        Restored configuration
+    """
+    try:
+        config_service = get_config_service()
+        return config_service.restore_backup(backup_name)
+    except ConfigBackupError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Failed to restore backup: {e}"
+        ) from e
+
+
+@router.delete("/backups/{backup_name}")
+def delete_backup(
+    backup_name: str, auth: dict = Depends(require_auth)
+) -> Dict[str, str]:
+    """Delete a configuration backup.
+
+    Args:
+        backup_name: Name of backup file to delete
+
+    Returns:
+        Success message
+    """
+    try:
+        config_service = get_config_service()
+        config_service.delete_backup(backup_name)
+        return {"message": f"Backup '{backup_name}' deleted successfully"}
+    except ConfigBackupError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Failed to delete backup: {e}"
+        ) from e
+
+
+@router.get("/section/advanced", response_model=Dict[str, object])
+def get_advanced_config(
+    auth: Optional[dict] = Depends(require_auth)
+) -> Dict[str, object]:
+    """Get advanced configuration section.
+
+    Returns:
+        Dictionary with advanced configuration settings
+    """
+    try:
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+        return app_config.other.get("advanced", {})
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to load advanced config: {e}"
+        ) from e
+
+
+@router.post("/section/advanced", response_model=Dict[str, str])
+def update_advanced_config(
+    config: Dict[str, object], auth: dict = Depends(require_auth)
+) -> Dict[str, str]:
+    """Update advanced configuration section.
+
+    Args:
+        config: Advanced configuration settings
+        auth: Authentication token (required)
+
+    Returns:
+        Success message
+    """
+    try:
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+
+        # Update advanced section in other
+        if "advanced" not in app_config.other:
+            app_config.other["advanced"] = {}
+        app_config.other["advanced"].update(config)
+
+        config_service.save_config(app_config)
+        return {"message": "Advanced configuration updated successfully"}
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update advanced config: {e}"
+        ) from e
+
+
+@router.post("/directory", response_model=Dict[str, Any])
+async def update_directory(
+    directory_config: Dict[str, str], auth: dict = Depends(require_auth)
+) -> Dict[str, Any]:
+    """Update anime directory configuration.
+
+    Args:
+        directory_config: Dictionary with 'directory' key
+        auth: Authentication token (required)
+
+    Returns:
+        Success message
+    """
+    try:
+        directory = directory_config.get("directory")
+        if not directory:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Directory path is required"
+            )
+
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+
+        # Store directory in other section
+        app_config.other["anime_directory"] = directory
+
+        config_service.save_config(app_config)
+        
+        # Sync series from data files to database
+        sync_count = 0
+        try:
+            import structlog
+
+            from src.server.services.anime_service import sync_legacy_series_to_db
+            logger = structlog.get_logger(__name__)
+            sync_count = await sync_legacy_series_to_db(directory, logger)
+            logger.info(
+                "Directory updated: synced series from data files",
+                directory=directory,
+                count=sync_count
+            )
+        except Exception as e:
+            # Log but don't fail the directory update if sync fails
+            import structlog
+            structlog.get_logger(__name__).warning(
+                "Failed to sync series after directory update",
+                error=str(e)
+            )
+        
+        response: Dict[str, Any] = {
+            "message": "Anime directory updated successfully",
+            "synced_series": sync_count
+        }
+        
+        return response
+    except ConfigServiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update directory: {e}"
+        ) from e
+
+
+@router.post("/export")
+async def export_config(
+    export_options: Dict[str, bool], auth: dict = Depends(require_auth)
+):
+    """Export configuration to JSON file.
+
+    Args:
+        export_options: Options for export (include_sensitive, etc.)
+        auth: Authentication token (required)
+
+    Returns:
+        JSON file download response
+    """
+    try:
+        import json
+
+        from fastapi.responses import Response
+
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+
+        # Convert to dict
+        config_dict = app_config.model_dump()
+
+        # Optionally remove sensitive data
+        if not export_options.get("include_sensitive", False):
+            # Remove sensitive fields if present
+            config_dict.pop("password_salt", None)
+            config_dict.pop("password_hash", None)
+
+        # Create filename with timestamp
+        from datetime import datetime
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = f"aniworld_config_{timestamp}.json"
+
+        # Return as downloadable JSON
+        content = json.dumps(config_dict, indent=2)
+        return Response(
+            content=content,
+            media_type="application/json",
+            headers={
+                "Content-Disposition": f'attachment; filename="{filename}"'
+            }
+        )
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to export config: {e}"
+        ) from e
+
+
+@router.post("/reset", response_model=Dict[str, str])
+def reset_config(
+    reset_options: Dict[str, bool], auth: dict = Depends(require_auth)
+) -> Dict[str, str]:
+    """Reset configuration to defaults.
+
+    Args:
+        reset_options: Options for reset (preserve_security, etc.)
+        auth: Authentication token (required)
+
+    Returns:
+        Success message
+    """
+    try:
+        config_service = get_config_service()
+
+        # Create backup before resetting
+        config_service.create_backup("pre_reset")
+
+        # Load default config
+        default_config = AppConfig()
+
+        # If preserve_security is True, keep authentication settings
+        if reset_options.get("preserve_security", True):
+            current_config = config_service.load_config()
+            # Preserve security-related fields from other
+            if "password_salt" in current_config.other:
+                default_config.other["password_salt"] = (
+                    current_config.other["password_salt"]
+                )
+            if "password_hash" in current_config.other:
+                default_config.other["password_hash"] = (
+                    current_config.other["password_hash"]
+                )
+
+        # Save default config
+        config_service.save_config(default_config)
+
+        return {
+            "message": "Configuration reset to defaults successfully"
+        }
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to reset config: {e}"
+        ) from e
+
+
+@router.post("/tmdb/validate", response_model=Dict[str, Any])
+async def validate_tmdb_key(
+    api_key_data: Dict[str, str], auth: dict = Depends(require_auth)
+) -> Dict[str, Any]:
+    """Validate TMDB API key by making a test request.
+
+    Args:
+        api_key_data: Dictionary with 'api_key' field
+        auth: Authentication token (required)
+
+    Returns:
+        Validation result with success status and message
+    """
+    import aiohttp
+    
+    api_key = api_key_data.get("api_key", "").strip()
+    
+    if not api_key:
+        return {
+            "valid": False,
+            "message": "API key is required"
+        }
+    
+    try:
+        # Test the API key with a simple configuration request
+        url = f"https://api.themoviedb.org/3/configuration?api_key={api_key}"
+        
+        timeout = aiohttp.ClientTimeout(total=10)
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, timeout=timeout) as response:
+                if response.status == 200:
+                    return {
+                        "valid": True,
+                        "message": "TMDB API key is valid"
+                    }
+                elif response.status == 401:
+                    return {
+                        "valid": False,
+                        "message": "Invalid API key"
+                    }
+                else:
+                    return {
+                        "valid": False,
+                        "message": f"TMDB API error: {response.status}"
+                    }
+    except aiohttp.ClientError as e:
+        return {
+            "valid": False,
+            "message": f"Connection error: {str(e)}"
+        }
+    except Exception as e:
+        return {
+            "valid": False,
+            "message": f"Validation error: {str(e)}"
+        }

src/server/api/download.py

@@ -4,13 +4,13 @@ This module provides REST API endpoints for managing the anime download queue,
 including adding episodes, removing items, controlling queue processing, and
 retrieving queue status and statistics.
 """
-from fastapi import APIRouter, Depends, HTTPException, Path, status
+from fastapi import APIRouter, Depends, Path, status
+from fastapi.responses import JSONResponse
 
+from src.server.exceptions import BadRequestError, NotFoundError, ServerError
 from src.server.models.download import (
     DownloadRequest,
-    DownloadResponse,
     QueueOperationRequest,
-    QueueReorderRequest,
     QueueStatusResponse,
 )
 from src.server.services.download_service import DownloadService, DownloadServiceError
@@ -21,8 +21,8 @@ router = APIRouter(prefix="/api/queue", tags=["download"])
 
 @router.get("/status", response_model=QueueStatusResponse)
 async def get_queue_status(
-    download_service: DownloadService = Depends(get_download_service),
     _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
 ):
     """Get current download queue status and statistics.
 
@@ -44,24 +44,25 @@ async def get_queue_status(
         queue_status = await download_service.get_queue_status()
         queue_stats = await download_service.get_queue_stats()
 
-        return QueueStatusResponse(status=queue_status, statistics=queue_stats)
+        # Build response matching QueueStatusResponse model
+        response = QueueStatusResponse(
+            status=queue_status,
+            statistics=queue_stats,
+        )
+        
+        return response
 
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to retrieve queue status: {str(e)}",
+        raise ServerError(
+            message=f"Failed to retrieve queue status: {str(e)}"
         )
 
 
-@router.post(
-    "/add",
-    response_model=DownloadResponse,
-    status_code=status.HTTP_201_CREATED,
-)
+@router.post("/add", status_code=status.HTTP_201_CREATED)
 async def add_to_queue(
     request: DownloadRequest,
-    download_service: DownloadService = Depends(get_download_service),
     _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
 ):
     """Add episodes to the download queue.
 
@@ -73,7 +74,12 @@ async def add_to_queue(
     Requires authentication.
 
     Args:
-        request: Download request with serie info, episodes, and priority
+        request: Download request containing:
+            - serie_id: Series key (primary identifier, 'attack-on-titan')
+            - serie_folder: Filesystem folder name for storing downloads
+            - serie_name: Display name for the series
+            - episodes: List of episodes to download
+            - priority: Queue priority level
 
     Returns:
         DownloadResponse: Status and list of created download item IDs
@@ -85,324 +91,49 @@ async def add_to_queue(
     try:
         # Validate request
         if not request.episodes:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="At least one episode must be specified",
+            raise BadRequestError(
+                message="At least one episode must be specified"
             )
 
         # Add to queue
         added_ids = await download_service.add_to_queue(
             serie_id=request.serie_id,
+            serie_folder=request.serie_folder,
             serie_name=request.serie_name,
             episodes=request.episodes,
             priority=request.priority,
         )
 
-        return DownloadResponse(
-            status="success",
-            message=f"Added {len(added_ids)} episode(s) to download queue",
-            added_items=added_ids,
-            failed_items=[],
+        # Keep a backwards-compatible response shape and return it as a
+        # raw JSONResponse so FastAPI won't coerce it based on any
+        # response_model defined elsewhere.
+        payload = {
+            "status": "success",
+            "message": f"Added {len(added_ids)} episode(s) to download queue",
+            "added_items": added_ids,
+            "item_ids": added_ids,
+            "failed_items": [],
+        }
+
+        return JSONResponse(
+            content=payload,
+            status_code=status.HTTP_201_CREATED,
         )
 
     except DownloadServiceError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        )
-    except HTTPException:
+        raise BadRequestError(message=str(e))
+    except (BadRequestError, NotFoundError, ServerError):
         raise
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to add episodes to queue: {str(e)}",
-        )
-
-
-@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_from_queue(
-    item_id: str = Path(..., description="Download item ID to remove"),
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Remove a specific item from the download queue.
-
-    Removes a download item from the queue. If the item is currently
-    downloading, it will be cancelled and marked as cancelled. If it's
-    pending, it will simply be removed from the queue.
-
-    Requires authentication.
-
-    Args:
-        item_id: Unique identifier of the download item to remove
-
-    Raises:
-        HTTPException: 401 if not authenticated, 404 if item not found,
-                      500 on service error
-    """
-    try:
-        removed_ids = await download_service.remove_from_queue([item_id])
-
-        if not removed_ids:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Download item {item_id} not found in queue",
-            )
-
-    except DownloadServiceError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to remove item from queue: {str(e)}",
-        )
-
-
-@router.delete("/", status_code=status.HTTP_204_NO_CONTENT)
-async def remove_multiple_from_queue(
-    request: QueueOperationRequest,
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Remove multiple items from the download queue.
-
-    Batch removal of multiple download items. Each item is processed
-    individually, and the operation continues even if some items are not
-    found.
-
-    Requires authentication.
-
-    Args:
-        request: List of download item IDs to remove
-
-    Raises:
-        HTTPException: 401 if not authenticated, 400 for invalid request,
-                      500 on service error
-    """
-    try:
-        if not request.item_ids:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="At least one item ID must be specified",
-            )
-
-        await download_service.remove_from_queue(request.item_ids)
-
-        # Note: We don't raise 404 if some items weren't found, as this is
-        # a batch operation and partial success is acceptable
-
-    except DownloadServiceError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to remove items from queue: {str(e)}",
-        )
-
-
-@router.post("/start", status_code=status.HTTP_200_OK)
-async def start_queue(
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Start the download queue processor.
-
-    Starts processing the download queue. Downloads will be processed according
-    to priority and concurrency limits. If the queue is already running, this
-    operation is idempotent.
-
-    Requires authentication.
-
-    Returns:
-        dict: Status message indicating queue has been started
-
-    Raises:
-        HTTPException: 401 if not authenticated, 500 on service error
-    """
-    try:
-        await download_service.start()
-
-        return {
-            "status": "success",
-            "message": "Download queue processing started",
-        }
-
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to start download queue: {str(e)}",
-        )
-
-
-@router.post("/stop", status_code=status.HTTP_200_OK)
-async def stop_queue(
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Stop the download queue processor.
-
-    Stops processing the download queue. Active downloads will be allowed to
-    complete (with a timeout), then the queue processor will shut down.
-    Queue state is persisted before shutdown.
-
-    Requires authentication.
-
-    Returns:
-        dict: Status message indicating queue has been stopped
-
-    Raises:
-        HTTPException: 401 if not authenticated, 500 on service error
-    """
-    try:
-        await download_service.stop()
-
-        return {
-            "status": "success",
-            "message": "Download queue processing stopped",
-        }
-
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to stop download queue: {str(e)}",
-        )
-
-
-@router.post("/pause", status_code=status.HTTP_200_OK)
-async def pause_queue(
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Pause the download queue processor.
-
-    Pauses download processing. Active downloads will continue, but no new
-    downloads will be started until the queue is resumed.
-
-    Requires authentication.
-
-    Returns:
-        dict: Status message indicating queue has been paused
-
-    Raises:
-        HTTPException: 401 if not authenticated, 500 on service error
-    """
-    try:
-        await download_service.pause_queue()
-
-        return {
-            "status": "success",
-            "message": "Download queue paused",
-        }
-
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to pause download queue: {str(e)}",
-        )
-
-
-@router.post("/resume", status_code=status.HTTP_200_OK)
-async def resume_queue(
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Resume the download queue processor.
-
-    Resumes download processing after being paused. The queue will continue
-    processing pending items according to priority.
-
-    Requires authentication.
-
-    Returns:
-        dict: Status message indicating queue has been resumed
-
-    Raises:
-        HTTPException: 401 if not authenticated, 500 on service error
-    """
-    try:
-        await download_service.resume_queue()
-
-        return {
-            "status": "success",
-            "message": "Download queue resumed",
-        }
-
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to resume download queue: {str(e)}",
-        )
-
-
-@router.post("/reorder", status_code=status.HTTP_200_OK)
-async def reorder_queue(
-    request: QueueReorderRequest,
-    download_service: DownloadService = Depends(get_download_service),
-    _: dict = Depends(require_auth),
-):
-    """Reorder an item in the pending queue.
-
-    Changes the position of a pending download item in the queue. This only
-    affects items that haven't started downloading yet. The position is
-    0-based.
-
-    Requires authentication.
-
-    Args:
-        request: Item ID and new position in queue
-
-    Returns:
-        dict: Status message indicating item has been reordered
-
-    Raises:
-        HTTPException: 401 if not authenticated, 404 if item not found,
-                      400 for invalid request, 500 on service error
-    """
-    try:
-        success = await download_service.reorder_queue(
-            item_id=request.item_id,
-            new_position=request.new_position,
-        )
-
-        if not success:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail=f"Item {request.item_id} not found in pending queue",
-            )
-
-        return {
-            "status": "success",
-            "message": "Queue item reordered successfully",
-        }
-
-    except DownloadServiceError as e:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e),
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to reorder queue item: {str(e)}",
+        raise ServerError(
+            message=f"Failed to add episodes to queue: {str(e)}"
         )
 
 
 @router.delete("/completed", status_code=status.HTTP_200_OK)
 async def clear_completed(
-    download_service: DownloadService = Depends(get_download_service),
     _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
 ):
     """Clear completed downloads from history.
 
@@ -427,17 +158,316 @@ async def clear_completed(
         }
 
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to clear completed items: {str(e)}",
+        raise ServerError(
+            message=f"Failed to clear completed items: {str(e)}"
+        )
+
+
+@router.delete("/failed", status_code=status.HTTP_200_OK)
+async def clear_failed(
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Clear failed downloads from history.
+
+    Removes all failed download items from the queue history. This helps
+    keep the queue display clean and manageable.
+
+    Requires authentication.
+
+    Returns:
+        dict: Status message with count of cleared items
+
+    Raises:
+        HTTPException: 401 if not authenticated, 500 on service error
+    """
+    try:
+        cleared_count = await download_service.clear_failed()
+
+        return {
+            "status": "success",
+            "message": f"Cleared {cleared_count} failed item(s)",
+            "count": cleared_count,
+        }
+
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to clear failed items: {str(e)}"
+        )
+
+
+@router.delete("/pending", status_code=status.HTTP_200_OK)
+async def clear_pending(
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Clear all pending downloads from the queue.
+
+    Removes all pending download items from the queue. This is useful for
+    clearing the entire queue at once instead of removing items one by one.
+
+    Requires authentication.
+
+    Returns:
+        dict: Status message with count of cleared items
+
+    Raises:
+        HTTPException: 401 if not authenticated, 500 on service error
+    """
+    try:
+        cleared_count = await download_service.clear_pending()
+
+        return {
+            "status": "success",
+            "message": f"Removed {cleared_count} pending item(s)",
+            "count": cleared_count,
+        }
+
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to clear pending items: {str(e)}"
+        )
+
+
+@router.delete("/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_from_queue(
+    item_id: str = Path(..., description="Download item ID to remove"),
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Remove a specific item from the download queue.
+
+    Removes a download item from the queue. If the item is currently
+    downloading, it will be cancelled and marked as cancelled. If it's
+    pending, it will simply be removed from the queue.
+
+    Requires authentication.
+
+    Args:
+        item_id: Unique identifier of the download item to remove
+
+    Raises:
+        HTTPException: 401 if not authenticated, 404 if item not found,
+                      500 on service error
+    """
+    try:
+        removed_ids = await download_service.remove_from_queue([item_id])
+
+        if not removed_ids:
+            raise NotFoundError(
+                message=f"Download item {item_id} not found in queue",
+                resource_type="download_item",
+                resource_id=item_id
+            )
+
+    except DownloadServiceError as e:
+        raise BadRequestError(message=str(e))
+    except (BadRequestError, NotFoundError, ServerError):
+        raise
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to remove item from queue: {str(e)}"
+        )
+
+
+@router.delete("/", status_code=status.HTTP_204_NO_CONTENT)
+async def remove_multiple_from_queue(
+    request: QueueOperationRequest,
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Remove multiple items from the download queue.
+
+    Removes multiple download items from the queue based on provided IDs.
+    Items that are currently downloading will be cancelled.
+
+    Requires authentication.
+
+    Args:
+        request: Request containing list of item IDs to remove
+
+    Raises:
+        HTTPException: 401 if not authenticated, 404 if no items found,
+                      500 on service error
+    """
+    try:
+        removed_ids = await download_service.remove_from_queue(
+            request.item_ids
+        )
+
+        if not removed_ids:
+            raise NotFoundError(
+                message="No matching items found in queue",
+                resource_type="download_items"
+            )
+
+    except DownloadServiceError as e:
+        raise BadRequestError(message=str(e))
+    except (BadRequestError, NotFoundError, ServerError):
+        raise
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to remove items from queue: {str(e)}"
+        )
+
+
+@router.post("/start", status_code=status.HTTP_200_OK)
+async def start_queue(
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Start automatic queue processing.
+
+    Starts processing all pending downloads sequentially, one at a time.
+    The queue will continue processing until all items are complete or
+    the queue is manually stopped. Processing continues even if the browser
+    is closed.
+
+    Only one download can be active at a time. If a download is already
+    active or queue processing is running, an error is returned.
+
+    Requires authentication.
+
+    Returns:
+        dict: Status message confirming queue processing started
+
+    Raises:
+        HTTPException: 401 if not authenticated, 400 if queue is empty or
+                      processing already active, 500 on service error
+    """
+    try:
+        result = await download_service.start_queue_processing()
+        
+        if result is None:
+            raise BadRequestError(
+                message="No pending downloads in queue"
+            )
+
+        return {
+            "status": "success",
+            "message": "Queue processing started",
+        }
+    
+    except DownloadServiceError as e:
+        raise BadRequestError(message=str(e))
+    except (BadRequestError, NotFoundError, ServerError):
+        raise
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to start queue processing: {str(e)}"
+        )
+
+
+@router.post("/stop", status_code=status.HTTP_200_OK)
+async def stop_queue(
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Stop processing new downloads from queue.
+
+    Prevents new downloads from starting. The current active download will
+    continue to completion, but no new downloads will be started from the
+    pending queue.
+
+    Requires authentication.
+
+    Returns:
+        dict: Status message indicating queue processing has been stopped
+
+    Raises:
+        HTTPException: 401 if not authenticated, 500 on service error
+    """
+    try:
+        await download_service.stop_downloads()
+
+        return {
+            "status": "success",
+            "message": (
+                "Queue processing stopped (current download will continue)"
+            ),
+        }
+
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to stop queue processing: {str(e)}"
+        )
+
+
+@router.post("/pause", status_code=status.HTTP_200_OK)
+async def pause_queue(
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Pause queue processing (alias for stop).
+
+    Prevents new downloads from starting. The current active download will
+    continue to completion, but no new downloads will be started from the
+    pending queue.
+
+    Requires authentication.
+
+    Returns:
+        dict: Status message indicating queue processing has been paused
+
+    Raises:
+        HTTPException: 401 if not authenticated, 500 on service error
+    """
+    try:
+        await download_service.stop_downloads()
+
+        return {
+            "status": "success",
+            "message": "Queue processing paused",
+        }
+
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to pause queue processing: {str(e)}"
+        )
+
+
+@router.post("/reorder", status_code=status.HTTP_200_OK)
+async def reorder_queue(
+    request: QueueOperationRequest,
+    _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
+):
+    """Reorder items in the pending queue.
+
+    Reorders the pending queue based on the provided list of item IDs.
+    Items will be placed in the order specified by the item_ids list.
+    Items not included in the list will remain at the end of the queue.
+
+    Requires authentication.
+
+    Args:
+        request: List of download item IDs in desired order
+
+    Returns:
+        dict: Status message
+
+    Raises:
+        HTTPException: 401 if not authenticated, 404 if no items match,
+                      500 on service error
+    """
+    try:
+        await download_service.reorder_queue(request.item_ids)
+        return {
+            "status": "success",
+            "message": f"Queue reordered with {len(request.item_ids)} items",
+        }
+
+    except Exception as e:
+        raise ServerError(
+            message=f"Failed to reorder queue: {str(e)}"
         )
 
 
 @router.post("/retry", status_code=status.HTTP_200_OK)
 async def retry_failed(
     request: QueueOperationRequest,
-    download_service: DownloadService = Depends(get_download_service),
     _: dict = Depends(require_auth),
+    download_service: DownloadService = Depends(get_download_service),
 ):
     """Retry failed downloads.
 
@@ -464,11 +494,11 @@ async def retry_failed(
         return {
             "status": "success",
             "message": f"Retrying {len(retried_ids)} failed item(s)",
+            "retried_count": len(retried_ids),
             "retried_ids": retried_ids,
         }
 
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to retry downloads: {str(e)}",
+        raise ServerError(
+            message=f"Failed to retry downloads: {str(e)}"
         )

src/server/api/health.py

@@ -0,0 +1,348 @@
+"""Health check endpoints for system monitoring and status verification."""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+import psutil
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.server.utils.dependencies import get_database_session
+
+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 = 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):
+    """Database health status."""
+
+    status: str
+    connection_time_ms: float
+    message: Optional[str] = None
+
+
+class SystemMetrics(BaseModel):
+    """System resource metrics."""
+
+    cpu_percent: float
+    memory_percent: float
+    memory_available_mb: float
+    disk_percent: float
+    disk_free_mb: float
+    uptime_seconds: float
+
+
+class DependencyHealth(BaseModel):
+    """Health status of external dependencies."""
+
+    database: DatabaseHealth
+    filesystem: Dict[str, Any]
+    system: SystemMetrics
+
+
+class DetailedHealthStatus(BaseModel):
+    """Comprehensive health check response."""
+
+    status: str
+    timestamp: str
+    version: str = APP_VERSION
+    dependencies: DependencyHealth
+    startup_time: datetime
+
+
+# Global startup time
+startup_time = datetime.now()
+
+
+async def check_database_health(db: AsyncSession) -> DatabaseHealth:
+    """Check database connection and performance.
+
+    Args:
+        db: Database session dependency.
+
+    Returns:
+        DatabaseHealth: Database status and connection time.
+    """
+    try:
+        import time
+
+        start_time = time.time()
+        await db.execute(text("SELECT 1"))
+        connection_time = (time.time() - start_time) * 1000  # Convert to milliseconds
+
+        return DatabaseHealth(
+            status="healthy",
+            connection_time_ms=connection_time,
+            message="Database connection successful",
+        )
+    except Exception as e:
+        logger.error("Database health check failed: %s", e)
+        return DatabaseHealth(
+            status="unhealthy",
+            connection_time_ms=0,
+            message=f"Database connection failed: {str(e)}",
+        )
+
+
+async def check_filesystem_health() -> Dict[str, Any]:
+    """Check filesystem availability and permissions.
+
+    Returns:
+        dict: Filesystem status and available space.
+    """
+    try:
+        import os
+
+        data_dir = "data"
+        logs_dir = "logs"
+
+        data_accessible = os.path.exists(data_dir) and os.access(data_dir, os.W_OK)
+        logs_accessible = os.path.exists(logs_dir) and os.access(logs_dir, os.W_OK)
+
+        return {
+            "status": "healthy" if (data_accessible and logs_accessible) else "degraded",
+            "data_dir_writable": data_accessible,
+            "logs_dir_writable": logs_accessible,
+            "message": "Filesystem check completed",
+        }
+    except Exception as e:
+        logger.error("Filesystem health check failed: %s", e)
+        return {
+            "status": "unhealthy",
+            "message": f"Filesystem check failed: {str(e)}",
+        }
+
+
+def get_system_metrics() -> SystemMetrics:
+    """Get system resource metrics.
+
+    Returns:
+        SystemMetrics: CPU, memory, disk, and uptime information.
+    """
+    try:
+        import os
+        import time
+
+        # CPU usage
+        cpu_percent = psutil.cpu_percent(interval=1)
+
+        # Memory usage
+        memory_info = psutil.virtual_memory()
+        memory_percent = memory_info.percent
+        memory_available_mb = memory_info.available / (1024 * 1024)
+
+        # Disk usage
+        disk_info = psutil.disk_usage("/")
+        disk_percent = disk_info.percent
+        disk_free_mb = disk_info.free / (1024 * 1024)
+
+        # Uptime
+        boot_time = psutil.boot_time()
+        uptime_seconds = time.time() - boot_time
+
+        return SystemMetrics(
+            cpu_percent=cpu_percent,
+            memory_percent=memory_percent,
+            memory_available_mb=memory_available_mb,
+            disk_percent=disk_percent,
+            disk_free_mb=disk_free_mb,
+            uptime_seconds=uptime_seconds,
+        )
+    except Exception as 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(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=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),
+) -> DetailedHealthStatus:
+    """Comprehensive health check endpoint.
+
+    Checks database, filesystem, and system metrics.
+
+    Args:
+        db: Database session dependency.
+
+    Returns:
+        DetailedHealthStatus: Comprehensive health information.
+    """
+    logger.debug("Detailed health check requested")
+
+    try:
+        # Check dependencies
+        database_health = await check_database_health(db)
+        filesystem_health = await check_filesystem_health()
+        system_metrics = get_system_metrics()
+
+        # Determine overall status
+        overall_status = "healthy"
+        if database_health.status != "healthy":
+            overall_status = "degraded"
+        if filesystem_health.get("status") != "healthy":
+            overall_status = "degraded"
+
+        dependencies = DependencyHealth(
+            database=database_health,
+            filesystem=filesystem_health,
+            system=system_metrics,
+        )
+
+        return DetailedHealthStatus(
+            status=overall_status,
+            timestamp=datetime.now().isoformat(),
+            dependencies=dependencies,
+            startup_time=startup_time,
+        )
+    except Exception as e:
+        logger.error("Detailed health check failed: %s", e)
+        raise HTTPException(status_code=500, detail="Health check failed")
+
+
+@router.get("/metrics", response_model=SystemMetrics)
+async def get_metrics() -> SystemMetrics:
+    """Get system resource metrics.
+
+    Returns:
+        SystemMetrics: Current CPU, memory, disk, and uptime metrics.
+    """
+    logger.debug("System metrics requested")
+    return get_system_metrics()
+
+
+@router.get("/metrics/prometheus")
+async def get_prometheus_metrics() -> str:
+    """Get metrics in Prometheus format.
+
+    Returns:
+        str: Prometheus formatted metrics.
+    """
+    from src.server.utils.metrics import get_metrics_collector
+
+    logger.debug("Prometheus metrics requested")
+    collector = get_metrics_collector()
+    return collector.export_prometheus_format()
+
+
+@router.get("/metrics/json")
+async def get_metrics_json() -> Dict[str, Any]:
+    """Get metrics as JSON.
+
+    Returns:
+        dict: Metrics in JSON format.
+    """
+    from src.server.utils.metrics import get_metrics_collector
+
+    logger.debug("JSON metrics requested")
+    collector = get_metrics_collector()
+    return collector.export_json()

src/server/api/logging.py

@@ -0,0 +1,230 @@
+"""Logging API endpoints for AniWorld.
+
+Provides endpoints for reading log configuration, listing log files,
+tailing/downloading individual log files, testing logging, and cleanup.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.responses import FileResponse
+
+from src.server.services.config_service import get_config_service
+from src.server.utils.dependencies import require_auth
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/logging", tags=["logging"])
+
+_LOG_DIR = Path("logs")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _log_dir() -> Path:
+    """Return the log directory, creating it if necessary."""
+    _LOG_DIR.mkdir(exist_ok=True)
+    return _LOG_DIR
+
+
+def _list_log_files() -> List[Dict[str, Any]]:
+    """Return metadata for all .log files in the log directory."""
+    result: List[Dict[str, Any]] = []
+    log_dir = _log_dir()
+    for entry in sorted(log_dir.iterdir()):
+        if entry.is_file() and entry.suffix in {".log", ".txt"}:
+            stat = entry.stat()
+            result.append(
+                {
+                    "name": entry.name,
+                    "size_mb": round(stat.st_size / (1024 * 1024), 2),
+                    "modified": stat.st_mtime,
+                }
+            )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@router.get("/config")
+def get_logging_config(
+    auth: Optional[dict] = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Return current logging configuration as used by the frontend.
+
+    Maps the internal ``LoggingConfig`` model fields to the shape expected
+    by ``logging-config.js``.
+    """
+    try:
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+        lc = app_config.logging
+
+        return {
+            "success": True,
+            "config": {
+                # Primary fields (match the model)
+                "log_level": lc.level,
+                "log_file": lc.file,
+                "max_bytes": lc.max_bytes,
+                "backup_count": lc.backup_count,
+                # UI-only flags – defaults; not yet persisted in the model
+                "enable_console_logging": True,
+                "enable_console_progress": False,
+                "enable_fail2ban_logging": False,
+            },
+        }
+    except Exception as exc:
+        logger.exception("Failed to read logging config")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to read logging config: {exc}",
+        ) from exc
+
+
+@router.get("/files")
+def list_files(
+    auth: Optional[dict] = Depends(require_auth),
+) -> Dict[str, Any]:
+    """List all available log files with metadata."""
+    try:
+        return {"success": True, "files": _list_log_files()}
+    except Exception as exc:
+        logger.exception("Failed to list log files")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to list log files: {exc}",
+        ) from exc
+
+
+@router.get("/files/{filename}/tail")
+def tail_file(
+    filename: str,
+    lines: int = 100,
+    auth: Optional[dict] = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Return the last *lines* lines of a log file.
+
+    Args:
+        filename: Name of the log file (no path traversal).
+        lines: Number of lines to return (default 100).
+
+    Returns:
+        Dict with ``success``, ``lines``, ``showing_lines``, ``total_lines``.
+    """
+    # Prevent path traversal
+    safe_name = Path(filename).name
+    file_path = _log_dir() / safe_name
+    if not file_path.exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Log file not found: {safe_name}",
+        )
+
+    try:
+        all_lines = file_path.read_text(encoding="utf-8", errors="replace").splitlines()
+        tail = all_lines[-lines:] if len(all_lines) > lines else all_lines
+        return {
+            "success": True,
+            "lines": tail,
+            "showing_lines": len(tail),
+            "total_lines": len(all_lines),
+        }
+    except Exception as exc:
+        logger.exception("Failed to tail log file %s", safe_name)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to read log file: {exc}",
+        ) from exc
+
+
+@router.get("/files/{filename}/download")
+def download_file(
+    filename: str,
+    auth: Optional[dict] = Depends(require_auth),
+) -> FileResponse:
+    """Download a log file as an attachment."""
+    safe_name = Path(filename).name
+    file_path = _log_dir() / safe_name
+    if not file_path.exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Log file not found: {safe_name}",
+        )
+    return FileResponse(
+        path=str(file_path),
+        filename=safe_name,
+        media_type="text/plain",
+    )
+
+
+@router.post("/test")
+def test_logging(
+    auth: dict = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Write test log messages at all levels."""
+    logging.getLogger("aniworld.test").debug("Test DEBUG message")
+    logging.getLogger("aniworld.test").info("Test INFO message")
+    logging.getLogger("aniworld.test").warning("Test WARNING message")
+    logging.getLogger("aniworld.test").error("Test ERROR message")
+    return {"success": True, "message": "Test messages written to log"}
+
+
+@router.post("/cleanup")
+def cleanup_logs(
+    payload: Dict[str, Any],
+    auth: dict = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Delete log files older than *days* days.
+
+    Args:
+        payload: JSON body with ``days`` (int) field.
+
+    Returns:
+        Dict with ``success`` and ``message`` describing what was deleted.
+    """
+    import time
+
+    days = payload.get("days", 30)
+    try:
+        days = int(days)
+        if days < 1:
+            raise ValueError("days must be >= 1")
+    except (TypeError, ValueError) as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid days value: {exc}",
+        ) from exc
+
+    cutoff = time.time() - days * 86400
+    removed: List[str] = []
+    errors: List[str] = []
+
+    for entry in _log_dir().iterdir():
+        if entry.is_file() and entry.suffix in {".log", ".txt"}:
+            if entry.stat().st_mtime < cutoff:
+                try:
+                    entry.unlink()
+                    removed.append(entry.name)
+                except OSError as exc:
+                    errors.append(f"{entry.name}: {exc}")
+
+    message = f"Removed {len(removed)} file(s) older than {days} days."
+    if errors:
+        message += f" Errors: {'; '.join(errors)}"
+
+    logger.info(
+        "Log cleanup by %s: removed=%s days=%s",
+        auth.get("username", "unknown"),
+        removed,
+        days,
+    )
+    return {"success": True, "message": message, "removed": removed}

src/server/api/nfo.py

@@ -0,0 +1,70 @@
+"""NFO Management API endpoints.
+
+Note: NFO service has been removed. All NFO endpoints return 503.
+"""
+from fastapi import APIRouter, HTTPException, status
+
+router = APIRouter(prefix="/api/nfo", tags=["nfo"])
+
+
+@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.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."
+    )
+
+
+@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}/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.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.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("/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

@@ -0,0 +1,155 @@
+"""Scheduler API endpoints for Aniworld.
+
+This module provides endpoints for managing scheduled tasks such as
+automatic anime library rescans.
+"""
+import logging
+from typing import Any, Dict, Optional
+
+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.scheduler_service import get_scheduler_service
+from src.server.utils.dependencies import require_auth
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/scheduler", tags=["scheduler"])
+
+
+def _build_response(config: SchedulerConfig) -> Dict[str, Any]:
+    """Build a standardised GET/POST response combining config + runtime status."""
+    scheduler_service = get_scheduler_service()
+    runtime = scheduler_service.get_status()
+
+    return {
+        "success": True,
+        "config": {
+            "enabled": config.enabled,
+            "interval_minutes": config.interval_minutes,
+            "schedule_time": config.schedule_time,
+            "schedule_days": config.schedule_days,
+            "auto_download_after_rescan": config.auto_download_after_rescan,
+        },
+        "status": {
+            "is_running": runtime.get("is_running", False),
+            "next_run": runtime.get("next_run"),
+            "last_run": runtime.get("last_run"),
+            "scan_in_progress": runtime.get("scan_in_progress", False),
+        },
+    }
+
+
+@router.get("/config")
+def get_scheduler_config(
+    auth: Optional[dict] = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Get current scheduler configuration along with runtime status.
+
+    Returns:
+        Combined config and status response.
+
+    Raises:
+        HTTPException: 500 if configuration cannot be loaded.
+    """
+    try:
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+        return _build_response(app_config.scheduler)
+    except ConfigServiceError as exc:
+        logger.error("Failed to load scheduler config: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to load scheduler configuration: {exc}",
+        ) from exc
+
+
+@router.post("/config")
+def update_scheduler_config(
+    scheduler_config: SchedulerConfig,
+    auth: dict = Depends(require_auth),
+) -> Dict[str, Any]:
+    """Update scheduler configuration and apply changes immediately.
+
+    Accepts the full SchedulerConfig body; any fields not supplied default
+    to their model defaults (backward compatible).
+
+    Returns:
+        Combined config and status response reflecting the saved config.
+
+    Raises:
+        HTTPException: 422 on validation errors (handled by FastAPI/Pydantic),
+            500 on save or scheduler failure.
+    """
+    try:
+        config_service = get_config_service()
+        app_config = config_service.load_config()
+        app_config.scheduler = scheduler_config
+        config_service.save_config(app_config)
+
+        logger.info(
+            "Scheduler config updated by %s: time=%s days=%s auto_dl=%s",
+            auth.get("username", "unknown"),
+            scheduler_config.schedule_time,
+            scheduler_config.schedule_days,
+            scheduler_config.auto_download_after_rescan,
+        )
+
+        # Apply changes to the running scheduler without restart
+        try:
+            sched_svc = get_scheduler_service()
+            sched_svc.reload_config(scheduler_config)
+        except Exception as sched_exc:  # pylint: disable=broad-exception-caught
+            logger.error("Scheduler reload after config update failed: %s", sched_exc)
+            # Config was saved — don't fail the request, just warn
+
+        return _build_response(scheduler_config)
+
+    except ConfigServiceError as exc:
+        logger.error("Failed to update scheduler config: %s", exc)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update scheduler configuration: {exc}",
+        ) from exc
+
+
+@router.post("/trigger-rescan", response_model=Dict[str, str])
+async def trigger_rescan(auth: dict = Depends(require_auth)) -> Dict[str, str]:
+    """Manually trigger a library rescan (and auto-download if configured).
+
+    Args:
+        auth: Authentication token (required)
+
+    Returns:
+        Dict with success message
+
+    Raises:
+        HTTPException: If rescan cannot be triggered
+    """
+    try:
+        from src.server.utils.dependencies import get_series_app  # noqa: PLC0415
+
+        series_app = get_series_app()
+        if not series_app:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="SeriesApp not initialized",
+            )
+
+        logger.info(
+            "Manual rescan triggered by %s", auth.get("username", "unknown")
+        )
+
+        from src.server.api.anime import trigger_rescan as do_rescan  # noqa: PLC0415
+
+        return await do_rescan()
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.exception("Failed to trigger manual rescan")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to trigger rescan: {exc}",
+        ) from exc

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/api/websocket.py

@@ -2,11 +2,20 @@
 
 This module provides WebSocket endpoints for clients to connect and receive
 real-time updates about downloads, queue status, and system events.
+
+Series Identifier Convention:
+    - `key`: Primary identifier for series (provider-assigned, URL-safe)
+             e.g., "attack-on-titan"
+    - `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
+    
+All series-related WebSocket events include `key` as the primary identifier
+in their data payload. The `folder` field is optional for display purposes.
 """
 from __future__ import annotations
 
+import time
 import uuid
-from typing import Optional
+from typing import Dict, Optional, Set
 
 import structlog
 from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect, status
@@ -21,18 +30,84 @@ from src.server.services.websocket_service import (
     WebSocketService,
     get_websocket_service,
 )
-from src.server.utils.dependencies import get_current_user_optional
 
 logger = structlog.get_logger(__name__)
 
 router = APIRouter(prefix="/ws", tags=["websocket"])
 
+# Valid room names - explicit allow-list for security
+VALID_ROOMS: Set[str] = {
+    "downloads",       # Download progress updates
+    "queue",           # Queue status changes
+    "scan",            # Scan progress updates
+    "system",          # System notifications
+    "errors",          # Error notifications
+}
+
+# Rate limiting configuration for WebSocket messages
+WS_RATE_LIMIT_MESSAGES_PER_MINUTE = 60
+WS_RATE_LIMIT_WINDOW_SECONDS = 60
+
+# In-memory rate limiting for WebSocket connections
+# WARNING: This resets on process restart. For production, consider Redis.
+_ws_rate_limits: Dict[str, Dict[str, float]] = {}
+
+
+def _check_ws_rate_limit(connection_id: str) -> bool:
+    """Check if a WebSocket connection has exceeded its rate limit.
+    
+    Args:
+        connection_id: Unique identifier for the WebSocket connection
+        
+    Returns:
+        bool: True if within rate limit, False if exceeded
+    """
+    now = time.time()
+    
+    if connection_id not in _ws_rate_limits:
+        _ws_rate_limits[connection_id] = {
+            "count": 0,
+            "window_start": now,
+        }
+    
+    record = _ws_rate_limits[connection_id]
+    
+    # Reset window if expired
+    if now - record["window_start"] > WS_RATE_LIMIT_WINDOW_SECONDS:
+        record["window_start"] = now
+        record["count"] = 0
+    
+    record["count"] += 1
+    
+    return record["count"] <= WS_RATE_LIMIT_MESSAGES_PER_MINUTE
+
+
+def _cleanup_ws_rate_limits(connection_id: str) -> None:
+    """Remove rate limit record for a disconnected connection.
+    
+    Args:
+        connection_id: Unique identifier for the WebSocket connection
+    """
+    _ws_rate_limits.pop(connection_id, None)
+
+
+def _validate_room_name(room: str) -> bool:
+    """Validate that a room name is in the allowed set.
+    
+    Args:
+        room: Room name to validate
+        
+    Returns:
+        bool: True if room is valid, False otherwise
+    """
+    return room in VALID_ROOMS
+
 
 @router.websocket("/connect")
 async def websocket_endpoint(
     websocket: WebSocket,
+    token: Optional[str] = None,
     ws_service: WebSocketService = Depends(get_websocket_service),
-    user_id: Optional[str] = Depends(get_current_user_optional),
 ):
     """WebSocket endpoint for client connections.
     
@@ -40,6 +115,10 @@ async def websocket_endpoint(
     The connection is maintained until the client disconnects or
     an error occurs.
     
+    Authentication:
+    - Optional token can be passed as query parameter: /ws/connect?token=<jwt>
+    - Unauthenticated connections are allowed but may have limited access
+    
     Message flow:
     1. Client connects
     2. Server sends "connected" message
@@ -55,21 +134,41 @@ async def websocket_endpoint(
     }
     ```
     
-    Server message format:
+    Server message format (series-related events include 'key' identifier):
     ```json
     {
         "type": "download_progress",
         "timestamp": "2025-10-17T10:30:00.000Z",
         "data": {
             "download_id": "abc123",
+            "key": "attack-on-titan",
+            "folder": "Attack on Titan (2013)",
             "percent": 45.2,
             "speed_mbps": 2.5,
             "eta_seconds": 180
         }
     }
     ```
+    
+    Note:
+        - `key` is the primary series identifier (provider-assigned, URL-safe)
+        - `folder` is optional display metadata
     """
     connection_id = str(uuid.uuid4())
+    user_id: Optional[str] = None
+    
+    # Optional: Validate token if provided
+    if token:
+        try:
+            from src.server.services.auth_service import auth_service
+            session = auth_service.create_session_model(token)
+            user_id = session.user_id
+        except Exception as e:
+            logger.warning(
+                "Invalid WebSocket authentication token",
+                connection_id=connection_id,
+                error=str(e),
+            )
     
     try:
         # Accept connection and register with service
@@ -99,6 +198,19 @@ async def websocket_endpoint(
                 # Receive message from client
                 data = await websocket.receive_json()
                 
+                # Check rate limit
+                if not _check_ws_rate_limit(connection_id):
+                    logger.warning(
+                        "WebSocket rate limit exceeded",
+                        connection_id=connection_id,
+                    )
+                    await ws_service.send_error(
+                        connection_id,
+                        "Rate limit exceeded. Please slow down.",
+                        "RATE_LIMIT_EXCEEDED",
+                    )
+                    continue
+                
                 # Parse client message
                 try:
                     client_msg = ClientMessage(**data)
@@ -118,9 +230,26 @@ async def websocket_endpoint(
                 # Handle room subscription requests
                 if client_msg.action in ["join", "leave"]:
                     try:
+                        room_name = client_msg.data.get("room", "")
+                        
+                        # Validate room name against allow-list
+                        if not _validate_room_name(room_name):
+                            logger.warning(
+                                "Invalid room name requested",
+                                connection_id=connection_id,
+                                room=room_name,
+                            )
+                            await ws_service.send_error(
+                                connection_id,
+                                f"Invalid room name: {room_name}. "
+                                f"Valid rooms: {', '.join(sorted(VALID_ROOMS))}",
+                                "INVALID_ROOM",
+                            )
+                            continue
+                        
                         room_req = RoomSubscriptionRequest(
                             action=client_msg.action,
-                            room=client_msg.data.get("room", ""),
+                            room=room_name,
                         )
                         
                         if room_req.action == "join":
@@ -210,7 +339,8 @@ async def websocket_endpoint(
             error=str(e),
         )
     finally:
-        # Cleanup connection
+        # Cleanup connection and rate limit record
+        _cleanup_ws_rate_limits(connection_id)
         await ws_service.disconnect(connection_id)
         logger.info("WebSocket connection closed", connection_id=connection_id)
 
@@ -232,5 +362,6 @@ async def websocket_status(
             "status": "operational",
             "active_connections": connection_count,
             "supported_message_types": [t.value for t in WebSocketMessageType],
+            "valid_rooms": sorted(VALID_ROOMS),
         },
     )

src/server/config/__init__.py

@@ -0,0 +1,69 @@
+"""
+Environment configuration loader for Aniworld application.
+
+This module provides unified configuration loading based on the environment
+(development, production, or testing). It automatically selects the appropriate
+settings configuration based on the ENVIRONMENT variable.
+"""
+
+import os
+from typing import Union
+
+from .development import DevelopmentSettings, get_development_settings
+from .production import ProductionSettings, get_production_settings
+
+# Environment options
+ENVIRONMENT = os.getenv("ENVIRONMENT", "development").lower()
+
+# Valid environment values
+VALID_ENVIRONMENTS = {"development", "production", "testing"}
+
+if ENVIRONMENT not in VALID_ENVIRONMENTS:
+    raise ValueError(
+        f"Invalid ENVIRONMENT '{ENVIRONMENT}'. "
+        f"Must be one of: {VALID_ENVIRONMENTS}"
+    )
+
+
+def get_settings() -> Union[DevelopmentSettings, ProductionSettings]:
+    """
+    Get environment-specific settings.
+
+    Returns:
+        DevelopmentSettings: If ENVIRONMENT is 'development' or 'testing'
+        ProductionSettings: If ENVIRONMENT is 'production'
+
+    Raises:
+        ValueError: If ENVIRONMENT is not valid
+
+    Example:
+        >>> settings = get_settings()
+        >>> print(settings.log_level)
+        INFO
+    """
+    if ENVIRONMENT in {"development", "testing"}:
+        return get_development_settings()
+    return get_production_settings()
+
+
+# Singleton instance - loaded on first call
+_settings_instance = None
+
+
+def _get_settings_cached() -> Union[DevelopmentSettings, ProductionSettings]:
+    """Get cached settings instance."""
+    global _settings_instance
+    if _settings_instance is None:
+        _settings_instance = get_settings()
+    return _settings_instance
+
+
+# Re-export for convenience
+__all__ = [
+    "get_settings",
+    "ENVIRONMENT",
+    "DevelopmentSettings",
+    "ProductionSettings",
+    "get_development_settings",
+    "get_production_settings",
+]

src/server/config/development.py

@@ -0,0 +1,239 @@
+"""
+Development environment configuration for Aniworld application.
+
+This module provides development-specific settings including debugging,
+hot-reloading, and relaxed security for local development.
+
+Environment Variables:
+    JWT_SECRET_KEY: Secret key for JWT token signing (default: dev-secret)
+    PASSWORD_SALT: Salt for password hashing (default: dev-salt)
+    DATABASE_URL: Development database connection string (default: SQLite)
+    LOG_LEVEL: Logging level (default: INFO)
+    CORS_ORIGINS: Comma-separated list of allowed CORS origins
+    API_RATE_LIMIT: API rate limit per minute (default: 1000)
+"""
+
+from typing import List
+
+from pydantic import Field, validator
+from pydantic_settings import BaseSettings
+
+
+class DevelopmentSettings(BaseSettings):
+    """Development environment configuration settings."""
+
+    # ============================================================================
+    # Security Settings (Relaxed for Development)
+    # ============================================================================
+
+    jwt_secret_key: str = Field(
+        default="dev-secret-key-change-in-production",
+        env="JWT_SECRET_KEY"
+    )
+    """JWT secret key (non-production value for development)."""
+
+    password_salt: str = Field(
+        default="dev-salt-change-in-production",
+        env="PASSWORD_SALT"
+    )
+    """Password salt (non-production value for development)."""
+
+    master_password_hash: str = Field(
+        default="$2b$12$wP0KBVbJKVAb8CdSSXw0NeGTKCk"
+        "bw4fSAFXIqR2/wDqPSEBn9w7lS",
+        env="MASTER_PASSWORD_HASH"
+    )
+    """Hash of the master password (dev: 'password')."""
+
+    master_password: str = Field(default="password", env="MASTER_PASSWORD")
+    """Master password for development (NEVER use in production)."""
+
+    allowed_hosts: List[str] = Field(
+        default=["localhost", "127.0.0.1", "*"], env="ALLOWED_HOSTS"
+    )
+    """Allowed hosts (permissive for development)."""
+
+    cors_origins: str = Field(default="*", env="CORS_ORIGINS")
+    """CORS origins (allow all for development)."""
+
+    # ============================================================================
+    # Database Settings
+    # ============================================================================
+
+    database_url: str = Field(
+        default="sqlite:///./data/aniworld_dev.db",
+        env="DATABASE_URL"
+    )
+    """Development database URL (SQLite by default)."""
+
+    database_pool_size: int = Field(default=5, env="DATABASE_POOL_SIZE")
+    """Database connection pool size."""
+
+    database_max_overflow: int = Field(default=10, env="DATABASE_MAX_OVERFLOW")
+    """Maximum overflow connections for database pool."""
+
+    database_pool_recycle: int = Field(
+        default=3600, env="DATABASE_POOL_RECYCLE"
+    )
+    """Recycle database connections every N seconds."""
+
+    # ============================================================================
+    # API Settings
+    # ============================================================================
+
+    api_rate_limit: int = Field(default=1000, env="API_RATE_LIMIT")
+    """API rate limit per minute (relaxed for development)."""
+
+    api_timeout: int = Field(default=60, env="API_TIMEOUT")
+    """API request timeout in seconds (longer for debugging)."""
+
+    # ============================================================================
+    # Logging Settings
+    # ============================================================================
+
+    log_level: str = Field(default="INFO", env="LOG_LEVEL")
+    """Logging level (INFO for standard output)."""
+
+    log_file: str = Field(default="logs/development.log", env="LOG_FILE")
+    """Path to development log file."""
+
+    log_rotation_size: int = Field(default=5_242_880, env="LOG_ROTATION_SIZE")
+    """Log file rotation size in bytes (default: 5MB)."""
+
+    log_retention_days: int = Field(default=7, env="LOG_RETENTION_DAYS")
+    """Number of days to retain log files."""
+
+    # ============================================================================
+    # Performance Settings
+    # ============================================================================
+
+    workers: int = Field(default=1, env="WORKERS")
+    """Number of Uvicorn worker processes (single for development)."""
+
+    worker_timeout: int = Field(default=120, env="WORKER_TIMEOUT")
+    """Worker timeout in seconds."""
+
+    max_request_size: int = Field(default=104_857_600, env="MAX_REQUEST_SIZE")
+    """Maximum request body size in bytes (default: 100MB)."""
+
+    session_timeout_hours: int = Field(
+        default=168, env="SESSION_TIMEOUT_HOURS"
+    )
+    """Session timeout in hours (longer for development)."""
+
+    # ============================================================================
+    # Provider Settings
+    # ============================================================================
+
+    default_provider: str = Field(
+        default="aniworld.to", env="DEFAULT_PROVIDER"
+    )
+    """Default content provider."""
+
+    provider_timeout: int = Field(default=60, env="PROVIDER_TIMEOUT")
+    """Provider request timeout in seconds (longer for debugging)."""
+
+    provider_retries: int = Field(default=1, env="PROVIDER_RETRIES")
+    """Number of retry attempts for provider requests."""
+
+    # ============================================================================
+    # Download Settings
+    # ============================================================================
+
+    max_concurrent_downloads: int = Field(
+        default=1, env="MAX_CONCURRENT_DOWNLOADS"
+    )
+    """Maximum concurrent downloads (limited for development)."""
+
+    download_timeout: int = Field(default=7200, env="DOWNLOAD_TIMEOUT")
+    """Download timeout in seconds (default: 2 hours)."""
+
+    # ============================================================================
+    # Application Paths
+    # ============================================================================
+
+    anime_directory: str = Field(
+        default="/tmp/aniworld_dev", env="ANIME_DIRECTORY"
+    )
+    """Directory where anime is stored (development default)."""
+
+    temp_directory: str = Field(
+        default="/tmp/aniworld_dev/temp", env="TEMP_DIRECTORY"
+    )
+    """Temporary directory for downloads and cache."""
+
+    # ============================================================================
+    # Validators
+    # ============================================================================
+
+    @validator("log_level")
+    @classmethod
+    def validate_log_level(cls, v: str) -> str:
+        """Validate log level is valid."""
+        valid_levels = {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}
+        if v.upper() not in valid_levels:
+            raise ValueError(
+                f"Invalid log level '{v}'. Must be one of: {valid_levels}"
+            )
+        return v.upper()
+
+    @validator("cors_origins")
+    @classmethod
+    def parse_cors_origins(cls, v: str) -> str:
+        """Parse comma-separated CORS origins."""
+        if not v:
+            return "http://localhost,http://127.0.0.1"
+        return v
+
+    # ============================================================================
+    # Configuration
+    # ============================================================================
+
+    class Config:
+        """Pydantic config."""
+
+        env_file = ".env.development"
+        extra = "ignore"
+        case_sensitive = False
+
+    # ============================================================================
+    # Properties
+    # ============================================================================
+
+    @property
+    def parsed_cors_origins(self) -> List[str]:
+        """Get parsed CORS origins as list."""
+        if not self.cors_origins or self.cors_origins == "*":
+            return ["*"]
+        return [origin.strip() for origin in self.cors_origins.split(",")]
+
+    @property
+    def is_production(self) -> bool:
+        """Check if running in production mode."""
+        return False
+
+    @property
+    def debug_enabled(self) -> bool:
+        """Check if debug mode is enabled."""
+        return False
+
+    @property
+    def reload_enabled(self) -> bool:
+        """Check if auto-reload is enabled."""
+        return True
+
+
+def get_development_settings() -> DevelopmentSettings:
+    """
+    Get development settings instance.
+
+    This is a factory function that should be called when settings are needed.
+
+    Returns:
+        DevelopmentSettings instance configured from environment variables
+    """
+    return DevelopmentSettings()
+
+
+# Export factory for backward compatibility
+development_settings = DevelopmentSettings()