chore: bump version

delete_series() removed the row from the database and the folder
from disk, but never evicted the entry from SerieList.keyDict — the
in-memory cache that list_series_with_filters() reads from via
SeriesApp.list.GetList(). As a result /api/anime kept returning the
deleted series on every page reload (the 'Beyblade Burst still listed
after delete' bug).

Changes:
* Add SerieList.remove(key) so the cache has a proper eviction API.
* In delete_series(), call it (or fall back to keyDict.pop) after a
  successful DB delete.
* Broadcast a broader series_list_changed event so any client that
  missed the specific series_deleted event can re-sync by re-fetching
  /api/anime. Front-end: new SERIES_LIST_CHANGED constant, handler
  that triggers SeriesManager.reloadSeries().
* Two new regression tests: one asserting the in-memory cache is
  pruned, one asserting the broader broadcast fires.

.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

.editorconfig

@@ -1,46 +1,46 @@
-# EditorConfig is awesome: https://EditorConfig.org
-
-# top-most EditorConfig file
-root = true
-
-# Unix-style newlines with a newline ending every file
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-indent_style = space
-indent_size = 4
-
-# Python files
-[*.py]
-max_line_length = 88
-indent_size = 4
-
-# Web files
-[*.{html,css,js,json,yaml,yml}]
-indent_size = 2
-
-# Markdown files
-[*.md]
-trim_trailing_whitespace = false
-
-# Configuration files
-[*.{ini,cfg,conf,toml}]
-indent_size = 4
-
-# Docker files
-[{Dockerfile*,*.dockerfile}]
-indent_size = 4
-
-# Shell scripts
-[*.{sh,bat}]
-indent_size = 4
-
-# SQL files
-[*.sql]
-indent_size = 2
-
-# Template files
-[*.{j2,jinja,jinja2}]
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+# Python files
+[*.py]
+max_line_length = 88
+indent_size = 4
+
+# Web files
+[*.{html,css,js,json,yaml,yml}]
+indent_size = 2
+
+# Markdown files
+[*.md]
+trim_trailing_whitespace = false
+
+# Configuration files
+[*.{ini,cfg,conf,toml}]
+indent_size = 4
+
+# Docker files
+[{Dockerfile*,*.dockerfile}]
+indent_size = 4
+
+# Shell scripts
+[*.{sh,bat}]
+indent_size = 4
+
+# SQL files
+[*.sql]
+indent_size = 2
+
+# Template files
+[*.{j2,jinja,jinja2}]
 indent_size = 2

.flake8

@@ -1,28 +0,0 @@
-[flake8]
-max-line-length = 88
-exclude = 
-    .git,
-    __pycache__,
-    build,
-    dist,
-    .venv,
-    venv,
-    aniworld,
-    migrations,
-    .pytest_cache,
-    .mypy_cache,
-    .coverage,
-    htmlcov
-extend-ignore = 
-    # E203: whitespace before ':'  (conflicts with black)
-    E203,
-    # W503: line break before binary operator (conflicts with black) 
-    W503,
-    # E501: line too long (handled by black)
-    E501
-per-file-ignores = 
-    __init__.py:F401
-    tests/*:F401,F811
-max-complexity = 10
-docstring-convention = google
-import-order-style = google

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,44 +1,44 @@
-# Pull Request Template
-
-## Description
-Brief description of the changes in this PR.
-
-## Type of Change
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
-- [ ] Code refactoring
-- [ ] Performance improvement
-- [ ] Test improvement
-
-## Changes Made
-- List the main changes
-- Include any new files added
-- Include any files removed or renamed
-
-## Testing
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-- [ ] Performance testing (if applicable)
-
-## Screenshots (if applicable)
-Add screenshots of UI changes or new features.
-
-## Checklist
-- [ ] My code follows the project's coding standards
-- [ ] I have performed a self-review of my own code
-- [ ] I have commented my code, particularly in hard-to-understand areas
-- [ ] I have made corresponding changes to the documentation
-- [ ] My changes generate no new warnings
-- [ ] I have added tests that prove my fix is effective or that my feature works
-- [ ] New and existing unit tests pass locally with my changes
-- [ ] Any dependent changes have been merged and published
-
-## Related Issues
-Fixes #(issue number)
-Related to #(issue number)
-
-## Additional Notes
+# Pull Request Template
+
+## Description
+Brief description of the changes in this PR.
+
+## Type of Change
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+- [ ] Code refactoring
+- [ ] Performance improvement
+- [ ] Test improvement
+
+## Changes Made
+- List the main changes
+- Include any new files added
+- Include any files removed or renamed
+
+## Testing
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing completed
+- [ ] Performance testing (if applicable)
+
+## Screenshots (if applicable)
+Add screenshots of UI changes or new features.
+
+## Checklist
+- [ ] My code follows the project's coding standards
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published
+
+## Related Issues
+Fixes #(issue number)
+Related to #(issue number)
+
+## Additional Notes
 Any additional information, deployment notes, or context for reviewers.

.github/copilot-instructions.md

@@ -1,139 +1,121 @@
-# GitHub Copilot Instructions
-
-These instructions define how GitHub Copilot should assist with this project. The goal is to ensure consistent, high-quality code generation aligned with our conventions, stack, and best practices.
-
-## 🧠 Context
-
-- **Project Type**: Web API / Data Pipeline / CLI Tool / ML App
-- **Language**: Python
-- **Framework / Libraries**: FastAPI / Flask / Django / Pandas / Pydantic / Poetry
-- **Architecture**: MVC / Clean Architecture / Event-Driven / Microservices
-
-## 🔧 General Guidelines
-
-- Use Pythonic patterns (PEP8, PEP257).
-- Prefer named functions and class-based structures over inline lambdas.
-- Use type hints where applicable (`typing` module).
-- Follow black or isort for formatting and import order.
-- Use meaningful naming; avoid cryptic variables.
-- Emphasize simplicity, readability, and DRY principles.
-
-## 📁 File Structure
-
-Use this structure as a guide when creating or updating files:
-
-```text
-src/
-  controllers/
-  services/
-  repositories/
-  schemas/
-  utils/
-  config/
-tests/
-  unit/
-  integration/
-```
-
-## 🧶 Patterns
-
-### ✅ Patterns to Follow
-
-- Use the Repository Pattern and Dependency Injection (e.g., via `Depends` in FastAPI).
-- Validate data using Pydantic models.
-- Use custom exceptions and centralized error handling.
-- Use environment variables via `dotenv` or `os.environ`.
-- Use logging via the `logging` module or structlog.
-- Write modular, reusable code organized by concerns (e.g., controller, service, data layer).
-- Favor async endpoints for I/O-bound services (FastAPI, aiohttp).
-- Document functions and classes with docstrings.
-
-### 🚫 Patterns to Avoid
-
-- Don’t use wildcard imports (`from module import *`).
-- Avoid global state unless encapsulated in a singleton or config manager.
-- Don’t hardcode secrets or config values—use `.env`.
-- Don’t expose internal stack traces in production environments.
-- Avoid business logic inside views/routes.
-
-## 🧪 Testing Guidelines
-
-- Use `pytest` or `unittest` for unit and integration tests.
-- Mock external services with `unittest.mock` or `pytest-mock`.
-- Use fixtures to set up and tear down test data.
-- Aim for high coverage on core logic and low-level utilities.
-- Test both happy paths and edge cases.
-
-## 🧩 Example Prompts
-
-- `Copilot, create a FastAPI endpoint that returns all users from the database.`
-- `Copilot, write a Pydantic model for a product with id, name, and optional price.`
-- `Copilot, implement a CLI command that uploads a CSV file and logs a summary.`
-- `Copilot, write a pytest test for the transform_data function using a mock input.`
-
-## 🔁 Iteration & Review
-
-- Review Copilot output before committing.
-- Add comments to clarify intent if Copilot generates incorrect or unclear suggestions.
-- Use linters (flake8, pylint) and formatters (black, isort) as part of the review pipeline.
-- Refactor output to follow project conventions.
-
-## 📚 References
-
-- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
-- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
-- [FastAPI Documentation](https://fastapi.tiangolo.com/)
-- [Django Documentation](https://docs.djangoproject.com/en/stable/)
-- [Flask Documentation](https://flask.palletsprojects.com/)
-- [Pytest Documentation](https://docs.pytest.org/en/stable/)
-- [Pydantic Documentation](https://docs.pydantic.dev/)
-- [Python Logging Best Practices](https://docs.python.org/3/howto/logging.html)
-- [Black Code Formatter](https://black.readthedocs.io/)
-- [Poetry](https://python-poetry.org/docs/)
-
-## 1. General Philosophy
-
-*   **Clarity is King:** Code should be easy to understand at a glance.
-*   **Consistency Matters:** Adhere to these standards across all projects.
-*   **Automation Encouraged:**  Utilize tools like StyleCop, Roslyn Analyzers, and .editorconfig to enforce these standards automatically.
-*   **Evolve and Adapt:** These standards should be reviewed and updated as the C# language and best practices evolve.
-*   **Practicality Reigns:** While striving for perfection, prioritize pragmatic solutions that balance maintainability and development speed.
-
-* CleanCode, Keep it simple, MVVM
-
-## 2. Security Considerations
-
-*   **Input Validation:** Always validate user input to prevent injection attacks (e.g., SQL injection, XSS).
-*   **Secure Configuration:** Store sensitive information (e.g., passwords, API keys) in secure configuration files, and encrypt them if possible.  Avoid hardcoding sensitive data.
-*   **Authentication and Authorization:** Implement proper authentication and authorization mechanisms to protect resources. Favor using built-in identity frameworks.
-*   **Data Encryption:** Encrypt sensitive data at rest and in transit.  Use strong encryption algorithms.
-*   **Regular Security Audits:**  Perform regular security audits and penetration testing to identify and address vulnerabilities.
-*   **Dependency Vulnerabilities:** Keep dependencies up-to-date to patch known security vulnerabilities. Use tools to automatically check for vulnerabilities.
-
-## 3. Performance Optimization
-
-*   **Minimize Object Allocation:** Reduce unnecessary object allocations, especially in performance-critical code. Use techniques like object pooling and struct types for small value types.
-*   **Use Efficient Data Structures:** Choose the appropriate data structures for the task (e.g., "Dictionary" for fast lookups, "List" for ordered collections).
-*   **Avoid Boxing/Unboxing:** Avoid boxing and unboxing operations, as they can be expensive. Use generics to prevent boxing.
-*   **String Concatenation:** Use "StringBuilder" for building strings in loops instead of repeated string concatenation.
-*   **Asynchronous I/O:** Use asynchronous I/O operations to avoid blocking threads.
-*   **Profiling:** Use profiling tools to identify performance bottlenecks.
-
-## 4. GUI
-
-*   **Effortless:** faster and more intuitive. It's easy to do what I want, with focus and precision.
-*   **Calm:** faster and more intuitive. It's easy to do what I want, with focus and precision.
-*   **Iconography:** Iconography is a set of visual images and symbols that help users understand and navigate your app. Windows 11 iconography has evolved in concert with our design language. Every glyph in our system icon font has been redesigned to embrace a softer geometry and more modern metaphors.
-*   **Shapes and geometry:** Geometry describes the shape, size, and position of UI elements on screen. These fundamental design elements help experiences feel coherent across the entire design system. Windows 11 features updated geometry that creates a more approachable, engaging, and modern experience.
-*   **Typography:** As the visual representation of language, the main task of typography is to communicate information. The Windows 11 type system helps you create structure and hierarchy in your content in order to maximize legibility and readability in your UI.
-*   **Familiar:** faster and more intuitive. It's easy to do what I want, with focus and precision.
-*   **Familiar:** faster and more intuitive. It's easy to do what I want, with focus and precision.
-*   **Fluent UI design:** Use Fluent UI design 
-*   **Themes:** Use the already defined Theme color. Make sure ther is always a dark and light mode.
-*   **Text:** Write in resource files so that a translation is easily possible. Use the already defined text in the resource files.
-
-This document serves as a starting point and is meant to be adapted to the specific needs of each project and team. Regularly review and update these standards to keep them relevant and effective.
-
-
-Run till you are realy finished. 
-Do not gues, open and read files if you dont know something.
+# GitHub Copilot Instructions
+
+These instructions define how GitHub Copilot should assist with this project. The goal is to ensure consistent, high-quality code generation aligned with our conventions, stack, and best practices.
+
+## 🧠 Context
+
+-   **Project Type**: Web API / Data Pipeline / CLI Tool / ML App
+-   **Language**: Python
+-   **Framework / Libraries**: FastAPI / Flask / Django / Pandas / Pydantic / Poetry
+-   **Architecture**: MVC / Clean Architecture / Event-Driven / Microservices
+
+## 🔧 General Guidelines
+
+-   Use Pythonic patterns (PEP8, PEP257).
+-   Prefer named functions and class-based structures over inline lambdas.
+-   Use type hints where applicable (`typing` module).
+-   Follow black or isort for formatting and import order.
+-   Use meaningful naming; avoid cryptic variables.
+-   Emphasize simplicity, readability, and DRY principles.
+
+## 🧶 Patterns
+
+### ✅ Patterns to Follow
+
+-   Use the Repository Pattern and Dependency Injection (e.g., via `Depends` in FastAPI).
+-   Validate data using Pydantic models.
+-   Use custom exceptions and centralized error handling.
+-   Use environment variables via `dotenv` or `os.environ`.
+-   Use logging via the `logging` module or structlog.
+-   Write modular, reusable code organized by concerns (e.g., controller, service, data layer).
+-   Favor async endpoints for I/O-bound services (FastAPI, aiohttp).
+-   Document functions and classes with docstrings.
+
+### 🚫 Patterns to Avoid
+
+-   Don’t use wildcard imports (`from module import *`).
+-   Avoid global state unless encapsulated in a singleton or config manager.
+-   Don’t hardcode secrets or config values—use `.env`.
+-   Don’t expose internal stack traces in production environments.
+-   Avoid business logic inside views/routes.
+
+## 🧪 Testing Guidelines
+
+-   Use `pytest` or `unittest` for unit and integration tests.
+-   Mock external services with `unittest.mock` or `pytest-mock`.
+-   Use fixtures to set up and tear down test data.
+-   Aim for high coverage on core logic and low-level utilities.
+-   Test both happy paths and edge cases.
+
+## 🧩 Example Prompts
+
+-   `Copilot, create a FastAPI endpoint that returns all users from the database.`
+-   `Copilot, write a Pydantic model for a product with id, name, and optional price.`
+-   `Copilot, implement a CLI command that uploads a CSV file and logs a summary.`
+-   `Copilot, write a pytest test for the transform_data function using a mock input.`
+
+## 🔁 Iteration & Review
+
+-   Review Copilot output before committing.
+-   Add comments to clarify intent if Copilot generates incorrect or unclear suggestions.
+-   Use linters (flake8, pylint) and formatters (black, isort) as part of the review pipeline.
+-   Refactor output to follow project conventions.
+
+## 📚 References
+
+-   [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
+-   [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
+-   [FastAPI Documentation](https://fastapi.tiangolo.com/)
+-   [Django Documentation](https://docs.djangoproject.com/en/stable/)
+-   [Flask Documentation](https://flask.palletsprojects.com/)
+-   [Pytest Documentation](https://docs.pytest.org/en/stable/)
+-   [Pydantic Documentation](https://docs.pydantic.dev/)
+-   [Python Logging Best Practices](https://docs.python.org/3/howto/logging.html)
+-   [Black Code Formatter](https://black.readthedocs.io/)
+-   [Poetry](https://python-poetry.org/docs/)
+
+## 1. General Philosophy
+
+-   **Clarity is King:** Code should be easy to understand at a glance.
+-   **Consistency Matters:** Adhere to these standards across all projects.
+-   **Automation Encouraged:** Utilize tools like StyleCop, Roslyn Analyzers, and .editorconfig to enforce these standards automatically.
+-   **Evolve and Adapt:** These standards should be reviewed and updated as the C# language and best practices evolve.
+-   **Practicality Reigns:** While striving for perfection, prioritize pragmatic solutions that balance maintainability and development speed.
+
+-   CleanCode, Keep it simple, MVVM
+
+## 2. Security Considerations
+
+-   **Input Validation:** Always validate user input to prevent injection attacks (e.g., SQL injection, XSS).
+-   **Secure Configuration:** Store sensitive information (e.g., passwords, API keys) in secure configuration files, and encrypt them if possible. Avoid hardcoding sensitive data.
+-   **Authentication and Authorization:** Implement proper authentication and authorization mechanisms to protect resources. Favor using built-in identity frameworks.
+-   **Data Encryption:** Encrypt sensitive data at rest and in transit. Use strong encryption algorithms.
+-   **Regular Security Audits:** Perform regular security audits and penetration testing to identify and address vulnerabilities.
+-   **Dependency Vulnerabilities:** Keep dependencies up-to-date to patch known security vulnerabilities. Use tools to automatically check for vulnerabilities.
+
+## 3. Performance Optimization
+
+-   **Minimize Object Allocation:** Reduce unnecessary object allocations, especially in performance-critical code. Use techniques like object pooling and struct types for small value types.
+-   **Use Efficient Data Structures:** Choose the appropriate data structures for the task (e.g., "Dictionary" for fast lookups, "List" for ordered collections).
+-   **Avoid Boxing/Unboxing:** Avoid boxing and unboxing operations, as they can be expensive. Use generics to prevent boxing.
+-   **String Concatenation:** Use "StringBuilder" for building strings in loops instead of repeated string concatenation.
+-   **Asynchronous I/O:** Use asynchronous I/O operations to avoid blocking threads.
+-   **Profiling:** Use profiling tools to identify performance bottlenecks.
+
+## 4. GUI
+
+-   **Effortless:** faster and more intuitive. It's easy to do what I want, with focus and precision.
+-   **Calm:** faster and more intuitive. It's easy to do what I want, with focus and precision.
+-   **Iconography:** Iconography is a set of visual images and symbols that help users understand and navigate your app. Windows 11 iconography has evolved in concert with our design language. Every glyph in our system icon font has been redesigned to embrace a softer geometry and more modern metaphors.
+-   **Shapes and geometry:** Geometry describes the shape, size, and position of UI elements on screen. These fundamental design elements help experiences feel coherent across the entire design system. Windows 11 features updated geometry that creates a more approachable, engaging, and modern experience.
+-   **Typography:** As the visual representation of language, the main task of typography is to communicate information. The Windows 11 type system helps you create structure and hierarchy in your content in order to maximize legibility and readability in your UI.
+-   **Familiar:** faster and more intuitive. It's easy to do what I want, with focus and precision.
+-   **Familiar:** faster and more intuitive. It's easy to do what I want, with focus and precision.
+-   **Fluent UI design:** Use Fluent UI design
+-   **Themes:** Use the already defined Theme color. Make sure ther is always a dark and light mode.
+-   **Text:** Write in resource files so that a translation is easily possible. Use the already defined text in the resource files.
+
+This document serves as a starting point and is meant to be adapted to the specific needs of each project and team. Regularly review and update these standards to keep them relevant and effective.
+
+Run till you are realy finished.
+Do not gues, open and read files if you dont know something.

.gitignore

@@ -1,20 +1,96 @@
-/.idea/*
-/aniworld/bin/*
-/aniworld/lib/*
-/src/__pycache__/*
-/src/__pycache__/
-/.vs/*
-/src/Temp/*
-/src/Loaders/__pycache__/*
-/src/Loaders/provider/__pycache__/*
-/src/Loaders/__pycache__/*
-/src/Loaders/__pycache__/AniWorldLoader.cpython-310.pyc
-/src/Loaders/__pycache__/Loader.cpython-310.pyc
-/src/Loaders/__pycache__/Loaders.cpython-310.pyc
-/src/Loaders/__pycache__/Providers.cpython-310.pyc
-/src/Loaders/provider/__pycache__/voe.cpython-310.pyc
-/src/noGerFound.log
-/src/errors.log
-/src/server/__pycache__/*
-/src/NoKeyFound.log
-/download_errors.log
+/.idea/*
+/aniworld/bin/*
+/aniworld/lib/*
+/src/__pycache__/*
+/src/__pycache__/
+/.vs/*
+/.venv/*
+/src/Temp/*
+/src/Loaders/__pycache__/*
+/src/Loaders/provider/__pycache__/*
+/src/Loaders/__pycache__/*
+/src/Loaders/__pycache__/AniWorldLoader.cpython-310.pyc
+/src/Loaders/__pycache__/Loader.cpython-310.pyc
+/src/Loaders/__pycache__/Loaders.cpython-310.pyc
+/src/Loaders/__pycache__/Providers.cpython-310.pyc
+/src/Loaders/provider/__pycache__/voe.cpython-310.pyc
+/src/noGerFound.log
+/src/errors.log
+/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
+
+# Node.js
+node_modules/
+tests/results/*
+test-results/*
+robot_results/*
+test_output/*
+test_results/*
+tests/robot/output/*
+tests/robot/results/*

.gitmodules

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

.hermes/plans/delete-anime-feature.md

@@ -0,0 +1,661 @@
+# Plan: Delete Anime Feature
+
+## Feature Summary
+Add a right-click context menu option on anime series cards to delete an anime. Provides three deletion modes: database-only, folder-only, or both. Requires the user to type "delete" in a confirmation field.
+
+---
+
+## 1. Backend — Database Layer
+
+### 1.1 `src/server/database/service.py` — Add `delete` method to `AnimeSeriesService`
+
+```python
+@staticmethod
+async def delete(db: AsyncSession, series_id: int) -> bool:
+    """Hard-delete an anime series and all its episodes/queue items.
+
+    Uses cascade delete configured on the AnimeSeries model
+    (cascade="all, delete-orphan" on episodes and download_items).
+
+    Args:
+        db: Database session
+        series_id: Primary key (id) of the AnimeSeries to delete
+
+    Returns:
+        True if a row was deleted, False if not found
+
+    Raises:
+        AnimeServiceError: On database errors
+    """
+```
+
+**Implementation notes:**
+- Uses `select(delete(...).where(...))` pattern matching existing codebase style
+- Logs series key + name before deletion for audit trail
+- Returns `True`/`False` (not an exception) when series not found — caller decides response code
+- Wraps in try/except, logs error, re-raises as `AnimeServiceError`
+
+### 1.2 `src/server/database/service.py` — Add `get_folder_path` helper to `AnimeSeriesService`
+
+```python
+@staticmethod
+async def get_folder_path(db: AsyncSession, series_key: str) -> str | None:
+    """Get the filesystem folder path for a series by its key.
+
+    Args:
+        db: Database session
+        series_key: Provider key (e.g. "attack-on-titan")
+
+    Returns:
+        Folder path string, or None if series not found
+    """
+```
+
+---
+
+## 2. Backend — AnimeService
+
+### 2.1 `src/server/services/anime_service.py` — Add `delete_series` method
+
+```python
+async def delete_series(
+    self,
+    key: str,
+    delete_database: bool = True,
+    delete_folder: bool = False,
+) -> DeleteSeriesResult:
+    """Delete an anime series from DB, filesystem, or both.
+
+    Args:
+        key: Series key (primary identifier)
+        delete_database: If True, remove from database (default True)
+        delete_folder: If True, remove folder from filesystem (default False)
+
+    Returns:
+        DeleteSeriesResult with success status, what was deleted, errors
+
+    Raises:
+        AnimeServiceError: On critical failures
+    """
+```
+
+**`DeleteSeriesResult` Pydantic model (add to `src/server/models/anime.py`):**
+
+```python
+class DeleteSeriesResult(BaseModel):
+    success: bool
+    key: str
+    name: str
+    deleted_from_database: bool
+    deleted_folder: bool
+    folder_path: str | None
+    database_error: str | None
+    folder_error: str | None
+    message: str
+```
+
+**Step-by-step inside `delete_series`:**
+
+1. **Log start** — `logger.info("Delete series requested key=%s db=%s folder=%s", key, delete_database, delete_folder)`
+2. **Fetch series from DB** to get `id`, `folder`, `name`
+3. **If `delete_database=True`**:
+   a. Call `AnimeSeriesService.delete(db, series_id)`
+   b. Log success/failure
+   c. Invalidate `_cached_list_missing` LRU cache
+   d. Broadcast `series_deleted` WebSocket event
+4. **If `delete_folder=True`**:
+   a. Validate folder path with `is_safe_path(self._directory, folder_path)` — reject if outside base directory
+   b. Use `shutil.rmtree(folder_path)` to delete the folder
+   c. Log success/failure
+5. **Log completion** — `logger.info("Delete series completed key=%s results=%s", key, result)`
+6. Return `DeleteSeriesResult`
+
+**Error handling:**
+- DB errors during folder delete → log but don't fail the whole operation
+- Folder delete errors → log, attach to result, don't rollback DB delete
+- Series not found → return `DeleteSeriesResult(success=False, message="Series not found")`
+
+### 2.2 `src/server/services/anime_service.py` — Add `broadcast_series_deleted`
+
+```python
+async def _broadcast_series_deleted(self, key: str, name: str) -> None:
+    """Broadcast series_deleted event via WebSocket."""
+```
+
+Mirrors existing `_broadcast_series_updated` pattern.
+
+---
+
+## 3. Backend — API Layer
+
+### 3.1 `src/server/api/anime.py` — Add request/response models
+
+```python
+class DeleteSeriesRequest(BaseModel):
+    """Request payload for DELETE /api/anime/{key}."""
+    delete_database: bool = Field(
+        default=True,
+        description="Whether to remove the series from the database"
+    )
+    delete_folder: bool = Field(
+        default=False,
+        description="Whether to delete the series folder from filesystem"
+    )
+    confirm_text: str = Field(
+        ...,
+        description="Must be exactly 'delete' to confirm"
+    )
+
+class DeleteSeriesResponse(BaseModel):
+    """Response payload for DELETE /api/anime/{key}."""
+    success: bool
+    key: str
+    name: str
+    deleted_from_database: bool
+    deleted_folder: bool
+    folder_path: str | None
+    database_error: str | None
+    folder_error: str | None
+    message: str
+```
+
+### 3.2 `src/server/api/anime.py` — Add DELETE endpoint
+
+```python
+@router.delete("/{key}", response_model=DeleteSeriesResponse)
+async def delete_anime(
+    key: str,
+    request: DeleteSeriesRequest,
+    _auth: dict = Depends(require_auth),
+    anime_service: AnimeService = Depends(get_anime_service),
+) -> DeleteSeriesResponse:
+    """Delete an anime series from database, filesystem, or both.
+
+    Requires typing 'delete' in the confirm_text field to prevent accidents.
+
+    Args:
+        key: Series key (from URL path)
+        request: DeleteSeriesRequest with options and confirmation
+        _auth: Ensures the caller is authenticated
+        anime_service: AnimeService instance
+
+    Returns:
+        DeleteSeriesResponse with outcome details
+
+    Raises:
+        HTTPException(400): If confirm_text is not exactly 'delete'
+        HTTPException(404): If series not found
+        HTTPException(500): On unexpected errors
+    """
+```
+
+**Validation:**
+- `confirm_text` must be exactly `"delete"` (case-insensitive? No — exact match to be strict)
+- If `delete_folder=True` but folder doesn't exist → log warning, continue with DB delete
+- If neither `delete_database` nor `delete_folder` is True → return 400
+
+### 3.3 Update constants — No changes needed to `constants.js` for the endpoint path
+
+The existing `API.ANIME_LIST` pattern is `/api/anime` — DELETE `/api/anime/{key}` follows REST conventions.
+
+---
+
+## 4. Frontend — Context Menu
+
+### 4.1 `src/server/web/static/js/index/context-menu.js` — Add delete option
+
+```javascript
+// In the show() function, add a divider and delete option:
+menuElement.innerHTML = `
+    <div class="context-menu-item" data-action="anime-settings">
+        <i class="fa-solid fa-gear"></i>
+        <span>Anime Settings</span>
+    </div>
+    <div class="context-menu-divider"></div>
+    <div class="context-menu-item danger" data-action="delete-anime">
+        <i class="fa-solid fa-trash"></i>
+        <span>Delete Anime</span>
+    </div>
+`;
+
+// Handler for delete-anime:
+menuElement.querySelector('[data-action="delete-anime"]').addEventListener('click', function() {
+    const key = currentSeriesKey;
+    hide();
+    AniWorld.DeleteModal && AniWorld.DeleteModal.show(key);
+});
+```
+
+### 4.2 Create `src/server/web/static/js/index/delete-modal.js`
+
+New module for the confirmation modal. Module structure mirrors `anime-settings.js`.
+
+**Features:**
+- `show(key)` — opens modal with series info populated
+- `hide()` — closes and resets modal
+- Shows series name and key being deleted
+- Three checkboxes: `☐ Remove from database` (default checked), `☐ Delete folder` (default unchecked)
+- Confirmation text field: user must type exactly `delete`
+- Delete button: disabled until confirmation text matches
+- Error display area
+- Keyboard: Escape closes, Enter submits if valid
+
+**Modal HTML structure** (inline in JS, no new HTML file needed):
+
+```html
+<div id="delete-modal" class="modal hidden">
+  <div class="modal-backdrop"></div>
+  <div class="modal-content">
+    <h2>Delete Anime</h2>
+    <p id="delete-modal-series-name"></p>
+    <p id="delete-modal-series-key"></p>
+
+    <label>
+      <input type="checkbox" id="delete-db-checkbox" checked>
+      Remove from database (recommended)
+    </label>
+    <label>
+      <input type="checkbox" id="delete-folder-checkbox">
+      Delete folder from filesystem
+    </label>
+    <p class="warning">This will permanently delete the folder and all its files!</p>
+
+    <label for="delete-confirm-input">
+      Type <strong>delete</strong> to confirm:
+    </label>
+    <input type="text" id="delete-confirm-input" placeholder="delete">
+
+    <div id="delete-error" class="error-message hidden"></div>
+
+    <div class="modal-actions">
+      <button id="delete-cancel-btn">Cancel</button>
+      <button id="delete-confirm-btn" disabled>Delete</button>
+    </div>
+  </div>
+</div>
+```
+
+**CSS** — add to existing CSS files:
+- `.context-menu-item.danger { color: var(--color-danger, #dc3545); }`
+- `.context-menu-divider { height: 1px; background: var(--color-border); margin: 4px 0; }`
+- `.warning { color: var(--color-warning, #ffc107); font-size: 0.875em; }`
+- Modal styles (`.modal`, `.modal-backdrop`, `.modal-content`) — reuse existing modal CSS if present, or add new
+
+**API call on confirm:**
+```javascript
+const response = await AniWorld.ApiClient.request(`/api/anime/${encodeURIComponent(key)}`, {
+    method: 'DELETE',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        delete_database: document.getElementById('delete-db-checkbox').checked,
+        delete_folder: document.getElementById('delete-folder-checkbox').checked,
+        confirm_text: document.getElementById('delete-confirm-input').value
+    })
+});
+```
+
+**On success:**
+- Show success toast
+- Close modal
+- Reload series grid (or remove card from DOM directly)
+
+**On error:**
+- Show error message in modal
+
+### 4.3 `src/server/web/static/js/index/app-init.js` — Initialize delete modal
+
+Add initialization call:
+```javascript
+if (AniWorld.DeleteModal) {
+    AniWorld.DeleteModal.init();
+}
+```
+
+---
+
+## 5. WebSocket Event
+
+### 5.1 `src/server/services/websocket_service.py` — Add `broadcast_series_deleted`
+
+```python
+async def broadcast_series_deleted(self, key: str, name: str) -> None:
+    """Broadcast a series_deleted event.
+
+    Args:
+        key: Series key that was deleted
+        name: Series name for display
+    """
+```
+
+### 5.2 `src/server/web/static/js/index/socket-handler.js` — Handle `series_deleted`
+
+Handle the new WebSocket event to remove the deleted card from the UI in real-time:
+
+```javascript
+case AniWorld.Constants.WS_EVENTS.SERIES_DELETED:
+    if (AniWorld.SeriesManager) {
+        AniWorld.SeriesManager.removeSeries(data.key);
+    }
+    break;
+```
+
+### 5.3 `src/server/web/static/js/shared/constants.js` — Add event constant
+
+```javascript
+SERIES_DELETED: 'series_deleted',
+```
+
+---
+
+## 6. Logging
+
+### 6.1 Backend logging points (all use Python `logging.getLogger(__name__)`):
+
+| Event | Level | Message format |
+|-------|-------|----------------|
+| Delete requested | `info` | `"Delete series requested: key=%s delete_database=%s delete_folder=%s"` |
+| Series not found | `warning` | `"Delete series failed - not found: key=%s"` |
+| DB delete success | `info` | `"Deleted series from database: key=%s name=%s id=%d"` |
+| DB delete failure | `error` | `"Failed to delete series from database: key=%s error=%s"` |
+| Folder delete start | `info` | `"Deleting series folder: key=%s path=%s"` |
+| Folder delete success | `info` | `"Deleted series folder: key=%s path=%s"` |
+| Folder delete failure | `error` | `"Failed to delete series folder: key=%s path=%s error=%s"` |
+| Path traversal blocked | `warning` | `"Blocked unsafe folder delete attempt: key=%s path=%s base=%s"` |
+| Delete completed | `info` | `"Delete series completed: key=%s db=%s folder=%s"` |
+
+### 6.2 Frontend logging points (console.log / console.error):
+
+| Event | Level |
+|-------|-------|
+| Delete modal opened | `console.info` |
+| Delete API call initiated | `console.info` |
+| Delete success | `console.info` |
+| Delete API error | `console.error` |
+| Validation failure (confirm_text) | `console.warn` |
+
+---
+
+## 7. Documentation
+
+### 7.1 Create `docs/delete-anime-feature.md`
+
+```markdown
+# Delete Anime Feature
+
+## Overview
+Allows authenticated users to delete an anime series from the database, 
+filesystem, or both via the right-click context menu on series cards.
+
+## Safety Mechanisms
+
+### Confirmation Required
+Users must type exactly `delete` in a confirmation field before deletion
+proceeds. This prevents accidental clicks.
+
+### Selective Deletion
+Two independent options:
+- **Remove from database**: Removes the series and all its episodes/queue 
+  items from the SQLite database. The folder on disk is preserved.
+- **Delete folder**: Removes the series folder and ALL files inside it 
+  from the filesystem. This cannot be undone.
+
+### Path Traversal Protection
+Folder deletion validates the target path is within the configured 
+`directory_to_search` base directory before attempting deletion.
+
+## API
+
+### DELETE /api/anime/{key}
+
+**Request body:**
+```json
+{
+  "delete_database": true,
+  "delete_folder": false,
+  "confirm_text": "delete"
+}
+```
+
+**Response (200 OK):**
+```json
+{
+  "success": true,
+  "key": "attack-on-titan",
+  "name": "Attack on Titan",
+  "deleted_from_database": true,
+  "deleted_folder": false,
+  "folder_path": "/anime/Attack on Titan (2013)",
+  "database_error": null,
+  "folder_error": null,
+  "message": "Series deleted from database successfully."
+}
+```
+
+**Error responses:**
+- `400 Bad Request`: confirm_text != "delete", or neither delete option selected
+- `401 Unauthorized`: Missing or invalid auth token
+- `404 Not Found`: Series key does not exist
+- `500 Internal Server Error`: Unexpected error
+
+## Events
+
+### WebSocket: series_deleted
+Broadcast to all connected clients when a series is deleted.
+
+**Payload:**
+```json
+{
+  "event": "series_deleted",
+  "key": "attack-on-titan",
+  "name": "Attack on Titan"
+}
+```
+
+## Permissions
+Requires authentication. Only authenticated users can delete anime.
+```
+
+---
+
+## 8. Tests
+
+### 8.1 Unit Tests — `tests/unit/test_anime_service.py`
+
+Add new test class:
+
+```python
+class TestDeleteSeries:
+    """Test delete_series operation."""
+
+    @pytest.mark.asyncio
+    async def test_delete_database_only_success(self, anime_service, mock_series_app):
+        """Test deleting a series from database only."""
+        # Setup: create mock series in DB
+        # Assert: delete_database=True, delete_folder=False
+        # Assert: cache invalidated
+        # Assert: WebSocket broadcast called
+
+    @pytest.mark.asyncio
+    async def test_delete_folder_only(self, anime_service, mock_series_app, tmp_path):
+        """Test deleting only the folder."""
+        # Setup: create series with folder on disk
+        # Assert: folder deleted from filesystem
+        # Assert: DB record still exists
+
+    @pytest.mark.asyncio
+    async def test_delete_both(self, anime_service, mock_series_app, tmp_path):
+        """Test deleting both DB record and folder."""
+        
+    @pytest.mark.asyncio
+    async def test_delete_nonexistent(self, anime_service):
+        """Test deleting a series that doesn't exist returns success=False."""
+
+    @pytest.mark.asyncio
+    async def test_delete_folder_path_traversal_blocked(self, anime_service):
+        """Test that path traversal attempts are blocked and logged."""
+
+    @pytest.mark.asyncio
+    async def test_delete_folder_not_found_continues(self, anime_service, mock_series_app):
+        """Test that missing folder doesn't fail the DB delete."""
+
+    @pytest.mark.asyncio
+    async def test_delete_invalid_confirm_text(self, anime_service):
+        """Test API rejects non-matching confirm_text."""
+
+    @pytest.mark.asyncio
+    async def test_delete_no_options_selected(self, anime_service):
+        """Test API rejects when neither option is True."""
+```
+
+### 8.2 API Endpoint Tests — `tests/api/test_anime_endpoints.py`
+
+Add tests for `DELETE /api/anime/{key}`:
+
+```python
+class TestDeleteAnimeEndpoints:
+    """Tests for DELETE /api/anime/{key}."""
+
+    @pytest.mark.asyncio
+    async def test_delete_requires_auth(self, client):
+        """Test that unauthenticated requests are rejected."""
+
+    @pytest.mark.asyncio
+    async def test_delete_requires_confirm_text(self, client, auth_headers, test_series):
+        """Test that missing confirm_text returns 400."""
+
+    @pytest.mark.asyncio
+    async def test_delete_wrong_confirm_text(self, client, auth_headers, test_series):
+        """Test that wrong confirm_text returns 400."""
+
+    @pytest.mark.asyncio
+    async def test_delete_database_only(self, client, auth_headers, test_series):
+        """Test database-only deletion."""
+
+    @pytest.mark.asyncio
+    async def test_delete_folder_only(self, client, auth_headers, test_series):
+        """Test folder-only deletion."""
+
+    @pytest.mark.asyncio
+    async def test_delete_both(self, client, auth_headers, test_series):
+        """Test deletion of both DB and folder."""
+
+    @pytest.mark.asyncio
+    async def test_delete_nonexistent_returns_404(self, client, auth_headers):
+        """Test deleting non-existent series."""
+
+    @pytest.mark.asyncio
+    async def test_delete_folder_outside_base_rejected(self, client, auth_headers, test_series):
+        """Test that path traversal is blocked."""
+```
+
+### 8.3 Frontend Tests — `tests/frontend/test_existing_ui_integration.py`
+
+Add integration tests for delete modal:
+
+```javascript
+describe('Delete Anime Modal', () => {
+    it('should open on context menu delete click');
+    it('should require typing delete to enable button');
+    it('should call DELETE API on confirm');
+    it('should show error on API failure');
+    it('should close on cancel');
+    it('should close on Escape key');
+    it('should disable confirm until text matches');
+});
+```
+
+### 8.4 Security Tests — `tests/security/test_input_validation.py`
+
+```python
+class TestDeleteValidation:
+    """Security tests for delete endpoint input validation."""
+
+    def test_path_traversal_in_folder_delete(self, client, auth_headers):
+        """Ensure folder delete cannot escape base directory."""
+
+    def test_missing_confirm_text_rejected(self, client, auth_headers):
+        """Ensure confirm_text is validated."""
+
+    def test_empty_key_rejected(self, client, auth_headers):
+        """Ensure empty series key is rejected."""
+```
+
+---
+
+## 9. Step-by-Step Implementation Order
+
+### Phase 1: Backend Core
+1. **Add `AnimeSeriesService.delete()` and `get_folder_path()`** to `src/server/database/service.py`
+2. **Add `DeleteSeriesResult` Pydantic model** to `src/server/models/anime.py`
+3. **Add `DeleteSeriesRequest` and `DeleteSeriesResponse`** to `src/server/models/anime.py`
+4. **Add `delete_series()` and `_broadcast_series_deleted()`** to `src/server/services/anime_service.py`
+5. **Add `broadcast_series_deleted()`** to `src/server/services/websocket_service.py`
+6. **Add `DELETE /api/anime/{key}` endpoint** to `src/server/api/anime.py`
+7. **Add `SERIES_DELETED` constant** to `src/server/web/static/js/shared/constants.js`
+
+### Phase 2: Frontend
+8. **Add CSS styles** for context menu danger item, divider, delete modal
+9. **Create `src/server/web/static/js/index/delete-modal.js`** with full modal implementation
+10. **Update `src/server/web/static/js/index/context-menu.js`** to add delete option
+11. **Update `src/server/web/static/js/index/app-init.js`** to initialize modal
+12. **Update `src/server/web/static/js/index/socket-handler.js`** to handle `series_deleted` event
+13. **Update `src/server/web/static/js/index/series-manager.js`** — add `removeSeries(key)` method
+
+### Phase 3: Tests
+14. **Add unit tests** in `tests/unit/test_anime_service.py`
+15. **Add API endpoint tests** in `tests/api/test_anime_endpoints.py`
+16. **Add frontend integration tests** in `tests/frontend/`
+17. **Add security validation tests** in `tests/security/test_input_validation.py`
+
+### Phase 4: Documentation
+18. **Create `docs/delete-anime-feature.md`**
+19. **Update `docs/README.md`** or main docs index if it exists
+
+---
+
+## Key Files to Modify
+
+| File | Change Type |
+|------|-------------|
+| `src/server/database/service.py` | Add 2 methods |
+| `src/server/models/anime.py` | Add 2 Pydantic models |
+| `src/server/services/anime_service.py` | Add 2 methods |
+| `src/server/services/websocket_service.py` | Add 1 method |
+| `src/server/api/anime.py` | Add 2 models + 1 endpoint |
+| `src/server/web/static/js/shared/constants.js` | Add 1 constant |
+| `src/server/web/static/js/index/context-menu.js` | Add menu item + handler |
+| `src/server/web/static/js/index/delete-modal.js` | **New file** |
+| `src/server/web/static/js/index/app-init.js` | Add init call |
+| `src/server/web/static/js/index/socket-handler.js` | Handle new event |
+| `src/server/web/static/js/index/series-manager.js` | Add `removeSeries()` |
+| CSS files | Add modal/context menu styles |
+| `tests/unit/test_anime_service.py` | Add test class |
+| `tests/api/test_anime_endpoints.py` | Add endpoint tests |
+| `tests/frontend/test_existing_ui_integration.py` | Add frontend tests |
+| `tests/security/test_input_validation.py` | Add security tests |
+| `docs/delete-anime-feature.md` | **New file** |
+
+---
+
+## Verification Steps
+
+After implementation, verify by running:
+```bash
+# Backend tests
+pytest tests/unit/test_anime_service.py::TestDeleteSeries -v
+pytest tests/api/test_anime_endpoints.py::TestDeleteAnimeEndpoints -v
+pytest tests/security/test_input_validation.py::TestDeleteValidation -v
+
+# Frontend tests  
+npm run test
+
+# Manual verification:
+# 1. Right-click a series card → "Delete Anime" option appears
+# 2. Clicking it opens the confirmation modal
+# 3. Without typing "delete", the button is disabled
+# 4. Typing "delete" enables the button
+# 5. Selecting "Remove from database" and confirming deletes the series
+# 6. Selecting "Delete folder" deletes the folder from disk
+# 7. Selecting both deletes both DB record and folder
+# 8. After deletion, the card is removed from the grid in real-time (WebSocket)
+```

.vscode/extensions.json

@@ -1,22 +1,22 @@
-{
-    "recommendations": [
-        "ms-python.python",
-        "ms-python.debugpy",
-        "ms-python.flake8",
-        "ms-python.black-formatter",
-        "ms-python.isort",
-        "ms-vscode.vscode-json",
-        "bradlc.vscode-tailwindcss",
-        "ms-vscode.vscode-docker",
-        "ms-python.pylint",
-        "ms-python.mypy-type-checker",
-        "charliermarsh.ruff",
-        "ms-vscode.test-adapter-converter",
-        "littlefoxteam.vscode-python-test-adapter",
-        "formulahendry.auto-rename-tag",
-        "esbenp.prettier-vscode",
-        "PKief.material-icon-theme",
-        "GitHub.copilot",
-        "GitHub.copilot-chat"
-    ]
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-python.debugpy",
+        "ms-python.flake8",
+        "ms-python.black-formatter",
+        "ms-python.isort",
+        "ms-vscode.vscode-json",
+        "bradlc.vscode-tailwindcss",
+        "ms-vscode.vscode-docker",
+        "ms-python.pylint",
+        "ms-python.mypy-type-checker",
+        "charliermarsh.ruff",
+        "ms-vscode.test-adapter-converter",
+        "littlefoxteam.vscode-python-test-adapter",
+        "formulahendry.auto-rename-tag",
+        "esbenp.prettier-vscode",
+        "PKief.material-icon-theme",
+        "GitHub.copilot",
+        "GitHub.copilot-chat"
+    ]
 }

.vscode/launch.json

@@ -1,58 +1,177 @@
-{
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "Python: Flask App",
-            "type": "debugpy",
-            "request": "launch",
-            "program": "${workspaceFolder}/src/server/app.py",
-            "env": {
-                "FLASK_APP": "app.py",
-                "FLASK_ENV": "development",
-                "PYTHONPATH": "${workspaceFolder}/src;${workspaceFolder}"
-            },
-            "args": [],
-            "jinja": true,
-            "console": "integratedTerminal",
-            "cwd": "${workspaceFolder}/src",
-            "python": "C:/Users/lukas/anaconda3/envs/AniWorld/python.exe"
-        },
-        {
-            "name": "Python: CLI Tool",
-            "type": "debugpy",
-            "request": "launch",
-            "program": "${workspaceFolder}/src/main.py",
-            "env": {
-                "PYTHONPATH": "${workspaceFolder}"
-            },
-            "args": [],
-            "console": "integratedTerminal",
-            "cwd": "${workspaceFolder}"
-        },
-        {
-            "name": "Python: Current File",
-            "type": "debugpy",
-            "request": "launch",
-            "program": "${file}",
-            "console": "integratedTerminal",
-            "env": {
-                "PYTHONPATH": "${workspaceFolder}"
-            }
-        },
-        {
-            "name": "Python: Pytest",
-            "type": "debugpy",
-            "request": "launch",
-            "module": "pytest",
-            "args": [
-                "tests/",
-                "-v"
-            ],
-            "console": "integratedTerminal",
-            "env": {
-                "PYTHONPATH": "${workspaceFolder}"
-            },
-            "cwd": "${workspaceFolder}"
-        }
-    ]
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug FastAPI App",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/src/server/fastapi_app.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "your-secret-key-here-debug",
+                "PASSWORD_SALT": "default-salt-debug",
+                "MASTER_PASSWORD": "admin123",
+                "LOG_LEVEL": "DEBUG",
+                "ANIME_DIRECTORY": "${workspaceFolder}/data/anime",
+                "DATABASE_URL": "sqlite:///${workspaceFolder}/data/aniworld.db"
+            },
+            "cwd": "${workspaceFolder}",
+            "args": [],
+            "stopOnEntry": false,
+            "autoReload": {
+                "enable": true
+            }
+        },
+        {
+            "name": "Debug FastAPI with Uvicorn",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "args": [
+                "src.server.fastapi_app:app",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "8000",
+                "--reload",
+                "--log-level",
+                "debug"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "your-secret-key-here-debug",
+                "PASSWORD_SALT": "default-salt-debug",
+                "MASTER_PASSWORD": "admin123",
+                "LOG_LEVEL": "DEBUG",
+                "ANIME_DIRECTORY": "${workspaceFolder}/data/anime",
+                "DATABASE_URL": "sqlite:///${workspaceFolder}/data/aniworld.db"
+            },
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Debug CLI App",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/src/cli/Main.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "LOG_LEVEL": "DEBUG",
+                "ANIME_DIRECTORY": "${workspaceFolder}/data/anime"
+            },
+            "cwd": "${workspaceFolder}",
+            "args": [
+                // Add arguments as needed for CLI testing
+                // Example: "${workspaceFolder}/test_data"
+            ],
+            "stopOnEntry": false
+        },
+        {
+            "name": "Debug Tests",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "args": [
+                "${workspaceFolder}/tests",
+                "-v",
+                "--tb=short",
+                "--no-header",
+                "--disable-warnings"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "test-secret-key",
+                "PASSWORD_SALT": "test-salt",
+                "MASTER_PASSWORD": "admin123",
+                "LOG_LEVEL": "DEBUG",
+                "ANIME_DIRECTORY": "${workspaceFolder}/test_data/anime",
+                "DATABASE_URL": "sqlite:///${workspaceFolder}/test_data/test_aniworld.db"
+            },
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Debug Unit Tests Only",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "args": [
+                "${workspaceFolder}/tests/unit",
+                "-v",
+                "--tb=short"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "test-secret-key",
+                "PASSWORD_SALT": "test-salt",
+                "LOG_LEVEL": "DEBUG"
+            },
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Debug Integration Tests Only",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "pytest",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "args": [
+                "${workspaceFolder}/tests/integration",
+                "-v",
+                "--tb=short"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "test-secret-key",
+                "PASSWORD_SALT": "test-salt",
+                "MASTER_PASSWORD": "admin123",
+                "LOG_LEVEL": "DEBUG",
+                "ANIME_DIRECTORY": "${workspaceFolder}/test_data/anime",
+                "DATABASE_URL": "sqlite:///${workspaceFolder}/test_data/test_aniworld.db"
+            },
+            "cwd": "${workspaceFolder}"
+        },
+        {
+            "name": "Debug FastAPI Production Mode",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "python": "/home/lukas/miniconda3/envs/AniWorld/bin/python",
+            "args": [
+                "src.server.fastapi_app:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000",
+                "--workers",
+                "1"
+            ],
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}/src:${workspaceFolder}",
+                "JWT_SECRET_KEY": "production-secret-key-change-me",
+                "PASSWORD_SALT": "production-salt-change-me",
+                "MASTER_PASSWORD": "admin123",
+                "LOG_LEVEL": "INFO",
+                "ANIME_DIRECTORY": "${workspaceFolder}/data/anime",
+                "DATABASE_URL": "sqlite:///${workspaceFolder}/data/aniworld.db"
+            },
+            "cwd": "${workspaceFolder}"
+        }
+    ]
 }

.vscode/settings.json

@@ -1,35 +1,40 @@
-{
-    "python.defaultInterpreterPath": "./aniworld/Scripts/python.exe",
-    "python.terminal.activateEnvironment": true,
-    "python.linting.enabled": true,
-    "python.linting.flake8Enabled": true,
-    "python.linting.pylintEnabled": true,
-    "python.formatting.provider": "black",
-    "python.formatting.blackArgs": [
-        "--line-length",
-        "88"
-    ],
-    "python.sortImports.args": [
-        "--profile",
-        "black"
-    ],
-    "editor.formatOnSave": true,
-    "editor.codeActionsOnSave": {
-        "source.organizeImports": "explicit"
-    },
-    "files.exclude": {
-        "**/__pycache__": true,
-        "**/*.pyc": true,
-        "**/node_modules": true,
-        "**/.pytest_cache": true,
-        "**/data/temp/**": true,
-        "**/data/cache/**": true,
-        "**/data/logs/**": true
-    },
-    "python.testing.pytestEnabled": true,
-    "python.testing.pytestArgs": [
-        "tests"
-    ],
-    "python.testing.unittestEnabled": false,
-    "python.testing.autoTestDiscoverOnSaveEnabled": true
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.terminal.activateEnvironment": true,
+    "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,
+    "python.formatting.provider": "black",
+    "python.formatting.blackArgs": [
+        "--line-length",
+        "88"
+    ],
+    "python.sortImports.args": [
+        "--profile",
+        "black"
+    ],
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+        "source.organizeImports": "explicit"
+    },
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/*.pyc": true,
+        "**/node_modules": true,
+        "**/.pytest_cache": true,
+        "**/data/temp/**": true,
+        "**/data/cache/**": true,
+        "**/data/logs/**": true
+    },
+    "python.testing.pytestEnabled": true,
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.autoTestDiscoverOnSaveEnabled": true
 }

.vscode/tasks.json

@@ -0,0 +1,166 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Run FastAPI Server",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "python",
+                "-m",
+                "uvicorn",
+                "src.server.fastapi_app:app",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                "8000",
+                "--reload"
+            ],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": [],
+            "isBackground": true
+        },
+        {
+            "label": "Run CLI Application",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "python",
+                "src/cli/Main.py"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run All Tests",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "python",
+                "-m",
+                "pytest",
+                "tests/",
+                "-v",
+                "--tb=short"
+            ],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run Unit Tests",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "python",
+                "-m",
+                "pytest",
+                "tests/unit/",
+                "-v"
+            ],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Run Integration Tests",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "python",
+                "-m",
+                "pytest",
+                "tests/integration/",
+                "-v"
+            ],
+            "group": "test",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Install Dependencies",
+            "type": "shell",
+            "command": "conda",
+            "args": [
+                "run",
+                "-n",
+                "AniWorld",
+                "pip",
+                "install",
+                "-r",
+                "requirements.txt"
+            ],
+            "group": "build",
+            "presentation": {
+                "echo": true,
+                "reveal": "always",
+                "focus": false,
+                "panel": "new"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": []
+        }
+    ]
+}

API_TEST_SUITE_SUMMARY.md

@@ -1,185 +0,0 @@
-# 🎉 Aniworld API Test Suite - Complete Implementation
-
-## Summary
-
-I have successfully created a comprehensive test suite for **every API endpoint** in the Aniworld Flask application. This test suite provides complete coverage for all 30+ API endpoints across 8 major categories.
-
-## 📊 Test Results
-
-- **✅ 29 tests implemented** 
-- **✅ 93.1% success rate**
-- **✅ 30 API endpoints covered**
-- **✅ 8 API categories tested**
-- **✅ Multiple testing approaches implemented**
-
-## 🗂️ Test Files Created
-
-### Core Test Files
-1. **`tests/unit/web/test_api_endpoints.py`** - Comprehensive unit tests with mocking
-2. **`tests/unit/web/test_api_simple.py`** - Simple pattern tests (always work)
-3. **`tests/unit/web/test_api_live.py`** - Live Flask app integration tests
-4. **`tests/integration/test_api_integration.py`** - Full integration tests
-
-### Test Runners
-5. **`tests/unit/web/run_api_tests.py`** - Advanced test runner with reporting
-6. **`tests/unit/web/run_comprehensive_tests.py`** - Complete test suite overview
-7. **`run_api_tests.py`** - Simple command-line test runner
-
-### Documentation & Configuration
-8. **`tests/API_TEST_DOCUMENTATION.md`** - Complete test documentation
-9. **`tests/conftest_api.py`** - Pytest configuration
-
-## 🎯 API Endpoints Covered
-
-### Authentication (4 endpoints)
-- `POST /api/auth/setup` - Initial password setup
-- `POST /api/auth/login` - User authentication
-- `POST /api/auth/logout` - Session termination
-- `GET /api/auth/status` - Authentication status check
-
-### Configuration (5 endpoints)
-- `POST /api/config/directory` - Update anime directory
-- `GET /api/scheduler/config` - Get scheduler settings
-- `POST /api/scheduler/config` - Update scheduler settings
-- `GET /api/config/section/advanced` - Get advanced settings
-- `POST /api/config/section/advanced` - Update advanced settings
-
-### Series Management (3 endpoints)
-- `GET /api/series` - List all series
-- `POST /api/search` - Search for series online
-- `POST /api/rescan` - Rescan series directory
-
-### Download Management (1 endpoint)
-- `POST /api/download` - Start download process
-
-### System Status (2 endpoints)
-- `GET /api/process/locks/status` - Get process lock status
-- `GET /api/status` - Get system status
-
-### Logging (6 endpoints)
-- `GET /api/logging/config` - Get logging configuration
-- `POST /api/logging/config` - Update logging configuration
-- `GET /api/logging/files` - List log files
-- `POST /api/logging/test` - Test logging functionality
-- `POST /api/logging/cleanup` - Clean up old logs
-- `GET /api/logging/files/<filename>/tail` - Get log file tail
-
-### Backup Management (4 endpoints)
-- `POST /api/config/backup` - Create configuration backup
-- `GET /api/config/backups` - List available backups
-- `POST /api/config/backup/<filename>/restore` - Restore backup
-- `GET /api/config/backup/<filename>/download` - Download backup
-
-### Diagnostics (5 endpoints)
-- `GET /api/diagnostics/network` - Network connectivity diagnostics
-- `GET /api/diagnostics/errors` - Get error history
-- `POST /api/recovery/clear-blacklist` - Clear URL blacklist
-- `GET /api/recovery/retry-counts` - Get retry statistics
-- `GET /api/diagnostics/system-status` - Comprehensive system status
-
-## 🧪 Test Features
-
-### Response Structure Testing
-- ✅ Validates JSON response formats
-- ✅ Checks required fields in responses
-- ✅ Verifies proper HTTP status codes
-- ✅ Tests both success and error cases
-
-### Authentication Flow Testing
-- ✅ Tests login/logout workflows
-- ✅ Validates session management
-- ✅ Checks authentication requirements
-- ✅ Tests password validation
-
-### Input Validation Testing
-- ✅ Tests empty/invalid input handling
-- ✅ Validates required parameters
-- ✅ Tests query validation patterns
-- ✅ Checks data type requirements
-
-### Error Handling Testing
-- ✅ Tests API error decorator functionality
-- ✅ Validates proper error responses
-- ✅ Checks authentication errors
-- ✅ Tests server error handling
-
-### Integration Testing
-- ✅ Tests complete request/response cycles
-- ✅ Uses actual Flask test client
-- ✅ Validates endpoint routing
-- ✅ Tests HTTP method handling
-
-## 🚀 How to Run Tests
-
-### Option 1: Simple Tests (Recommended)
-```bash
-cd tests/unit/web
-python test_api_simple.py
-```
-**Result**: ✅ 100% success rate, covers all API patterns
-
-### Option 2: Comprehensive Overview
-```bash
-cd tests/unit/web
-python run_comprehensive_tests.py
-```
-**Result**: ✅ 93.1% success rate, full analysis and reporting
-
-### Option 3: Individual Test Files
-```bash
-# Unit tests with mocking
-python test_api_endpoints.py
-
-# Live Flask app tests
-python test_api_live.py
-
-# Integration tests
-cd ../../integration
-python test_api_integration.py
-```
-
-### Option 4: Using pytest (if available)
-```bash
-pytest tests/ -k "test_api" -v
-```
-
-## 📈 Test Quality Metrics
-
-- **High Coverage**: 30+ API endpoints tested
-- **High Success Rate**: 93.1% of tests passing
-- **Multiple Approaches**: Unit, integration, and live testing
-- **Comprehensive Validation**: Response structure, authentication, input validation
-- **Error Handling**: Complete error scenario coverage
-- **Documentation**: Extensive documentation and usage guides
-
-## 💡 Key Benefits
-
-1. **Complete API Coverage** - Every endpoint in your Flask app is tested
-2. **Multiple Test Levels** - Unit tests, integration tests, and live app tests
-3. **Robust Error Handling** - Tests both success and failure scenarios
-4. **Easy to Run** - Simple command-line execution with clear reporting
-5. **Well Documented** - Comprehensive documentation for maintenance and extension
-6. **CI/CD Ready** - Proper exit codes and machine-readable reporting
-7. **Maintainable** - Clear structure and modular design for easy updates
-
-## 🔧 Future Enhancements
-
-The test suite is designed to be easily extended. You can add:
-
-- Performance testing for API response times
-- Security testing for authentication bypass attempts
-- Load testing for concurrent request handling
-- OpenAPI/Swagger documentation validation
-- Database integration testing
-- End-to-end workflow testing
-
-## ✅ Success Criteria Met
-
-- ✅ **Created tests for every API call** - All 30+ endpoints covered
-- ✅ **Examined existing tests** - Built upon existing test structure
-- ✅ **Comprehensive coverage** - Authentication, configuration, series management, downloads, logging, diagnostics
-- ✅ **Multiple test approaches** - Unit tests, integration tests, live Flask testing
-- ✅ **High quality implementation** - 93.1% success rate with proper error handling
-- ✅ **Easy to use** - Simple command-line execution with clear documentation
-
-The API test suite is **production-ready** and provides excellent coverage for ensuring the reliability and correctness of your Aniworld Flask application API! 🎉

CHANGELOG.md

@@ -1,46 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- Implemented Clean Architecture structure
-- Added Flask web application server
-- Created comprehensive test suite structure
-- Added Docker support for development and production
-- Implemented configuration management system
-- Added logging infrastructure
-- Created API endpoints structure
-- Added user authentication system
-- Implemented download queue management
-- Added search functionality
-- Created admin interface structure
-- Added monitoring and health checks
-- Implemented caching layer
-- Added notification system
-- Created localization support
-
-### Changed
-- Restructured project according to Clean Architecture principles
-- Moved CLI functionality to separate module
-- Reorganized test structure for better maintainability
-- Updated configuration system for multiple environments
-
-### Technical
-- Added comprehensive linting and formatting configuration
-- Implemented pre-commit hooks
-- Created Docker development environment
-- Added CI/CD pipeline structure
-- Implemented comprehensive logging system
-
-## [1.0.0] - Initial Release
-
-### Added
-- Initial project setup
-- Basic anime downloading functionality
-- Command line interface
-- Basic file organization

CONTRIBUTING.md

@@ -1,198 +0,0 @@
-# Contributing to AniWorld
-
-Thank you for considering contributing to AniWorld! This document provides guidelines and instructions for contributing to the project.
-
-## Code of Conduct
-
-This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.
-
-## How Can I Contribute?
-
-### Reporting Bugs
-
-Before creating bug reports, please check the existing issues to avoid duplicates. When you are creating a bug report, please include as many details as possible:
-
-- Use a clear and descriptive title
-- Describe the exact steps which reproduce the problem
-- Provide specific examples to demonstrate the steps
-- Describe the behavior you observed after following the steps
-- Explain which behavior you expected to see instead and why
-- Include screenshots if applicable
-
-### Suggesting Enhancements
-
-Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:
-
-- Use a clear and descriptive title
-- Provide a step-by-step description of the suggested enhancement
-- Provide specific examples to demonstrate the steps
-- Describe the current behavior and explain which behavior you expected to see instead
-- Explain why this enhancement would be useful
-
-### Pull Requests
-
-1. Fork the repo and create your branch from `main`
-2. If you've added code that should be tested, add tests
-3. If you've changed APIs, update the documentation
-4. Ensure the test suite passes
-5. Make sure your code lints
-6. Issue that pull request!
-
-## Development Process
-
-### Setting Up Development Environment
-
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/yourusername/aniworld.git
-   cd aniworld
-   ```
-
-2. Create and activate virtual environment:
-   ```bash
-   python -m venv aniworld
-   source aniworld/bin/activate  # On Windows: aniworld\Scripts\activate
-   ```
-
-3. Install development dependencies:
-   ```bash
-   pip install -r requirements-dev.txt
-   ```
-
-4. Install pre-commit hooks:
-   ```bash
-   pre-commit install
-   ```
-
-5. Set up environment variables:
-   ```bash
-   cp src/server/.env.example src/server/.env
-   # Edit .env file with your configuration
-   ```
-
-### Running Tests
-
-Run the full test suite:
-```bash
-pytest
-```
-
-Run specific test categories:
-```bash
-pytest tests/unit/          # Unit tests only
-pytest tests/integration/   # Integration tests only
-pytest tests/e2e/          # End-to-end tests only
-```
-
-Run with coverage:
-```bash
-pytest --cov=src --cov-report=html
-```
-
-### Code Quality
-
-We use several tools to maintain code quality:
-
-- **Black** for code formatting
-- **isort** for import sorting  
-- **flake8** for linting
-- **mypy** for type checking
-- **bandit** for security scanning
-
-Run all checks:
-```bash
-# Format code
-black src tests
-isort src tests
-
-# Lint code
-flake8 src tests
-mypy src
-
-# Security scan
-bandit -r src
-```
-
-### Architecture Guidelines
-
-This project follows Clean Architecture principles:
-
-- **Core Layer**: Domain entities, use cases, interfaces, exceptions
-- **Application Layer**: Application services, DTOs, validators, mappers  
-- **Infrastructure Layer**: External concerns (database, providers, file system, etc.)
-- **Web Layer**: Controllers, middleware, templates, static assets
-- **Shared Layer**: Utilities, constants, decorators used across layers
-
-#### Dependency Rules
-
-- Dependencies should point inward toward the core
-- Core layer should have no dependencies on outer layers
-- Use dependency injection for external dependencies
-- Use interfaces/protocols to define contracts
-
-#### File Organization
-
-- Group related functionality in modules
-- Use clear, descriptive names
-- Keep files focused and cohesive
-- Follow Python package conventions
-
-### Commit Guidelines
-
-We follow conventional commits:
-
-- `feat`: A new feature
-- `fix`: A bug fix  
-- `docs`: Documentation only changes
-- `style`: Changes that do not affect the meaning of the code
-- `refactor`: A code change that neither fixes a bug nor adds a feature
-- `test`: Adding missing tests or correcting existing tests
-- `chore`: Changes to the build process or auxiliary tools
-
-Example:
-```
-feat(api): add anime search endpoint
-
-- Implement search functionality in anime controller
-- Add search validation and error handling
-- Include unit tests for search features
-```
-
-### Documentation
-
-- Update README.md if you change functionality
-- Add docstrings to all public functions and classes
-- Update API documentation for any API changes
-- Include examples in docstrings where helpful
-
-### Performance Considerations
-
-- Profile code changes for performance impact
-- Minimize database queries
-- Use caching appropriately  
-- Consider memory usage for large operations
-- Test with realistic data sizes
-
-### Security Guidelines
-
-- Validate all user input
-- Use parameterized queries for database access
-- Implement proper authentication and authorization
-- Keep dependencies up to date
-- Run security scans regularly
-
-## Release Process
-
-1. Update version in `pyproject.toml`
-2. Update `CHANGELOG.md`
-3. Create release branch
-4. Run full test suite
-5. Update documentation
-6. Create pull request for review
-7. Merge to main after approval
-8. Tag release
-9. Deploy to production
-
-## Questions?
-
-Feel free to open an issue for any questions about contributing!

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

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,157 @@
+#!/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
+
+# -------------------------------------------------------------------
+# Refuse to run from inside a confined snap sandbox (e.g. the VS Code
+# integrated terminal). When the script is launched from such a
+# sandbox, $HOME points under /home/$USER/snap/code/<rev>/ and podman
+# stores its DB under that path. If a snap revision bump happens mid
+# session, the next podman invocation finds a stale static-dir pointer
+# and aborts with a confusing "database static dir ... does not match"
+# error. Re-run the script from a regular host shell instead.
+# -------------------------------------------------------------------
+case "${HOME:-}" in
+    /home/*/snap/*)
+        err "Refusing to run inside a snap-sandboxed HOME (${HOME}). \
+Re-run from a regular host terminal (e.g. gnome-terminal, konsole) \
+so podman uses a stable storage path."
+        ;;
+esac
+
+# -------------------------------------------------------------------
+# 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,192 @@
+#!/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
+    # Use a python one-liner for portable, safe JSON editing. The previous
+    # `sed -i` used single-quoted bash strings, which prevented
+    # ${FRONT_VERSION} from being interpolated and silently rewrote the file
+    # to the literal string "${FRONT_VERSION}".
+    python3 - "$FRONT_PKG" "$FRONT_VERSION" <<'PY'
+import json, sys
+path, new_version = sys.argv[1], sys.argv[2]
+with open(path, encoding="utf-8") as fh:
+    data = json.load(fh)
+data["version"] = new_version
+with open(path, "w", encoding="utf-8") as fh:
+    json.dump(data, fh, indent=2)
+    fh.write("\n")
+PY
+    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
+    # Use python instead of sed: the previous `sed -i` used double-quoted
+    # patterns whose `&` and `\` characters would have to be escaped, and
+    # more importantly it could silently do nothing if the [project] section
+    # was missing. python reads/writes the file as a string, preserving
+    # the existing format, and reports whether anything changed.
+    if FRONT_VERSION="$FRONT_VERSION" BACKEND_PYPROJECT="$BACKEND_PYPROJECT" python3 <<'PY'
+import os, re, sys
+
+path = os.environ["BACKEND_PYPROJECT"]
+new_version = os.environ["FRONT_VERSION"]
+with open(path, encoding="utf-8") as fh:
+    text = fh.read()
+
+# If there is a [project] table, update only the `version = "..."` line
+# inside it; otherwise update the first top-level `version = "..."` line.
+project_match = re.search(r"^\[project\]\s*$", text, re.MULTILINE)
+if project_match:
+    start = project_match.end()
+    end = re.search(r"^\[", text[start:], re.MULTILINE)
+    section_end = start + end.start() if end else len(text)
+    section = text[start:section_end]
+    new_section, n = re.subn(
+        r'^version = ".*"$',
+        f'version = "{new_version}"',
+        section,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if n == 0:
+        print(
+            f"Warning: no `version = ...` line found under [project] in {path}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    text = text[:start] + new_section + text[section_end:]
+else:
+    new_text, n = re.subn(
+        r'^version = ".*"$',
+        f'version = "{new_version}"',
+        text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if n == 0:
+        print(
+            f"Warning: no `version = ...` line found in {path}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    text = new_text
+
+with open(path, "w", encoding="utf-8") as fh:
+    fh.write(text)
+PY
+    then
+        echo "pyproject.toml version updated → ${FRONT_VERSION}"
+    fi
+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
+

Docs/ARCHITECTURE.md

@@ -0,0 +1,848 @@
+# 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
+|   +-- setup_service.py    # Series key resolution from folder names
+|   +-- nfo_scan_service.py # NFO creation, update, and regeneration from TMDB
+|   +-- scan_service.py     # Library rescan (episodes, missing files)
+|   +-- folder_naming_service.py # Folder rename to Title (YYYY) convention
+|   +-- scheduler/          # Scheduled tasks
+|   |   +-- scheduler_service.py # Cron-based library rescans
++-- 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 wrapper (uses ApiClient internally)
+|   +-- queue-renderer.js   # Queue DOM rendering
+|   +-- progress-handler.js # Download progress updates
+|   +-- queue-socket-handler.js # WebSocket events for queue
+|   +-- queue-init.js       # Queue page initialisation and orchestration
+```
+
+**Queue Module Public APIs:**
+
+```javascript
+// queue-api.js — wraps /api/queue/* endpoints via AniWorld.ApiClient
+AniWorld.QueueAPI.loadQueueData()          // GET /api/queue/status → queue data
+AniWorld.QueueAPI.startQueue()             // POST /api/queue/start
+AniWorld.QueueAPI.stopQueue()              // POST /api/queue/stop
+AniWorld.QueueAPI.removeFromQueue(itemId)  // DELETE /api/queue/{item_id}
+AniWorld.QueueAPI.retryDownloads(itemIds) // POST /api/queue/retry
+AniWorld.QueueAPI.clearCompleted()        // DELETE /api/queue/completed
+AniWorld.QueueAPI.clearFailed()           // DELETE /api/queue/failed
+AniWorld.QueueAPI.clearPending()           // DELETE /api/queue/pending
+
+// queue-init.js — page orchestration (imports QueueAPI internally)
+AniWorld.QueueApp.init()                  // Bootstrap; calls loadQueueData()
+AniWorld.QueueApp.loadQueueData()         // Fetch queue data and render
+AniWorld.QueueApp.startDownload()         // Start queue processing
+AniWorld.QueueApp.stopDownloads()        // Stop queue processing
+AniWorld.QueueApp.removeFromQueue(id)     // Remove single item
+AniWorld.QueueApp.retryDownload(id)       // Retry failed item
+AniWorld.QueueApp.retryAllFailed()        // Retry all failed items
+AniWorld.QueueApp.clearQueue(type)        // Clear completed|failed|pending
+```
+
+> **Module dependency rule**: Queue page modules must access API endpoints via
+> `AniWorld.QueueAPI.<method>()`. The `API` object (`AniWorld.Constants.API`) is
+> private to each module's IIFE closure and is NOT a global. Do NOT use bare
+> `fetch(API.QUEUE_STATUS, ...)` in `queue-init.js` — use
+> `AniWorld.QueueAPI.loadQueueData()` instead.
+```
+
+#### 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/server/`)
+
+Domain logic for anime series management, NFO metadata, and episode downloads.
+
+```
+src/server/
++-- SerieScanner.py         # Directory scanning, targeted single-series scan
++-- SerieList.py            # Series collection (stub; see src/server/database/SerieList.py)
++-- nfo/                    # NFO metadata generation and mapping
+|   +-- nfo_generator.py   # TVShowNFO → XML serialiser (generate_tvshow_nfo)
+|   +-- nfo_mapper.py       # TMDB API dict → TVShowNFO (tmdb_to_nfo_model,
+|   |                       #   _extract_rating_by_country, _extract_fsk_rating)
+|   +-- nfo_models.py       # Pydantic models for NFO XML (TVShowNFO, ActorInfo…)
+|   +-- tmdb_client.py     # Async TMDB API client
++-- providers/              # External provider adapters
+|   +-- base_provider.py    # Loader interface
+|   +-- provider_factory.py # Provider registry
+|   +-- aniworld_provider.py # AniWorld scraper
+|   +-- enhanced_provider.py # Multi-provider with failover
+|   +-- provider_config.py  # Provider preference configuration
+|   +-- streaming/          # Provider-specific extractors (VOE, Doodstream, etc.)
++-- entities/
+|   +-- nfo_models.py       # Domain entities for NFO (aligns with nfo/nfo_models.py)
++-- interfaces/
+|   +-- callbacks.py        # Progress callback system
+|   +-- providers.py        # Provider interface definitions
++-- exceptions/
+     +-- Exceptions.py      # Custom exceptions
+```
+
+**Key Components:**
+
+|| Component | Purpose |
+| --- | --- |
+| `SerieScanner` | Scans directories for anime; `scan_single_series()` for targeted scans |
+| `tmdb_client.py` | Async TMDB API client |
+| `nfo_generator.py` | Serialises `TVShowNFO` to XML |
+| `nfo_mapper.py` | Maps TMDB API response to `TVShowNFO` domain model |
+| `enhanced_provider.py` | Multi-provider downloader with failover chain |
+
+> **Note:** The `src/core/` directory was an earlier architectural proposal and is
+> currently empty. All domain logic lives under `src/server/`.
+
+### 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/server/providers/aniworld_provider.py](../src/server/providers/aniworld_provider.py),
+[src/server/providers/enhanced_provider.py](../src/server/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/server/providers/base_provider.py](../src/server/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/server/SerieScanner.py](../src/server/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,342 @@
+# 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-20
+
+### Added
+
+- **Delete Anime Feature** — Right-click on any anime card and select
+  "Delete Anime" to remove a series. Three modes are available:
+  database only, folder only, or both. A typed-confirmation
+  (`delete`) is required to prevent accidental deletions. The
+  operation is broadcast via WebSocket so all connected clients
+  remove the card in real-time. Path traversal protection prevents
+  folder deletion outside the anime base directory.
+  - `DELETE /api/anime/{key}` endpoint (`src/server/api/anime.py`)
+  - `AnimeService.delete_series()` orchestrator
+    (`src/server/services/anime_service.py`)
+  - `broadcast_series_deleted()` WebSocket broadcast
+    (`src/server/services/websocket_service.py`)
+  - `DeleteSeriesRequest` / `DeleteSeriesResult` Pydantic models
+    (`src/server/models/anime.py`)
+  - Frontend modal with typed confirmation
+    (`src/server/web/static/js/index/delete-modal.js`)
+  - Right-click "Delete Anime" context menu item
+    (`src/server/web/static/js/index/context-menu.js`)
+  - `SERIES_DELETED` WebSocket event handling
+    (`src/server/web/static/js/index/socket-handler.js`)
+  - `SeriesManager.removeSeries()` grid cleanup
+    (`src/server/web/static/js/index/series-manager.js`)
+  - Full test suite:
+    `tests/unit/test_delete_anime_service.py`,
+    `tests/api/test_delete_anime_endpoint.py`,
+    `tests/frontend/test_delete_modal.py`,
+    `tests/security/test_delete_anime_security.py`
+  - Documentation: `Docs/DELETE_ANIME_FEATURE.md`
+
+- **Anime Settings page** — renamed from "NFO Diagnostics". Right-click
+  on any anime card → "Anime Settings" navigates to
+  `/anime/settings?key=<series>`. The new page lets the user view and
+  edit `name`, `folder`, `tmdb_id`, `tvdb_id`, and `site` directly in
+  the database, with options to rename the on-disk folder and
+  regenerate `tvshow.nfo` in one click.
+- **New API endpoints** under `/api/anime/{key}/`:
+    - `GET  /settings` — return full editable settings payload
+    - `PUT  /settings` — update fields with validation
+    - `POST /regenerate-nfo` — regenerate `tvshow.nfo` from TMDB
+- **Pydantic models**: `AnimeSettingsResponse`,
+  `AnimeSettingsUpdateRequest`, `AnimeSettingsRegenerateNfoResponse`
+  in [src/server/models/anime.py](../src/server/models/anime.py).
+- **Frontend module**: `AniWorld.AnimeSettingsManager` IIFE in
+  [src/server/web/static/js/pages/anime-settings.js](../src/server/web/static/js/pages/anime-settings.js)
+  with public API: `init`, `loadSeries`, `saveSettings`,
+  `regenerateNfo`, `validateField`, `populateForm`, `showSaveSuccess`,
+  `showError`.
+- **Vitest JS unit tests** covering every public function on
+  `AnimeSettingsManager` — 31 tests in
+  [tests/frontend/unit/anime_settings.test.js](../tests/frontend/unit/anime_settings.test.js).
+- **Playwright E2E test** for the right-click → settings page flow in
+  [tests/frontend/e2e/anime_settings_page.spec.js](../tests/frontend/e2e/anime_settings_page.spec.js).
+
+### Changed
+
+- **Right-click context menu** on the library page: "NFO Diagnostics"
+  → "Anime Settings" (`data-action="nfo-diagnostics"` →
+  `data-action="anime-settings"`).
+- **Configuration modal link**: "Open NFO Diagnostics" → "Open Anime
+  Settings", target URL `/settings/nfo` → `/anime/settings`.
+- **Page route**: `/settings/nfo` returns a 301 redirect to
+  `/anime/settings` for backwards compatibility with bookmarks.
+- **Pydantic model rename** in [src/server/models/nfo.py](../src/server/models/nfo.py):
+    - `NfoDiagnosticsResponse` → `NfoSettingsResponse`
+    - `NfoSeriesDiagnostics` → `NfoSeriesSettings`
+- **Function rename** in [src/server/api/nfo.py](../src/server/api/nfo.py):
+    - `get_nfo_diagnostics` → `get_nfo_settings`
+    - `repair_nfo` → `repair_nfo_settings`
+
+### Fixed
+
+- **Queue view blank after adding items**: `queue-init.js`'s `loadQueueData()` called
+  `API.QUEUE_STATUS` directly, but `API` is a local variable inside
+  `AniWorld.QueueAPI`'s IIFE — not accessible globally. Items added to the
+  queue were persisted server-side but the queue page could not fetch them,
+  leaving the view empty with an `API is not defined` console error. Fixed by
+  replacing the inline `fetch` with `AniWorld.QueueAPI.loadQueueData()`, which
+  already exists and correctly accesses the endpoint through its own closure.
+  The same file already uses `AniWorld.QueueAPI.*` for all other queue
+  operations (`startQueue`, `stopQueue`, `removeFromQueue`, etc.).
+
+- **Bug**: `src/server/api/nfo.py` called the non-existent
+  `anime_service.update_series_nfo_status(...)` method, which would
+  raise `AttributeError` after a successful NFO repair. Renamed the
+  call to the existing `update_nfo_status(...)` method (matching its
+  signature `(key, has_nfo, tmdb_id=None, tvdb_id=None, db=None)`)
+  and added an explicit `AnimeSeriesService.update(db, id, nfo_path=...)`
+  call to keep `nfo_path` in sync. Covered by regression tests in
+  `TestBugFixCreateOrUpdateNfo`.
+
+- **Bug**: Right-clicking a series card and choosing "Anime Settings"
+  opened `/anime/settings?key=null` instead of carrying the series key.
+  Root cause: the click handler in
+  [src/server/web/static/js/index/context-menu.js](../src/server/web/static/js/index/context-menu.js)
+  called `hide()` BEFORE building the URL — and `hide()` cleared
+  `currentSeriesKey` to null. Fix captures the key into a local
+  `const` before calling `hide()`. Regression-locked by
+  `tests/frontend/unit/context_menu.test.js` (5 tests).
+
+---
+
+## [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/server/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.
+- **Temp file cleanup after every download** (`src/server/providers/aniworld_provider.py`,
+  `src/server/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 (`src/server/nfo/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/server/nfo/nfo_mapper.py`**: New module containing
+  `tmdb_to_nfo_model()`, `_extract_rating_by_country()`, and
+  `_extract_fsk_rating()`. Extracted to keep files under 500 lines and isolate
+  pure mapping logic.
+- **`src/server/nfo/nfo_generator.py`**: XML serialiser for NFO files
+  (`generate_tvshow_nfo`).
+- **US MPAA rating**: `_extract_rating_by_country(ratings, "US")` now maps the
+  US TMDB content rating to the `<mpaa>` NFO tag.
+- **`NfoScanService` (`src/server/services/nfo_scan_service.py`)**: New service
+  that detects incomplete `tvshow.nfo` files and regenerates them from TMDB.
+  Provides `scan_all()`, `_scan_series()`, `_create_nfo()`,
+  `_update_nfo_if_needed()`, and `_regenerate_nfo()`. 17 NFO tags are written.
+- **`ScanService` (`src/server/services/scan_service.py`)**: New service for
+  library rescans — detects new and removed episode files and syncs the
+  `episodes` table accordingly.
+- **`FolderNamingService` (`src/server/services/folder_naming_service.py`)**:
+  Renames series folders to the `Title (YYYY)` convention using the year from
+  `tvshow.nfo`. Prevents double-year accumulation on repeated runs.
+
+### Changed
+
+- `src/server/nfo/nfo_mapper.py` and `src/server/nfo/nfo_generator.py`
+  replaced the monolithic NFO logic from the previous service.
+- NFO generation moved to `src/server/nfo/nfo_generator.py`.
+
+---
+
+## [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/config_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/DELETE_ANIME_FEATURE.md

@@ -0,0 +1,179 @@
+# Delete Anime Feature
+
+## Overview
+
+The Delete Anime feature allows authenticated users to remove an anime series from the Aniworld library. It supports three deletion modes: **database only**, **folder only**, or **both**. A mandatory typed-confirmation (`delete`) prevents accidental deletions.
+
+---
+
+## Usage
+
+### How to Delete an Anime
+
+1. **Right-click** on any anime series card in the library grid.
+2. Select **"Delete Anime"** from the context menu.
+3. A confirmation modal appears with two options:
+   - ☑️ **Remove from database** (recommended) — removes series and episodes from SQLite
+   - ☐ **Delete folder from filesystem** — deletes the folder and all files inside
+4. **Type `delete`** in the confirmation text field to enable the Delete button.
+5. Click **Delete** to proceed.
+
+### What Gets Deleted
+
+| Option | Effect |
+|--------|--------|
+| Database only | Series, episodes, and queue entries removed from SQLite. Folder on disk is preserved. Downloaded episode files remain. |
+| Folder only | Entire folder and all files inside deleted from filesystem. Database record preserved with `is_downloaded=True`. |
+| Both | Full removal: database record deleted AND folder/files deleted from disk. |
+
+---
+
+## Architecture
+
+### Backend Components
+
+| File | Role |
+|------|------|
+| `src/server/api/anime.py` | `DELETE /api/anime/{key}` endpoint |
+| `src/server/services/anime_service.py` | `AnimeService.delete_series()` orchestrator |
+| `src/server/services/websocket_service.py` | `broadcast_series_deleted()` for real-time UI updates |
+| `src/server/database/service.py` | `AnimeSeriesService.get_folder_path()` + existing `delete()` |
+| `src/server/models/anime.py` | `DeleteSeriesRequest` / `DeleteSeriesResult` Pydantic models |
+
+### Frontend Components
+
+| File | Role |
+|------|------|
+| `src/server/web/static/js/index/delete-modal.js` | Modal UI, confirm text validation, API calls |
+| `src/server/web/static/js/index/context-menu.js` | Right-click "Delete Anime" menu item |
+| `src/server/web/static/js/index/socket-handler.js` | `SERIES_DELETED` WebSocket event handler |
+| `src/server/web/static/js/index/series-manager.js` | `removeSeries(key)` — removes card from grid |
+| `src/server/web/static/js/index/app-init.js` | Initializes `DeleteModal` |
+| `src/server/web/static/css/components/modals.css` | Modal and context menu styles |
+| `src/server/web/templates/index.html` | Loads `delete-modal.js` before `app-init.js` |
+
+### API Endpoint
+
+```
+DELETE /api/anime/{key}
+```
+
+**Request body:**
+```json
+{
+    "delete_database": true,
+    "delete_folder": false,
+    "confirm_text": "delete"
+}
+```
+
+**Success response (200):**
+```json
+{
+    "success": true,
+    "key": "attack-on-titan",
+    "name": "Attack on Titan",
+    "deleted_from_database": true,
+    "deleted_folder": false,
+    "folder_path": null,
+    "database_error": null,
+    "folder_error": null,
+    "message": "Removed from database."
+}
+```
+
+**Error responses:**
+| Status | Condition |
+|--------|-----------|
+| 400 | `confirm_text != "delete"` or neither flag is `true` |
+| 401 | Not authenticated |
+| 404 | Series `key` not found in database |
+| 500 | Unexpected server error |
+
+### WebSocket Event
+
+After a successful delete, the server broadcasts a `series_deleted` event:
+
+```json
+{
+    "type": "series_deleted",
+    "data": {
+        "key": "attack-on-titan",
+        "name": "Attack on Titan"
+    }
+}
+```
+
+All connected clients remove the card from their grid in real-time.
+
+---
+
+## Safety Mechanisms
+
+### 1. Typed Confirmation
+Users must type exactly `delete` (case-sensitive) to unlock the Delete button. This prevents accidental clicks from triggering deletion.
+
+### 2. Path Traversal Protection
+Before deleting a folder, `is_safe_path()` validates the path stays within the configured anime base directory. Paths outside this boundary are rejected with a `folder_error`.
+
+### 3. Granular Options
+The two independent checkboxes ensure users consciously choose what to delete. Default is **database only** (recommended).
+
+### 4. WebSocket Broadcast
+All clients are notified immediately when a series is deleted, keeping multiple browser sessions in sync.
+
+### 5. No Shell Injection
+Series keys are never passed to shell commands. All file operations use `pathlib.Path`.
+
+---
+
+## Logging
+
+### Backend Logs (Python/`logging`)
+
+| Event | Level | Message |
+|-------|-------|---------|
+| Delete initiated | INFO | `Delete anime initiated: key={key} delete_db={x} delete_folder={x}` |
+| Series not found | WARNING | `Delete anime failed — series not found: key={key}` |
+| Path traversal attempt | WARNING | `Delete anime blocked — path traversal attempt: key={key} path={path}` |
+| DB error | ERROR | `Delete anime DB error: key={key} error={message}` |
+| Folder delete error | ERROR | `Delete anime folder error: key={key} error={message}` |
+| Delete succeeded | INFO | `Delete anime succeeded: key={key} deleted_db={x} deleted_folder={x}` |
+
+### Frontend Logs (JS/`console`)
+
+| Event | Method |
+|-------|--------|
+| Modal opened | `console.info('[DeleteModal] Opening for key:', key)` |
+| Delete confirmed | `console.info('[DeleteModal] Initiating delete:', {...})` |
+| Delete succeeded | `console.info('[DeleteModal] Delete succeeded:', result)` |
+| API/network error | `console.error('[DeleteModal] Delete request failed:', err)` |
+| Series removed from grid | `console.info('[SeriesManager] Removed series from local state:', key)` |
+| WS event received | `console.info('[SocketHandler] Series deleted:', data)` |
+
+---
+
+## Configuration
+
+No new configuration options are required. The feature uses existing paths:
+- **Anime base directory**: `settings.anime_directory` (for path traversal validation)
+- **Database path**: `series_app.database_path` (for DB deletion)
+- **Queue cleanup**: `AnimeSeriesService.delete(series_key)` cascades to queue items
+
+---
+
+## Testing
+
+See:
+- `tests/unit/test_delete_anime_service.py` — unit tests for `AnimeService.delete_series()`
+- `tests/api/test_delete_anime_endpoint.py` — API endpoint tests including auth, validation, error cases
+- `tests/frontend/test_delete_modal.py` — frontend modal logic and DOM validation tests
+- `tests/security/test_delete_anime_security.py` — security tests for path traversal, XSS, auth bypass
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-08-16 | Feature added. `DELETE /api/anime/{key}`, right-click context menu, typed-confirmation modal, WebSocket sync. |

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/NAVIGATION.md

@@ -0,0 +1,234 @@
+# Navigation & Redirect Logic
+
+This document describes the setup flow navigation, covering how users progress from initial setup through to the main application.
+
+## Overview
+
+The application uses a middleware-based redirect system to enforce a strict state machine. Users must complete each phase before accessing the next. Attempting to bypass the current phase redirects to the appropriate page.
+
+## State Machine
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         NAVIGATION STATES                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  NO_SETUP ──────────► SETUP_COMPLETE ──────────► UNRESOLVED_PENDING    │
+│       │                     │                         │                 │
+│       │                     │                         │                 │
+│       ▼                     ▼                         ▼                 │
+│   /setup               /loading                   /setup/unresolved     │
+│                       (series scan)               (resolve folders)     │
+│                                                                          │
+│                                                  UNRESOLVED_DONE ───────┐
+│                                                       │                  │
+│                                                       ▼                  │
+│                                              NFO_SCAN_PENDING           │
+│                                                       │                  │
+│                                                       ▼                  │
+│                                                  /loading                │
+│                                                  (NFO scan)              │
+│                                                       │                  │
+│                                                       ▼                  │
+│                                                 COMPLETE                 │
+│                                                       │                  │
+│                                                       ▼                  │
+│                                                    /login                │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## State Definitions
+
+| State | Condition | Target Page |
+|-------|-----------|-------------|
+| `NO_SETUP` | No master password configured | `/setup` |
+| `SETUP_COMPLETE` | Initial config passed, loading not started | `/loading` |
+| `UNRESOLVED_PENDING` | Setup done, unresolved exist, not marked done | `/setup/unresolved` |
+| `UNRESOLVED_DONE` | Unresolved phase marked complete, NFO scan pending | `/loading` |
+| `NFO_SCAN_PENDING` | Unresolved done, NFO scan incomplete | `/loading` |
+| `COMPLETE` | All phases finished | `/login` |
+
+## Middleware: SetupRedirectMiddleware
+
+**File:** `src/server/middleware/setup_redirect.py`
+
+The middleware intercepts all requests and enforces the state machine.
+
+### Exempt Paths (always accessible)
+
+| Path | Purpose |
+|------|---------|
+| `/setup` | Initial setup page |
+| `/setup/unresolved` | Unresolved folder resolution |
+| `/loading` | Initialization progress page |
+| `/login` | Authentication |
+| `/api/auth/*` | Auth endpoints |
+| `/api/config/*` | Config API |
+| `/api/health` | Health check |
+| `/static/*` | Static assets |
+
+### Middleware Logic
+
+The middleware checks the current state and redirects accordingly:
+
+```
+1. NO_SETUP state:
+   → Redirect ALL requests to /setup
+   → Exception: /setup itself is accessible
+
+2. SETUP_COMPLETE state:
+   → Redirect /setup to /loading
+   → Redirect any other page to /loading
+
+3. UNRESOLVED_PENDING state (unresolved folders exist, not marked done):
+   → Redirect /setup to /setup/unresolved
+   → Redirect /loading to /setup/unresolved
+   → Allow access to /setup/unresolved
+   → Redirect any other page to /setup/unresolved
+
+4. UNRESOLVED_DONE state (unresolved marked done, NFO scan pending):
+   → Redirect /setup to /loading
+   → Redirect /setup/unresolved to /loading
+   → Redirect any other page to /loading
+
+5. NFO_SCAN_PENDING state:
+   → Redirect /setup to /loading
+   → Redirect /setup/unresolved to /loading
+   → Allow access to /loading (NFO phase runs)
+   → Redirect any other page to /loading
+
+6. COMPLETE state (loading finished):
+   → Redirect /setup, /loading, /setup/unresolved to /login
+   → Allow access to /login and main app
+```
+
+### Phase Tracking Flags
+
+| Flag | Purpose |
+|------|---------|
+| `setup_complete` | Initial configuration was saved |
+| `loading_started` | Loading phase has been initiated (redirected to /loading) |
+| `unresolved_completed` | User clicked "Done" on unresolved page |
+| `loading_complete` | Series scan + initial loading finished |
+| `nfo_scan_complete` | Final NFO scan finished |
+
+## Pages
+
+### 1. Setup Page (`/setup`)
+
+**File:** `src/server/web/templates/setup.html`
+
+Handles initial configuration:
+- Master password creation
+- Anime directory selection
+- Database initialization
+
+**Allowed in states:** `NO_SETUP`
+
+**Post-completion:**
+- Sets `setup_complete` flag
+- Redirects to `/loading`
+
+### 2. Loading Page (`/loading`)
+
+**File:** `src/server/web/templates/loading.html`
+
+Shows initialization progress via WebSocket:
+- Series scanning
+- Database population
+- Logo/image loading
+
+**Allowed in states:** `SETUP_COMPLETE`, `UNRESOLVED_DONE`, `NFO_SCAN_PENDING`
+
+**Post-initialization (series scan complete):**
+```javascript
+async function checkUnresolvedAndProceed() {
+    const res = await fetch('/api/setup/unresolved', {
+        headers: { 'Authorization': `Bearer ${token}` }
+    });
+    const folders = await res.json();
+    
+    if (folders.length > 0) {
+        window.location.href = '/setup/unresolved';
+    } else {
+        window.location.href = '/login';
+    }
+}
+```
+
+**Post-NFO scan:**
+- Sets `nfo_scan_complete` flag
+- Redirects to `/login`
+
+### 3. Unresolved Folders Page (`/setup/unresolved`)
+
+**File:** `src/server/web/templates/unresolved.html`
+
+Allows manual resolution of folders that couldn't be auto-matched:
+- Shows list of unresolved folders
+- Provides search suggestions
+- Input field for entering provider key
+- Resolve/delete actions
+- **Done button** to complete the phase without resolving all folders
+
+**Allowed in states:** `UNRESOLVED_PENDING`
+
+**Done button behavior:**
+- Sets `unresolved_completed` flag
+- Redirects to `/loading` for final NFO scan
+
+**After completion:**
+- Any access redirects to `/loading`
+
+### 4. Login Page (`/login`)
+
+**File:** `src/server/web/templates/login.html`
+
+Authentication page. After successful login → redirect to `/` (main app).
+
+**Allowed in states:** `COMPLETE`
+
+## API Endpoints
+
+### Unresolved Folders API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/setup/unresolved` | List all unresolved folders |
+| `GET` | `/api/setup/unresolved/{folder_name}` | Get specific folder details |
+| `POST` | `/api/setup/unresolved/{folder_name}/resolve` | Resolve with provider key |
+| `POST` | `/api/setup/unresolved/{folder_name}/search` | Re-search for matches |
+| `DELETE` | `/api/setup/unresolved/{folder_name}` | Remove folder from tracking |
+| `POST` | `/api/setup/unresolved/done` | Mark unresolved phase as complete |
+
+### Auth API
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/auth/setup` | Create master password |
+| `POST` | `/api/auth/login` | Authenticate |
+| `POST` | `/api/auth/logout` | End session |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/server/middleware/setup_redirect.py` | Redirect middleware (state machine) |
+| `src/server/controllers/page_controller.py` | Page route handlers |
+| `src/server/web/templates/setup.html` | Setup template |
+| `src/server/web/templates/loading.html` | Loading template |
+| `src/server/web/templates/unresolved.html` | Unresolved folders template |
+| `src/server/api/setup_endpoints.py` | Unresolved folders API |
+| `src/server/database/service.py` | UnresolvedFolderService |
+
+## Navigation Summary
+
+| Current State | Access `/setup` | Access `/loading` | Access `/setup/unresolved` |
+|--------------|-----------------|-------------------|---------------------------|
+| NO_SETUP | ✅ Allowed | ❌ → `/setup` | ❌ → `/setup` |
+| SETUP_COMPLETE | ❌ → `/loading` | ✅ Allowed | ❌ → `/loading` |
+| UNRESOLVED_PENDING | ❌ → `/setup/unresolved` | ❌ → `/setup/unresolved` | ✅ Allowed |
+| UNRESOLVED_DONE | ❌ → `/loading` | ✅ Allowed (NFO phase) | ❌ → `/loading` |
+| NFO_SCAN_PENDING | ❌ → `/loading` | ✅ Allowed (NFO phase) | ❌ → `/loading` |
+| COMPLETE | ❌ → `/login` | ❌ → `/login` | ❌ → `/login` |

Docs/NFO_GUIDE.md

@@ -0,0 +1,891 @@
+# 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 customise NFO generation by modifying `src/server/nfo/nfo_generator.py`:
+
+```python
+# src/server/nfo/nfo_generator.py
+def generate_tvshow_nfo(metadata: TVShowNFO) -> 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/server/nfo/nfo_mapper.py` (`tmdb_to_nfo_model`).
+The XML serialisation lives in `src/server/nfo/nfo_generator.py`
+(`generate_tvshow_nfo`).
+
+---
+
+## 11. Automatic NFO Repair
+
+NFO repair runs as part of the scheduled daily scan via ``SchedulerService``.
+When the scheduler fires, it calls ``_run_nfo_scan()`` which delegates to
+``NfoScanService.scan_all()``. This detects series whose ``tvshow.nfo`` is
+missing required tags and regenerates them from TMDB.
+
+### How It Works
+
+1. **Scheduler** fires the daily job (``SchedulerService._run_nfo_scan()``)
+2. **Detect** — ``NfoScanService._scan_series()`` parses each ``tvshow.nfo``
+   and calls ``_create_nfo()`` / ``_update_nfo_if_needed()`` /
+   ``_regenerate_nfo()`` to fill missing tags from TMDB
+3. **Repair** — If TMDB lookup succeeds, the NFO is overwritten with complete
+   data; if it fails, the original is kept and the failure is logged
+
+### Tags Written / Updated
+
+The NFO scan writes all 17 tags listed in the
+[Tag Reference](#10-tag-reference) above. Missing or empty tags trigger a
+regeneration from TMDB.
+
+### Log Messages
+
+|| Message | Meaning |
+| --- | --- |
+| `NFO scan complete: N series processed` | Scan finished normally |
+| `NFO scan skipped: TMDB API key not configured` | ``tmdb_api_key`` is empty — set it in ``data/config.json`` |
+| `NFO scan skipped: anime directory not configured` | ``anime_directory`` is not set |
+
+### Manual Repair
+
+You can repair a single series on demand via the API:
+
+```http
+POST /api/nfo/{series_key}/create
+```
+
+or update with fresh TMDB data:
+
+```http
+POST /api/nfo/{series_key}/update
+```
+
+### Source Files
+
+|| File | Purpose |
+| --- | --- |
+| ``src/server/services/scheduler/scheduler_service.py`` | ``SchedulerService._run_nfo_scan()`` — entry point called by the scheduler |
+| ``src/server/services/nfo_scan_service.py`` | ``NfoScanService.scan_all()`` — detects incomplete NFOs and regenerates them |
+| ``src/server/services/scan_service.py`` | ``ScanService`` — library rescan (episodes, missing files) |
+| ``src/server/services/folder_naming_service.py`` | ``FolderNamingService`` — renames folders to ``Title (YYYY)`` format |
+
+---
+
+## 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,75 @@
+
+### Testing FolderNamingService
+
+FolderNamingService fixes missing years in anime folder names after NFO refresh. Test file: `tests/unit/test_folder_naming_service.py`.
+
+Key methods tested:
+- `_build_target_folder()` — constructs safe "Title (YYYY)" names, strips existing year suffix first (prevents double-year like "Naruto (1999) (1999)")
+- `_folder_has_year()` — detects existing `(YYYY)` pattern
+- `_extract_year_from_folder_name()` — parses `(YYYY)` suffix
+- `_extract_title_from_folder_name()` — strips year suffix
+
+```python
+# Safe: repeated calls never accumulate years
+r1 = FolderNamingService._build_target_folder("Naruto", 1999)
+r2 = FolderNamingService._build_target_folder(r1, 1999)
+assert r1 == r2 == "Naruto (1999)"
+
+# Safe: existing year is replaced, not appended
+result = FolderNamingService._build_target_folder("Naruto (2020)", 1999)
+assert result == "Naruto (1999)"
+assert "2020" not in result
+```
+
+The service is also tested end-to-end with mocked filesystem and database:
+- Renames folder and updates DB when year is missing from folder name
+- Skips rename when folder already has a year
+- Skips rename when DB has no year
+- Skips when target folder already exists on disk
+- Safety guard detects and skips if target folder year mismatches DB year
+
+### 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,119 @@
+# 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
+- **Delete Anime**: Right-click any anime card → "Delete Anime" to remove a series from the database, filesystem, or both. Type `delete` in the confirmation field to proceed. See [Delete Anime Feature](./DELETE_ANIME_FEATURE.md) for details.
+
+## 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
+- **Queue Processing Order**: Items processed in user-defined order via drag-and-drop reordering (`POST /api/queue/reorder`)
+- **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,8 @@
+API key : 299ae8f630a31bda814263c551361448
+9bc3e547caff878615cbdba2cc421d37
+
+/setup
+
+
+SeriesApp initialized for directory:
+to remove:

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" }, $"{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.");

Makefile

@@ -0,0 +1,24 @@
+.PHONY: up down clean browser-clean setup test-robot
+
+up:
+	python run_server.py
+
+down:
+	pkill -f "uvicorn src.server.fastapi_app:app" || pkill -f "python.*run_server.py" || true
+
+clean:
+	rm -rf data/*.db data/*.db-shm data/*.db-wal data/config.json
+
+browser-clean:
+	rm -rf "$$HOME/.cache/microsoft-edge"/* || true
+	rm -rf "$$HOME/.cache/mozilla/firefox"/* || true
+	find "$$HOME/.mozilla/firefox" -name "cache2" -type d -exec rm -rf {} \; 2>/dev/null || true
+
+setup:
+	curl -X POST http://127.0.0.1:8000/setup \
+		-H "Content-Type: application/json" \
+		-H "X-API-Key: 299ae8f630a31bda814263c551361448" \
+		-d '{"path": "/home/lukas/Volume/serien/", "password": "Hallo123!"}'
+
+test-robot:
+	bash tests/robot/run.sh

README.md

@@ -1,70 +1,202 @@
-# AniWorld - Anime Download and Management System
+# Aniworld Download Manager
 
-A comprehensive anime download and management system with web interface and CLI support.
+A web-based anime download manager with REST API, WebSocket real-time updates, and a modern web interface.
 
-## Project Structure
+## Features
 
-This project follows Clean Architecture principles with clear separation of concerns:
-
-### Core (`src/server/core/`)
-- **entities/**: Domain entities (Series, Episodes, etc.)
-- **interfaces/**: Domain interfaces and contracts
-- **use_cases/**: Business use cases and logic
-- **exceptions/**: Domain-specific exceptions
-
-### Infrastructure (`src/server/infrastructure/`)
-- **database/**: Database layer and repositories
-- **providers/**: Anime and streaming providers
-- **file_system/**: File system operations
-- **external/**: External integrations
-- **caching/**: Caching implementations
-- **logging/**: Logging infrastructure
-
-### Application (`src/server/application/`)
-- **services/**: Application services
-- **dto/**: Data Transfer Objects
-- **validators/**: Input validation
-- **mappers/**: Data mapping
-
-### Web (`src/server/web/`)
-- **controllers/**: Flask blueprints and API endpoints
-- **middleware/**: Web middleware
-- **templates/**: Jinja2 templates
-- **static/**: CSS, JavaScript, and images
-
-### Shared (`src/server/shared/`)
-- **constants/**: Application constants
-- **utils/**: Utility functions
-- **decorators/**: Custom decorators
-- **middleware/**: Shared middleware
+- 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
 
-1. **Setup Environment:**
-   ```bash
-   conda activate AniWorld
-   set ANIME_DIRECTORY="\\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien"
-   cd src\server
-   ```
+### Prerequisites
 
-2. **Run the Web Application:**
-   ```bash
-   python app.py
-   ```
+- Python 3.10+
+- Conda (recommended) or virtualenv
 
-3. **Run CLI Commands:**
-   ```bash
-   cd src
-   python main.py
-   ```
+### Installation
 
-## Development
+1. Clone the repository:
 
-- **Documentation**: See `docs/` directory
-- **Tests**: See `tests/` directory
-- **Configuration**: See `config/` directory
-- **Data**: Application data in `data/` directory
+```bash
+git clone https://github.com/your-repo/aniworld.git
+cd aniworld
+```
 
-## Architecture
+2. Create and activate conda environment:
 
-The application uses Clean Architecture with dependency injection and clear layer boundaries. Each layer has specific responsibilities and depends only on inner layers.
+```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

aniworld/pyvenv.cfg

@@ -1,5 +0,0 @@
-home = /usr/bin
-include-system-site-packages = false
-version = 3.12.3
-executable = /usr/bin/python3.12
-command = /usr/bin/python3 -m venv /mnt/d/repo/AniWorld/aniworld

config.json

@@ -1,49 +0,0 @@
-{
-    "security": {
-        "master_password_hash": "bb202031f646922388567de96a784074272efbbba9eb5d2259e23af04686d2a5",
-        "salt": "c3149a46648b4394410b415ea654c31731b988ee59fc91b8fb8366a0b32ef0c1",
-        "session_timeout_hours": 24,
-        "max_failed_attempts": 5,
-        "lockout_duration_minutes": 30
-    },
-    "anime": {
-        "directory": "\\\\sshfs.r\\ubuntu@192.168.178.43\\media\\serien\\Serien",
-        "download_threads": 3,
-        "download_speed_limit": null,
-        "auto_rescan_time": "03:00",
-        "auto_download_after_rescan": false
-    },
-    "logging": {
-        "level": "INFO",
-        "enable_console_logging": true,
-        "enable_console_progress": false,
-        "enable_fail2ban_logging": true,
-        "log_file": "aniworld.log",
-        "max_log_size_mb": 10,
-        "log_backup_count": 5
-    },
-    "providers": {
-        "default_provider": "aniworld.to",
-        "preferred_language": "German Dub",
-        "fallback_providers": [
-            "aniworld.to"
-        ],
-        "provider_timeout": 30,
-        "retry_attempts": 3,
-        "provider_settings": {
-            "aniworld.to": {
-                "enabled": true,
-                "priority": 1,
-                "quality_preference": "720p"
-            }
-        }
-    },
-    "advanced": {
-        "max_concurrent_downloads": 3,
-        "download_buffer_size": 8192,
-        "connection_timeout": 30,
-        "read_timeout": 300,
-        "enable_debug_mode": false,
-        "cache_duration_minutes": 60
-    }
-}

config/development/config.json

@@ -1,44 +0,0 @@
-{
-    "database": {
-        "url": "sqlite:///data/database/anime_dev.db",
-        "pool_size": 5,
-        "max_overflow": 10,
-        "echo": true
-    },
-    "redis": {
-        "url": "redis://localhost:6379/1",
-        "socket_timeout": 10,
-        "socket_connect_timeout": 10,
-        "max_connections": 10
-    },
-    "logging": {
-        "level": "DEBUG",
-        "format": "detailed",
-        "log_to_file": true,
-        "log_to_console": true
-    },
-    "security": {
-        "session_timeout": 86400,
-        "csrf_enabled": false,
-        "secure_cookies": false,
-        "debug_mode": true
-    },
-    "performance": {
-        "cache_timeout": 300,
-        "enable_compression": false,
-        "debug_toolbar": true
-    },
-    "downloads": {
-        "max_concurrent": 3,
-        "timeout": 1800,
-        "retry_attempts": 2,
-        "download_path": "data/temp/downloads",
-        "temp_path": "data/temp"
-    },
-    "development": {
-        "auto_reload": true,
-        "debug_mode": true,
-        "profiler_enabled": true,
-        "mock_external_apis": false
-    }
-}

config/docker/development.env

@@ -1,28 +0,0 @@
-# Development Environment Variables
-FLASK_ENV=development
-DEBUG=True
-
-# Database
-DATABASE_URL=sqlite:///data/database/anime_dev.db
-
-# Redis
-REDIS_URL=redis://redis:6379/1
-
-# Security
-SECRET_KEY=dev-secret-key
-SESSION_TIMEOUT=86400
-
-# Logging
-LOG_LEVEL=DEBUG
-LOG_FORMAT=detailed
-
-# Performance
-CACHE_TIMEOUT=300
-
-# Downloads
-DOWNLOAD_PATH=/app/data/temp/downloads
-MAX_CONCURRENT_DOWNLOADS=3
-
-# Development
-AUTO_RELOAD=true
-DEBUG_TOOLBAR=true

config/docker/production.env

@@ -1,31 +0,0 @@
-# Production Environment Variables
-FLASK_ENV=production
-DEBUG=False
-
-# Database
-DATABASE_URL=postgresql://aniworld:password@postgres:5432/aniworld_prod
-DATABASE_POOL_SIZE=20
-
-# Redis
-REDIS_URL=redis://redis:6379/0
-
-# Security
-SECRET_KEY=change-this-in-production
-SESSION_TIMEOUT=3600
-CSRF_TOKEN_TIMEOUT=3600
-
-# Logging
-LOG_LEVEL=INFO
-LOG_FORMAT=json
-
-# Performance
-CACHE_TIMEOUT=3600
-MAX_WORKERS=4
-
-# Downloads
-DOWNLOAD_PATH=/app/downloads
-MAX_CONCURRENT_DOWNLOADS=10
-
-# Monitoring
-HEALTH_CHECK_ENABLED=true
-METRICS_ENABLED=true

config/docker/testing.env

@@ -1,28 +0,0 @@
-# Testing Environment Variables
-FLASK_ENV=testing
-DEBUG=False
-TESTING=True
-
-# Database
-DATABASE_URL=sqlite:///data/database/anime_test.db
-
-# Redis
-REDIS_URL=redis://redis:6379/2
-
-# Security
-SECRET_KEY=test-secret-key
-WTF_CSRF_ENABLED=False
-
-# Logging
-LOG_LEVEL=WARNING
-
-# Performance
-CACHE_TIMEOUT=60
-
-# Downloads
-DOWNLOAD_PATH=/app/data/temp/test_downloads
-MAX_CONCURRENT_DOWNLOADS=1
-
-# Testing
-MOCK_EXTERNAL_APIS=true
-FAST_MODE=true

config/production/config.json

@@ -1,50 +0,0 @@
-{
-    "database": {
-        "url": "postgresql://user:password@localhost/aniworld_prod",
-        "pool_size": 20,
-        "max_overflow": 30,
-        "pool_timeout": 30,
-        "pool_recycle": 3600
-    },
-    "redis": {
-        "url": "redis://redis-prod:6379/0",
-        "socket_timeout": 5,
-        "socket_connect_timeout": 5,
-        "retry_on_timeout": true,
-        "max_connections": 50
-    },
-    "logging": {
-        "level": "INFO",
-        "format": "json",
-        "file_max_size": "50MB",
-        "backup_count": 10,
-        "log_to_file": true,
-        "log_to_console": false
-    },
-    "security": {
-        "session_timeout": 3600,
-        "csrf_enabled": true,
-        "secure_cookies": true,
-        "max_login_attempts": 5,
-        "login_lockout_duration": 900
-    },
-    "performance": {
-        "cache_timeout": 3600,
-        "enable_compression": true,
-        "max_request_size": "16MB",
-        "request_timeout": 30
-    },
-    "downloads": {
-        "max_concurrent": 10,
-        "timeout": 3600,
-        "retry_attempts": 3,
-        "download_path": "/app/downloads",
-        "temp_path": "/app/temp"
-    },
-    "monitoring": {
-        "health_check_interval": 60,
-        "metrics_enabled": true,
-        "performance_monitoring": true,
-        "error_reporting": true
-    }
-}

config/testing/config.json

@@ -1,40 +0,0 @@
-{
-    "database": {
-        "url": "sqlite:///data/database/anime_test.db",
-        "pool_size": 1,
-        "echo": false
-    },
-    "redis": {
-        "url": "redis://localhost:6379/2",
-        "socket_timeout": 5,
-        "max_connections": 5
-    },
-    "logging": {
-        "level": "WARNING",
-        "format": "simple",
-        "log_to_file": false,
-        "log_to_console": true
-    },
-    "security": {
-        "session_timeout": 3600,
-        "csrf_enabled": false,
-        "secure_cookies": false,
-        "testing": true
-    },
-    "performance": {
-        "cache_timeout": 60,
-        "enable_compression": false
-    },
-    "downloads": {
-        "max_concurrent": 1,
-        "timeout": 30,
-        "retry_attempts": 1,
-        "download_path": "data/temp/test_downloads",
-        "temp_path": "data/temp/test"
-    },
-    "testing": {
-        "mock_external_apis": true,
-        "fast_mode": true,
-        "cleanup_after_tests": true
-    }
-}

docker/Dockerfile

@@ -1,62 +0,0 @@
-# Use an official Python runtime as a parent image
-FROM python:3.11-slim
-
-# Set environment variables
-ENV PYTHONUNBUFFERED=1 \
-    PYTHONDONTWRITEBYTECODE=1 \
-    PIP_NO_CACHE_DIR=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
-
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
-    gcc \
-    sqlite3 \
-    curl \
-    wget \
-    && rm -rf /var/lib/apt/lists/*
-
-# Create app user for security
-RUN groupadd -r aniworld && useradd -r -g aniworld aniworld
-
-# Set the working directory inside the container
-WORKDIR /app
-
-# Copy requirements first for better Docker layer caching
-COPY requirements.txt .
-
-# Install Python dependencies
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application code
-COPY src/ ./src/
-COPY main.py .
-COPY Loader.py .
-COPY *.md ./
-
-# Create necessary directories
-RUN mkdir -p /app/data /app/logs /app/backups /app/temp && \
-    chown -R aniworld:aniworld /app
-
-# Copy configuration and scripts (if they exist)
-COPY docker ./docker
-
-# Set default environment variables
-ENV ANIME_DIRECTORY="/app/data" \
-    DATABASE_PATH="/app/data/aniworld.db" \
-    LOG_LEVEL="INFO" \
-    FLASK_ENV="production" \
-    WEB_HOST="0.0.0.0" \
-    WEB_PORT="5000"
-
-# Expose the web server port
-EXPOSE 5000
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:5000/api/health/system || exit 1
-
-# Switch to non-root user
-USER aniworld
-
-# Default command - run web server
-CMD ["python", "src/server/app.py"]

docker/Dockerfile.dev

@@ -1,39 +0,0 @@
-# Development Dockerfile
-FROM python:3.11-slim
-
-# Set environment variables
-ENV PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONUNBUFFERED=1 \
-    FLASK_ENV=development \
-    FLASK_DEBUG=1
-
-# Set work directory
-WORKDIR /app
-
-# Install system dependencies
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends \
-    gcc \
-    g++ \
-    libc6-dev \
-    libffi-dev \
-    libssl-dev \
-    curl \
-    git \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install Python dependencies
-COPY requirements.txt requirements-dev.txt ./
-RUN pip install --no-cache-dir -r requirements-dev.txt
-
-# Copy project
-COPY . .
-
-# Create necessary directories
-RUN mkdir -p data/database data/logs data/cache data/temp/downloads
-
-# Expose port
-EXPOSE 5000
-
-# Development command
-CMD ["python", "src/server/app.py"]

docker/docker-compose.dev.yml

@@ -1,52 +0,0 @@
-version: '3.8'
-
-services:
-  app:
-    build:
-      context: ..
-      dockerfile: docker/Dockerfile.dev
-    ports:
-      - "5000:5000"
-    volumes:
-      - ../src:/app/src
-      - ../data:/app/data
-      - ../tests:/app/tests
-      - ../config:/app/config
-    environment:
-      - FLASK_ENV=development
-      - FLASK_DEBUG=1
-      - DATABASE_URL=sqlite:///data/database/anime.db
-      - REDIS_URL=redis://redis:6379/0
-    depends_on:
-      - redis
-    networks:
-      - aniworld-dev
-
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-    volumes:
-      - redis_data:/data
-    networks:
-      - aniworld-dev
-
-  nginx:
-    image: nginx:alpine
-    ports:
-      - "80:80"
-    volumes:
-      - ../docker/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
-      - ../src/server/web/static:/var/www/static:ro
-    depends_on:
-      - app
-    networks:
-      - aniworld-dev
-
-volumes:
-  redis_data:
-
-
-networks:
-  aniworld-dev:
-    driver: bridge

docker/docker-compose.yml

@@ -1,167 +0,0 @@
-version: "3.8"
-
-services:
-  # AniWorld Web Application
-  aniworld-web:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: aniworld-web
-    restart: unless-stopped
-    environment:
-      - ANIME_DIRECTORY=/app/data/anime
-      - DATABASE_PATH=/app/data/aniworld.db
-      - LOG_LEVEL=INFO
-      - FLASK_ENV=production
-      - WEB_HOST=0.0.0.0
-      - WEB_PORT=5000
-      - MASTER_PASSWORD=${MASTER_PASSWORD:-admin123}
-    volumes:
-      - anime_data:/app/data
-      - anime_logs:/app/logs
-      - anime_backups:/app/backups
-      - anime_temp:/app/temp
-      - ${ANIME_DIRECTORY:-./data}:/app/data/anime
-    ports:
-      - "${WEB_PORT:-5000}:5000"
-    networks:
-      - aniworld
-      - vpn
-    depends_on:
-      - redis
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:5000/api/health/system"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 40s
-
-  # Redis for caching and session management
-  redis:
-    image: redis:7-alpine
-    container_name: aniworld-redis
-    restart: unless-stopped
-    command: redis-server --appendonly yes
-    volumes:
-      - redis_data:/data
-    networks:
-      - aniworld
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 30s
-      timeout: 3s
-      retries: 3
-
-  # Nginx reverse proxy
-  nginx:
-    image: nginx:alpine
-    container_name: aniworld-nginx
-    restart: unless-stopped
-    ports:
-      - "${HTTP_PORT:-80}:80"
-      - "${HTTPS_PORT:-443}:443"
-    volumes:
-      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
-      - ./docker/nginx/ssl:/etc/nginx/ssl:ro
-      - nginx_logs:/var/log/nginx
-    networks:
-      - aniworld
-    depends_on:
-      - aniworld-web
-    healthcheck:
-      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  # Monitoring with Prometheus (optional)
-  prometheus:
-    image: prom/prometheus
-    container_name: aniworld-prometheus
-    restart: unless-stopped
-    command:
-      - '--config.file=/etc/prometheus/prometheus.yml'
-      - '--storage.tsdb.path=/prometheus'
-      - '--web.console.libraries=/etc/prometheus/console_libraries'
-      - '--web.console.templates=/etc/prometheus/consoles'
-      - '--storage.tsdb.retention.time=200h'
-      - '--web.enable-lifecycle'
-    volumes:
-      - ./docker/prometheus:/etc/prometheus
-      - prometheus_data:/prometheus
-    networks:
-      - aniworld
-    profiles:
-      - monitoring
-
-  # Grafana for monitoring dashboards (optional)
-  grafana:
-    image: grafana/grafana
-    container_name: aniworld-grafana
-    restart: unless-stopped
-    environment:
-      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
-    volumes:
-      - grafana_data:/var/lib/grafana
-      - ./docker/grafana/provisioning:/etc/grafana/provisioning
-    ports:
-      - "${GRAFANA_PORT:-3000}:3000"
-    networks:
-      - aniworld
-    depends_on:
-      - prometheus
-    profiles:
-      - monitoring
-
-  # VPN/Network services (existing)
-  wireguard:
-    container_name: aniworld-wireguard
-    image: jordanpotter/wireguard
-    user: "1013:1001"
-    cap_add:
-      - NET_ADMIN
-      - SYS_MODULE
-    sysctls:
-      net.ipv4.conf.all.src_valid_mark: 1
-    volumes:
-      - ${WG_CONFIG_PATH:-/server_aniworld/wg0.conf}:/etc/wireguard/wg0.conf
-    restart: unless-stopped
-    networks:
-      - vpn
-    profiles:
-      - vpn
-
-  # Network test utility
-  curl:
-    image: curlimages/curl
-    command: ifconfig.io
-    user: "1013:1001"
-    network_mode: service:wireguard
-    depends_on:
-      - wireguard
-    profiles:
-      - vpn
-
-networks:
-  aniworld:
-    driver: bridge
-  vpn:
-    driver: bridge
-
-volumes:
-  anime_data:
-    driver: local
-  anime_logs:
-    driver: local
-  anime_backups:
-    driver: local
-  anime_temp:
-    driver: local
-  redis_data:
-    driver: local
-  nginx_logs:
-    driver: local
-  prometheus_data:
-    driver: local
-  grafana_data:
-    driver: local

docker/grafana/provisioning/dashboards/dashboards.yml

@@ -1,14 +0,0 @@
-# Grafana Dashboard Provisioning Configuration
-
-apiVersion: 1
-
-providers:
-  - name: 'aniworld-dashboards'
-    orgId: 1
-    folder: 'AniWorld'
-    type: file
-    disableDeletion: false
-    updateIntervalSeconds: 30
-    allowUiUpdates: true
-    options:
-      path: /etc/grafana/provisioning/dashboards

docker/grafana/provisioning/datasources/prometheus.yml

@@ -1,14 +0,0 @@
-# Grafana Datasource Configuration
-
-apiVersion: 1
-
-datasources:
-  - name: Prometheus
-    type: prometheus
-    access: proxy
-    url: http://prometheus:9090
-    isDefault: true
-    editable: true
-    jsonData:
-      timeInterval: "30s"
-      httpMethod: "POST"

docker/nginx/nginx.conf

@@ -1,185 +0,0 @@
-# AniWorld Nginx Configuration
-# Reverse proxy configuration for the Flask application
-
-worker_processes auto;
-error_log /var/log/nginx/error.log warn;
-pid /var/run/nginx.pid;
-
-events {
-    worker_connections 1024;
-    use epoll;
-    multi_accept on;
-}
-
-http {
-    include /etc/nginx/mime.types;
-    default_type application/octet-stream;
-
-    # Logging format
-    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
-                   '$status $body_bytes_sent "$http_referer" '
-                   '"$http_user_agent" "$http_x_forwarded_for"';
-
-    access_log /var/log/nginx/access.log main;
-
-    # Performance settings
-    sendfile on;
-    tcp_nopush on;
-    tcp_nodelay on;
-    keepalive_timeout 65;
-    types_hash_max_size 2048;
-    server_tokens off;
-
-    # Gzip compression
-    gzip on;
-    gzip_vary on;
-    gzip_proxied any;
-    gzip_comp_level 6;
-    gzip_types
-        text/plain
-        text/css
-        text/xml
-        text/javascript
-        application/json
-        application/javascript
-        application/xml+rss
-        application/atom+xml
-        image/svg+xml;
-
-    # Rate limiting
-    limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
-    limit_req_zone $binary_remote_addr zone=api:10m rate=30r/m;
-    limit_req_zone $binary_remote_addr zone=general:10m rate=60r/m;
-
-    # Upstream backend
-    upstream aniworld_backend {
-        server aniworld-web:5000 max_fails=3 fail_timeout=30s;
-        keepalive 32;
-    }
-
-    # HTTP server (redirect to HTTPS if SSL is enabled)
-    server {
-        listen 80;
-        server_name _;
-
-        # Health check endpoint for load balancer
-        location /health {
-            access_log off;
-            return 200 "healthy\n";
-            add_header Content-Type text/plain;
-        }
-
-        # Redirect to HTTPS if SSL certificate exists
-        location / {
-            if (-f /etc/nginx/ssl/server.crt) {
-                return 301 https://$host$request_uri;
-            }
-            # If no SSL, proxy directly
-            try_files $uri @proxy_to_app;
-        }
-
-        location @proxy_to_app {
-            proxy_pass http://aniworld_backend;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-            proxy_connect_timeout 30s;
-            proxy_send_timeout 30s;
-            proxy_read_timeout 30s;
-        }
-    }
-
-    # HTTPS server (if SSL certificate is available)
-    server {
-        listen 443 ssl http2;
-        server_name _;
-
-        # SSL configuration (if certificates exist)
-        ssl_certificate /etc/nginx/ssl/server.crt;
-        ssl_certificate_key /etc/nginx/ssl/server.key;
-        ssl_session_cache shared:SSL:1m;
-        ssl_session_timeout 5m;
-        ssl_ciphers HIGH:!aNULL:!MD5;
-        ssl_prefer_server_ciphers on;
-
-        # Security headers
-        add_header X-Frame-Options "SAMEORIGIN" always;
-        add_header X-XSS-Protection "1; mode=block" always;
-        add_header X-Content-Type-Options "nosniff" always;
-        add_header Referrer-Policy "no-referrer-when-downgrade" always;
-        add_header Content-Security-Policy "default-src 'self' http: https: data: blob: 'unsafe-inline'" always;
-        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
-
-        # Health check endpoint
-        location /health {
-            access_log off;
-            return 200 "healthy\n";
-            add_header Content-Type text/plain;
-        }
-
-        # Rate limited endpoints
-        location /login {
-            limit_req zone=login burst=3 nodelay;
-            try_files $uri @proxy_to_app;
-        }
-
-        location /api/ {
-            limit_req zone=api burst=10 nodelay;
-            try_files $uri @proxy_to_app;
-        }
-
-        # Static files caching
-        location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
-            expires 1y;
-            add_header Cache-Control "public, immutable";
-            try_files $uri @proxy_to_app;
-        }
-
-        # WebSocket support for SocketIO
-        location /socket.io/ {
-            proxy_pass http://aniworld_backend;
-            proxy_http_version 1.1;
-            proxy_set_header Upgrade $http_upgrade;
-            proxy_set_header Connection "upgrade";
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-            proxy_cache_bypass $http_upgrade;
-        }
-
-        # Main application
-        location / {
-            limit_req zone=general burst=20 nodelay;
-            try_files $uri @proxy_to_app;
-        }
-
-        location @proxy_to_app {
-            proxy_pass http://aniworld_backend;
-            proxy_set_header Host $host;
-            proxy_set_header X-Real-IP $remote_addr;
-            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-            proxy_set_header X-Forwarded-Proto $scheme;
-            
-            # Timeouts
-            proxy_connect_timeout 30s;
-            proxy_send_timeout 60s;
-            proxy_read_timeout 60s;
-            
-            # Buffer settings
-            proxy_buffering on;
-            proxy_buffer_size 4k;
-            proxy_buffers 8 4k;
-            
-            # Error handling
-            proxy_next_upstream error timeout invalid_header http_500 http_502 http_503;
-        }
-
-        # Custom error pages
-        error_page 500 502 503 504 /50x.html;
-        location = /50x.html {
-            root /usr/share/nginx/html;
-        }
-    }
-}

docker/prometheus/alerts.yml

@@ -1,226 +0,0 @@
-# AniWorld Alerting Rules
-
-groups:
-  - name: aniworld.rules
-    rules:
-      # Application Health Alerts
-      - alert: AniWorldDown
-        expr: up{job="aniworld-web"} == 0
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "AniWorld application is down"
-          description: "AniWorld web application has been down for more than 1 minute."
-
-      - alert: AniWorldHighResponseTime
-        expr: histogram_quantile(0.95, rate(flask_request_duration_seconds_bucket[5m])) > 5
-        for: 2m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High response time for AniWorld"
-          description: "95th percentile response time is {{ $value }} seconds."
-
-      # System Resource Alerts
-      - alert: HighCPUUsage
-        expr: aniworld_cpu_usage_percent > 80
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High CPU usage on AniWorld server"
-          description: "CPU usage is above 80% for more than 5 minutes. Current value: {{ $value }}%"
-
-      - alert: HighMemoryUsage
-        expr: aniworld_memory_usage_percent > 85
-        for: 3m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High memory usage on AniWorld server"
-          description: "Memory usage is above 85% for more than 3 minutes. Current value: {{ $value }}%"
-
-      - alert: CriticalMemoryUsage
-        expr: aniworld_memory_usage_percent > 95
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Critical memory usage on AniWorld server"
-          description: "Memory usage is above 95%. Current value: {{ $value }}%"
-
-      - alert: HighDiskUsage
-        expr: aniworld_disk_usage_percent > 90
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High disk usage on AniWorld server"
-          description: "Disk usage is above 90% for more than 5 minutes. Current value: {{ $value }}%"
-
-      - alert: CriticalDiskUsage
-        expr: aniworld_disk_usage_percent > 95
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Critical disk usage on AniWorld server"
-          description: "Disk usage is above 95%. Current value: {{ $value }}%"
-
-      # Database Alerts
-      - alert: DatabaseConnectionFailure
-        expr: up{job="aniworld-web"} == 1 and aniworld_database_connected == 0
-        for: 2m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Database connection failure"
-          description: "AniWorld cannot connect to the database for more than 2 minutes."
-
-      - alert: SlowDatabaseQueries
-        expr: aniworld_database_query_duration_seconds > 5
-        for: 1m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Slow database queries detected"
-          description: "Database queries are taking longer than 5 seconds. Current duration: {{ $value }}s"
-
-      # Download Performance Alerts
-      - alert: HighDownloadFailureRate
-        expr: rate(aniworld_downloads_failed_total[5m]) / rate(aniworld_downloads_total[5m]) > 0.1
-        for: 3m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High download failure rate"
-          description: "Download failure rate is above 10% for the last 5 minutes."
-
-      - alert: NoDownloadActivity
-        expr: increase(aniworld_downloads_total[1h]) == 0
-        for: 2h
-        labels:
-          severity: info
-        annotations:
-          summary: "No download activity detected"
-          description: "No downloads have been initiated in the last 2 hours."
-
-      # Process Alerts
-      - alert: HighThreadCount
-        expr: aniworld_process_threads > 100
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High thread count in AniWorld process"
-          description: "Thread count is above 100 for more than 5 minutes. Current count: {{ $value }}"
-
-      - alert: ProcessMemoryLeak
-        expr: increase(aniworld_process_memory_bytes[1h]) > 100000000  # 100MB
-        for: 1h
-        labels:
-          severity: warning
-        annotations:
-          summary: "Potential memory leak detected"
-          description: "Process memory usage has increased by more than 100MB in the last hour."
-
-      # Network Alerts
-      - alert: NetworkConnectivityIssue
-        expr: aniworld_network_connectivity == 0
-        for: 2m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Network connectivity issue"
-          description: "AniWorld is experiencing network connectivity issues."
-
-      # Security Alerts
-      - alert: HighFailedLoginAttempts
-        expr: increase(aniworld_failed_login_attempts_total[5m]) > 10
-        for: 1m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High number of failed login attempts"
-          description: "More than 10 failed login attempts in the last 5 minutes."
-
-      - alert: UnauthorizedAPIAccess
-        expr: increase(aniworld_unauthorized_api_requests_total[5m]) > 50
-        for: 2m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High number of unauthorized API requests"
-          description: "More than 50 unauthorized API requests in the last 5 minutes."
-
-      # Cache Performance Alerts
-      - alert: LowCacheHitRate
-        expr: aniworld_cache_hit_rate < 0.7
-        for: 10m
-        labels:
-          severity: info
-        annotations:
-          summary: "Low cache hit rate"
-          description: "Cache hit rate is below 70% for more than 10 minutes. Current rate: {{ $value }}"
-
-  - name: infrastructure.rules
-    rules:
-      # Redis Alerts
-      - alert: RedisDown
-        expr: up{job="redis"} == 0
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Redis is down"
-          description: "Redis server has been down for more than 1 minute."
-
-      - alert: RedisHighMemoryUsage
-        expr: redis_memory_used_bytes / redis_memory_max_bytes > 0.9
-        for: 5m
-        labels:
-          severity: warning
-        annotations:
-          summary: "Redis high memory usage"
-          description: "Redis memory usage is above 90%."
-
-      # Nginx Alerts
-      - alert: NginxDown
-        expr: up{job="nginx"} == 0
-        for: 1m
-        labels:
-          severity: critical
-        annotations:
-          summary: "Nginx is down"
-          description: "Nginx reverse proxy has been down for more than 1 minute."
-
-      - alert: NginxHighErrorRate
-        expr: rate(nginx_http_requests_total{status=~"5.."}[5m]) / rate(nginx_http_requests_total[5m]) > 0.05
-        for: 2m
-        labels:
-          severity: warning
-        annotations:
-          summary: "High error rate in Nginx"
-          description: "Nginx is returning more than 5% server errors."
-
-  - name: custom.rules
-    rules:
-      # Custom Business Logic Alerts
-      - alert: AnimeCollectionSizeIncreaseStalled
-        expr: increase(aniworld_anime_total[24h]) == 0
-        for: 48h
-        labels:
-          severity: info
-        annotations:
-          summary: "Anime collection size hasn't increased"
-          description: "No new anime have been added to the collection in the last 48 hours."
-
-      - alert: EpisodeDownloadBacklog
-        expr: aniworld_episodes_pending > 1000
-        for: 1h
-        labels:
-          severity: warning
-        annotations:
-          summary: "Large episode download backlog"
-          description: "More than 1000 episodes are pending download. Current backlog: {{ $value }}"

docker/prometheus/prometheus.yml

@@ -1,67 +0,0 @@
-# Prometheus Configuration for AniWorld Monitoring
-
-global:
-  scrape_interval: 15s
-  evaluation_interval: 15s
-
-rule_files:
-  - "alerts.yml"
-
-alerting:
-  alertmanagers:
-    - static_configs:
-        - targets:
-          - alertmanager:9093
-
-scrape_configs:
-  # AniWorld Application Metrics
-  - job_name: 'aniworld-web'
-    static_configs:
-      - targets: ['aniworld-web:5000']
-    metrics_path: '/api/health/metrics'
-    scrape_interval: 30s
-    scrape_timeout: 10s
-
-  # System Metrics (Node Exporter)
-  - job_name: 'node-exporter'
-    static_configs:
-      - targets: ['node-exporter:9100']
-
-  # Redis Metrics
-  - job_name: 'redis'
-    static_configs:
-      - targets: ['redis-exporter:9121']
-
-  # Nginx Metrics
-  - job_name: 'nginx'
-    static_configs:
-      - targets: ['nginx-exporter:9113']
-
-  # Prometheus Self-Monitoring
-  - job_name: 'prometheus'
-    static_configs:
-      - targets: ['localhost:9090']
-
-  # Health Check Monitoring
-  - job_name: 'aniworld-health'
-    static_configs:
-      - targets: ['aniworld-web:5000']
-    metrics_path: '/api/health/system'
-    scrape_interval: 60s
-    
-  # Blackbox Exporter for External Monitoring
-  - job_name: 'blackbox'
-    metrics_path: /probe
-    params:
-      module: [http_2xx]
-    static_configs:
-      - targets:
-        - http://aniworld-web:5000/health
-        - http://aniworld-web:5000/api/health/ready
-    relabel_configs:
-      - source_labels: [__address__]
-        target_label: __param_target
-      - source_labels: [__param_target]
-        target_label: instance
-      - target_label: __address__
-        replacement: blackbox-exporter:9115

docs/development/setup.md

@@ -1,686 +0,0 @@
-# AniWorld Installation and Setup Guide
-
-This comprehensive guide will help you install, configure, and deploy the AniWorld anime downloading and management application.
-
-## Table of Contents
-
-1. [Quick Start with Docker](#quick-start-with-docker)
-2. [Manual Installation](#manual-installation)
-3. [Configuration](#configuration)
-4. [Running the Application](#running-the-application)
-5. [Monitoring and Health Checks](#monitoring-and-health-checks)
-6. [Backup and Maintenance](#backup-and-maintenance)
-7. [Troubleshooting](#troubleshooting)
-8. [Advanced Deployment](#advanced-deployment)
-
-## Quick Start with Docker
-
-The easiest way to get AniWorld running is using Docker Compose.
-
-### Prerequisites
-
-- Docker Engine 20.10+ 
-- Docker Compose 2.0+
-- At least 2GB RAM
-- 10GB disk space (minimum)
-
-### Installation Steps
-
-1. **Clone the Repository**
-   ```bash
-   git clone <repository-url>
-   cd Aniworld
-   ```
-
-2. **Create Environment File**
-   ```bash
-   cp .env.example .env
-   ```
-
-3. **Configure Environment Variables**
-   Edit `.env` file:
-   ```env
-   # Required Settings
-   ANIME_DIRECTORY=/path/to/your/anime/collection
-   MASTER_PASSWORD=your_secure_password
-   
-   # Optional Settings  
-   WEB_PORT=5000
-   HTTP_PORT=80
-   HTTPS_PORT=443
-   GRAFANA_PASSWORD=grafana_admin_password
-   
-   # VPN Settings (if using)
-   WG_CONFIG_PATH=/path/to/wireguard/config
-   ```
-
-4. **Start the Application**
-   ```bash
-   # Basic deployment
-   docker-compose up -d
-   
-   # With monitoring
-   docker-compose --profile monitoring up -d
-   
-   # With VPN
-   docker-compose --profile vpn up -d
-   
-   # Full deployment with all services
-   docker-compose --profile monitoring --profile vpn up -d
-   ```
-
-5. **Access the Application**
-   - Web Interface: http://localhost:5000
-   - Grafana Monitoring: http://localhost:3000 (if monitoring profile enabled)
-
-### Environment File (.env) Template
-
-Create a `.env` file in the root directory:
-
-```env
-# Core Application Settings
-ANIME_DIRECTORY=/data/anime
-MASTER_PASSWORD=change_this_secure_password
-DATABASE_PATH=/app/data/aniworld.db
-LOG_LEVEL=INFO
-
-# Web Server Configuration
-WEB_PORT=5000
-WEB_HOST=0.0.0.0
-FLASK_ENV=production
-
-# Reverse Proxy Configuration
-HTTP_PORT=80
-HTTPS_PORT=443
-
-# Monitoring (optional)
-GRAFANA_PASSWORD=admin_password
-
-# VPN Configuration (optional)
-WG_CONFIG_PATH=/path/to/wg0.conf
-
-# Performance Settings
-MAX_DOWNLOAD_WORKERS=4
-MAX_SPEED_MBPS=100
-CACHE_SIZE_MB=512
-
-# Security Settings
-SESSION_TIMEOUT=86400
-MAX_LOGIN_ATTEMPTS=5
-```
-
-## Manual Installation
-
-### System Requirements
-
-- Python 3.10 or higher
-- SQLite 3.35+
-- 4GB RAM (recommended)
-- 20GB disk space (recommended)
-
-### Installation Steps
-
-1. **Install System Dependencies**
-
-   **Ubuntu/Debian:**
-   ```bash
-   sudo apt update
-   sudo apt install python3 python3-pip python3-venv sqlite3 curl wget
-   ```
-
-   **CentOS/RHEL:**
-   ```bash
-   sudo yum install python3 python3-pip sqlite curl wget
-   ```
-
-   **Windows:**
-   - Install Python 3.10+ from python.org
-   - Install SQLite from sqlite.org
-   - Install Git for Windows
-
-2. **Clone and Setup**
-   ```bash
-   git clone <repository-url>
-   cd Aniworld
-   
-   # Create virtual environment
-   python3 -m venv aniworld-env
-   
-   # Activate virtual environment
-   source aniworld-env/bin/activate  # Linux/Mac
-   aniworld-env\Scripts\activate     # Windows
-   
-   # Install Python dependencies
-   pip install -r requirements.txt
-   ```
-
-3. **Create Configuration**
-   ```bash
-   cp src/server/config.py.example src/server/config.py
-   ```
-
-4. **Configure Application**
-   Edit `src/server/config.py`:
-   ```python
-   import os
-   
-   class Config:
-       # Core settings
-       anime_directory = os.getenv('ANIME_DIRECTORY', '/path/to/anime')
-       master_password = os.getenv('MASTER_PASSWORD', 'change_me')
-       database_path = os.getenv('DATABASE_PATH', './data/aniworld.db')
-       
-       # Web server settings
-       host = os.getenv('WEB_HOST', '127.0.0.1')
-       port = int(os.getenv('WEB_PORT', 5000))
-       debug = os.getenv('FLASK_DEBUG', 'False').lower() == 'true'
-       
-       # Performance settings
-       max_workers = int(os.getenv('MAX_DOWNLOAD_WORKERS', 4))
-       max_speed_mbps = int(os.getenv('MAX_SPEED_MBPS', 100))
-   ```
-
-5. **Initialize Database**
-   ```bash
-   cd src/server
-   python -c "from database_manager import init_database_system; init_database_system()"
-   ```
-
-6. **Run the Application**
-   ```bash
-   cd src/server
-   python app.py
-   ```
-
-## Configuration
-
-### Core Configuration Options
-
-#### Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ANIME_DIRECTORY` | `/app/data` | Path to anime collection |
-| `MASTER_PASSWORD` | `admin123` | Web interface password |
-| `DATABASE_PATH` | `/app/data/aniworld.db` | SQLite database file path |
-| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
-| `WEB_HOST` | `0.0.0.0` | Web server bind address |
-| `WEB_PORT` | `5000` | Web server port |
-| `MAX_DOWNLOAD_WORKERS` | `4` | Maximum concurrent downloads |
-| `MAX_SPEED_MBPS` | `100` | Download speed limit (Mbps) |
-
-#### Advanced Configuration
-
-Edit `src/server/config.py` for advanced settings:
-
-```python
-class Config:
-    # Download settings
-    download_timeout = 300  # 5 minutes
-    retry_attempts = 3
-    retry_delay = 5  # seconds
-    
-    # Cache settings
-    cache_size_mb = 512
-    cache_ttl = 3600  # 1 hour
-    
-    # Security settings
-    session_timeout = 86400  # 24 hours
-    max_login_attempts = 5
-    lockout_duration = 300  # 5 minutes
-    
-    # Monitoring settings
-    health_check_interval = 30  # seconds
-    metrics_retention_days = 7
-```
-
-### Directory Structure Setup
-
-```
-/your/anime/directory/
-├── Series Name 1/
-│   ├── Season 1/
-│   ├── Season 2/
-│   └── data          # Metadata file
-├── Series Name 2/
-│   ├── episodes/
-│   └── data          # Metadata file
-└── ...
-```
-
-## Running the Application
-
-### Development Mode
-
-```bash
-cd src/server
-export FLASK_ENV=development
-export FLASK_DEBUG=1
-python app.py
-```
-
-### Production Mode
-
-#### Using Gunicorn (Recommended)
-
-```bash
-# Install gunicorn
-pip install gunicorn
-
-# Run with gunicorn
-cd src/server
-gunicorn -w 4 -b 0.0.0.0:5000 --timeout 300 app:app
-```
-
-#### Using systemd Service
-
-Create `/etc/systemd/system/aniworld.service`:
-
-```ini
-[Unit]
-Description=AniWorld Web Application
-After=network.target
-
-[Service]
-Type=simple
-User=aniworld
-WorkingDirectory=/opt/aniworld/src/server
-Environment=PATH=/opt/aniworld/aniworld-env/bin
-Environment=ANIME_DIRECTORY=/data/anime
-Environment=MASTER_PASSWORD=your_password
-ExecStart=/opt/aniworld/aniworld-env/bin/gunicorn -w 4 -b 0.0.0.0:5000 app:app
-Restart=always
-RestartSec=10
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Enable and start:
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable aniworld
-sudo systemctl start aniworld
-```
-
-### Using Docker
-
-#### Single Container
-```bash
-docker run -d \
-  --name aniworld \
-  -p 5000:5000 \
-  -v /path/to/anime:/app/data/anime \
-  -v /path/to/data:/app/data \
-  -e MASTER_PASSWORD=your_password \
-  aniworld:latest
-```
-
-#### Docker Compose (Recommended)
-```bash
-docker-compose up -d
-```
-
-## Monitoring and Health Checks
-
-### Health Check Endpoints
-
-| Endpoint | Purpose |
-|----------|---------|
-| `/health` | Basic health check for load balancers |
-| `/api/health/system` | System resource metrics |
-| `/api/health/database` | Database connectivity |
-| `/api/health/dependencies` | External dependencies |
-| `/api/health/detailed` | Comprehensive health report |
-| `/api/health/ready` | Kubernetes readiness probe |
-| `/api/health/live` | Kubernetes liveness probe |
-| `/api/health/metrics` | Prometheus metrics |
-
-### Monitoring with Grafana
-
-1. **Enable Monitoring Profile**
-   ```bash
-   docker-compose --profile monitoring up -d
-   ```
-
-2. **Access Grafana**
-   - URL: http://localhost:3000
-   - Username: admin
-   - Password: (set in GRAFANA_PASSWORD env var)
-
-3. **Import Dashboards**
-   - System metrics dashboard
-   - Application performance dashboard
-   - Download statistics dashboard
-
-### Log Management
-
-**Viewing Logs:**
-```bash
-# Docker logs
-docker-compose logs -f aniworld-web
-
-# System logs (if using systemd)
-journalctl -u aniworld -f
-
-# Application logs
-tail -f src/server/logs/app.log
-```
-
-**Log Rotation Configuration:**
-Create `/etc/logrotate.d/aniworld`:
-```
-/opt/aniworld/src/server/logs/*.log {
-    daily
-    rotate 30
-    compress
-    delaycompress
-    missingok
-    notifempty
-    create 644 aniworld aniworld
-    postrotate
-        systemctl reload aniworld
-    endscript
-}
-```
-
-## Backup and Maintenance
-
-### Database Backup
-
-**Manual Backup:**
-```bash
-# Via API
-curl -X POST "http://localhost:5000/api/database/backups/create" \
-  -H "Content-Type: application/json" \
-  -d '{"backup_type": "full", "description": "Manual backup"}'
-
-# Direct SQLite backup
-sqlite3 /app/data/aniworld.db ".backup /path/to/backup.db"
-```
-
-**Automated Backup Script:**
-```bash
-#!/bin/bash
-# backup.sh
-BACKUP_DIR="/backups"
-DATE=$(date +%Y%m%d_%H%M%S)
-DB_PATH="/app/data/aniworld.db"
-
-# Create backup
-sqlite3 "$DB_PATH" ".backup $BACKUP_DIR/aniworld_$DATE.db"
-
-# Compress
-gzip "$BACKUP_DIR/aniworld_$DATE.db"
-
-# Clean old backups (keep 30 days)
-find "$BACKUP_DIR" -name "aniworld_*.db.gz" -mtime +30 -delete
-```
-
-**Cron Job for Daily Backups:**
-```bash
-# Add to crontab
-0 2 * * * /opt/aniworld/scripts/backup.sh
-```
-
-### Database Maintenance
-
-**Vacuum Database (reclaim space):**
-```bash
-curl -X POST "http://localhost:5000/api/database/maintenance/vacuum"
-```
-
-**Update Statistics:**
-```bash
-curl -X POST "http://localhost:5000/api/database/maintenance/analyze"
-```
-
-**Integrity Check:**
-```bash
-curl -X POST "http://localhost:5000/api/database/maintenance/integrity-check"
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. Permission Denied Errors
-```bash
-# Fix file permissions
-chown -R aniworld:aniworld /opt/aniworld
-chmod -R 755 /opt/aniworld
-
-# Fix data directory permissions
-chown -R aniworld:aniworld /data/anime
-```
-
-#### 2. Database Lock Errors
-```bash
-# Check for hung processes
-ps aux | grep aniworld
-
-# Kill hung processes
-pkill -f aniworld
-
-# Restart service
-systemctl restart aniworld
-```
-
-#### 3. High Memory Usage
-```bash
-# Check memory usage
-curl "http://localhost:5000/api/health/performance"
-
-# Restart application to free memory
-docker-compose restart aniworld-web
-```
-
-#### 4. Network Connectivity Issues
-```bash
-# Test network connectivity
-curl "http://localhost:5000/api/health/dependencies"
-
-# Check DNS resolution
-nslookup aniworld.to
-
-# Test with VPN if configured
-docker-compose exec aniworld-web curl ifconfig.io
-```
-
-### Performance Tuning
-
-#### 1. Increase Worker Processes
-```env
-MAX_DOWNLOAD_WORKERS=8
-```
-
-#### 2. Adjust Speed Limits
-```env
-MAX_SPEED_MBPS=200
-```
-
-#### 3. Increase Cache Size
-```env
-CACHE_SIZE_MB=1024
-```
-
-#### 4. Database Optimization
-```bash
-# Regular maintenance
-sqlite3 /app/data/aniworld.db "VACUUM; ANALYZE;"
-
-# Enable WAL mode for better concurrency
-sqlite3 /app/data/aniworld.db "PRAGMA journal_mode=WAL;"
-```
-
-### Debug Mode
-
-Enable debug logging:
-```env
-LOG_LEVEL=DEBUG
-FLASK_DEBUG=1
-```
-
-View debug information:
-```bash
-# Check application logs
-docker-compose logs -f aniworld-web
-
-# Check system health
-curl "http://localhost:5000/api/health/detailed"
-```
-
-## Advanced Deployment
-
-### Load Balancing with Multiple Instances
-
-#### Docker Swarm
-```yaml
-version: '3.8'
-services:
-  aniworld-web:
-    image: aniworld:latest
-    deploy:
-      replicas: 3
-      update_config:
-        parallelism: 1
-        delay: 30s
-    networks:
-      - aniworld
-```
-
-#### Kubernetes Deployment
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: aniworld-web
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: aniworld-web
-  template:
-    metadata:
-      labels:
-        app: aniworld-web
-    spec:
-      containers:
-      - name: aniworld-web
-        image: aniworld:latest
-        ports:
-        - containerPort: 5000
-        env:
-        - name: ANIME_DIRECTORY
-          value: "/data/anime"
-        - name: MASTER_PASSWORD
-          valueFrom:
-            secretKeyRef:
-              name: aniworld-secrets
-              key: master-password
-        volumeMounts:
-        - name: anime-data
-          mountPath: /data/anime
-        - name: app-data
-          mountPath: /app/data
-        livenessProbe:
-          httpGet:
-            path: /api/health/live
-            port: 5000
-          initialDelaySeconds: 30
-          periodSeconds: 30
-        readinessProbe:
-          httpGet:
-            path: /api/health/ready
-            port: 5000
-          initialDelaySeconds: 5
-          periodSeconds: 10
-```
-
-### SSL/TLS Configuration
-
-#### Automatic SSL with Let's Encrypt
-```bash
-# Install certbot
-sudo apt install certbot python3-certbot-nginx
-
-# Obtain certificate
-sudo certbot --nginx -d your-domain.com
-
-# Auto-renewal
-echo "0 12 * * * /usr/bin/certbot renew --quiet" | sudo tee -a /etc/crontab
-```
-
-#### Manual SSL Certificate
-Place certificates in `docker/nginx/ssl/`:
-- `server.crt` - SSL certificate
-- `server.key` - Private key
-
-### High Availability Setup
-
-#### Database Replication
-```bash
-# Master-slave SQLite replication using litestream
-docker run -d \
-  --name litestream \
-  -v /app/data:/data \
-  -e LITESTREAM_ACCESS_KEY_ID=your_key \
-  -e LITESTREAM_SECRET_ACCESS_KEY=your_secret \
-  litestream/litestream \
-  replicate /data/aniworld.db s3://your-bucket/db
-```
-
-#### Shared Storage
-```yaml
-# docker-compose.yml with NFS
-services:
-  aniworld-web:
-    volumes:
-      - type: volume
-        source: anime-data
-        target: /app/data/anime
-        volume:
-          driver: local
-          driver_opts:
-            type: nfs
-            o: addr=your-nfs-server,rw
-            device: ":/path/to/anime"
-```
-
-### Security Hardening
-
-#### 1. Network Security
-```yaml
-# Restrict network access
-networks:
-  aniworld:
-    driver: bridge
-    ipam:
-      config:
-        - subnet: 172.20.0.0/16
-```
-
-#### 2. Container Security
-```dockerfile
-# Run as non-root user
-USER 1000:1000
-
-# Read-only root filesystem
-docker run --read-only --tmpfs /tmp aniworld:latest
-```
-
-#### 3. Secrets Management
-```bash
-# Use Docker secrets
-echo "your_password" | docker secret create master_password -
-
-# Use in compose
-services:
-  aniworld-web:
-    secrets:
-      - master_password
-    environment:
-      - MASTER_PASSWORD_FILE=/run/secrets/master_password
-```
-
-This installation guide covers all aspects of deploying AniWorld from development to production environments. Choose the deployment method that best fits your infrastructure and requirements.

instruction2.md

@@ -1,20 +0,0 @@
-
-Use the checklist to write the app. start on the first task. make sure each task is finished.
-mark a finished task with x, and save it.
-Stop if all Task are finshed
-
-before you start the app run
-conda activate AniWorld
-set ANIME_DIRECTORY="\\sshfs.r\ubuntu@192.168.178.43\media\serien\Serien"
-cd src\server
-
-make sure you run the command on the same powershell terminal. otherwiese this do not work.
-
-fix the folowing issues one by one:
-
-
-app.js:962 
- Error loading configuration: SyntaxError: Unexpected token '<', "<!doctype "... is not valid JSON
-showConfigModal	@	app.js:962
-await in showConfigModal		
-(anonymous)	@	app.js:315

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "aniworld-web",
+  "version": "1.5.11",
+  "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.10.1",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

pyproject.toml

@@ -1,254 +1,5 @@
-[build-system]
-requires = ["setuptools>=61.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "aniworld"
-version = "1.0.0"
-description = "AniWorld Anime Downloader and Manager"
-readme = "README.md"
-requires-python = ">=3.8"
-license = {text = "MIT"}
-authors = [
-    {name = "AniWorld Team", email = "contact@aniworld.dev"},
-]
-keywords = ["anime", "downloader", "flask", "web", "streaming"]
-classifiers = [
-    "Development Status :: 4 - Beta",
-    "Intended Audience :: End Users/Desktop",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.8",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
-    "Topic :: Multimedia :: Video",
-    "Topic :: Software Development :: Libraries :: Application Frameworks",
-]
-
-dependencies = [
-    "flask>=2.3.0",
-    "flask-cors>=4.0.0",
-    "flask-login>=0.6.0",
-    "flask-session>=0.5.0",
-    "flask-wtf>=1.1.0",
-    "flask-migrate>=4.0.0",
-    "sqlalchemy>=2.0.0",
-    "alembic>=1.11.0",
-    "requests>=2.31.0",
-    "beautifulsoup4>=4.12.0",
-    "lxml>=4.9.0",
-    "pydantic>=2.0.0",
-    "pydantic-settings>=2.0.0",
-    "python-dotenv>=1.0.0",
-    "celery>=5.3.0",
-    "redis>=4.6.0",
-    "cryptography>=41.0.0",
-    "bcrypt>=4.0.0",
-    "click>=8.1.0",
-    "rich>=13.4.0",
-    "psutil>=5.9.0",
-    "aiofiles>=23.1.0",
-    "httpx>=0.24.0",
-    "websockets>=11.0.0",
-    "jinja2>=3.1.0",
-    "markupsafe>=2.1.0",
-    "wtforms>=3.0.0",
-    "email-validator>=2.0.0",
-    "python-dateutil>=2.8.0",
-]
-
-[project.optional-dependencies]
-dev = [
-    "pytest>=7.4.0",
-    "pytest-cov>=4.1.0",
-    "pytest-asyncio>=0.21.0",
-    "pytest-flask>=1.2.0",
-    "pytest-mock>=3.11.0",
-    "black>=23.7.0",
-    "isort>=5.12.0",
-    "flake8>=6.0.0",
-    "mypy>=1.5.0",
-    "pre-commit>=3.3.0",
-    "coverage>=7.3.0",
-    "bandit>=1.7.5",
-    "safety>=2.3.0",
-    "ruff>=0.0.284",
-]
-test = [
-    "pytest>=7.4.0",
-    "pytest-cov>=4.1.0",
-    "pytest-asyncio>=0.21.0",
-    "pytest-flask>=1.2.0",
-    "pytest-mock>=3.11.0",
-    "factory-boy>=3.3.0",
-    "faker>=19.3.0",
-]
-docs = [
-    "sphinx>=7.1.0",
-    "sphinx-rtd-theme>=1.3.0",
-    "sphinx-autodoc-typehints>=1.24.0",
-    "myst-parser>=2.0.0",
-]
-production = [
-    "gunicorn>=21.2.0",
-    "gevent>=23.7.0",
-    "supervisor>=4.2.0",
-]
-
-[project.urls]
-Homepage = "https://github.com/yourusername/aniworld"
-Repository = "https://github.com/yourusername/aniworld.git"
-Documentation = "https://aniworld.readthedocs.io/"
-"Bug Tracker" = "https://github.com/yourusername/aniworld/issues"
-
-[project.scripts]
-aniworld = "src.main:main"
-aniworld-server = "src.server.app:cli"
-
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["*"]
-exclude = ["tests*"]
-
-[tool.black]
-line-length = 88
-target-version = ['py38', 'py39', 'py310', 'py311']
-include = '\.pyi?$'
-extend-exclude = '''
-/(
-  # directories
-  \.eggs
-  | \.git
-  | \.hg
-  | \.mypy_cache
-  | \.tox
-  | \.venv
-  | venv
-  | aniworld
-  | build
-  | dist
-)/
-'''
-
-[tool.isort]
-profile = "black"
-multi_line_output = 3
-line_length = 88
-include_trailing_comma = true
-force_grid_wrap = 0
-use_parentheses = true
-ensure_newline_before_comments = true
-
-[tool.flake8]
-max-line-length = 88
-extend-ignore = ["E203", "W503", "E501"]
-exclude = [
-    ".git",
-    "__pycache__",
-    "build",
-    "dist",
-    ".venv",
-    "venv",
-    "aniworld",
-]
-
-[tool.mypy]
-python_version = "3.8"
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-disallow_incomplete_defs = true
-check_untyped_defs = true
-disallow_untyped_decorators = true
-no_implicit_optional = true
-warn_redundant_casts = true
-warn_unused_ignores = true
-warn_no_return = true
-warn_unreachable = true
-strict_equality = true
-
-[[tool.mypy.overrides]]
-module = [
-    "bs4.*",
-    "lxml.*",
-    "celery.*",
-    "redis.*",
-]
-ignore_missing_imports = true
-
 [tool.pytest.ini_options]
-minversion = "6.0"
-addopts = "-ra -q --strict-markers --strict-config"
-testpaths = [
-    "tests",
-]
-python_files = [
-    "test_*.py",
-    "*_test.py",
-]
-python_classes = [
-    "Test*",
-]
-python_functions = [
-    "test_*",
-]
+asyncio_mode = "auto"
 markers = [
-    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
-    "integration: marks tests as integration tests",
-    "e2e: marks tests as end-to-end tests",
-    "unit: marks tests as unit tests",
-    "api: marks tests as API tests",
-    "web: marks tests as web interface tests",
-]
-
-[tool.coverage.run]
-source = ["src"]
-omit = [
-    "*/tests/*",
-    "*/venv/*",
-    "*/__pycache__/*",
-    "*/migrations/*",
-]
-
-[tool.coverage.report]
-exclude_lines = [
-    "pragma: no cover",
-    "def __repr__",
-    "if self.debug:",
-    "if settings.DEBUG",
-    "raise AssertionError",
-    "raise NotImplementedError",
-    "if 0:",
-    "if __name__ == .__main__.:",
-    "class .*\\bProtocol\\):",
-    "@(abc\\.)?abstractmethod",
-]
-
-[tool.ruff]
-target-version = "py38"
-line-length = 88
-select = [
-    "E",  # pycodestyle errors
-    "W",  # pycodestyle warnings
-    "F",  # pyflakes
-    "I",  # isort
-    "B",  # flake8-bugbear
-    "C4", # flake8-comprehensions
-    "UP", # pyupgrade
-]
-ignore = [
-    "E501",  # line too long, handled by black
-    "B008",  # do not perform function calls in argument defaults
-    "C901",  # too complex
-]
-
-[tool.ruff.per-file-ignores]
-"__init__.py" = ["F401"]
-"tests/**/*" = ["F401", "F811"]
-
-[tool.bandit]
-exclude_dirs = ["tests", "venv", "aniworld"]
-skips = ["B101", "B601"]
+    "asyncio: mark test as asynchronous"
+]

pytest.ini

@@ -1,23 +0,0 @@
-[tool:pytest]
-minversion = 6.0
-addopts = -ra -q --strict-markers --strict-config --cov=src --cov-report=html --cov-report=term
-testpaths = 
-    tests
-python_files = 
-    test_*.py
-    *_test.py
-python_classes = 
-    Test*
-python_functions = 
-    test_*
-markers =
-    slow: marks tests as slow (deselect with -m "not slow")
-    integration: marks tests as integration tests
-    e2e: marks tests as end-to-end tests
-    unit: marks tests as unit tests
-    api: marks tests as API tests
-    web: marks tests as web interface tests
-    smoke: marks tests as smoke tests
-filterwarnings =
-    ignore::DeprecationWarning
-    ignore::PendingDeprecationWarning

requirements-dev.txt

@@ -1,32 +0,0 @@
-# Development dependencies
--r requirements.txt
-
-# Testing
-pytest>=7.4.0
-pytest-cov>=4.1.0
-pytest-asyncio>=0.21.0
-pytest-flask>=1.2.0
-pytest-mock>=3.11.0
-factory-boy>=3.3.0
-faker>=19.3.0
-
-# Code Quality
-black>=23.7.0
-isort>=5.12.0
-flake8>=6.0.0
-mypy>=1.5.0
-ruff>=0.0.284
-
-# Security
-bandit>=1.7.5
-safety>=2.3.0
-
-# Development tools
-pre-commit>=3.3.0
-coverage>=7.3.0
-
-# Documentation
-sphinx>=7.1.0
-sphinx-rtd-theme>=1.3.0
-sphinx-autodoc-typehints>=1.24.0
-myst-parser>=2.0.0

requirements-test.txt

@@ -1,9 +0,0 @@
-# Test dependencies only
-pytest>=7.4.0
-pytest-cov>=4.1.0
-pytest-asyncio>=0.21.0
-pytest-flask>=1.2.0
-pytest-mock>=3.11.0
-factory-boy>=3.3.0
-faker>=19.3.0
-coverage>=7.3.0

requirements.txt

@@ -1,50 +1,34 @@
-# Core Flask dependencies
-flask>=2.3.0
-flask-cors>=4.0.0
-flask-login>=0.6.0
-flask-session>=0.5.0
-flask-wtf>=1.1.0
-flask-migrate>=4.0.0
-
-# Database
-sqlalchemy>=2.0.0
-alembic>=1.11.0
-
-# HTTP and Web Scraping
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+jinja2==3.1.2
+python-multipart==0.0.6
+pydantic==2.5.0
+pydantic-settings==2.1.0
+python-jose[cryptography]==3.3.0
+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
+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
-lxml>=4.9.0
-httpx>=0.24.0
+chardet>=5.2.0
+fake-useragent>=1.4.0
+yt-dlp>=2024.1.0
+urllib3>=2.0.0
 
-# Data Validation and Configuration
-pydantic>=2.0.0
-pydantic-settings>=2.0.0
-python-dotenv>=1.0.0
-
-# Task Queue and Caching
-celery>=5.3.0
-redis>=4.6.0
-
-# Security
-cryptography>=41.0.0
-bcrypt>=4.0.0
-
-# CLI and User Interface
-click>=8.1.0
-rich>=13.4.0
-
-# System and File Operations
-psutil>=5.9.0
-aiofiles>=23.1.0
-
-# WebSocket support
-websockets>=11.0.0
-
-# Template and Form handling
-jinja2>=3.1.0
-markupsafe>=2.1.0
-wtforms>=3.0.0
-email-validator>=2.0.0
-
-# Date and time utilities
-python-dateutil>=2.8.0
+# Robot Framework testing dependencies
+robotframework>=7.0
+robotframework-browser>=18.0
+robotframework-requests>=0.9
+robotframework-jsonlibrary>=0.5

run_api_tests.py

@@ -1,80 +0,0 @@
-#!/usr/bin/env python3
-"""
-Simple test execution script for API tests.
-Run this from the command line to execute all API tests.
-"""
-
-import subprocess
-import sys
-import os
-
-def main():
-    """Main execution function."""
-    print("🚀 Aniworld API Test Executor")
-    print("=" * 40)
-    
-    # Get the directory of this script
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    project_root = os.path.join(script_dir, '..', '..')
-    
-    # Change to project root
-    os.chdir(project_root)
-    
-    print(f"📁 Working directory: {os.getcwd()}")
-    print(f"🐍 Python version: {sys.version}")
-    
-    # Try to run the comprehensive test runner
-    test_runner = os.path.join('tests', 'unit', 'web', 'run_api_tests.py')
-    
-    if os.path.exists(test_runner):
-        print(f"\n🧪 Running comprehensive test suite...")
-        try:
-            result = subprocess.run([sys.executable, test_runner], capture_output=False)
-            return result.returncode
-        except Exception as e:
-            print(f"❌ Error running comprehensive tests: {e}")
-    
-    # Fallback to individual test files
-    print(f"\n🔄 Falling back to individual test execution...")
-    
-    test_files = [
-        os.path.join('tests', 'unit', 'web', 'test_api_endpoints.py'),
-        os.path.join('tests', 'integration', 'test_api_integration.py')
-    ]
-    
-    total_failures = 0
-    
-    for test_file in test_files:
-        if os.path.exists(test_file):
-            print(f"\n📋 Running {test_file}...")
-            try:
-                result = subprocess.run([
-                    sys.executable, '-m', 'unittest', 
-                    test_file.replace('/', '.').replace('\\', '.').replace('.py', ''),
-                    '-v'
-                ], capture_output=False, cwd=project_root)
-                
-                if result.returncode != 0:
-                    total_failures += 1
-                    print(f"❌ Test file {test_file} had failures")
-                else:
-                    print(f"✅ Test file {test_file} passed")
-                    
-            except Exception as e:
-                print(f"❌ Error running {test_file}: {e}")
-                total_failures += 1
-        else:
-            print(f"⚠️  Test file not found: {test_file}")
-    
-    # Final summary
-    print(f"\n{'='*40}")
-    if total_failures == 0:
-        print("🎉 All tests completed successfully!")
-        return 0
-    else:
-        print(f"❌ {total_failures} test file(s) had issues")
-        return 1
-
-if __name__ == '__main__':
-    exit_code = main()
-    sys.exit(exit_code)

run_server.py

@@ -1,17 +1,34 @@
 #!/usr/bin/env python3
+"""
+Startup script for the Aniworld FastAPI application.
 
-import os
-import sys
-import subprocess
+This script starts the application with proper logging configuration
+and graceful shutdown support via Ctrl+C (SIGINT) or SIGTERM.
+"""
+import uvicorn
 
-# Change to the server directory 
-server_dir = os.path.join(os.path.dirname(__file__), 'src', 'server')
-os.chdir(server_dir)
+from src.infrastructure.logging.uvicorn_config import get_uvicorn_log_config
 
-# Add parent directory to Python path
-sys.path.insert(0, '..')
-
-# Run the app
-if __name__ == '__main__':
-    # Use subprocess to run the app properly
-    subprocess.run([sys.executable, 'app.py'], cwd=server_dir)
+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
+    )

src/Main.py

@@ -1,229 +0,0 @@
-import sys
-import os
-import logging
-from server.infrastructure.providers import aniworld_provider
-
-from rich.progress import Progress
-from server.core.entities import SerieList
-from server.infrastructure.file_system.SerieScanner import SerieScanner
-from server.infrastructure.providers.provider_factory import Loaders
-from server.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/__init__.py

@@ -1,3 +0,0 @@
-"""
-Command line interface for the AniWorld application.
-"""

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

@@ -1,49 +0,0 @@
-{
-    "security": {
-        "master_password_hash": "1353f6d9db7090c302864c2d6437dc11cc96cd66d59d7737d1b345603fdbdfda",
-        "salt": "a25e23440d681cef2d75c0adb6de0913359a1d8b9f98f9747fc75f53c79c4bd4",
-        "session_timeout_hours": 24,
-        "max_failed_attempts": 5,
-        "lockout_duration_minutes": 30
-    },
-    "anime": {
-        "directory": "\\\\sshfs.r\\ubuntu@192.168.178.43\\media\\serien\\Serien",
-        "download_threads": 3,
-        "download_speed_limit": null,
-        "auto_rescan_time": "03:00",
-        "auto_download_after_rescan": false
-    },
-    "logging": {
-        "level": "INFO",
-        "enable_console_logging": true,
-        "enable_console_progress": false,
-        "enable_fail2ban_logging": true,
-        "log_file": "aniworld.log",
-        "max_log_size_mb": 10,
-        "log_backup_count": 5
-    },
-    "providers": {
-        "default_provider": "aniworld.to",
-        "preferred_language": "German Dub",
-        "fallback_providers": [
-            "aniworld.to"
-        ],
-        "provider_timeout": 30,
-        "retry_attempts": 3,
-        "provider_settings": {
-            "aniworld.to": {
-                "enabled": true,
-                "priority": 1,
-                "quality_preference": "720p"
-            }
-        }
-    },
-    "advanced": {
-        "max_concurrent_downloads": 3,
-        "download_buffer_size": 8192,
-        "connection_timeout": 30,
-        "read_timeout": 300,
-        "enable_debug_mode": false,
-        "cache_duration_minutes": 60
-    }
-}

src/config/settings.py

@@ -0,0 +1,191 @@
+import re
+import secrets
+from typing import Optional
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings from environment variables."""
+    
+    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",
+        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)"
+    )
+
+    @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/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()