Backend Python Architecture & Documentation
This document provides a technical overview of the Python backend files used in Posterizarr's WebUI. The backend is built using FastAPI and serves as the intermediary between the React frontend and the underlying PowerShell scripts or local databases.
Architecture Overview
The backend handles the following core responsibilities:
- API Endpoints: Serves data to the frontend (FastAPI).
- Configuration Management: Reads, writes, and maps the
config.jsonfile. - Database Operations: Manages SQLite databases for runtime statistics, exported media, and caching.
- Task Orchestration: Triggers PowerShell scripts via a queue manager or scheduler.
File Breakdown (webui\backend\)
Core API & Application
main.py: The primary FastAPI application entry point. It defines all the API routes, initializes the server, handles CORS, and integrates with other backend modules.auth_middleware.py: Handles authentication and security middleware for the FastAPI routes, ensuring that unauthorized users cannot trigger operations or read configurations (includes strict API Key requirements for webhooks).
Configuration & Data Mapping
config_database.py: Interacts with the backend database storing configuration states.config_mapper.py: A crucial file that maps frontend JSON/API payloads to the expectedconfig.jsonformat required by the PowerShell scripts. It ensures data sanitization and type casting.config_tooltips.py: Stores the tooltip descriptions and metadata for configuration fields, served dynamically to the frontendConfigEditor.defaults.py: Contains default settings, schemas, and fallback configurations for the application.
Databases & State
database.py: The core SQLAlchemy/SQLite configuration file that establishes connections and base models.media_export_database.py: Manages the database schema and operations for media exported from Plex/Jellyfin/Emby.overlay_cache.py: Managesoverlay_cache.db(Dynamic Overlays fingerprints, media ratings metadata, layer snapshots, and title-change tracking) and implements the read-only multi-database inspector backing/api/dynamic-overlays/database-statsand/api/dynamic-overlays/database-entries(strictly excludingconfig.db).runtime_database.py: Manages the schema for runtime statistics (successes, failures, durations).server_libraries_database.py: Caches the library configurations of connected media servers.
Task Management & Scheduling
queue_manager.py: Manages the execution queue for PowerShell scripts, ensuring that multiple operations (like manual generation vs library sync) don't conflict or overlap destructively.scheduler.py: Handles cron-like scheduling for automated tasks (e.g., triggeringPosterizarr.ps1at set intervals).runtime_parser.py: Parses the output of the PowerShell scripts to update theruntime_database.pywith execution statistics.
Utilities & Helpers
logs_watcher.py: A dual-purpose background watcher that monitors Posterizarr log files in real-time (allowing the frontend to stream logs via WebSockets) and tracks newly appended entries inLogs/ImageChoices.csvto broadcast real-timeasset_updatedWebSocket events to media server plugins (Jellyfin/Emby) without requiring polling or filesystem hooks on the assets folder.plex_push_service.py: Lightweight, standalone Plex push and synchronization service. Provides collection matching and normalization ([boxset],&/and, trailing keywords), visual diff state calculations (synced,update_available,missing_server,missing_local), thread-safe SQLite change caching (database/plex_push_cache.db), single/batch REST poster uploads to Plex Media Server, and scheduled background sync execution for selected libraries and asset types without invoking PowerShell.improve_logging.py: Enhances standard Python logging for the backend application.overlay_generator.py: A backend helper script used for generating quick preview overlays for the UI without invoking the full PowerShell stack.studio_logos.py: Handles studio, network, and production company logo resolution, local caching, and transparent PNG delivery for collection designs and media badges.migrate_runtime_data.py: A migration script used to upgrade database schemas or runtime data formats between versions.release_notes.py: TTL-cached GitHub Releases fetcher, strict stable SemVer parser, and post-update "What's New" evaluator backing/api/releases,/api/whats-new, and/api/whats-new/dismiss.support_bundle.py: Builds the diagnostic ZIP requested byPOST /api/admin/support-zip, independently of application startup tasks.animetafill_service.py: Integration service bridging AniMetaFill into Posterizarr's backend. Coordinates anime canon/filler classification tasks, library scans, and triggers overlay generation.animetafill_core/: Core engine for anime episode classification:classifier.py: Evaluates episode data against SIMKL and AnimeFillerList providers.database.py: Local SQLite cache for anime episode classifications and sync states.media_scanner.py: Scans Plex, Jellyfin, and Emby servers for configured anime libraries.overlay_yaml.py(OverlayYamlGenerator): Generates and parses unified episode overlay YAML files (anime_overlays.yml).sonarr_client.py: Maps absolute episode numbers to season/episode numbers via Sonarr.
Security Utilities (main.py)
is_safe_url(url, allow_private, allow_apprise_schemes): Validates URL schemes (http/httpsor custom Apprise schemes) and resolves DNS hostnames to ensure loopback (127.0.0.1,localhost,::1) and private/link-local/multicast IP addresses are strictly blocked against SSRF attacks (unless private network access is explicitly authorized for configured media servers).get_safe_path(base_dir, user_path): Enforces strict directory containment, preventing path traversal attacks when resolving user-specified asset files or collection presets.sanitize_command_arg(arg): Cleans command line arguments passed to PowerShell, stripping null bytes and non-printable control characters, and disallowing unintended flag injections.mask_secret(secret): Redacts sensitive strings (API keys, tokens, passwords) before writing to server logs.
Log Retention
Service diagnostics and per-item progress are not mirrored into BackendServer.log
or FrontendUI.log. Ratings/provider refresh details stay in RatingsRefresh.log,
overlay synchronization in DynamicOverlaysSync.log, and episode-title comparison
and recreation in EpisodeTitleChanges.log. Plex Sync, image cleanup, AniMetaFill,
and overlay-default updates retain their own service logs. Scheduler orchestration
is recorded in Scheduler.log. These logs are available separately in the log viewer;
general backend/API and browser diagnostics retain their existing UI log targets.
Backend/container startup does not delete or truncate logs. In Docker, UILogs lives under the persistent /config volume. BackendServer.log and FrontendUI.log append across restarts because they record continuous server activity rather than individual jobs.
These two continuous logs rotate at approximately 10 MiB per active file and
retain three numbered backups (.log.1 through .log.3). Backend and browser
entries in FrontendUI.log share the same thread-safe handler, including the
single and batch UI-log endpoints. Individual formatted records are limited to
32,768 characters with a truncation marker, so one large UI payload cannot grow
the active log without bound. An already oversized log rotates on the next
write; its full previous contents are initially retained in the first backup
until normal backup rotation ages it out. No blanket startup cleanup is used.
EpisodeTitleChanges.log and Scheduler.log use the same bounded continuous-log
rotation rather than being reset by background scans.
When a Python job actually starts, its previous active log is renamed to Name.old.log and the new run writes a fresh Name.log. One previous run is retained; the next rotation replaces that backup. This applies to Plex Sync, Dynamic Overlays Sync, Overlay Defaults, Ratings Refresh, AniMetaFill, and Plex Image Cleanup. Rejected/busy jobs do not rotate logs. If rotation fails, the existing log is retained and new output is appended rather than discarded. The .old.log files remain available in the log viewer.
PowerShell runs keep their existing timestamped archive behavior under RotatedLogs; backend startup does not clear those archives.
Support Bundles
The Generate Support Logs action includes application/UI logs, selected change-detection JSON reports, scheduler and application configuration, Dynamic Overlays/AniMetaFill JSON settings, active overlay YAML files, and default templates. Legacy JSON locations and the older Overlayfiles/kometa directory are supported.
Database exports include media_export.db, runtime_stats.db, server_libraries.db, imagechoices.db, overlay_cache.db, animetafill.db, and plex_push_cache.db when present. SQLite's backup API captures a consistent committed snapshot, including WAL-backed updates, without changing the source database. Overlay layer snapshots remain available for recipe-drift diagnosis.
JSON/YAML settings and database text are sanitized before packaging. Credentials, supported notification URLs, and local addresses are masked. Sanitized databases are compacted to remove old values from unused pages. If a selected file cannot be parsed, backed up, or sanitized, the export fails rather than returning an unsanitized archive. Failed exports remove their temporary staging directory; successful downloads retain the existing background cleanup.
Artwork, fonts, quarantine contents, links/junctions, SQLite sidecar files, and compressed log archives are not included. Support bundles still contain diagnostic library titles and paths; review the ZIP before sharing it publicly.
Contribution Guidelines
When making a Pull Request to the Python backend:
- New Endpoints: Define routes in
main.py(or a dedicated router file if it grows) and ensure they are protected byauth_middleware.pyor appropriate security decorators. - Database Schema Changes: Ensure you provide a migration strategy or update
migrate_runtime_data.pyso existing users do not lose their data. - Configuration Parsing: If a new feature introduces a new
config.jsonfield, updateconfig_mapper.pyand provide a tooltip inconfig_tooltips.py. - Security Protections: When proxying remote URLs or writing local files, always apply
is_safe_urlandget_safe_path.