TaskHub.Shared

TaskHub.Shared.Domain - Technical Manual

The TaskHub.Shared.Domain module provides the foundational building blocks for implementing a rich, observable domain model following the principles of Domain-Driven Design (DDD). It enforces strong encapsulation, invariant protection, and a reliable event-driven architecture.

🏛 Deep Architecture

1. Aggregate Lifecycle & Internal Event Bus

The AggregateBase<TId> class is the heart of the domain. It manages more than just an identifier:

State Protection: It encourages the use of private set properties, forcing all state mutations to go through public methods that validate business rules (Invariants).
Domain Event Collection: It maintains a protected readonly List<IDomainEvent> MyEvents. When a business rule is executed, the aggregate “records” what happened by calling AddEvent().
Atomic Persistence: These events are “staged” within the aggregate instance. They are not dispatched immediately but are captured by the UnitOfWork during the persistence phase, ensuring that business data and event records are saved in one atomic database transaction.

2. Domain Exception Strategy

TaskHub uses a specialized exception hierarchy to distinguish between Expected Business Rule Violations and Unexpected Technical Failures:

DomainException: The base class for all business errors. When thrown, the BasicHostBuilder global exception handler catches it and converts it into a Result object with an appropriate error code, preventing 500 internal server errors for known business rules.
DomainErrorBase: A record-based pattern for defining structured error details that can be localized and sent to the client.

🛠 API Reference

`AggregateBase<TId>`

`IDomainEvent`

🚀 Complex Implementation Example

Scenario: A Project Management Aggregate

using TaskHub.Shared.Domain.Aggregates;
using TaskHub.Shared.Domain.Events;
using TaskHub.Shared.Domain.Exceptions;

public class Project : AggregateBase<Guid>
{
    private readonly List<ProjectTask> _tasks = new();

    public Project(Guid id, string name, Guid ownerId) : base(id)
    {
        if (string.IsNullOrWhiteSpace(name)) throw new DomainException("Project name cannot be empty.");
        
        Name = name;
        OwnerId = ownerId;
        Status = ProjectStatus.Active;

        AddEvent(new ProjectCreatedDomainEvent(id, name, ownerId));
    }

    public string Name { get; private set; }
    public Guid OwnerId { get; private set; }
    public ProjectStatus Status { get; private set; }
    public IReadOnlyCollection<ProjectTask> Tasks => _tasks.AsReadOnly();

    public void AddTask(string title, string description)
    {
        if (Status != ProjectStatus.Active)
            throw new DomainException("Cannot add tasks to an inactive project.");

        if (_tasks.Any(t => t.Title == title))
            throw new DomainException($"Task with title '{title}' already exists.");

        var task = new ProjectTask(Guid.NewGuid(), title, description);
        _tasks.Add(task);

        AddEvent(new TaskAddedToProjectDomainEvent(Id, task.Id, title));
    }

    public void Complete()
    {
        if (_tasks.Any(t => !t.IsCompleted))
            throw new DomainException("Cannot complete project while tasks are pending.");

        Status = ProjectStatus.Completed;
        AddEvent(new ProjectCompletedDomainEvent(Id));
    }
}

⚙️ Persistence Integration (EF Core)

The domain model is designed to be mapped seamlessly to EF Core. Use IEntityTypeConfiguration to map the private fields and collections.

public class ProjectConfiguration : IEntityTypeConfiguration<Project>
{
    public void Configure(EntityTypeBuilder<Project> builder)
    {
        builder.HasKey(x => x.Id);
        
        // Map the private list to a backing field
        builder.HasMany(x => x.Tasks)
               .WithOne()
               .HasForeignKey("ProjectId")
               .OnDelete(DeleteBehavior.Cascade);
               
        var navigation = builder.Metadata.FindNavigation(nameof(Project.Tasks));
        navigation?.SetPropertyAccessMode(PropertyAccessMode.Field);
    }
}

👁 Telemetry & Diagnostics

Captured Data

When events are dispatched via the IEventsBus (integrated with the Outbox), the system automatically adds:

event.type: The full name of the event class.
aggregate.id: The ID of the aggregate that produced the event.

✅ Best Practices & Anti-Patterns

🟢 Best Practices

Always use UTC: Ensure all domain event timestamps use DateTime.UtcNow.
Reference by ID: Only store references to other aggregate roots by their Id. Use navigation properties only for entities within the same aggregate boundary.
Immutable Events: Define domain events as public record to ensure they cannot be modified after creation.

🔴 Anti-Patterns

Business Logic in Services: Avoid “Anemic Domain Models” where aggregates are just data buckets and services contain all the logic. Logic belongs in the aggregate.
Injecting Dependencies into Aggregates: Aggregates should be “pure” and not depend on external services (like DBs or APIs). Pass data into them via method arguments.

This site is open source. Improve this page.