Backend architecture priorities: stabilize tests, boundaries, and runtime workflows

[therobbiedavis]

Why I’m opening this

I want to take a step back and make sure the backend stays easy to trust as the project grows.

We've made a lot of changes to the backend already so it has a lot of the right pieces already thanks to @T4g1: separate projects, a real test suite, security middleware, background workers, and dedicated services for imports, downloads, search, metadata, and filesystem work. The concern is not that the backend is going in the wrong direction. The concern is that some of the most important behavior is now spread across a few very large files and several background loops, and the current test/build state makes it harder to move confidently.

This issue is a roadmap for tightening the backend before more features pile on top of it.

Subtasks

• Get the dependencies aligned to ensure consistent environment for testing Stabilize dependency restores and frontend build validation #679

  • dotnet test listenarr.slnx --no-restore currently fails before tests run because package versions are resolving inconsistently, especially EF Core 10.0.7 vs 10.0.8.
  • Clean up the central package/version setup so CI and local test runs use the same dependency graph.
  • This should come first, because I need a green validation loop before doing meaningful refactors.

• Make the architecture boundaries clear and intentional

  • The current backend diagram (see below) describes application as business logic and infrastructure as persistence/files/external adapters.
  • In practice, listenarr.application still references infrastructure-shaped packages like EF Core/SQLite, HtmlAgilityPack, ImageSharp, TagLibSharp, and Swagger-related packages.
  • Decide what belongs in application vs infrastructure, then either move those concerns behind interfaces or update the architecture docs if the current boundary is intentional.

• Break down the biggest controllers and services into focused workflows

  • LibraryController, SearchService, AudibleService, and several adapter/controller files have grown large enough that they are harder to reason about safely.
  • Extract focused use-case services for things like scanning, import planning, metadata lookup, search orchestration, mapping, and validation.
  • Keep behavior unchanged while doing this. The goal is safer future work, not a big rewrite.

• Rationalize background workers and queue ownership

  • Listenarr has many hosted services: scans, moves, cache cleanup, download monitoring, completed-download processing, queue monitoring, automatic search, author/series sync, ffmpeg install, metadata rescan, processing jobs, and unmatched scans.
  • Define which worker owns each state transition and what retry/backoff/idempotency rules apply.
  • Add focused tests around the handoffs between downloads, imports, scans, and moves.

• Harden file/import safety paths

  • This is the highest user-trust area because Listenarr touches real library files through moves, hardlinks/copies, scans, remote path mapping, archive extraction, image caching, and ffprobe.
  • Strengthen path containment checks, idempotent imports, resumable jobs, and audit/logging around file mutations.
  • Prefer tests that use real temporary directories so filesystem behavior is verified instead of only mocked.

• Simplify startup and security composition

  • Program.cs still carries a lot: config creation, logging, API versioning, auth/CSRF, migrations, SignalR, static files, Swagger, HTTP clients, and hosted-service toggles.
  • Extract startup modules so service registration and the request pipeline are easier to audit.
  • Add end-to-end coverage for auth enabled/disabled, API keys, session cookies, CSRF, SignalR auth, and reverse-proxy headers.

Suggested order

1. Fix dependency drift so tests compile and run.
2. Add or repair tests around the riskiest runtime paths.
3. Extract large workflows in small behavior-preserving steps.
4. Move infrastructure concerns out of application as the boundaries become clearer.
5. Update the architecture diagram/documentation to match the final decisions.

Notes

• Repository interfaces currently live under listenarr.application/Interfaces/Repositories, not listenarr.domain, so the backend diagram should be corrected or the boundary should be made explicit.
• This issue is not meant as a “rewrite the backend” ticket. It is a maintainer roadmap for reducing risk, making behavior easier to verify, and keeping Listenarr pleasant to develop.