Best-practice architecture for .NET Core projects

✅ Recommended Architecture: Clean Architecture / Hexagonal / Onion

These modern patterns are domain-driven , decouple infrastructure , and test-friendly .

🔹 1. Layers & Responsibilities

1. Presentation Layer (API/UI)

   • ASP.NET Core Web API / MVC / Razor Pages / Blazor

   • Handles HTTP requests, model binding, validation, and authentication

   • Calls Application layer (never directly the DB or services)

2. Application Layer (Use Cases)

   • Contains business logic & use cases

   • Uses CQRS (Commands/Queries) with MediatR (best practice in 2025)

   • Defines interfaces for persistence, email, cache, etc.

   • Does not depend on infrastructure implementation

3. Domain Layer (Core)

   • Contains Entities, Value Objects, Domain Events, Aggregates

   • Pure C# classes, no dependency on EF Core or external libs

   • Business rules live here

4. Infrastructure Layer

   • Implements interfaces from the Application layer

   • EF Core repositories, third-party services (Braintree, PayPal, AWS, etc.)

   • Logging, Email, File storage, Payment gateways

   • Should not contain business logic

🔹 2. Best Practices

• Dependency Inversion → Infrastructure depends on Application, not the other way around

• CQRS + MediatR → Separate read (queries) and write (commands) logic

• FluentValidation for request validation

• AutoMapper for DTO ↔ Entity mapping

• Serilog / NLog for logging

• EF Core Migrations for database versioning

• Swagger / NSwag for API documentation

• Unit Testing in Application + Domain

• Integration Testing in Infrastructure

🔹 3. Folder Structure Example

  
    src/
 ├── MyProject.Api              -> Presentation (Controllers, Filters, Middlewares)
 ├── MyProject.Application      -> Use cases, CQRS, Interfaces, DTOs
 ├── MyProject.Domain           -> Entities, Value Objects, Events
 ├── MyProject.Infrastructure   -> EF Core, Repositories, Services, Configurations
 └── MyProject.Tests            -> Unit & Integration Tests
  

🔹 4. Tech & Tools Suggestions

• Authentication & Authorization → IdentityServer or JWT

• Database → EF Core with Repository + Unit of Work pattern

• Caching → Redis

• API Versioning → Microsoft.AspNetCore.Mvc.Versioning

• Observability → OpenTelemetry + Application Insights

• CI/CD → GitHub Actions / Azure DevOps / Jenkins

• Containerization → Docker + Kubernetes (future scaling)

🔹 5. When to Use This

• ✅ Medium to large projects

• ✅ Microservices or modular monoliths

• ✅ Teams with multiple devs

• ✅ Long-term maintainability needed

For small projects , a simplified 3-layer architecture (Controller → Service → Repository) is enough.

These three are often confused because they share principles like dependency inversion, separation of concerns, and domain-centric design , but they differ in emphasis and structure.

1️⃣ Clean Architecture

📌 Concept

• Proposed by Robert C. Martin (Uncle Bob).

• Organizes the system into concentric circles with the domain (entities) at the center.

• Dependency Rule: All dependencies point inward (towards the domain).

• Use Cases (Application layer) orchestrate the rules.

✅ Pros

• Clear separation of concerns.

• Technology/framework independent → easy to replace EF Core, UI, or external services.

• Highly testable.

• Supports CQRS and MediatR well.

❌ Cons

• Can feel “over-engineered” for small projects.

• Steep learning curve for new devs.

• Requires discipline to avoid leaks between layers.

2️⃣ Hexagonal Architecture (Ports & Adapters)

📌 Concept

• Introduced by Alistair Cockburn.

• Focuses on interactions with the system through ports (interfaces) and adapters (implementations).

• The application core is isolated, while external systems (DB, APIs, UI, message brokers) connect via adapters.

✅ Pros

• Very flexible → easy to swap DBs, UIs, APIs without touching core logic.

• Strong alignment with microservices.

• Good for systems with multiple interfaces (REST, gRPC, CLI, etc.).

• Encourages testability through mocking ports.

❌ Cons

• Can introduce too many abstractions (interfaces everywhere).

• Might add boilerplate for simple apps.

• Needs strong architecture governance to stay clean.

3️⃣ Onion Architecture

📌 Concept

• Proposed by Jeffrey Palermo.

• Similar to Clean Architecture ,but focuses on layers wrapped around the domain .

• The domain model is at the core, surrounded by Application Services, Infrastructure, and UI.

• Dependencies go inward (outer → inner).

✅ Pros

• Keeps domain logic independent.

• Easy to test the domain in isolation.

• Strong separation of concerns.

• Good for enterprise applications with rich business rules.

❌ Cons

• Similar to Clean → adds complexity for small projects.

• Can be misunderstood → developers sometimes still leak EF Core or infrastructure into the domain.

• Heavier initial setup.

🔄 Quick Comparison Table

Feature	Clean Architecture	Hexagonal Architecture	Onion Architecture
Origin	Uncle Bob (2012)	Alistair Cockburn (2005)	Jeffrey Palermo (2008)
Core Focus	Domain + Use Cases	Ports & Adapters	Domain-Centric Layers
External Systems	Infrastructure outer ring	Adapters (DB, UI, API)	Infrastructure outer layer
Dependencies	Inward	Core → Ports → Adapters	Inward
Best Fit	Enterprise apps, CQRS, APIs	Microservices, multiple interfaces	Enterprise apps, DDD-heavy systems
Complexity	Medium-High	Medium-High	Medium

🎯 Simplified Way to Think

• Clean Architecture = Onion with explicit use cases (CQRS-style).

• Onion Architecture = Domain-centric layering (classic form).

• Hexagonal Architecture = More about system boundaries (ports/adapters).