Clarify backend architecture boundaries

.github/.cursorrules

@@ -1,5 +1,17 @@
 # Listenarr Copilot Rules
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow:
+
+- `CONTRIBUTING.md`
+- `BACKEND_ARCHITECTURE.md`
+- `.github/RULES.md`
+- `.github/AGENTS.md`
+- `.github/copilot-instructions.md`
+
+Repository-specific guidance takes precedence over general examples in this file. Keep infrastructure-shaped dependencies out of `listenarr.application`; define application-owned ports there and implement adapters in infrastructure/API.
+
 ## Project Overview
 Listenarr is a C# .NET Core Web API backend with Vue.js frontend for automated audiobook downloading and processing. The backend uses ASP.NET Core with Entity Framework Core and SQLite, while the frontend uses Vue.js 3 with TypeScript, Pinia, and Vite.
 
@@ -306,4 +318,4 @@ var audiobooks = await _db.Audiobooks
 ```
 
 Remember: This project follows established patterns. When in doubt, look at existing code for examples of how similar functionality is implemented.</content>
-<parameter name="filePath">c:\Users\Robbie\Documents\GitHub\Listenarr\.cursorrules
+<parameter name="filePath">c:\Users\Robbie\Documents\GitHub\Listenarr\.cursorrules

.github/AGENTS.md

@@ -1,6 +1,18 @@
 ````markdown
 # Secure .NET Code Generation Codex
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow:
+
+- `CONTRIBUTING.md`
+- `BACKEND_ARCHITECTURE.md`
+- `.github/RULES.md`
+- `.github/copilot-instructions.md`
+- `.github/.cursorrules`
+
+Repository-specific guidance takes precedence over general examples in this file. Keep infrastructure-shaped dependencies out of `listenarr.application`; define application-owned ports there and implement adapters in infrastructure/API.
+
 As a security-aware developer, generate secure .NET code using ASP.NET Core that inherently prevents top security weaknesses.
 Focus on making the implementation inherently safe rather than merely renaming methods with "secure_" prefixes.
 Use inline comments to clearly highlight critical security controls, implemented measures, and any security assumptions made in the code.

.github/ANTHROPIC.md

@@ -1,5 +1,9 @@
 # Anthropic/Claude Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/AZURE_OPENAI.md

@@ -1,5 +1,9 @@
 # Azure OpenAI Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend for automated audiobook downloads. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/BARD.md

@@ -1,5 +1,9 @@
 # Google Bard/Gemini Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/BEDROCK.md

@@ -1,5 +1,9 @@
 # Amazon Bedrock Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/CLAUDE.md

@@ -1,6 +1,18 @@
 ````markdown
 # Secure Code Generation Rules for .NET/ASP.NET Core
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow:
+
+- `CONTRIBUTING.md`
+- `BACKEND_ARCHITECTURE.md`
+- `.github/RULES.md`
+- `.github/copilot-instructions.md`
+- `.github/.cursorrules`
+
+Repository-specific guidance takes precedence over general examples in this file. Keep infrastructure-shaped dependencies out of `listenarr.application`; define application-owned ports there and implement adapters in infrastructure/API.
+
 As a security-aware developer, generate secure .NET code using ASP.NET Core that inherently prevents top security weaknesses. Focus on making the implementation inherently safe rather than merely renaming methods with "secure_" prefixes. Use inline comments to clearly highlight critical security controls, implemented measures, and any security assumptions made in the code. Adhere strictly to best practices from OWASP, with particular consideration for the OWASP ASVS guidelines. **Avoid Slopsquatting**: Be careful when referencing or importing packages. Do not guess if a package exists. Comment on any low reputation or uncommon packages you have included.
 
 ---

.github/CLAUDE_LISTENARR.md

@@ -1,5 +1,9 @@
 # Claude AI Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Quick Reference
 This file contains Claude-specific guidance for the Listenarr audiobook management system. For comprehensive secure coding practices, see [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md). For complete project details, see [copilot-instructions.md](copilot-instructions.md).
 

.github/COHERE.md

@@ -1,5 +1,9 @@
 # Cohere Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/HUGGINGFACE.md

@@ -1,5 +1,9 @@
 # Hugging Face Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic provider guidance.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/OpenAI.md

@@ -1,5 +1,18 @@
 # OpenAI Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow:
+
+- `CONTRIBUTING.md`
+- `BACKEND_ARCHITECTURE.md`
+- `.github/RULES.md`
+- `.github/copilot-instructions.md`
+- `.github/AGENTS.md`
+- `.github/.cursorrules`
+
+Repository-specific guidance takes precedence over general examples in this file. Keep infrastructure-shaped dependencies out of `listenarr.application`; define application-owned ports there and implement adapters in infrastructure/API.
+
 ## Overview
 Listenarr is a C# .NET 10.0 audiobook management system with Vue.js 3 frontend. See [copilot-instructions.md](copilot-instructions.md) for complete details.
 

.github/RULES.md

@@ -2,6 +2,16 @@
 
 This folder contains comprehensive instructions for AI assistants working with the Listenarr audiobook management system.
 
+## Mandatory First Step
+
+Before making code, dependency, workflow, or documentation changes, AI agents must review and follow:
+
+- Repository contribution rules: [`../CONTRIBUTING.md`](../CONTRIBUTING.md)
+- Backend architecture boundaries: [`../BACKEND_ARCHITECTURE.md`](../BACKEND_ARCHITECTURE.md)
+- The primary AI guidance files listed below, especially [`copilot-instructions.md`](copilot-instructions.md), [`AGENTS.md`](AGENTS.md), and [`.cursorrules`](.cursorrules)
+
+If these documents conflict, follow the more specific repository guidance first. In particular, keep infrastructure-shaped dependencies out of `listenarr.application`; add application-owned ports and implement adapters in infrastructure/API.
+
 ## Primary Reference Files
 
 ### [copilot-instructions.md](copilot-instructions.md) - **MOST COMPREHENSIVE**
@@ -61,10 +71,11 @@ These files provide quick-start guidance tailored to specific AI providers, with
 
 ## Quick Start
 
-1. **For comprehensive project understanding**: Read [copilot-instructions.md](copilot-instructions.md)
-2. **For security compliance**: Read [AGENTS.md](AGENTS.md)
-3. **For coding standards**: Read [.cursorrules](.cursorrules)
-4. **For provider-specific guidance**: Choose your AI provider file above
+1. **Before changing anything**: Read [`../CONTRIBUTING.md`](../CONTRIBUTING.md) and [`../BACKEND_ARCHITECTURE.md`](../BACKEND_ARCHITECTURE.md)
+2. **For comprehensive project understanding**: Read [copilot-instructions.md](copilot-instructions.md)
+3. **For security compliance**: Read [AGENTS.md](AGENTS.md)
+4. **For coding standards**: Read [.cursorrules](.cursorrules)
+5. **For provider-specific guidance**: Choose your AI provider file above
 
 ## Project Overview (Quick Reference)
 

.github/WARP.md

@@ -2,6 +2,10 @@
 
 This file provides guidance to WARP (warp.dev) when working with code in this repository.
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic tool guidance.
+
 ## Project Overview
 
 Listenarr is an automated audiobook collection management system built as a full-stack application with a C# .NET 10 backend API and Vue.js 3 frontend. The project follows a monorepo structure with integrated build processes.

.github/clinerules

@@ -1,5 +1,9 @@
 # Cline AI Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic tool guidance.
+
 As a security-aware developer, generate secure .NET code using ASP.NET Core that inherently prevents top security weaknesses.
 Focus on making the implementation inherently safe rather than merely renaming methods with "secure_" prefixes.
 Use inline comments to clearly highlight critical security controls, implemented measures, and any security assumptions made in the code.

.github/copilot-instructions.md

@@ -2,6 +2,18 @@
 
 This is a complete C# .NET Web API backend with Vue.js frontend for automated audiobook downloading and processing.
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow:
+
+- `CONTRIBUTING.md`
+- `BACKEND_ARCHITECTURE.md`
+- `.github/RULES.md`
+- `.github/AGENTS.md`
+- `.github/.cursorrules`
+
+Repository-specific guidance takes precedence over general examples in this file. Keep infrastructure-shaped dependencies out of `listenarr.application`; define application-owned ports there and implement adapters in infrastructure/API.
+
 ## Project Overview
 - **Backend**: ASP.NET Core Web API (.NET 10.0+ / net10.0) with modular service architecture
 - **Frontend**: Vue.js 3 + TypeScript + Pinia + Vue Router + Vite

.github/windsurfrules

@@ -6,6 +6,10 @@ globs: **/*.cs, **/*.csproj, **/*.json, **/*.xml, **/*.vue, **/*.ts
 
 # Windsurf AI Instructions for Listenarr
 
+## Required Repository Context
+
+Before making code, dependency, workflow, or documentation changes, review and follow `CONTRIBUTING.md`, `BACKEND_ARCHITECTURE.md`, `.github/RULES.md`, and the primary AI guidance files. Repository-specific guidance takes precedence over generic tool guidance.
+
 As a security-aware developer, generate secure .NET code using ASP.NET Core that inherently prevents top security weaknesses.
 Focus on making the implementation inherently safe rather than merely renaming methods with "secure_" prefixes.
 Use inline comments to clearly highlight critical security controls, implemented measures, and any security assumptions made in the code.

BACKEND_ARCHITECTURE.md

@@ -0,0 +1,47 @@
+# Backend Architecture Boundaries
+
+Listenarr is moving toward a layered backend where each project has a clear job:
+
+- `listenarr.domain` owns the domain model, value objects, domain exceptions, and business rules that do not need hosting, persistence, files, or network access.
+- `listenarr.application` owns use-case orchestration, application services, DTOs, mapping, and contracts that other layers implement. It can coordinate work, but it should avoid owning persistence, file, network, parsing, or image-processing implementations.
+- `listenarr.infrastructure` owns concrete adapters for technical concerns: EF Core and SQLite persistence, filesystem work, external HTTP clients, metadata/tagging libraries, HTML scraping/parsing, image inspection, cache implementations, SignalR infrastructure, and downloader integrations.
+- `listenarr.api` is the composition and hosting layer. It wires dependency injection, controllers, middleware, Swagger/OpenAPI, auth policy, and request pipeline behavior.
+
+## Current Decision
+
+The diagram describes the intended boundary: application is business/use-case logic and infrastructure is persistence, files, and external adapters. The codebase is still in transition, but implementation-specific packages should be kept out of `listenarr.application` unless there is a documented reason to do otherwise.
+
+New implementation-specific dependencies should go in `listenarr.infrastructure`. The application layer should define contracts and coordinate use cases; infrastructure should implement those contracts with EF Core, filesystem, HTTP, parsing, image, tagging, and other adapter libraries.
+
+The application project should not reference SQLite providers, EF Core implementation packages, Swagger/OpenAPI packages, HTML parsers, image libraries, audio tagging libraries, ASP.NET Core hosting types, SignalR hubs, HTTP context, or data-protection implementations directly. SQLite and EF Core belong to infrastructure, Swagger/OpenAPI belongs to API, hosted adapters and SignalR delivery belong to infrastructure/API, and parsing/tagging/image inspection belong behind application ports implemented by infrastructure.
+
+## Boundary Cleanup
+
+The application layer now delegates these infrastructure-shaped concerns through interfaces:
+
+- EF Core update failures are translated by infrastructure into application-owned `PersistenceException` types before they leave persistence.
+- TagLibSharp ASIN writing is behind `IAudioTagWriter`, implemented by infrastructure.
+- ImageSharp cover probing is behind `ICoverImageProbe`, implemented by infrastructure.
+- HtmlAgilityPack text extraction and Audible author-page parsing are behind `IHtmlTextExtractor` and `IAudibleAuthorPageParser`, implemented by infrastructure.
+- Hosted services and SignalR hubs live in infrastructure. Application code publishes client events through `IHubBroadcaster` instead of referencing hubs or `IHubContext`.
+- HTTP request details are exposed to application services through `IRequestContextAccessor`, with ASP.NET Core adaptation handled outside application.
+- Secret protection is exposed through `ISecretProtector`, with Data Protection implemented in infrastructure.
+- `listenarr.application` no longer has an ASP.NET Core framework reference. It may reference general `Microsoft.Extensions.*` abstractions for logging, options, caching, dependency-factory access, and HTTP client factories, but it should not reference host/web implementation packages.
+
+## Migration Direction
+
+Use this pattern when moving a concern out of application:
+
+1. Keep the application-level interface, DTOs, and result models in `listenarr.application` or `listenarr.domain`.
+2. Move the concrete implementation to the appropriate `listenarr.infrastructure` feature or technology folder.
+3. Register the implementation in `listenarr.infrastructure/Extensions/InfrastructureServiceRegistrationExtensions.cs`.
+4. Keep `listenarr.api` responsible for calling the registration extension and composing the host.
+5. Add or update focused tests before deleting the old implementation.
+
+Recommended follow-up slices:
+
+- Revisit background workers that combine orchestration with persistence or filesystem details and split the use case from the hosted adapter.
+- Continue replacing direct service-locator patterns with narrower application ports where a worker or service only needs one operation from another layer.
+- Keep new host-specific concerns in API or infrastructure and expose them to application through small application-owned contracts.
+
+Until those slices are complete, reviewers should treat any new infrastructure-shaped application dependency as a boundary regression unless it is explicitly documented.

CONTRIBUTING.md

@@ -400,6 +400,7 @@ If you have any questions about contributing, please:
 ---
 
 ## Layering rules & migration steps (practical)
+- Backend project boundaries are documented in `BACKEND_ARCHITECTURE.md`. Keep infrastructure-shaped dependencies out of `listenarr.application`; add an application-owned port and implement the adapter in infrastructure/API instead.
 - Keep contracts (interfaces, DTOs, domain models) in `listenarr.application` or `listenarr.domain`.
 - Keep framework-dependent implementations (EF Core, HttpClients, filesystem) in `listenarr.infrastructure`.
 - `listenarr.api` should only compose services, host controllers, and register DI; do not add new interfaces that duplicate application/infrastructure contracts.

Directory.Packages.props

@@ -20,7 +20,12 @@
 		<PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="$(EFVersion)" />
 		<PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="$(EFVersion)" />
 		<PackageVersion Include="Microsoft.EntityFrameworkCore.Sqlite" Version="$(EFVersion)" />
+		<PackageVersion Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.8" />
+		<PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.8" />
+		<PackageVersion Include="Microsoft.Extensions.Http" Version="10.0.8" />
 		<PackageVersion Include="Microsoft.Extensions.Http.Polly" Version="10.0.8" />
+		<PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.8" />
+		<PackageVersion Include="Microsoft.Extensions.Options" Version="10.0.8" />
 		<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.6.0" />
 		<PackageVersion Include="Moq" Version="4.20.72" />
 		<PackageVersion Include="Polly" Version="8.6.6" />

listenarr.api/Attributes/LocalOrAdminAttribute.cs

@@ -1,4 +1,3 @@
-using Listenarr.Application.Security;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.AspNetCore.Mvc.Filters;
 
@@ -9,8 +8,8 @@ public class LocalOrAdminAttribute : Attribute, IAuthorizationFilter
     {
         public void OnAuthorization(AuthorizationFilterContext context)
         {
-            var isLoopback = SecurityRequestUtils.IsLoopbackRequest(context.HttpContext);
-            var isAuth = SecurityRequestUtils.IsAuthenticatedAdminOrApiKey(context.HttpContext);
+            var isLoopback = HttpSecurityRequestUtils.IsLoopbackRequest(context.HttpContext);
+            var isAuth = HttpSecurityRequestUtils.IsAuthenticatedAdminOrApiKey(context.HttpContext);
 
             if (!isLoopback && !isAuth)
             {