Introduction to Solution

Overview

The YourProject solution is a comprehensive enterprise application built using FlexBase Framework and following Domain-Driven Design (DDD) principles with Clean Architecture patterns. This solution demonstrates a modern, scalable approach to building business applications with clear separation of concerns, testability, and maintainability.

Solution Architecture

The solution is organized into two main folders that represent the architectural layers:

1. YourProject.Application

The main application layer containing all business logic, domain models, and application services.

2. YourProject.Framework

The framework layer providing infrastructure abstractions and bridges to external systems.

Project Structure and DDD Layers

Domain Layer (Core Business Logic)

YourProject.DomainModels

  • Purpose: Contains the core domain entities and rich domain models

  • DDD Role: Domain Layer - Pure business logic

  • Key Components:

    • Rich Domain Models - Main business entities with behavior that control access to their children (e.g., EntityName.cs, EntityState.cs)

    • Value Objects - Immutable objects defined by their attributes (e.g., ValueObjectName.cs, ValueObjectStatus.cs)

    • Entities - Objects with distinct identity (e.g., EntityName.cs, EntityCategory.cs)

    • Domain Services - Business logic that doesn't belong to a specific entity

  • Dependencies: Only depends on YourProject.CommonLib and YourProject.Messages

  • Clean Architecture: Innermost layer, no external dependencies

Example: In an e-commerce system, you might have Order as a rich domain model with behavior, OrderItem as value objects, Payment as a separate rich domain model, and Product as a catalog entity.

YourProject.CommonLib

  • Purpose: Shared domain utilities and common business logic

  • DDD Role: Domain Layer - Shared kernel

  • Key Components:

    • Custom exceptions (e.g., CustomExceptions.cs)

    • Database type constants (e.g., DbTypeConstants.cs)

    • HTTP response handlers (e.g., HttpResponseHandler.cs)

    • Logger category constants (e.g., LoggerCategoryConstants.cs)

  • Dependencies: None (pure domain utilities)

YourProject.Mappers

  • Purpose: Object mapping between domain models and DTOs

  • DDD Role: Application Layer - Data transformation

  • Key Components:

    • AutoMapper configurations (e.g., AutomapperConfiguration.cs)

    • Domain-to-DTO mappers (e.g., OrderDomainDtoMappers.cs, ProductDomainDtoMappers.cs)

    • Feature-specific mappers (e.g., OrderFeatureMappers.cs, ProductFeatureMappers.cs)

  • Dependencies: Domain models and DTOs

Application Layer (Use Cases and Application Services)

YourProject.Handlers

  • Purpose: Command handlers implementing CQRS pattern

  • DDD Role: Application Layer - Command handling

  • Key Components:

    • Create Handlers - Handle entity creation commands (e.g., AddEntityHandler.cs, CreateEntityHandler.cs)

    • Update Handlers - Handle entity modification commands (e.g., UpdateEntityHandler.cs, ModifyEntityHandler.cs)

    • Delete Handlers - Handle entity removal commands (e.g., DeleteEntityHandler.cs, RemoveEntityHandler.cs)

    • Business Process Handlers - Handle complex business operations (e.g., ProcessEntityHandler.cs, ExecuteWorkflowHandler.cs)

  • Dependencies: Domain models, repositories, and service bus

Example: In an e-commerce system, you might have AddOrderHandler.cs, UpdateOrderHandler.cs, DeleteOrderHandler.cs, and ProcessPaymentHandler.cs.

YourProject.Queries

  • Purpose: Query handlers for read operations (CQRS)

  • DDD Role: Application Layer - Query handling

  • Key Components:

    • Single Entity Queries - Retrieve individual entities (e.g., GetEntityQuery.cs, FindEntityByIdQuery.cs)

    • List Queries - Retrieve collections of entities (e.g., GetEntityListQuery.cs, GetAllEntitiesQuery.cs)

    • Paged Queries - Retrieve paginated results (e.g., GetEntityPagedListQuery.cs, SearchEntitiesQuery.cs)

    • Complex Queries - Retrieve data across multiple entities (e.g., GetEntityWithDetailsQuery.cs, GetEntityReportQuery.cs)

  • Dependencies: Domain models and repositories

Example: In an e-commerce system, you might have GetOrderQuery.cs, GetOrderListQuery.cs, GetOrderPagedListQuery.cs, and GetOrderWithItemsQuery.cs.

YourProject.PreBus

  • Purpose: Pre-bus services for business logic orchestration

  • DDD Role: Application Layer - Business orchestration

  • Key Components:

    • Entity Management Services - Core business operations for entities (e.g., EntityService.cs, EntityManagementService.cs)

    • Validation Services - Business rule validation (e.g., EntityValidationService.cs, BusinessRuleValidator.cs)

    • Workflow Services - Complex business process orchestration (e.g., EntityWorkflowService.cs, ProcessOrchestrator.cs)

    • Integration Services - External system integration (e.g., ExternalServiceClient.cs, ThirdPartyIntegrationService.cs)

  • Dependencies: Domain models, handlers, and queries

Example: In an e-commerce system, you might have OrderService.cs, OrderValidationService.cs, OrderWorkflowService.cs, and PaymentGatewayService.cs.

YourProject.RESTClients

  • Purpose: External service integration

  • DDD Role: Application Layer - External service integration

  • Key Components:

    • REST service clients (e.g., RESTServicesMaster_Common.cs)

    • External API integrations (e.g., PaymentGatewayClient.cs, InventoryServiceClient.cs)

  • Dependencies: Common libraries and HTTP clients

Infrastructure Layer (External Concerns)

Database Infrastructure

YourProject.BaseEF

  • Purpose: Base Entity Framework configuration

  • DDD Role: Infrastructure Layer - Data persistence

  • Key Components:

    • Base DbContext (e.g., YourProjectDbContext.cs)

    • Entity configurations (e.g., OrderConfiguration.cs, ProductConfiguration.cs)

    • Repository base classes (e.g., BaseRepository.cs)

  • Dependencies: Entity Framework Core, domain models

YourProject.BaseEF.SqlServer / MySql / PostgreSql

  • Purpose: Database-specific implementations

  • DDD Role: Infrastructure Layer - Database providers

  • Key Components:

    • Database-specific DbContext (e.g., YourProjectSqlServerDbContext.cs)

    • Provider-specific configurations (e.g., SqlServerOrderConfiguration.cs)

  • Dependencies: Base EF, specific database providers

Message Bus Infrastructure

YourProject.Nsb

  • Purpose: NServiceBus configuration and messaging

  • DDD Role: Infrastructure Layer - Message transport

  • Key Features:

    • Multiple transport options (RabbitMQ, Azure Service Bus, SQL Server)

    • Message persistence

    • Learning transport for development

  • Key Components:

    • Bus configuration (e.g., NsbConfiguration.cs, NsbRouteConfig.cs)

    • Message routing (e.g., MessageRoutingConfiguration.cs)

  • Dependencies: NServiceBus packages, core bridge

Presentation Layer (API and Controllers)

YourProject.WebControllers

  • Purpose: REST API controllers

  • DDD Role: Presentation Layer - API endpoints

  • Key Components:

    • Entity Controllers - RESTful endpoints for entity operations (e.g., EntityController.cs, EntityManagementController.cs)

    • CRUD Operations - Create, Read, Update, Delete endpoints (e.g., EntityController_Add.cs, EntityController_Get.cs)

    • Search Controllers - Search and filtering endpoints (e.g., EntitySearchController.cs, EntityFilterController.cs)

    • Report Controllers - Data reporting and analytics endpoints (e.g., EntityReportController.cs, AnalyticsController.cs)

  • Dependencies: DTOs, mappers, and application services

Example: In an e-commerce system, you might have OrdersController_AddOrder.cs, OrdersController_GetOrders.cs, ProductsController.cs, and PaymentsController.cs.

YourProject.CronJobs

  • Purpose: Background job processing

  • DDD Role: Presentation Layer - Background processing

  • Key Components:

    • Scheduled job definitions (e.g., OrderCleanupJob.cs, PaymentProcessingJob.cs)

    • Job configuration (e.g., CronJobConfiguration.cs)

  • Dependencies: Application services and infrastructure

Control Contracts (API Contracts)

YourProject.DTOs

  • Purpose: Data Transfer Objects for API contracts

  • DDD Role: Presentation Layer - API contracts

  • Key Components:

    • Command DTOs - Data for create/update operations (e.g., AddEntityDto.cs, UpdateEntityDto.cs)

    • Query DTOs - Data for read operations (e.g., GetEntityDto.cs, EntityListDto.cs)

    • Input/Output DTOs - Request/response data structures (e.g., EntityInputDto.cs, EntityOutputDto.cs)

    • Domain DTOs - Internal data transfer objects (e.g., EntityDomainDto.cs, EntityDetailDto.cs)

  • Dependencies: Common libraries

Example: In an e-commerce system, you might have AddOrderDto.cs, UpdateOrderDto.cs, GetOrderDto.cs, and OrderDomainDto.cs.

YourProject.Messages

  • Purpose: Command and Event definitions

  • DDD Role: Application Layer - Message contracts

  • Key Components:

    • Command Messages - Instructions for business operations (e.g., AddEntityCommand.cs, UpdateEntityCommand.cs, DeleteEntityCommand.cs)

    • Event Messages - Notifications of state changes (e.g., EntityAddedEvent.cs, EntityUpdatedEvent.cs, EntityDeletedEvent.cs)

    • Integration Events - Cross-bounded context communications (e.g., EntityProcessedEvent.cs, WorkflowCompletedEvent.cs)

  • Dependencies: Core framework

Example: In an e-commerce system, you might have AddOrderCommand.cs, UpdateOrderCommand.cs, OrderAddedEvent.cs, and PaymentProcessedEvent.cs.

YourProject.SharedEvents

  • Purpose: Cross-bounded context events

  • DDD Role: Application Layer - Integration events

  • Key Components:

    • Cross-domain events (e.g., OrderCompletedEvent.cs, InventoryUpdatedEvent.cs)

  • Dependencies: Core framework

Endpoints (Deployment Units)

YourProject.EndPoint.WebAPI

  • Purpose: Main web API endpoint

  • DDD Role: Presentation Layer - Web API host

  • Key Features:

    • RESTful API endpoints

    • Swagger documentation

    • Authentication and authorization

    • Multi-database support

  • Key Components:

    • Program.cs (e.g., Program.cs, Startup.cs)

    • Configuration files (e.g., appsettings.json, appsettings.Development.json)

  • Dependencies: All application layers

YourProject.EndPoint.Handlers.Default

  • Purpose: Message handler endpoint

  • DDD Role: Application Layer - Message processing host

  • Key Components:

    • Handler configuration (e.g., Program.cs, Worker.cs)

    • Message routing (e.g., NsbRouteConfig.cs)

  • Dependencies: Handlers, infrastructure

YourProject.EndPoint.Subscribers.Default

  • Purpose: Event subscriber endpoint

  • DDD Role: Application Layer - Event processing host

  • Key Components:

    • Subscriber configuration (e.g., Program.cs, Worker.cs)

    • Event routing (e.g., NsbRouteConfig.cs)

  • Dependencies: Subscribers, infrastructure

YourProject.EndPoint.CronJob

  • Purpose: Background job endpoint

  • DDD Role: Application Layer - Background processing host

  • Key Components:

    • Job configuration (e.g., Program.cs, Worker.cs)

    • Schedule definitions (e.g., CronJobConfiguration.cs)

  • Dependencies: Cron jobs, infrastructure

Database Migrations

YourProject.Migrations.*

  • Purpose: Database schema management

  • DDD Role: Infrastructure Layer - Database versioning

  • Key Features:

    • Multi-database support (SQL Server, MySQL, PostgreSQL)

    • Tenant-specific migrations

    • Schema versioning

  • Key Components:

    • Migration files (e.g., 20240101_InitialCreate.cs, 20240102_AddOrderTable.cs)

    • Tenant migrations (e.g., Tenant_20240101_InitialCreate.cs)

  • Dependencies: Domain models, Entity Framework

Framework Layer (Infrastructure Abstractions)

YourProject.CoreBridge

  • Purpose: Core framework abstractions

  • DDD Role: Infrastructure Layer - Framework abstractions

  • Key Components:

    • Service bus bridges (e.g., IFlexServiceBusBridge.cs, FlexServiceBusContextBridge.cs)

    • Repository abstractions (e.g., IFlexRepositoryBridge.cs, IFlexQueryRepositoryBridge.cs)

    • Domain model bridges (e.g., DomainModelBridge.cs, DtoBridge.cs)

    • Query abstractions (e.g., FlexiQueryBridge.cs, FlexiQueryPagedListBridge.cs)

  • Dependencies: FlexBase Core framework

YourProject.EFCoreBridge

  • Purpose: Entity Framework specific implementations

  • DDD Role: Infrastructure Layer - EF implementations

  • Key Components:

    • EF repository implementations (e.g., FlexEFRepositoryBridge.cs, FlexEFQueryRepositoryBridge.cs)

  • Dependencies: Core bridge, Entity Framework

YourProject.AspNetCoreBridge

  • Purpose: ASP.NET Core specific implementations

  • DDD Role: Infrastructure Layer - Web framework implementations

  • Key Components:

    • Controller bridges (e.g., FlexControllerBridge.cs, ControllerExtensionMethods.cs)

    • HTTP context accessors (e.g., FlexDefaultHttpContextAccessorBridge.cs)

  • Dependencies: Core bridge, ASP.NET Core

YourProject.HandlerInterfaces

  • Purpose: Handler interface definitions

  • DDD Role: Application Layer - Handler contracts

  • Key Components:

    • Entity Handler Interfaces - Contracts for entity operations (e.g., IAddEntityHandler.cs, IUpdateEntityHandler.cs, IDeleteEntityHandler.cs)

    • Process Handler Interfaces - Contracts for business processes (e.g., IProcessEntityHandler.cs, IExecuteWorkflowHandler.cs)

    • Query Handler Interfaces - Contracts for data retrieval (e.g., IGetEntityHandler.cs, ISearchEntityHandler.cs)

  • Dependencies: Messages and DTOs

Example: In an e-commerce system, you might have IAddOrderHandler.cs, IUpdateOrderHandler.cs, IProcessPaymentHandler.cs, and IAddProductHandler.cs.

YourProject.Handlers.Default.Nsb

  • Purpose: Default NServiceBus handler implementations

  • DDD Role: Infrastructure Layer - Message handling

  • Key Components:

    • Entity Handlers - Concrete implementations for entity operations (e.g., AddEntityHandler.cs, UpdateEntityHandler.cs, DeleteEntityHandler.cs)

    • Process Handlers - Concrete implementations for business processes (e.g., ProcessEntityHandler.cs, ExecuteWorkflowHandler.cs)

    • Query Handlers - Concrete implementations for data retrieval (e.g., GetEntityHandler.cs, SearchEntityHandler.cs)

  • Dependencies: Handler interfaces, NServiceBus

Example: In an e-commerce system, you might have AddOrderHandler.cs, UpdateOrderHandler.cs, ProcessPaymentHandler.cs, and AddProductHandler.cs.

YourProject.Subscribers.Default.Nsb

  • Purpose: Default NServiceBus subscriber implementations

  • DDD Role: Infrastructure Layer - Event handling

  • Key Components:

    • Entity Event Subscribers - Handle entity-related events (e.g., EntityAddedSubscriber.cs, EntityUpdatedSubscriber.cs)

    • Process Event Subscribers - Handle business process events (e.g., ProcessCompletedSubscriber.cs, WorkflowFinishedSubscriber.cs)

    • Integration Event Subscribers - Handle cross-system events (e.g., ExternalSystemNotificationSubscriber.cs)

  • Dependencies: Handler interfaces, NServiceBus

Example: In an e-commerce system, you might have OrderAddedSubscriber.cs, OrderUpdatedSubscriber.cs, and PaymentProcessedSubscriber.cs.

Key Architectural Patterns

1. Domain-Driven Design (DDD)

  • Rich Domain Models: Main business entities with behavior that control access to their children

  • Value Objects: Immutable objects defined by their attributes

  • Entities: Objects with distinct identity and lifecycle

  • Domain Services: Business logic that doesn't belong to a specific entity

  • Repositories: Data access abstraction

Example: In an e-commerce system, Order might be a rich domain model with behavior, OrderItem as value objects, Payment as a separate rich domain model, and Product as a catalog entity.

2. Clean Architecture

  • Dependency Inversion: All dependencies point inward

  • Separation of Concerns: Clear layer boundaries

  • Testability: Each layer can be tested independently

  • Independence: Business logic independent of frameworks

3. CQRS (Command Query Responsibility Segregation)

  • Commands: Instructions that change system state (e.g., AddEntity, UpdateEntity, DeleteEntity)

  • Queries: Instructions that retrieve data (e.g., GetEntities, GetEntityById, SearchEntities)

  • Handlers: Separate command and query handlers for different responsibilities

  • Read Models: Optimized data structures for querying

Example: In an e-commerce system, you might have AddOrder, UpdateOrder, DeleteOrder commands and GetOrders, GetOrderById, GetProducts queries.

4. Event-Driven Architecture

  • Commands: Trigger business operations

  • Events: Notify of state changes

  • Subscribers: React to events

  • Message Bus: NServiceBus for reliable messaging

5. Multi-Tenant Architecture

  • Tenant Isolation: Separate databases per tenant

  • Tenant Context: Passed through all layers

  • Tenant-Specific Migrations: Database versioning per tenant

Technology Stack

  • .NET 8.0: Latest .NET framework

  • FlexBase Framework: Custom enterprise framework

  • Entity Framework Core: ORM for data access

  • NServiceBus: Message bus and service bus

  • ASP.NET Core: Web API framework

  • AutoMapper: Object mapping

  • Multi-Database Support: SQL Server, MySQL, PostgreSQL

Usage and Deployment

Development

  1. Web API: Run YourProject.EndPoint.WebAPI for REST API

  2. Message Processing: Run YourProject.EndPoint.Handlers.Default for command processing

  3. Event Processing: Run YourProject.EndPoint.Subscribers.Default for event processing

  4. Background Jobs: Run YourProject.EndPoint.CronJob for scheduled tasks

Database Setup

  1. Run appropriate migration project based on your database choice

  2. Configure connection strings in appsettings

  3. Apply migrations using Entity Framework tools

Configuration

  • Multi-Environment: Development, Staging, Production configurations

  • Database Providers: Support for multiple database engines

  • Message Transports: Configurable message bus transports

  • Logging: Structured logging with different levels

This solution demonstrates a production-ready, enterprise-grade architecture that follows industry best practices for maintainability, scalability, and testability.

Last updated