Skip to main content

​
Introduction

The Hybrid DDD Architecture is a .NET template that combines Domain-Driven Design (DDD) principles with modern architectural patterns to create scalable, maintainable enterprise applications. This architecture emphasizes separation of concerns, testability, and flexibility through well-defined layers and reusable core modules.

​
Architecture Philosophy

This template embraces a hybrid approach that balances:
  • Domain-Driven Design: Business logic encapsulated in rich domain entities with validation
  • CQRS Pattern: Separate commands and queries for write and read operations
  • Event-Driven Architecture: Domain events and integration events for loose coupling
  • Clean Architecture: Dependencies flow inward toward the domain core
  • Reusable Core Modules: Shared infrastructure components across projects

​
Design Principles

​
1. Separation of Concerns

The architecture is organized into three distinct layers:
  • Domain Layer: Contains business entities, value objects, and domain logic
  • Application Layer: Orchestrates use cases, commands, queries, and application services
  • Infrastructure Layer: Provides technical implementations for persistence, messaging, and external APIs

​
2. Dependency Rule

Dependencies flow inward: 
Infrastructure → Application → Domain
The Domain layer has no dependencies on other layers, ensuring business logic remains pure and testable.

​
3. Explicit Interfaces

All external dependencies are abstracted through interfaces defined in the Application layer, allowing for:
  • Easy testing with mocks
  • Swappable implementations (e.g., MongoDB vs SQL Server)
  • Clear contracts between layers

​
Component Interactions

​
Request Flow

A typical request flows through the system as follows:

​
Command Flow Example

When creating a new entity:
  1. API receives request and creates a command object
  2. Command is sent to the Command/Query Bus
  3. Handler processes the command:
    • Creates domain entity
    • Validates using domain validators
    • Persists via repository
    • Publishes domain events
  4. Event handlers respond to domain events (notifications, integration events)
  5. Response returned to the API layer

​
Query Flow Example

When retrieving data:
  1. API receives request and creates a query object
  2. Query is sent to the Command/Query Bus
  3. Handler processes the query:
    • Retrieves data via repository
    • Maps to DTOs
    • Returns paginated results
  4. Response returned to the API layer

​
Core Technologies

The architecture leverages these key technologies:

MediatR

Implements the mediator pattern for CQRS command/query handling

AutoMapper

Handles object-to-object mapping between layers

FluentValidation

Provides domain entity validation

RabbitMQ

Enables event-driven communication between services

​
Key Benefits

​
Maintainability

  • Clear separation of concerns makes code easier to understand
  • Each layer has well-defined responsibilities
  • Changes in one layer have minimal impact on others

​
Testability

  • Domain logic can be tested in isolation
  • Infrastructure dependencies can be mocked
  • CQRS pattern simplifies handler testing

​
Scalability

  • Event-driven architecture enables microservices
  • CQRS allows independent scaling of read/write operations
  • Reusable core modules reduce duplication

​
Flexibility

  • Multiple database options (MongoDB, SQL Server)
  • Pluggable event bus implementations
  • Easy to swap implementations without changing business logic

​
Architecture Layers

The template is organized into three primary layers:

Domain

Business entities, validators, and domain logic

Application

Use cases, commands, queries, and orchestration

Infrastructure

Persistence, messaging, and external integrations

​
Core Modules

The architecture includes reusable core modules that provide common functionality:
  • Core.Application.CommandQueryBus: CQRS implementation using MediatR
  • Core.Application.EventBus: Event publishing and subscription abstractions
  • Core.Application.Repositories: Generic repository interfaces
  • Core.Application.Mapping: Object mapping utilities
  • Core.Application.Adapters.Http: HTTP client abstractions
  • Core.Domain: Base domain entity classes and validation

Learn More

Explore the reusable core modules in detail

​
Next Steps

Core Modules

Learn about the reusable core modules

Architecture Layers

Deep dive into Domain, Application, and Infrastructure layers

CQRS Pattern

Understand command and query separation

Quick Start

Start building with the template

Build docs developers (and LLMs) love

Get started for freeTalk to us