Proposal: Enforce Backend Boundaries Through Project Separation

[hypnotoad08]

Introduction

While reviewing the backend, I noticed two areas where the current project boundaries could be clearer.

First, some code in Listenarr.Application does work that would normally
belong in Infrastructure. For example, AudibleService makes HTTP requests to
Audible from the Application project.

Second, Listenarr.Infrastructure already separates external integrations,
persistence, filesystem access, and download clients by namespace. Promoting
those namespaces into projects would allow the compiler to enforce the
boundaries that are currently maintained through code organization.

Proposed Changes

Step 1: Move the Existing Application Contracts into Their Own Project

Listenarr.Application already organizes its contracts by feature under
listenarr.application/<Feature>/Contracts/. Move those contracts into a new
Listenarr.Application.Contracts project while keeping their feature
ownership.

The project name supplies the Contracts boundary, so the existing folder
structure should be flattened instead of repeating Contracts beneath every
feature:

Listenarr.Application.Contracts/
├── Common/
├── Audiobooks/
│   └── Repositories/
├── Downloads/
├── Search/
└── Security/

For example, the resulting namespaces would be
Listenarr.Application.Contracts.Common,
Listenarr.Application.Contracts.Audiobooks, and
Listenarr.Application.Contracts.Audiobooks.Repositories—not
Listenarr.Application.Contracts.Audiobooks.Contracts.

This includes service contracts, repository contracts currently under
Contracts/Repositories, and the request, result, or projection models used by
those contracts.

This lets Infrastructure projects implement Application contracts without
referencing the full Listenarr.Application project.

Interfaces used only inside one project stay with that project.

Step 2: Promote Infrastructure Namespaces into Projects

Listenarr.Infrastructure already organizes several responsibilities by
namespace. I'd propose promoting those boundaries into projects:

• Listenarr.Infrastructure.ExternalServices: Audible, metadata providers, indexers, notification services.
• Listenarr.Infrastructure.Persistence: database access.
• Listenarr.Infrastructure.Filesystem: local file operations.
• Listenarr.Infrastructure.DownloadClients: downloader integrations.
• Listenarr.Infrastructure.Http: shared HTTP configuration and policies used by projects that make outbound requests.

Listenarr.Infrastructure would remain for shared infrastructure and concerns
that do not need a separate project. It would become smaller as the larger,
well-defined responsibilities move out.

Code inside each project would remain organized by feature first and technical
role second, following the existing backend convention.

End State

Current project dependencies:

Listenarr.Api
├── Listenarr.Application
├── Listenarr.Infrastructure
└── Listenarr.Domain

Listenarr.Infrastructure
├── Listenarr.Application
└── Listenarr.Domain

Listenarr.Application
└── Listenarr.Domain

Proposed project dependencies:

Listenarr.Api
├── Listenarr.Application
├── Listenarr.Infrastructure
└── Listenarr.Domain

Listenarr.Application
├── Listenarr.Application.Contracts
└── Listenarr.Domain

Listenarr.Application.Contracts
└── Listenarr.Domain

Listenarr.Infrastructure
├── Listenarr.Application
├── Listenarr.Infrastructure.ExternalServices
├── Listenarr.Infrastructure.Persistence
├── Listenarr.Infrastructure.Filesystem
├── Listenarr.Infrastructure.DownloadClients
└── Listenarr.Domain

Listenarr.Infrastructure.ExternalServices
├── Listenarr.Application.Contracts
├── Listenarr.Infrastructure.Http
└── Listenarr.Domain

Listenarr.Infrastructure.Persistence
├── Listenarr.Application.Contracts
└── Listenarr.Domain

Listenarr.Infrastructure.Filesystem
├── Listenarr.Application.Contracts
└── Listenarr.Domain

Listenarr.Infrastructure.DownloadClients
├── Listenarr.Application.Contracts
├── Listenarr.Infrastructure.Http
└── Listenarr.Domain

Listenarr.Domain has no project dependencies in either structure.

Listenarr.Infrastructure remains the API's single entry point for
infrastructure registration. It delegates each responsibility to the focused
Infrastructure project that owns it, while the API remains responsible for
wiring the application together at startup.

Expected Benefits

• A clear answer to "where does this go?" for new integrations and
  infrastructure code.
• Business logic can be tested without calling Audible, a database, or the
  filesystem.
• Providers can be replaced or added without changing the business workflow.

Finding and Migrating Existing Code

A common approach to a refactor like this is to define code that crosses the
agreed boundaries as named anti-patterns and use analyzers to identify it. This
creates an inventory of code that needs to be cleaned up and gives contributors
clear guidance for migrating each occurrence to the new pattern without
requiring one large refactor.

For example:

[ArchitectureAntiPattern(
    ArchitectureAntiPatternKind.OutboundHttpInBusinessLayer,
    "This Application service calls an external API directly instead of using an external-service adapter.")]

A small analyzer could show these as warnings. Each anti-pattern would link to
a Markdown page containing an incorrect example, a correct example, and steps
for resolving it.

This would make the existing debt visible and give contributors enough context
to remove an anti-pattern when they are already working in that area. The
warnings could remain advisory unless there is later agreement to enforce a
rule after its existing uses have been removed.