Understanding Onion Architecture and Domain‑Driven Design

Why Use Onion Architecture?

Onion Architecture builds on a domain model and connects layers through interfaces, keeping external dependencies on the outside while the core domain entities and business rules remain at the center, resulting in flexible, sustainable, and portable code.

Provides a flexible, sustainable, and portable architecture.

Ensures loose coupling and clear separation of concerns between layers.

Improves maintainability because inner layers depend only on deeper layers.

Enhances testability; each layer can be unit‑tested independently.

Allows easy replacement of frameworks or technologies (e.g., RabbitMQ ↔ ActiveMQ, SQL ↔ MongoDB).

Principles

Dependency

Each concentric circle represents a responsibility layer; the outer circles depend on inner circles, but inner circles are unaware of the outer ones. Data formats may differ per layer, and data transferred across layers should be represented in a form convenient for the target layer (e.g., DTOs for APIs, entity objects for persistence).

Data Encapsulation

Every layer hides its internal implementation and exposes interfaces to outer layers, minimizing inter‑layer coupling while maximizing vertical cohesion within a layer. Abstract interfaces are defined in deeper layers and implemented in outer layers, often using dependency‑injection frameworks such as Spring.

Separation of Concerns

The application is divided into several layers, each with its own responsibilities and modules/packages, ensuring that concerns are isolated.

Coupling

Low coupling allows modules to interact without needing to know each other's internal details; inner layers never depend on outer layers.

Onion Architecture Layers

Using an order‑creation use case, the flow is: receive a request, validate the order, persist it, update inventory, debit the amount, and finally notify the customer. The diagram shows how each layer (domain, application, infrastructure) interacts and where the dependencies lie.

Domain Model / Entity

Domain entities are the core building blocks of DDD, representing concepts with a unique identity. For example, an Order entity contains attributes like OrderId, Address, UserInfo, OrderItems, PricingInfo, and behaviors such as AddOrderItems, GetPricingInfo, and ValidateOrder, independent of any specific technology.

Domain Service

Domain services encapsulate complex business rules (e.g., price and tax calculation, inventory updates) and are coordinated by application services. They are not simple CRUD services but contain essential algorithms for the domain.

Application Service

Also called a “use case”, an application service orchestrates steps without containing business logic. It coordinates domain services, pricing calculations, availability checks, order persistence, and user notifications, and is invoked only by infrastructure services.

Infrastructure Service

Infrastructure services (or adapters) form the outermost layer, handling communication with external systems such as notification services, gRPC endpoints, Kafka streams, or databases. They contain no domain logic.

Observability Service

Observability services monitor the application by collecting metrics, logs, and traces, storing them centrally, and providing visualization tools (e.g., Splunk, ELK, Grafana, Datadog).

Testing Strategy

Different layers require different testing approaches. The test pyramid suggests unit tests for domain models, services, and application logic; integration tests for infrastructure; and end‑to‑end or BDD tests for the whole application.

Microservices

Each microservice can adopt Onion Architecture, having its own domain model, use cases, and adapters (HTTP, gRPC, etc.). The architecture supports independent evolution and technology swaps within a microservice.

Application Structure and Layer Count

Applications can be organized as a single module or split into multiple modules, each representing a layer. The choice depends on complexity and project size; modularization is especially useful in microservice environments.

Frameworks, Clients, and Drivers

The infrastructure layer consists of frameworks, database clients, queues, and external services, providing configuration and wiring. Onion Architecture’s decoupling makes swapping technologies straightforward.

Do We Need Every Layer?

Layered organization promotes separation of concerns, but not all layers are mandatory. The necessity of a layer depends on the use case and application complexity; for simple applications, some layers (e.g., domain services) may be omitted.

Conclusion

Although Onion Architecture may seem complex at first, it is widely accepted for creating evolvable software. By dividing an application into layers, the system becomes easier to test, maintain, and migrate, and it facilitates adopting new frameworks or technologies without disrupting core business logic.