# 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 _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().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 OrderItems { get; set; } = new List(); // 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().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 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 { 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.* --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flexbase.in/core-concepts/domain-driven-design.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.