Onion Architecture: A Practical Implementation with OnionArchitectureDemo

Introduction

Onion Architecture helps maintainability, testability, and clear separation of concerns by placing business rules at the center and isolating external dependencies. This layered approach ensures that the core logic remains stable even when infrastructure or external systems evolve.

This article explains OnionArchitectureDemo's four-layer structure and highlights future improvements such as CQRS, Domain Events, AutoMapper, FluentValidation, Unit of Work, and Middleware, which are commonly used in enterprise-level .NET applications to increase scalability and consistency.

What is Onion Architecture?

A layered architectural style emphasizing domain-centric design, dependency inversion, and isolation of external concerns. It supports clean boundaries and ensures the business core remains stable even when technologies change.

Core Principles:

Domain at the center
Inner layers never depend on outer layers
Interfaces abstract external dependencies

Advantages:

Maintainable and testable codebase
Flexible infrastructure changes (swap database, email service, cloud provider, etc.)
Clean code and SOLID alignment
Encourages long-term sustainability and modularity

Architecture Overview

The Onion Architecture used in this project is composed of four primary layers, each with a well-defined responsibility. These layers interact through strict boundaries, reinforcing a clean and maintainable architecture.

1. Application Layer

The Application Layer manages use cases, business rules, DTOs, and service interfaces. It orchestrates the flow of data between the UI and the Domain layer, ensuring the business rules are applied correctly. It depends only on the Domain layer, not external resources, making it highly testable.

Contents:

Dtos/ProductDto.cs
Interfaces (IProductService, IEmailService)
Services/ProductService.cs

Key Points:

DTOs prevent domain entity exposure and ensure a clean contract between layers.
Interfaces abstract implementation details, supporting loose coupling and dependency inversion.
ProductService handles business logic using domain abstractions only, without knowing anything about the database or infrastructure details.
This layer is also the ideal place to integrate cross-cutting behaviors like validation, caching, and authorization in larger solutions.

2. Domain Layer

The Domain Layer is the core of the system, containing entities, value objects, and repository interfaces. It is completely isolated from external dependencies, making it the most stable and long-lived part of the architecture.

Contents:

Entities/Product.cs
Interfaces/IProductRepository.cs

Benefits:

Stable business rules remain unaffected by infrastructure changes.
High testability because the domain is completely independent.
Independent from database or external systems, enabling easy migrations (e.g., moving from SQLite to PostgreSQL or SQL Server).
Ideal location for adding Domain Events and domain-driven validation logic.

3. Infrastructure Layer

The Infrastructure Layer implements Application interfaces and handles external concerns such as database connections, email providers, and third-party systems. It is the layer where technology-specific implementations are placed.

Contents:

Data/AppDbContext
Repositories/ProductRepository
Services/EmailService

Capabilities:

EF Core with SQLite; however, the setup can easily be switched to other databases.
CRUD operations implemented through repository patterns.
External service integration such as SMTP providers, SendGrid, or logging systems.
Contains data access logic but never contains business rules.

4. WebAPI Layer

The WebAPI Layer exposes HTTP endpoints and manages dependency injection, configuration, and application startup pipeline. It acts as the outermost layer through which clients interact with the system.

Contents:

Controllers/ProductController
Program.cs

Role:

Bridges client requests and application logic by forwarding requests to Application services.
Provides central dependency management through DI container configuration.
Ensures controllers remain thin and contain no business logic, promoting the Single Responsibility Principle.

Visualized Workflow: OnionArchitectureDemo Project

1. Package Diagram

Package Diagram

2. Sequence Diagram

Sequence Diagram

Additional Recommended Patterns

These optional enhancements elevate OnionArchitectureDemo into a more scalable and production-ready architecture.

AutoMapper

Centralizes DTO ↔ Entity mapping, reduces repetitive code, and enhances readability. Ideal for large applications where many models need to be transformed.

CQRS & MediatR

Separates commands and queries, improving clarity and testability. MediatR also enables clean handler-based pipelines and behavior injection (logging, validation, etc.).

FluentValidation

Centralizes validation rules for cleaner code and offers reusable, expressive rule definitions.

Domain Events

Decouples domain logic from external actions such as notifications, logging, or integrations. Helps align the architecture with Domain-Driven Design (DDD) principles.

Unit of Work

Ensures transactional consistency across repositories, especially in complex write operations involving multiple aggregates.

Middleware Improvements

Global exception handling
Response wrapping
JWT authentication
Logging and performance monitoring

These ensure consistent API behavior and improve debugging and client-side integration.

Conclusion

OnionArchitectureDemo demonstrates a clean, extensible structure centered on business rules. While the current version reflects foundational concepts, integrating CQRS, Domain Events, UoW, and Middleware will elevate it to enterprise-ready architecture.

Onion Architecture remains an excellent choice for scalable, testable, and sustainable software development, especially in modern .NET applications where clean separation of concerns and maintainability are key priorities.

GitHub Project: OnionArchitectureDemo 👈

Prepared by Burhan Sözer
Software Engineering & GIS Solutions