[NEEDS CODE REVIEWER] 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.

[lolimmlost]

Hey @ManiMatter. Thanks you for your honesty and I appreciate you wanting this project to continue. I personally would like to be a contributor. However I would need direction / goal in mind that we can work towards together. I am open to discussing what the future of the project may look like. Thanks for this opportunity.

…

On Sat, Apr 18, 2026 at 4:11 AM ManiMatter ***@***.***> wrote: *ManiMatter* left a comment (ManiMatter/decluttarr#337) <#337?email_source=notifications&email_token=ADBC4Q4G7LPLSTC5DZZ4AZL4WNPHLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMRXGM2TCMJVG44KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4273511578> 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. — Reply to this email directly, view it on GitHub <#337?email_source=notifications&email_token=ADBC4Q4G7LPLSTC5DZZ4AZL4WNPHLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMRXGM2TCMJVG44KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4273511578>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADBC4Q3BUVJF6NFQEKXD44T4WNPHLAVCNFSM6AAAAACWSAOXR2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DENZTGUYTCNJXHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[ManiMatter]

Hey @ManiMatter. Thanks you for your honesty and I appreciate you wanting this project to continue. I personally would like to be a contributor. However I would need direction / goal in mind that we can work towards together. I am open to discussing what the future of the project may look like. Thanks for this opportunity.
…
On Sat, Apr 18, 2026 at 4:11 AM ManiMatter @.> wrote: ManiMatter left a comment (ManiMatter/decluttarr#337) <#337?email_source=notifications&email_token=ADBC4Q4G7LPLSTC5DZZ4AZL4WNPHLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMRXGM2TCMJVG44KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4273511578> 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. — Reply to this email directly, view it on GitHub <#337?email_source=notifications&email_token=ADBC4Q4G7LPLSTC5DZZ4AZL4WNPHLA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTIMRXGM2TCMJVG44KM4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2LK4DSL5RW63LNMVXHIX3POBSW4X3DNRUWG2Y#issuecomment-4273511578>, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADBC4Q3BUVJF6NFQEKXD44T4WNPHLAVCNFSM6AAAAACWSAOXR2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DENZTGUYTCNJXHA . You are receiving this because you authored the thread.Message ID: @.>

hi @lolimmlost - Awesome, I am so glad you raise your hand to become a contributor.
I have just added you to the contributor list.

I also started a "Discussion", suggest we take the exchange there on what to focus on next / where to bring the tool from here. #345

[ManiMatter]

First of all - looks awesome. I think this is a massive improvement for the tool!
Some thoughts on this PR:

1. Could you update the Readme to point out that there is a UI now, how to use it etc?
2. This version will create an initial database; how do we deal with a future situation where changes to existing tables are needed? Would it make sense to already now use "alembic" (potentially in conjunction with sqlalchemy?).
   ̶3̶)̶ ̶/̶d̶a̶t̶a̶ ̶s̶h̶o̶u̶l̶d̶ ̶b̶e̶ ̶e̶x̶c̶l̶u̶d̶e̶d̶ ̶v̶i̶a̶ ̶.̶g̶i̶t̶i̶g̶n̶o̶r̶e̶/̶.̶d̶o̶c̶k̶e̶r̶i̶g̶n̶o̶r̶e̶ (done. see commits above)
   ̶4̶)̶ ̶a̶d̶d̶ ̶s̶u̶p̶p̶o̶r̶t̶ ̶t̶o̶ ̶r̶u̶n̶ ̶t̶h̶i̶s̶ ̶b̶e̶h̶i̶n̶d̶ ̶p̶r̶o̶x̶y̶ ̶(̶f̶o̶r̶ ̶i̶n̶s̶t̶a̶n̶c̶e̶ ̶w̶h̶e̶n̶ ̶o̶n̶ ̶c̶o̶d̶e̶s̶e̶r̶v̶e̶r̶)̶ (done. see commits above)
3. the "web" variables are currently stored in the "general" section of the settings class. I don't think that's right; they should be in "web" - Could you please amend? the proxy variable (4) I added above I also put in general since the web-section doesn't exist yet, please also move it along.
4. Do you think it could be possible to edit the instances also via the UI? The nested yaml structure to support the different instances is something that comes up in issues again and again. If this could be done more easily via UI, this would be a big win.
5. Also, managing the settings per the different jobs would be great; which would eliminate the need for users to fight yaml as they could configure everything via UI

[lolimmlost]

Hey @ManiMatter, thanks for the detailed feedback! I've addressed your requests in the latest commits:

Done in this PR:

• ✅ Container not starting #1 README — Added a Web UI section covering features, configuration (YAML + env vars), Docker port mapping, and how to disable it (d52a011)
• ✅ Container does not restart after an error #2 Database migration strategy — Added a lightweight schema versioning system with a schema_version table and numbered migrations. Avoids the Alembic dependency (overkill for 3-table SQLite) while making future schema changes safe for existing databases (3685932)
• ✅ Deleting automatically old DEV packages #5 Web settings in own section — Extracted web_enabled, web_host, web_port, and proxy_prefix from General into a dedicated Web settings class in src/settings/_web.py, following the same pattern as _jobs.py, _download_clients.py, etc. Updated all consumers (a05a812)

Already done (by you):

• ✅ Added branch protection and limited automated testing #3 .gitignore/.dockerignore — 63bb8e6
• ✅ Added branch protection and limited automated testing  #4 Proxy support — a840262

#6 (Instance editing via UI) and #7 (Full job config via UI):
The settings page already supports toggling jobs and adjusting max_strikes/min_speed at runtime (#7 partial). However, full instance editing (#6) and complete job config management (#7) would be significant additions — instance config involves nested YAML structures with API keys and multiple arr types.

Would it make sense to merge this PR as-is and open separate PRs for #6 and #7 as follow-up features? Happy to take those on as a contributor.

Also pushed a few additional fixes while testing:

• Fixed XSS vulnerability in queue table onclick handlers (switched to data-* attributes with event delegation)
• Fixed wait_and_exit() regression when web UI is disabled (non-web path now also gets restart-on-failure)
• Added SRI integrity hashes to CDN-loaded assets (Pico CSS, HTMX, Alpine.js)
• Fixed uvicorn root_path=None causing 400 Bad Request

[ManiMatter]

Thank you, @lolimmlost for the additional changes.
I think your proposal makes a lot of sense to keep 6) and 7) separate and this can be merged as first version.

Before merging though I think it would be good if somebody could review this code in more detail, as it is a relatively big addition.

Time wise I won‘t be able to do it myself. I hope somebody volunteers as additional maintainer to you & me and reviews/merges this.

@lolimmlost As you look into 6) and 7), would you be willing to review #311? The author there introduced per-instance overrides, which, if merged, would play into 7) (ie. full config via (UI) thus I see them related.

[lolimmlost]

Confirmed! I have accepted your request!

…

On Tue, Apr 28, 2026 at 10:05 AM ManiMatter ***@***.***> wrote: *ManiMatter* left a comment (ManiMatter/decluttarr#337) <#337 (comment)> Hey there, I just re-invited you to become a collaborator, here is what I see on my end: image.png (view on web) <https://github.com/user-attachments/assets/f963153e-948b-441a-a956-4693b8134c79> It's the first time I'm doing it, please let me know in case you haven't received an invite. — Reply to this email directly, view it on GitHub <#337 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADBC4Q6UDWKN76MEV65DY7T4YDQGDAVCNFSM6AAAAACWSAOXR2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGMZXGQ4TIOBYHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[ManiMatter]

Cool. feel free to take on anything you want, for example open PRs, issues, or suggest new changes as you see fit.
There are definitely items where this tool would benefit from a code overhaul (it's my first python project ever...), thus feel free to take a go at anything you'd like and feel fully free to take any decisions (and tag me in tickets if you want a second opinion) :)

Suggest we update #345 for wider discussions if needed.

[lolimmlost]

Hey @ManiMatter, did a self-review pass on this PR and pushed fixes for what I found. One thing I'd like your call on before merging — it came from your a840262 commit so I didn't want to touch it unilaterally.

The thing: in src/web/app.py:51 the proxy support builds:

root_path = f"/{proxy_prefix}/{port}" if proxy_prefix else ""

Embedding the listen port matches code-server's /proxy/<port>/... convention. But users behind nginx/Traefik/Caddy expect a clean prefix like /decluttarr without the port — current code generates a root_path they don't want.

Options:

1. Keep as-is, document that proxy_prefix is code-server-specific
2. Drop the port: root_path = f"/{proxy_prefix}", code-server users set proxy_prefix: "proxy/9999"
3. Add a flag like code_server_mode: true to switch formats

Leaning toward 2 — cleaner, and code-server still works with one extra path segment in config. What do you prefer?

[ManiMatter]

Hey @lolimmlost, thanks for asking. I agree with your proposal to go for option 2, so that the same setting can be used for any proxy