Aggregate Root

Info

At ConnectSoft, Aggregates are not just a tactical modeling tool —
they are the cornerstone of building consistency, resilience, and clarity across SaaS, Microservices, and Event-Driven Architectures.

---

Introduction

In Domain-Driven Design (DDD), an Aggregate Root serves as the gateway for managing clusters of domain objects (Entities and Value Objects).
It enforces business invariants, transactional consistency, and boundary integrity within its domain scope.

An Aggregate is a consistency boundary.
The Aggregate Root is the only way to interact with the objects inside that boundary, ensuring that all business rules and constraints are honored.

At ConnectSoft, designing clear, resilient, and small Aggregates ensures:

• Domain consistency at scale
• High transactional reliability
• Microservice autonomy
• Event-driven decoupling

---

Concept Definition

An Aggregate Root:

• Defines and Protects a Boundary
  All internal modifications must go through the root entity.

• Maintains Invariants
  Business rules spanning multiple objects are guaranteed by the Aggregate.

• Manages the Lifecycle
  The root entity controls the creation and deletion of its child entities and value objects.

• Encapsulates Internal Structure
  Clients outside the Aggregate boundary only see and interact with the root entity.

• Supports Transactional Consistency
  All operations inside the Aggregate must succeed or fail as a single transaction.

---

📚 ConnectSoft Aggregate Design Principles

✅ One Aggregate Root per Aggregate
- No shared ownership. Clear, single-point control.

✅ Transactional Integrity
- Aggregate changes are committed atomically inside one transaction.

✅ Small and Focused Boundaries
- Aggregates model one clear business concept (e.g., Order, Patient, Account).

✅ Reference Other Aggregates by ID
- No object graphs crossing Aggregate boundaries — only identities are used externally.

✅ Event-First Design
- Aggregates raise Domain Events to signal significant changes across bounded contexts.

---

🧩 Visual: Aggregate Root Context

flowchart TD
    AggregateRoot("Aggregate Root (e.g., Order)")
    ChildEntity1("Child Entity (e.g., OrderItem)")
    ChildEntity2("Value Object (e.g., Address)")

    AggregateRoot -->|Manages| ChildEntity1
    AggregateRoot -->|Owns| ChildEntity2

    ExternalClient -.->|Only Accesses via Root| AggregateRoot
    ExternalClient -.->|Cannot Access Internals| ChildEntity1
    ExternalClient -.->|Cannot Access Internals| ChildEntity2

Hold "Alt" / "Option" to enable pan & zoom

✅ All external interactions happen through the Aggregate Root only.
✅ Internal structure remains hidden and protected from the outside world.

---

Real-World ConnectSoft Aggregate Examples

Domain	Aggregate Root	Child Entities / Value Objects	Invariant
E-Commerce	Order	OrderItem, ShippingAddress	An order must have at least one item.
Healthcare	Patient	Appointment, MedicalRecord	No duplicate appointments at the same time.
Finance	BankAccount	Transaction	Withdrawal cannot exceed balance.

---

Aggregates: Design Principles

Designing effective Aggregates is critical for maintaining consistency, scalability, and evolvability across complex systems.

At ConnectSoft, Aggregates are shaped using precise, strategic modeling, ensuring they remain:

• Small enough to maintain transactional consistency.
• Powerful enough to enforce business rules.
• Isolated enough to evolve independently.

---

📚 Core Design Principles

1. Single Entry Point

✅ All modifications to child entities and value objects must go through the Aggregate Root.
External clients should never directly modify internals.

Example:

• Only Order.AddItem() can add an OrderItem, not direct collection manipulation.

---

2. Protect Invariants

✅ Aggregates must enforce domain rules at all times, especially during state changes.

Example:

• A BankAccount aggregate ensures that withdrawals never create negative balances.

---

3. Reference Other Aggregates by ID

✅ Do not hold direct object references across Aggregate boundaries.
Use identifiers (IDs) to represent relationships.

Example:

• An Order references a CustomerId, not a Customer object.

---

4. Encapsulate Structure

✅ Hide internal entity graphs.
Only expose necessary behaviors via the Aggregate Root’s public API.

Example:

• Expose AddItem() or RemoveItem() methods; avoid exposing OrderItem collection for direct modification.

---

5. Transactional Consistency Boundary

✅ All operations that must succeed together belong inside one Aggregate.
If a process spans multiple Aggregates — use Domain Events and eventual consistency.

Example:

• Order and Inventory are separate aggregates; stock reservation happens asynchronously after order placement.

---

6. Delete Entire Aggregates as a Whole

✅ If an Aggregate Root is deleted, all internal entities and value objects are removed automatically.

Example:

• Deleting a Patient also deletes associated Appointments and MedicalRecords.

---

🎯 How to Recognize an Aggregate Root

Signal	Description	Example
Business Rule Ownership	The entity responsible for enforcing domain invariants.	BankAccount ensures withdrawal limits.
Lifecycle Manager	Manages creation, updates, deletion of related entities.	Order manages OrderItems.
Transactional Unit	Must be consistent across all state changes within itself.	Patient and Appointments must coordinate.
Reference Target	Other systems refer to this entity via ID.	OrderId, not OrderItemId.

---

🧩 Visual: Aggregate Root Boundary and Relationships

flowchart TD
    AggregateRoot("Aggregate Root (e.g., BankAccount)")
    ChildEntity1("Child Entity (e.g., Transaction)")
    ValueObject1("Value Object (e.g., Money)")
    ExternalSystem("External System (e.g., Payment Gateway)")

    AggregateRoot -->|Manages| ChildEntity1
    AggregateRoot -->|Uses| ValueObject1
    ExternalSystem -.->|References by ID| AggregateRoot

Hold "Alt" / "Option" to enable pan & zoom

✅ External systems never interact directly with child entities.
✅ Only Aggregate Root exposes controlled behaviors.

---

🔥 Strategic Modeling Guidance

• Keep Aggregates small: Prefer multiple small aggregates over one bloated aggregate.
• Aggregate boundaries should evolve as your domain understanding grows.
• Transactional costs grow with aggregate size — design accordingly.
• Model for consistency, not query convenience.
• Use Domain Events for workflows crossing Aggregate boundaries.

---

Advanced Best Practices for Aggregates

Building effective Aggregates requires balancing domain complexity, transactional consistency, and system scalability.

At ConnectSoft, these advanced best practices guide aggregate design across SaaS, microservices, and cloud-native solutions.

---

📚 Best Practices

✅ Design Aggregates for Invariants, Not Queries

• Focus on enforcing business rules within the Aggregate.
• Optimize for consistency, not for query or reporting convenience.

✅ Keep Aggregates Small

• Design Aggregates around the smallest transactional boundary possible.
• Avoid overly large aggregates that load unnecessary data.

✅ Reference Other Aggregates by ID Only

• Prevent tight coupling by using identifiers instead of object references.

✅ Model Behavior in the Aggregate Root

• Expose behaviors (methods) through the root — not the children.
• The root protects the consistency boundary.

✅ Raise Domain Events Inside Aggregates

• Let Aggregates signal important changes via events (e.g., OrderPlaced, FundsTransferred).

✅ Guard Invariants Proactively

• Validate rules before any state changes.
• Don't allow the Aggregate to reach an invalid intermediate state.

✅ Isolate Complex Operations

• For multi-aggregate operations, use Application Services and Domain Services — not massive aggregates.

✅ Treat Aggregates as Transactional Units

• All changes inside an aggregate must commit or rollback atomically.

---

🛑 Common Pitfalls to Avoid

Pitfall	Problem	ConnectSoft Recommendation
Overly Large Aggregates	Hard to maintain, hurts scalability, bloats transactions.	Model smaller, cohesive aggregates.
Cross-Aggregate References	Tight coupling, hidden side effects.	Always reference external aggregates by ID.
Anemic Aggregates	Aggregate root exposes only data, no behavior.	Model meaningful methods inside Aggregate Root.
Leaky Internals	External code modifies child entities directly.	Expose only controlled operations from the Root.
Ignoring Domain Events	Missed opportunities for decoupling workflows.	Raise domain events naturally inside aggregates.
Mixing Read and Write Models	Optimizations compromise consistency.	Use separate CQRS models if needed.
Batch Updates Across Aggregates	Violates transaction boundaries, poor consistency.	Coordinate with eventual consistency patterns.

---

🎯 Anti-Patterns Cheat Sheet

Anti-Pattern	Symptom	What To Do Instead
Aggregate Graph Explosion	Aggregate includes many unnecessary child objects.	Only include entities essential for consistency.
CRUD Aggregates	Aggregate simply stores and retrieves data without behavior.	Model domain behaviors directly in Aggregate Root.
Direct Child Entity Exposure	Application code modifies children directly.	Only allow changes through Aggregate Root methods.
Two Aggregates Sharing State	Two roots try to coordinate shared state inside transactions.	Split models and use Domain Events for coordination.

---

🧠 ConnectSoft Rule of Thumb

"The more natural and cohesive the behavior inside an Aggregate feels to the business expert, the better the model."

Always model aggregates in terms of real-world business rules and invariants, not technical database relations.

---

ConnectSoft.Extensions.EntityModel.Enumeration Base Classes

At ConnectSoft, we use the ConnectSoft.Extensions.EntityModel package to provide a consistent foundation for all aggregate roots and entities.

Base Classes and Interfaces:

• EntityWithTypedId<TIdentity> — Base class for entities with typed identity (e.g., Guid, int, string)
• IAggregateRoot<TPrimaryKey> — Interface marking an entity as an aggregate root
• IGenericEntity<TIdentity> — Base interface for all entities

Key Characteristics:

• Typed Identity — Entities have a strongly-typed Id property
• ORM Support — Virtual properties enable lazy loading and change tracking
• Value Semantics — Proper Equals() and GetHashCode() implementations based on identity
• Interface Segregation — Clear separation between aggregate roots and regular entities

---

Deep Dive: ConnectSoft Aggregate Root Implementation

Let's explore a real-world Product Aggregate from the ConnectSoft.Saas.ProductsCatalog microservice:

• Implementing IAggregateRoot<Guid>
• Managing Child Entities (Editions, Business Models)
• Using Enumerations for Domain States
• Working with Application Services and Domain Events

---

🛠️ Real-World Example: Product Aggregate Root from ConnectSoft.Saas.ProductsCatalog

Step 1: Define the Aggregate Root Interface

Real Implementation from ConnectSoft.Saas.ProductsCatalog.EntityModel:

// Ignore Spelling: Saas

namespace ConnectSoft.Saas.ProductsCatalog.EntityModel
{
    using System;
    using System.Collections.Generic;
    using ConnectSoft.Extensions.EntityModel;

    /// <summary>
    /// ConnectSoft.Saas.ProductsCatalog's aggregate root contract.
    /// Product is an entity that represents a SaaS product offering, such as a software package or service.
    /// </summary>
    public partial interface IProduct : IAggregateRoot<Guid>
    {
        /// <summary>
        /// Gets or sets a object identifier.
        /// </summary>
        Guid ProductId { get; set; }

        /// <summary>
        /// Gets or sets the name of the product (e.g., "CRM Suite", "Analytics Platform").
        /// </summary>
        string Name { get; set; }

        /// <summary>
        /// Gets or sets the display name of the product.
        /// </summary>
        string DisplayName { get; set; }

        /// <summary>
        /// Gets or sets the unique identifier for the product.
        /// </summary>
        string Key { get; set; }

        /// <summary>
        /// Gets or sets the detailed description of the product.
        /// </summary>
        string Description { get; set; }

        /// <summary>
        /// Gets or sets the category of the product (e.g., CRM, ERP, Analytics).
        /// </summary>
        string ProductCategory { get; set; }

        /// <summary>
        /// Gets or sets the status of the product.
        /// </summary>
        ProductStatusEnumeration Status { get; set; }

        /// <summary>
        /// Gets or sets the date when the product was created.
        /// </summary>
        DateTime CreationDate { get; set; }

        /// <summary>
        /// Gets or sets the latest version of the product.
        /// </summary>
        string? LatestVersion { get; set; }

        /// <summary>
        /// Gets or sets the release notes about recent updates.
        /// </summary>
        string? ReleaseNotes { get; set; }

        /// <summary>
        /// Gets or sets the date when the product was deactivated.
        /// </summary>
        DateTime? DeactivationDate { get; set; }

        /// <summary>
        /// Gets or sets the list of editions available for the product.
        /// </summary>
        IList<IEdition> Editions { get; set; }

        /// <summary>
        /// Gets or sets the list of business models that include this product.
        /// </summary>
        IList<IBusinessModel> IncludedInBusinessModels { get; set; }
    }
}

Key Pattern Elements:

✅ Extends IAggregateRoot<Guid> — Marks this as an aggregate root with Guid identity
✅ Interface Segregation — Separates contract from implementation
✅ Child Entity Collections — Editions and IncludedInBusinessModels are managed within the aggregate
✅ Uses Enumerations — ProductStatusEnumeration for domain-specific status values

---

Step 2: Implement the Aggregate Root Entity

Real Implementation from ConnectSoft.Saas.ProductsCatalog.EntityModel.PocoEntities:

// Ignore Spelling: Saas

namespace ConnectSoft.Saas.ProductsCatalog.EntityModel.PocoEntities
{
    using System;
    using System.Collections.Generic;
    using ConnectSoft.Extensions.EntityModel;

    /// <summary>
    /// Product poco entity.
    /// </summary>
    public partial class ProductEntity : EntityWithTypedId<Guid>, IProduct
    {
        /// <inheritdoc/>
        public virtual Guid ProductId { get; set; }

        /// <inheritdoc/>
        required public virtual string Name { get; set; }

        /// <inheritdoc/>
        required public virtual string DisplayName { get; set; }

        /// <inheritdoc/>
        required public virtual string Key { get; set; }

        /// <inheritdoc/>
        required public virtual string Description { get; set; }

        /// <inheritdoc/>
        required public virtual string ProductCategory { get; set; }

        /// <inheritdoc/>
        required public virtual ProductStatusEnumeration Status { get; set; }

        /// <inheritdoc/>
        public virtual DateTime CreationDate { get; set; }

        /// <inheritdoc/>
        public virtual DateTime? DeactivationDate { get; set; }

        /// <inheritdoc/>
        public virtual string? LatestVersion { get; set; }

        /// <inheritdoc/>
        public virtual string? ReleaseNotes { get; set; }

        /// <inheritdoc/>
        public virtual IList<IBusinessModel> IncludedInBusinessModels { get; set; } = new List<IBusinessModel>();

        /// <inheritdoc/>
        public virtual IList<IEdition> Editions { get; set; } = new List<IEdition>();

        /// <inheritdoc/>
        public override Guid Id
        {
            get
            {
                return this.ProductId;
            }

            protected set
            {
                this.ProductId = value;
            }
        }
    }
}

Key Implementation Patterns:

✅ Inherits from EntityWithTypedId<Guid> — Base class provides identity management and value semantics
✅ Implements IProduct — Satisfies the aggregate root interface contract
✅ Virtual Properties — Enables ORM lazy loading and change tracking
✅ Required Properties — Uses C# 11 required keyword for non-nullable properties
✅ Id Property Mapping — Overrides Id to map to ProductId for domain clarity
✅ Child Entity Collections — Initialized with empty lists to avoid null reference issues

---

Step 3: Child Entity Example (Edition)

Real Implementation showing how child entities are structured:

namespace ConnectSoft.Saas.ProductsCatalog.EntityModel.PocoEntities
{
    using System;
    using System.Collections.Generic;
    using ConnectSoft.Extensions.EntityModel;

    /// <summary>
    /// Edition poco entity.
    /// </summary>
    public class EditionEntity : EntityWithTypedId<Guid>, IEdition
    {
        /// <inheritdoc/>
        required public virtual Guid EditionId { get; set; }

        /// <inheritdoc/>
        required public virtual string Name { get; set; }

        /// <inheritdoc/>
        required public virtual string DisplayName { get; set; }

        /// <inheritdoc/>
        required public virtual string Key { get; set; }

        /// <inheritdoc/>
        required public virtual string Description { get; set; }

        /// <inheritdoc/>
        required public virtual DateTime CreationDate { get; set; }

        /// <inheritdoc/>
        required public virtual EditionStatusEnumeration Status { get; set; }

        /// <inheritdoc/>
        required public virtual IProduct Product { get; set; }  // ✅ References aggregate root

        /// <inheritdoc/>
        required public virtual IEditionPricingModel EditionPricing { get; set; }

        /// <inheritdoc/>
        required public virtual IList<IEditionFeature> EditionFeatures { get; set; } = new List<IEditionFeature>();

        /// <inheritdoc/>
        required public virtual IList<IServiceLevelAgreement> ServiceLevelAgreements { get; set; } = new List<IServiceLevelAgreement>();

        /// <inheritdoc/>
        public override Guid Id
        {
            get => this.EditionId;
            protected set => this.EditionId = value;
        }
    }
}

✅ References Aggregate Root — Product property maintains the relationship to the root
✅ Same Base Class — Uses EntityWithTypedId<Guid> for consistency
✅ Nested Collections — Can have its own child entities (e.g., EditionFeatures)

---

Step 4: Using Aggregates in Application Services

Real Implementation from ConnectSoft.Saas.ProductsCatalog.DomainModel.Impl:

namespace ConnectSoft.Saas.ProductsCatalog.DomainModel.Impl
{
    using System;
    using System.Threading.Tasks;
    using ConnectSoft.Extensions.PersistenceModel;
    using ConnectSoft.Saas.ProductsCatalog.EntityModel;
    using ConnectSoft.Saas.ProductsCatalog.EntityModel.PocoEntities;
    using ConnectSoft.Extensions.MessagingModel;
    using ConnectSoft.Saas.ProductsCatalog.MessagingModel;

    /// <summary>
    /// Default IProductsProcessor implementation to process, manage and store Products.
    /// </summary>
    public class DefaultProductsProcessor : IProductsProcessor
    {
        private readonly IProductsRepository repository;
        private readonly IUnitOfWork unitOfWork;
        private readonly IEventBus eventBus;
        private readonly TimeProvider dateTimeProvider;

        // ... constructor ...

        /// <summary>
        /// Creates a new Product aggregate root.
        /// </summary>
        public async Task<IProduct> CreateProduct(CreateProductInput input, CancellationToken token = default)
        {
            // 1. Validate input
            await this.createProductInputValidator.ValidateAndThrowAsync(input, token);

            // 2. Check if product already exists
            IProduct existingProduct = await this.repository.GetByIdAsync(input.ProductId);
            if (existingProduct != null)
            {
                throw new ProductAlreadyExistsException(input.ProductId);
            }

            // 3. Create new aggregate root
            ProductEntity newProduct = new ProductEntity()
            {
                ProductId = input.ProductId,
                CreationDate = this.dateTimeProvider.GetUtcNow().DateTime,
                Name = "Salesforce CRM Cloud",
                DisplayName = "Salesforce CRM Cloud",
                Key = "Salesforce-CRM-Cloud",
                Description = "Unified CRM platform for sales, marketing, and customer support.",
                ProductCategory = "CRM",
                Status = ProductStatusEnumeration.Active,  // ✅ Using enumeration
                LatestVersion = "v1.0.0",
                ReleaseNotes = "Initial release.",
            };

            // 4. Persist within transaction
            this.unitOfWork.ExecuteTransactional(() =>
            {
                newProduct.ProductId = input.ProductId;
                this.repository.Insert(newProduct);
            });

            // 5. Publish domain event (outside transaction for eventual consistency)
            await this.eventBus.PublishEvent<ProductCreatedEvent>(
                new ProductCreatedEvent()
                {
                    ProductId = newProduct.ProductId,
                },
                token);

            return newProduct;
        }

        /// <summary>
        /// Deletes a Product aggregate root and all its children.
        /// </summary>
        public async Task DeleteProduct(DeleteProductInput input, CancellationToken token = default)
        {
            // 1. Validate input
            await this.deleteProductInputValidator.ValidateAndThrowAsync(input, token);

            // 2. Load aggregate root
            IProduct productToDelete = await this.repository.GetByIdAsync(input.ProductId);
            if (productToDelete == null)
            {
                throw new ProductNotFoundException(input.ProductId);
            }

            // 3. Delete within transaction (cascades to children)
            this.unitOfWork.ExecuteTransactional(() =>
            {
                this.repository.Delete(productToDelete);
            });
        }
    }
}

Key Application Service Patterns:

✅ Repository Pattern — Uses IProductsRepository to load and persist aggregates
✅ Unit of Work — ExecuteTransactional() ensures atomic persistence
✅ Domain Events — Publishes events after successful persistence
✅ Validation — Input validation before domain operations
✅ Exception Handling — Domain-specific exceptions for business rule violations

---

Step 5: Domain Event Definition

Real Implementation showing how domain events are structured:

namespace ConnectSoft.Saas.ProductsCatalog.MessagingModel
{
    using System;
    using System.ComponentModel.DataAnnotations;
    using ConnectSoft.Extensions.DataAnnotations;
    using ConnectSoft.Extensions.MessagingModel;

    /// <summary>
    /// Event that used to raise when IProduct successfully created.
    /// </summary>
    public class ProductCreatedEvent : IEvent
    {
        /// <summary>
        /// Gets or sets a object identifier.
        /// </summary>
        [Required]
        [NotDefault]
        public Guid ProductId { get; set; }
    }
}

✅ Implements IEvent — ConnectSoft's event interface for messaging
✅ Data Annotations — Validation attributes ensure event data integrity
✅ Immutable Identity — Contains only the aggregate root ID for loose coupling

---

📚 Key Modeling Lessons from ConnectSoft Examples

✅ Aggregate Root (ProductEntity) inherits from EntityWithTypedId<Guid> and implements IAggregateRoot<Guid>

✅ Interface-Based Design (IProduct) separates contract from implementation

✅ Child entities (EditionEntity) reference the aggregate root via interface

✅ Virtual properties enable ORM lazy loading and change tracking

✅ Domain Events (ProductCreatedEvent) are published by Application Services after persistence

✅ Repository and Unit of Work patterns ensure transactional consistency

✅ Enumerations (ProductStatusEnumeration) express domain concepts clearly

✅ Validation happens at the Application Service layer before domain operations

---

📋 Complete Implementation Template

Here's a complete template you can use to create new aggregate roots following ConnectSoft patterns:

// Ignore Spelling: [Add any domain-specific terms here]

namespace YourNamespace.EntityModel
{
    using System;
    using System.Collections.Generic;
    using ConnectSoft.Extensions.EntityModel;

    /// <summary>
    /// Your aggregate root contract.
    /// </summary>
    public interface IYourAggregateRoot : IAggregateRoot<Guid>
    {
        /// <summary>
        /// Gets or sets a object identifier.
        /// </summary>
        Guid YourAggregateRootId { get; set; }

        /// <summary>
        /// Gets or sets the name.
        /// </summary>
        string Name { get; set; }

        // ... other properties ...

        /// <summary>
        /// Gets or sets child entities.
        /// </summary>
        IList<IChildEntity> ChildEntities { get; set; }
    }
}

namespace YourNamespace.EntityModel.PocoEntities
{
    using System;
    using System.Collections.Generic;
    using ConnectSoft.Extensions.EntityModel;

    /// <summary>
    /// Your aggregate root poco entity.
    /// </summary>
    public class YourAggregateRootEntity : EntityWithTypedId<Guid>, IYourAggregateRoot
    {
        /// <inheritdoc/>
        public virtual Guid YourAggregateRootId { get; set; }

        /// <inheritdoc/>
        required public virtual string Name { get; set; }

        // ... other properties ...

        /// <inheritdoc/>
        public virtual IList<IChildEntity> ChildEntities { get; set; } = new List<IChildEntity>();

        /// <inheritdoc/>
        public override Guid Id
        {
            get => this.YourAggregateRootId;
            protected set => this.YourAggregateRootId = value;
        }
    }
}

✅ Follow this pattern for all new aggregate roots to ensure consistency across ConnectSoft projects.

---

🧩 Real-World ConnectSoft Pattern: Raising Events from Aggregates

In ConnectSoft, domain events are typically published by Application Services after successful persistence, not directly from aggregates. This pattern ensures:

• Transactional Safety — Events are published only after successful database commits
• Eventual Consistency — Events are handled asynchronously outside the transaction boundary
• Infrastructure Separation — Aggregates remain pure domain models without infrastructure dependencies

sequenceDiagram
    participant API
    participant ApplicationService
    participant ProductAggregate
    participant Repository
    participant UnitOfWork
    participant EventBus
    participant OtherService

    API->>ApplicationService: CreateProduct()
    ApplicationService->>Repository: GetById()
    ApplicationService->>ProductAggregate: new ProductEntity()
    ApplicationService->>UnitOfWork: ExecuteTransactional()
    UnitOfWork->>Repository: Insert()
    ApplicationService->>EventBus: PublishEvent(ProductCreatedEvent)
    EventBus-->>OtherService: Notify ProductCreatedEvent

Hold "Alt" / "Option" to enable pan & zoom

Key Pattern: 1. Application Service creates/modifies aggregate 2. Aggregate is persisted within transaction 3. After successful persistence, event is published 4. Other services react to events asynchronously

---

🎯 ConnectSoft Aggregate Root Checklist

When implementing aggregate roots at ConnectSoft, ensure:

Checklist Item	Description	Example
✅ Inherit from EntityWithTypedId<TIdentity>	Use base class for identity management	EntityWithTypedId<Guid>
✅ Implement IAggregateRoot<TIdentity>	Mark as aggregate root via interface	IAggregateRoot<Guid>
✅ Define Interface Contract	Create interface for aggregate root	IProduct : IAggregateRoot<Guid>
✅ Use Virtual Properties	Enable ORM lazy loading	public virtual string Name { get; set; }
✅ Map Id Property	Override Id to map to domain-specific ID	ProductId maps to Id
✅ Initialize Collections	Avoid null reference exceptions	= new List<IChildEntity>()
✅ Use Enumerations	Express domain states clearly	ProductStatusEnumeration
✅ Reference Children by Interface	Maintain loose coupling	IList<IEdition> not List<EditionEntity>
✅ Repository Pattern	Use repositories for persistence	IProductsRepository
✅ Unit of Work	Ensure transactional consistency	IUnitOfWork.ExecuteTransactional()
✅ Domain Events	Publish events after persistence	IEventBus.PublishEvent<T>()

---

Conclusion

At ConnectSoft, Aggregate Roots are not optional — they are a strategic foundation for building reliable, resilient, and scalable systems.

When Aggregates are modeled carefully:

• Business rules are enforced naturally.
• Systems can scale independently across bounded contexts.
• Domain logic remains isolated, testable, and evolvable.
• Transaction boundaries are clear and respected.
• Event-driven workflows emerge cleanly without tight coupling.

---

🎯 Key Takeaways

✅ Design Aggregates Around Invariants
Focus on protecting business rules, not just grouping data.

✅ Keep Aggregates Small and Focused
Small boundaries make transactions fast and safe.

✅ Raise Domain Events
Let Aggregates announce meaningful changes across the platform.

✅ Use Identifiers to Reference Other Aggregates
IDs, not direct references, maintain loose coupling.

✅ Test Invariants Relentlessly
Build unit tests validating all Aggregate behaviors.

---

🧩 Advanced Architecture Patterns for Aggregates

Pattern	Purpose	When to Use
Event Sourcing	Persist changes as a stream of events instead of snapshots.	Highly dynamic, auditable domains (e.g., Banking, Logistics).
Command Sourcing	Capture the intent (commands) that led to state changes.	Systems needing deep traceability of user intentions.
Snapshotting	Optimize loading aggregates with many events.	Event-sourced systems with high event counts.
CQRS (Command Query Responsibility Segregation)	Separate models for reads and writes.	High-read systems, complex domain querying.
Transactional Outbox Pattern	Ensure reliable event publishing with database consistency.	Microservices communicating asynchronously via events.

---

🚀 ConnectSoft Modeling Philosophy

"Aggregates are the guardians of truth, integrity, and boundaries.
Systems that model them well don't just survive — they scale, evolve, and thrive."

At ConnectSoft, Aggregates are designed for clarity, autonomy, integrity, and change —
because the real world never stops changing.

---

References

• Books and Literature

  • Eric Evans — Domain-Driven Design: Tackling Complexity in the Heart of Software
  • Vaughn Vernon — Implementing Domain-Driven Design
  • Jimmy Nilsson — Applying Domain-Driven Design and Patterns

• Online Resources

  • Martin Fowler — DDD Aggregates
  • Microsoft — Microservices and DDD Guide
  • Sairyss — Domain-Driven Hexagon Patterns

• ConnectSoft Packages and Code

  • ConnectSoft.Extensions.EntityModel — Base classes and interfaces:
    • EntityWithTypedId<TIdentity> — Base class for entities with typed identity
    • IAggregateRoot<TPrimaryKey> — Interface marking aggregate roots
    • IGenericEntity<TIdentity> — Base interface for all entities
    • Proper Equals(), GetHashCode(), and identity semantics
  • ConnectSoft.Extensions.PersistenceModel — Persistence infrastructure:
    • IUnitOfWork — Unit of Work pattern implementation
    • Repository pattern support
    • Transaction management
  • ConnectSoft.Extensions.MessagingModel — Domain events:
    • IEvent — Base interface for domain events
    • IEventBus — Event publishing infrastructure
  • Real-World Examples — See ConnectSoft.Saas.ProductsCatalog.EntityModel for production implementations:
    • IProduct / ProductEntity — Complete aggregate root example
    • IEdition / EditionEntity — Child entity example
    • DefaultProductsProcessor — Application Service example
    • ProductCreatedEvent — Domain event example

• ConnectSoft Internal Standards

  • ConnectSoft Architecture Blueprints
  • ConnectSoft Microservices Reference Architecture
  • ConnectSoft Event-Driven Messaging Patterns