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.

// 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.

// 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.

// 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

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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.