Refactor solution to adopt a Clean Architecture-inspired structure

[nanotaboada]

Description

The current folder structure follows a traditional layered architecture (Controllers → Services → Repositories → Data) which, while functional, has some architectural limitations:

src/Dotnet.Samples.AspNetCore.WebApi/
├── Controllers/                                # HTTP/API concerns
├── Services/                                   # Business logic + orchestration
├── Repositories/                               # Data access abstractions & implementations
├── Data/                                       # EF Core DbContext
├── Models/                                     # Mix of entities + DTOs
├── Enums/                                      # Domain enums
├── Validators/                                 # Input validation
├── Mappings/                                   # Object mapping
├── Utilities/                                  # Various utilities
├── Configurations/                             # Infrastructure configuration
└── Extensions/                                 # Service registration

• Business logic is mixed across multiple layers
• Dependencies flow in all directions, making testing difficult
• Tight coupling between infrastructure and business logic
• Limited ability to swap implementations (database, external services)

This issue proposes migrating to Clean Architecture-inspired folder structure to improve maintainability, testability, and adherence to SOLID principles.

Proposed Solution

Restructure the project into Clean Architecture layers with proper dependency inversion:

src/
├── Dotnet.Samples.AspNetCore.WebApi.Domain/
│   ├── Entities/
│   │   └── Player.cs                            # Pure domain entity
│   └── Enums/
│       ├── Enumeration.cs
│       └── Position.cs
│
├── Dotnet.Samples.AspNetCore.WebApi.Core/
│   ├── DTOs/
│   │   ├── PlayerRequestModel.cs                # Input DTOs
│   │   └── PlayerResponseModel.cs               # Output DTOs
│   ├── Interfaces/
│   │   ├── IPlayerRepository.cs                 # Repository contracts
│   │   ├── IPlayerService.cs                    # Service contracts
│   │   └── IRepository.cs                       # Generic contracts
│   ├── Services/
│   │   └── PlayerService.cs                     # Business logic orchestration
│   ├── Validators/
│   │   └── PlayerRequestModelValidator.cs
│   ├── Mappings/
│   │   └── PlayerMappingProfile.cs
│   └── Exceptions/                              # Custom business exceptions
│
├── Dotnet.Samples.AspNetCore.WebApi.Infrastructure/
│   ├── Data/
│   │   └── PlayerDbContext.cs
│   ├── Repositories/
│   │   ├── Repository.cs                        # Generic implementation
│   │   └── PlayerRepository.cs                  # Specific implementation
│   ├── Migrations/                              # EF Core migrations
│   └── Extensions/                              # Infrastructure-specific extensions
│
└── Dotnet.Samples.AspNetCore.WebApi.Api/
    ├── Controllers/
    │   └── PlayerController.cs
    ├── Configurations/
    ├── Extensions/
    │   └── ServiceCollectionExtensions.cs       # DI configuration
    ├── Utilities/                               # Presentation utilities
    └── Program.cs                               # Application entry point

Dependency Flow

Api → Core → Domain
Infrastructure → Core → Domain

Suggested Approach

1. Create Domain project (Domain/)

   • Move Models/Player.cs → Domain/Entities/Player.cs
   • Move Enums/ → Domain/Enums/
   • No external dependencies

2. Create Core project (Core/)

   • Move Services/ → Core/Services/
   • Move Models/PlayerRequestModel.cs, PlayerResponseModel.cs → Core/DTOs/
   • Move Repositories/IPlayerRepository.cs, IRepository.cs → Core/Interfaces/
   • Move Validators/ → Core/Validators/
   • Move Mappings/ → Core/Mappings/
   • Reference: Domain only

3. Create Infrastructure project (Infrastructure/)

   • Move Repositories/Repository.cs, PlayerRepository.cs → Infrastructure/Repositories/
   • Move Data/ → Infrastructure/Data/
   • Move Migrations/ → Infrastructure/Migrations/
   • Reference: Domain, Core, EF Core packages

4. Refactor API project (Api/)

   • Rename current project from WebApi to Api
   • Keep Controllers/, Program.cs
   • Update Extensions/ServiceCollectionExtensions.cs for DI configuration
   • Reference: Core only (not Infrastructure directly)

5. Update Solution and Tests

   • Update .sln file with new project references
   • Update test projects to reference appropriate layers
   • Ensure all tests pass after migration

Acceptance Criteria

• Domain project contains only pure domain logic with no external dependencies
• Core project contains business logic and defines infrastructure contracts
• Infrastructure project implements Core interfaces and handles data access
• Api project contains only HTTP/presentation concerns
• Dependency flow follows Clean Architecture principles (inward dependencies only)
• All existing tests pass after migration
• No circular dependencies between projects
• Build and deployment work without issues
• Docker compose still functions correctly
• Database migrations continue to work
• API functionality remains unchanged (same endpoints, same behavior)

References

• Clean Architecture by Robert C. Martin
• Microsoft .NET Application Architecture Guides
• eShopOnContainers Reference Architecture
• Jason Taylor's Clean Architecture Template