feat: Add lightweight web UI for monitoring, activity history & runtime control

[lolimmlost]

Summary

Decluttarr currently has zero visibility into what it's doing — all config is YAML, all output is logs. This PR adds a lightweight web UI for monitoring, activity history, and runtime control without changing the existing daemon behavior.

• Dashboard — real-time queue view across all arr instances, instance status cards, live activity feed, "Run Now" button
• Activity Log — searchable, filterable, paginated history of every action (flags, removals, recoveries, strikes) stored in SQLite
• Settings Editor — toggle test_run, enable/disable jobs, adjust max_strikes/min_speed at runtime without editing YAML or restarting
• Download Protection — protect individual downloads from removal via the UI (supplements the qBit "Keep" tag)
• REST API — full JSON API with auto-generated OpenAPI docs at /api/docs
• SSE Live Updates — server-sent events push changes to the browser in real time

Tech Choices

Component	Choice	Why
Web framework	FastAPI	Async-native (shares existing asyncio loop), lightweight, built-in OpenAPI
Frontend	Jinja2 + HTMX + Alpine.js	No build step, no Node tooling in a Python project
Styling	Pico CSS (dark theme)	Classless CSS, minimal custom styles needed
Persistence	SQLite via aiosqlite	Zero config, file-based, auto-creates on first run
Real-time	Server-Sent Events	Simpler than WebSockets, unidirectional, HTMX-compatible

Architecture

The web server runs as a sibling asyncio task alongside the existing main loop — both share the same event loop and process memory. An EventBus class decouples the job system from the UI: jobs emit events at decision points, the web layer (ActivityRecorder + SSE) consumes them. When web is disabled, a NoOpEventBus is used with zero overhead.

Job System → EventBus → ActivityRecorder (writes SQLite)
                      → SSE endpoint (pushes to browser)

Browser → FastAPI API → reads Tracker state (queue/strikes)
                      → reads/writes SQLite (activity, config, protected)
                      → mutates Settings object (runtime config)

Database Schema (SQLite)

Three tables: activity_log (action history), protected_downloads (UI-managed protection), config_overrides (runtime config layered on top of YAML). Auto-created at ./data/decluttarr.db.

API Endpoints

Method	Path	Purpose
GET	/api/status	Uptime, test_run state, instance count
GET	/api/queue	Current queue across all arr instances with strike info
GET	/api/activity	Paginated activity log with filters
GET	/api/strikes	Current strike data across all trackers
POST/DELETE	/api/protected/{id}	Protect/unprotect a download
GET/PATCH	/api/config	Read/update runtime config
POST	/api/config/test-run	Toggle test_run on/off
POST	/api/config/reload	Reset overrides to YAML defaults
GET	/api/events	SSE stream for real-time updates
POST	/api/trigger	Manually trigger a job cycle

Configuration

Zero new required config. Defaults to enabled on port 9999.

# config.yaml (optional)
web:
  enabled: true    # or WEB_ENABLED=false to disable
  host: "0.0.0.0"
  port: 9999

Migration / Backward Compatibility

• Defaults to enabled but works with zero config — existing YAML configs unaffected
• No new required env vars — all web settings have sensible defaults
• Event bus is no-op when web is disabled — zero overhead on existing behavior
• Database auto-creates on first run
• All 192 existing tests pass unchanged

New Dependencies

fastapi==0.115.6
uvicorn[standard]==0.34.0
aiosqlite==0.20.0
jinja2==3.1.5
python-multipart==0.0.20

Files Changed

New (15 files in src/web/): events.py, database.py, app.py, routes.py, config_manager.py, templates (base, dashboard, activity, settings, 4 partials), static/style.css

Modified (11 files): main.py, job_manager.py, removal_job.py, removal_handler.py, strikes_handler.py, _general.py, _user_config.py, _instances.py, Dockerfile, requirements.txt, config_example.yaml

Screenshots

The UI uses Pico CSS dark theme with color-coded badges for arr instances (Sonarr=blue, Radarr=yellow, etc.), action types (removed=red, recovered=green, flagged=amber), and strike counts.

Test Plan

• pytest tests/ — all 192 existing tests pass
• Web UI loads at http://localhost:9999
• Job loop still runs on timer (verified via logs)
• Queue table shows downloads with strike/protection status
• Protect/unprotect buttons work and survive next cycle
• test_run toggle via settings page takes immediate effect
• "Run Now" button triggers early cycle
• Activity log records and displays actions
• Docker build succeeds with EXPOSE 9999
• Verify with WEB_ENABLED=false that web is fully disabled
• Test with multiple concurrent SSE clients

🤖 Generated with Claude Code

[Rubilmax]

Can we get this reviewed and merged please?

[lolimmlost]

Can we get this reviewed and merged please?

I appreciate your enthusiasm but definitively needs testing as I'm getting webui errors after a weeklong usage. I'll review the code once again this weekend.

[Rubilmax]

Amazing, thanks 🙏

[lolimmlost]

I'm attempting this fix for the crashing.

[lolimmlost]

Pushed a fix for a crash that was happening after ~1 week of uptime.

Root cause: When Sonarr/Radarr timed out (read timeout=15s), the unhandled exception propagated up through asyncio.gather(main_task, web_task), which cancelled the web server task too — killing the entire app.

Fix (commit 25f3e2f):

• Wrapped per-instance job runs and download client jobs in try/except so timeouts log an error and continue to the next cycle
• Added main_with_restart() wrapper so even unexpected failures auto-recover after 30s while the web UI stays up independently

Verified running 24hrs+ on production with multiple Sonarr/Radarr timeouts — all recovered cleanly on the next cycle, no crashes.

[lolimmlost]

I have tested the new fixes with 100% uptime after 48 hours. Ill be working on ui improvements; log pruning and api cache control.
Is pasword protections something we'd like for this but i assume the end user can secure it however they'd like. (cf access)

[ManiMatter]

hi, I am truly sorry I haven't looked into your PR in such a long time. I do appreciate very much that you took the time to contribute.

Unfortunately, I don't have the time to look into it still.
To overcome me being the bottleneck, I am looking to open this repo up to other people who help maintain it, and contributors can review each others code / merge.

Would you be willing to act as a formal contributor? If yes, I will add you, and if I find others (from open PRs), hopefully you can review each others PR and they can be merged.

Thanks for letting me know, and apologies again for my radio silence.