> For the complete documentation index, see [llms.txt](https://docs.flexbase.in/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flexbase.in/core-concepts/domain-driven-design.md).

# Domain-Driven Design

## Application created with Flexbase Domain-Driven Design Patterns & Best Practices

### 🏗️ Domain-Driven Design Implementation

The Application created with Flexbase demonstrates sophisticated Domain-Driven Design (DDD) patterns through its Handler-Domain-Domain Method architecture, showcasing enterprise-grade best practices and clean separation of concerns.

***

### 🎯 Core DDD Architecture

#### **Three-Layer Domain Pattern**

```
┌─────────────────────────────────────┐
│ Handler Layer (Application)         │ ← Orchestrates business operations
├─────────────────────────────────────┤
│ Domain Layer (Business Logic)       │ ← Contains pure business logic
├─────────────────────────────────────┤
│ Infrastructure Layer (Data)         │ ← Handles persistence and external concerns
└─────────────────────────────────────┘
```

#### **Key DDD Principles Implemented**

* **Rich Domain Models** - Business logic encapsulated in domain entities
* **Ubiquitous Language** - Domain terms used consistently across all layers
* **Domain Entities** - Business objects that manage their own state and invariants
* **Domain Events** - Business events published for side effects
* **Repository Pattern** - Clean data access abstraction

***

### 🔧 Handler Layer - Application Orchestration

#### **Handler Responsibilities**

The Handler layer acts as the **Application Service** in DDD, orchestrating business operations without containing business logic.

```csharp
// Handler Pattern - Application Service
public partial class AddOrderHandler : IAddOrderHandler
{
    // Dependencies injected - Clean Architecture
    protected readonly ILogger<AddOrderHandler> _logger;
    protected readonly IFlexHost _flexHost;           // Domain access
    protected readonly RepoFactory _repoFactory;      // Data access
    
    // Domain model instance
    protected Order? _model;
    protected FlexAppContextBridge? _flexAppContext;  // Context

    public virtual async Task Execute(AddOrderCommand cmd, IFlexServiceBusContext serviceBusContext)
    {
        // 1. Context Extraction - DDD Context Management
        _flexAppContext = cmd.Dto.GetAppContext();
        
        // 2. Repository Initialization - Infrastructure Setup
        _repoFactory.Init(cmd.Dto);
        
        // 3. Domain Method Invocation - CORE DDD PATTERN
        _model = _flexHost.GetDomainModel<Order>().AddOrder(cmd);
        
        // 4. Persistence Layer - Infrastructure Concern
        _repoFactory.GetRepo().InsertOrUpdate(_model);
        int records = await _repoFactory.GetRepo().SaveAsync();
        
        // 5. Event Publishing - DDD Event-Driven Architecture
        await this.Fire(EventCondition, serviceBusContext);
    }
}
```

#### **Handler Best Practices Demonstrated**

**1. Single Responsibility Principle**

* **Only orchestrates** - No business logic in handlers
* **Manages dependencies** - Coordinates between domain and infrastructure
* **Handles transactions** - Ensures data consistency
* **Publishes events** - Triggers side effects

**2. Dependency Inversion Principle**

* **Depends on abstractions** - Uses interfaces, not concrete implementations
* **Domain-first approach** - Handler calls domain, not vice versa
* **Infrastructure abstraction** - Repository pattern for data access

**3. Command Pattern Implementation**

* **Encapsulates requests** - Commands contain all necessary data
* **Type safety** - Strongly-typed command parameters
* **Validation** - Command-level validation before domain processing

***

### 🏛️ Domain Layer - Business Logic Encapsulation

#### **Domain Model Structure**

Domain models are **rich business objects** that encapsulate business logic and maintain invariants.

```csharp
// Domain Model - Rich Business Object
public partial class Order : DomainModelBridge
{
    // Domain Properties - Business State
    public Guid Id { get; set; }
    public string CustomerId { get; set; }
    public decimal TotalAmount { get; set; }
    public string Status { get; set; }
    public DateTime CreatedDate { get; set; }
    
    // Navigation Properties - Domain Relationships
    public virtual Customer? Customer { get; set; }
    public virtual ICollection<OrderItem> OrderItems { get; set; } = new List<OrderItem>();
    
    // Audit Properties - Cross-cutting Concerns
    public string? CreatedBy { get; set; }
    public string? LastModifiedBy { get; set; }
    public DateTime? LastModifiedDate { get; set; }
}
```

#### **Domain Model Best Practices**

**1. Rich Domain Models**

* **Behavior over data** - Methods contain business logic
* **Encapsulation** - Internal state protected from external modification
* **Invariants** - Business rules enforced within the domain

**2. Domain Entity Pattern**

* **Single responsibility** - Each domain entity manages its own business logic
* **Consistency boundaries** - Ensures data integrity within the domain object
* **State management** - Domain objects control their own state transitions

**3. Value Objects and Entities**

* **Entities** - Have identity (Order, Customer)
* **Value Objects** - No identity, immutable (Money, Address)
* **Clear boundaries** - Well-defined domain concepts

***

### ⚙️ Domain Methods - Business Logic Implementation

#### **Domain Method Pattern**

Domain methods contain the **core business logic** and are the heart of DDD implementation.

```csharp
// Domain Method - Business Logic Implementation
public virtual Order AddOrder(AddOrderCommand cmd)
{
    // 1. Input Validation - Domain Invariants
    Guard.AgainstNull("Order command cannot be empty", cmd);
    
    // 2. DTO to Domain Mapping - Data Transformation
    this.Convert(cmd.Dto);
    
    // 3. Business Logic Application - Core DDD
    this.CreatedBy = cmd.Dto.GetAppContext()?.UserId;
    this.LastModifiedBy = cmd.Dto.GetAppContext()?.UserId;
    
    // 4. Domain State Management - Entity State
    this.SetAdded(cmd.Dto.GetGeneratedId());
    
    // 5. Business Rules Enforcement - Domain Invariants
    this.ValidateOrderTotal();
    this.ApplyBusinessRules();
    
    // 6. Domain Event Publishing - Event-Driven DDD
    this.RaiseEvent(new OrderCreatedEvent
    {
        OrderId = this.Id,
        CustomerId = this.CustomerId,
        TotalAmount = this.TotalAmount,
        CreatedAt = DateTime.UtcNow
    });
    
    return this;
}
```

#### **Domain Method Best Practices**

**1. Business Logic Encapsulation**

* **Pure business logic** - No infrastructure concerns
* **Domain invariants** - Business rules enforced
* **Validation** - Domain-level validation
* **State management** - Domain entity state changes

**2. Command Pattern Integration**

* **Command objects** - Encapsulate all necessary data
* **Type safety** - Strongly-typed parameters
* **Context preservation** - User and request context maintained

**3. Event-Driven Architecture**

* **Domain events** - Business events published
* **Side effects** - Triggered by domain events
* **Loose coupling** - Modules communicate through events

***

### 🔄 Complete DDD Flow Example

#### **AddOrder Operation - DDD in Action**

```mermaid
graph TB
    subgraph "Handler Layer (Application)"
        Handler[AddOrderHandler.Execute]
        Context[Extract Context]
        Repo[Initialize Repository]
        Persist[Persist Changes]
        Event[Publish Events]
    end
    
    subgraph "Domain Layer (Business Logic)"
        Domain[Order Domain Model]
        Method[AddOrder Method]
        Rules[Business Rules]
        Validation[Domain Validation]
        State[State Management]
    end
    
    subgraph "Infrastructure Layer (Data)"
        Repository[Repository Factory]
        Database[(Database)]
        MessageBus[Event Bus]
    end
    
    Handler --> Context
    Context --> Repo
    Repo --> Domain
    Domain --> Method
    Method --> Rules
    Method --> Validation
    Method --> State
    Method --> Event
    Handler --> Persist
    Persist --> Repository
    Repository --> Database
    Event --> MessageBus
```

#### **Step-by-Step DDD Implementation**

**Step 1: Handler Orchestration**

```csharp
// Handler coordinates the operation
public virtual async Task Execute(AddOrderCommand cmd, IFlexServiceBusContext serviceBusContext)
{
    // Extract application context
    _flexAppContext = cmd.Dto.GetAppContext();
    
    // Initialize infrastructure
    _repoFactory.Init(cmd.Dto);
    
    // Delegate to domain - CORE DDD PRINCIPLE
    _model = _flexHost.GetDomainModel<Order>().AddOrder(cmd);
    
    // Handle infrastructure concerns
    _repoFactory.GetRepo().InsertOrUpdate(_model);
    await _repoFactory.GetRepo().SaveAsync();
    
    // Publish domain events
    await this.Fire(EventCondition, serviceBusContext);
}
```

**Step 2: Domain Business Logic**

```csharp
// Domain contains the business logic
public virtual Order AddOrder(AddOrderCommand cmd)
{
    // Business validation
    Guard.AgainstNull("Order command cannot be empty", cmd);
    
    // Data transformation
    this.Convert(cmd.Dto);
    
    // Business rules application
    this.CreatedBy = cmd.Dto.GetAppContext()?.UserId;
    this.LastModifiedBy = cmd.Dto.GetAppContext()?.UserId;
    this.SetAdded(cmd.Dto.GetGeneratedId());
    
    // Domain event publishing
    this.RaiseEvent(new OrderCreatedEvent { ... });
    
    return this;
}
```

**Step 3: Infrastructure Handling**

```csharp
// Infrastructure handles data persistence
_repoFactory.GetRepo().InsertOrUpdate(_model);
int records = await _repoFactory.GetRepo().SaveAsync();

// Event publishing for side effects
await this.Fire(EventCondition, serviceBusContext);
```

***

### 🎯 DDD Best Practices Demonstrated

#### **1. Separation of Concerns**

* **Handler Layer**: Orchestration, transaction management, event publishing
* **Domain Layer**: Business logic, rules, invariants, domain events
* **Infrastructure Layer**: Data persistence, external service integration

#### **2. Dependency Inversion**

* **High-level modules** (Handlers) don't depend on low-level modules (Database)
* **Domain layer** is independent of infrastructure
* **Abstractions** define contracts between layers

#### **3. Single Responsibility Principle**

* **Handlers**: Only orchestrate operations
* **Domain Models**: Only contain business logic
* **Repositories**: Only handle data access

#### **4. Open/Closed Principle**

* **Open for extension**: New domain methods, handlers, events
* **Closed for modification**: Existing domain logic doesn't change
* **Plugin architecture**: Easy to add new business capabilities

#### **5. Interface Segregation**

* **Focused interfaces**: Each interface serves specific purpose
* **Client-specific contracts**: Handlers only depend on what they need
* **Loose coupling**: Changes in one interface don't affect others

***

### 🚀 Advanced DDD Patterns

#### **1. Rich Domain Entity Pattern**

```csharp
// Order is a Rich Domain Entity
public partial class Order : DomainModelBridge
{
    // Manages related entities as part of the domain object
    public virtual ICollection<OrderItem> OrderItems { get; set; }
    
    // Business method that maintains domain consistency
    public virtual Order AddItemToOrder(AddItemToOrderCommand cmd)
    {
        // Business logic to add item
        // Maintains domain invariants
        // Publishes domain events
        return this;
    }
}
```

#### **2. Domain Events Pattern**

```csharp
// Domain events for side effects
public class OrderCreatedEvent : IFlexEvent
{
    public Guid OrderId { get; set; }
    public string CustomerId { get; set; }
    public decimal TotalAmount { get; set; }
    public DateTime CreatedAt { get; set; }
}

// Event publishing in domain method
this.RaiseEvent(new OrderCreatedEvent
{
    OrderId = this.Id,
    CustomerId = this.CustomerId,
    TotalAmount = this.TotalAmount,
    CreatedAt = DateTime.UtcNow
});
```

#### **3. Repository Pattern**

```csharp
// Repository abstraction for data access
_repoFactory.GetRepo().InsertOrUpdate(_model);
int records = await _repoFactory.GetRepo().SaveAsync();

// Domain doesn't know about database specifics
// Infrastructure handles the implementation details
```

#### **4. Command Pattern**

```csharp
// Commands encapsulate business operations
public class AddOrderCommand : FlexCommandBridge<AddOrderDto, FlexAppContextBridge>
{
    public AddOrderDto Dto { get; set; }
    public FlexAppContextBridge Context { get; set; }
    public string CorrelationId { get; set; }
    public DateTime Timestamp { get; set; }
}
```

***

### 📊 DDD Benefits Achieved

#### **1. Maintainability**

* **Clear boundaries** - Each layer has distinct responsibilities
* **Business logic isolation** - Domain logic is separate from infrastructure
* **Easy testing** - Each layer can be tested independently
* **Consistent patterns** - Same structure across all modules

#### **2. Scalability**

* **Horizontal scaling** - Stateless handlers can be scaled independently
* **Event-driven** - Loose coupling through domain events
* **Microservices ready** - Clear boundaries enable service extraction

#### **3. Business Alignment**

* **Ubiquitous language** - Domain terms used consistently
* **Business logic centralization** - All business rules in one place
* **Domain expert collaboration** - Clear domain model for business discussions

#### **4. Quality Assurance**

* **Type safety** - Compile-time validation throughout
* **Invariant enforcement** - Business rules enforced at domain level
* **Error prevention** - Framework prevents common mistakes
* **Consistent behavior** - Same patterns across all operations

***

### 🎯 Key Takeaways

#### **DDD Implementation Success**

The YourApplication solution demonstrates **enterprise-grade DDD implementation** with:

1. **Clean Architecture** - Clear separation between layers
2. **Rich Domain Models** - Business logic properly encapsulated in domain entities
3. **Event-Driven Design** - Loose coupling through domain events
4. **Repository Pattern** - Clean data access abstraction
5. **Command Pattern** - Encapsulated business operations

#### **Business Value Delivered**

* **Maintainable Code** - Clear structure and separation of concerns
* **Testable Architecture** - Each layer can be tested independently
* **Scalable Design** - Ready for horizontal scaling and microservices
* **Business Alignment** - Domain model reflects business concepts
* **Quality Assurance** - Consistent patterns and error prevention

***

*This document showcases how the YourApplication solution implements Domain-Driven Design principles through its Handler-Domain-Domain Method architecture, delivering enterprise-grade maintainability, scalability, and business alignment.*