Practical Domain-Driven Design: End-to-End Guide

public sealed record DocumentId
{
    public Guid Value { get; }

    public DocumentId(Guid value)
    {
        if (value == Guid.Empty)
            throw new DomainException("DocumentId cannot be empty.");

        Value = value;
    }

    public static DocumentId New() => new(Guid.NewGuid());

    public override string ToString() => Value.ToString();
}

public sealed record UserId
{
    public string Value { get; }

    public UserId(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new DomainException("UserId cannot be empty.");

        if (value.Length != 8 || !value.All(char.IsLetterOrDigit))
            throw new DomainException(
                "UserId must be an 8-character alphanumeric BlueRobinId.");

        Value = value.ToLowerInvariant();
    }

    public override string ToString() => Value;
}

public sealed record Filename
{
    private static readonly HashSet<string> AllowedExtensions =
        [".pdf", ".docx", ".xlsx", ".pptx", ".txt", ".md", ".jpg", ".png"];

    public string Value { get; }
    public string Extension => Path.GetExtension(Value).ToLowerInvariant();

    public Filename(string value)
    {
        if (string.IsNullOrWhiteSpace(value))
            throw new DomainException("Filename cannot be empty.");

        var ext = Path.GetExtension(value).ToLowerInvariant();

        if (!AllowedExtensions.Contains(ext))
            throw new DomainException(
                $"File extension '{ext}' is not supported. " +
                $"Allowed: {string.Join(", ", AllowedExtensions)}");

        // Sanitize: keep only the filename, not any path components
        Value = Path.GetFileName(value);
    }

    public override string ToString() => Value;
}

public class Document : AggregateRoot
{
    public DocumentId Id { get; private set; }
    public UserId OwnerId { get; private set; }
    public Filename OriginalFilename { get; private set; }
    public DocumentStatus Status { get; private set; }

    public DateTime CreatedAt { get; private set; }
    public DateTime? ProcessedAt { get; private set; }
    public DateTime? ArchivedAt { get; private set; }
    public string? Title { get; private set; }
    public string? Summary { get; private set; }

    // Private constructor for EF Core materialization
    private Document() { }

    // ── Factory Method ─────────────────────────────────
    // The only way to create a Document. Ensures initial
    // state is always valid and records the genesis event.

    public static Document Create(
        DocumentId id,
        UserId ownerId,
        Filename filename)
    {
        var doc = new Document
        {
            Id = id,
            OwnerId = ownerId,
            OriginalFilename = filename,
            Status = DocumentStatus.Draft,
            CreatedAt = DateTime.UtcNow
        };

        doc.AddDomainEvent(new DocumentCreated(id, ownerId, filename));
        return doc;
    }

    // ── State Transitions ──────────────────────────────

    public void RequestProcessing()
    {
        if (Status != DocumentStatus.Draft)
            throw new DomainException(
                $"Cannot request processing: document is in '{Status}' state. " +
                "Only Draft documents can be submitted for processing.");

        Status = DocumentStatus.Processing;
        AddDomainEvent(new DocumentProcessingRequested(Id));
    }

    public void MarkAsProcessed(string? title = null, string? summary = null)
    {
        if (Status != DocumentStatus.Processing)
            throw new DomainException(
                $"Cannot mark as processed: document is in '{Status}' state. " +
                "Only documents currently being processed can transition to Processed.");

        Status = DocumentStatus.Processed;
        ProcessedAt = DateTime.UtcNow;
        Title = title;
        Summary = summary;

        AddDomainEvent(new DocumentProcessed(Id));
    }

    public void UpdateMetadata(string? title, string? summary)
    {
        if (Status == DocumentStatus.Archived)
            throw new DomainException(
                "Cannot update metadata: document is archived and immutable.");

        if (Status == DocumentStatus.Draft)
            throw new DomainException(
                "Cannot update metadata: document has not been processed yet.");

        Title = title ?? Title;
        Summary = summary ?? Summary;

        AddDomainEvent(new DocumentMetadataUpdated(Id));
    }

    public void Archive()
    {
        if (Status == DocumentStatus.Archived)
            throw new DomainException("Document is already archived.");

        if (Status == DocumentStatus.Processing)
            throw new DomainException(
                "Cannot archive a document while it is processing.");

        if (Status == DocumentStatus.Draft)
            throw new DomainException(
                "Cannot archive a document that hasn't been processed.");

        Status = DocumentStatus.Archived;
        ArchivedAt = DateTime.UtcNow;

        AddDomainEvent(new DocumentArchived(Id));
    }
}

// Base marker for all domain events
public interface IDomainEvent
{
    DateTime OccurredAt { get; }
}

public sealed record DocumentCreated(
    DocumentId DocumentId,
    UserId OwnerId,
    Filename Filename) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public sealed record DocumentProcessingRequested(
    DocumentId DocumentId) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public sealed record DocumentProcessed(
    DocumentId DocumentId) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public sealed record DocumentMetadataUpdated(
    DocumentId DocumentId) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public sealed record DocumentArchived(
    DocumentId DocumentId) : IDomainEvent
{
    public DateTime OccurredAt { get; } = DateTime.UtcNow;
}

public interface IDocumentRepository
{
    Task<Document?> GetByIdAsync(DocumentId id, CancellationToken ct = default);
    Task<IReadOnlyList<Document>> GetByOwnerAsync(UserId ownerId, CancellationToken ct = default);
    Task AddAsync(Document document, CancellationToken ct = default);
    Task SaveChangesAsync(CancellationToken ct = default);
}

public class DocumentRepository : IDocumentRepository
{
    private readonly ArchivesDbContext _db;

    public DocumentRepository(ArchivesDbContext db) => _db = db;

    public async Task<Document?> GetByIdAsync(
        DocumentId id, CancellationToken ct = default)
    {
        return await _db.Documents
            .FirstOrDefaultAsync(d => d.Id == id, ct);
    }

    public async Task<IReadOnlyList<Document>> GetByOwnerAsync(
        UserId ownerId, CancellationToken ct = default)
    {
        return await _db.Documents
            .Where(d => d.OwnerId == ownerId)
            .OrderByDescending(d => d.CreatedAt)
            .ToListAsync(ct);
    }

    public async Task AddAsync(
        Document document, CancellationToken ct = default)
    {
        await _db.Documents.AddAsync(document, ct);
    }

    public async Task SaveChangesAsync(CancellationToken ct = default)
    {
        await _db.SaveChangesAsync(ct);
    }
}

public class DocumentConfiguration : IEntityTypeConfiguration<Document>
{
    public void Configure(EntityTypeBuilder<Document> builder)
    {
        builder.ToTable("documents");

        builder.HasKey(d => d.Id);

        // Value Object → column conversions
        builder.Property(d => d.Id)
            .HasConversion(
                id => id.Value,
                value => new DocumentId(value))
            .HasColumnName("id");

        builder.Property(d => d.OwnerId)
            .HasConversion(
                id => id.Value,
                value => new UserId(value))
            .HasColumnName("owner_id")
            .HasMaxLength(8);

        builder.Property(d => d.OriginalFilename)
            .HasConversion(
                fn => fn.Value,
                value => new Filename(value))
            .HasColumnName("original_filename")
            .HasMaxLength(255);

        builder.Property(d => d.Status)
            .HasConversion<string>()
            .HasColumnName("status")
            .HasMaxLength(20);

        builder.Property(d => d.CreatedAt).HasColumnName("created_at");
        builder.Property(d => d.ProcessedAt).HasColumnName("processed_at");
        builder.Property(d => d.ArchivedAt).HasColumnName("archived_at");
        builder.Property(d => d.Title).HasColumnName("title").HasMaxLength(500);
        builder.Property(d => d.Summary).HasColumnName("summary").HasMaxLength(2000);

        // Index for owner lookups
        builder.HasIndex(d => d.OwnerId).HasDatabaseName("ix_documents_owner_id");
        builder.HasIndex(d => d.Status).HasDatabaseName("ix_documents_status");
    }
}

public class ArchiveDocumentHandler
{
    private readonly IDocumentRepository _repository;
    private readonly IDomainEventDispatcher _dispatcher;
    private readonly ILogger<ArchiveDocumentHandler> _logger;

    public ArchiveDocumentHandler(
        IDocumentRepository repository,
        IDomainEventDispatcher dispatcher,
        ILogger<ArchiveDocumentHandler> logger)
    {
        _repository = repository;
        _dispatcher = dispatcher;
        _logger = logger;
    }

    public async Task<Result> HandleAsync(
        DocumentId documentId,
        UserId requestingUserId,
        CancellationToken ct)
    {
        // 1. Load the Aggregate
        var document = await _repository.GetByIdAsync(documentId, ct);
        if (document is null)
            return Result.NotFound($"Document {documentId} not found.");

        // 2. Authorization check (not a domain rule, but an application concern)
        if (document.OwnerId != requestingUserId)
            return Result.Forbidden("You can only archive your own documents.");

        // 3. Invoke Domain Behavior
        //    If invariants are violated, DomainException is thrown.
        document.Archive();

        // 4. Persist (transaction commit)
        await _repository.SaveChangesAsync(ct);

        // 5. Dispatch Domain Events (after commit succeeds)
        await _dispatcher.DispatchAsync(document.DomainEvents, ct);

        _logger.LogInformation(
            "Document {DocumentId} archived by {UserId}",
            documentId.Value.ToString()[..8],
            requestingUserId);

        return Result.Success();
    }
}

public class CreateDocumentHandler
{
    private readonly IDocumentRepository _repository;
    private readonly IDomainEventDispatcher _dispatcher;

    public CreateDocumentHandler(
        IDocumentRepository repository,
        IDomainEventDispatcher dispatcher)
    {
        _repository = repository;
        _dispatcher = dispatcher;
    }

    public async Task<Result<DocumentId>> HandleAsync(
        UserId ownerId,
        Filename filename,
        CancellationToken ct)
    {
        // Create the Aggregate via the factory method
        var documentId = DocumentId.New();
        var document = Document.Create(documentId, ownerId, filename);

        // Immediately request processing (auto-submit after upload)
        document.RequestProcessing();

        // Persist
        await _repository.AddAsync(document, ct);
        await _repository.SaveChangesAsync(ct);

        // Dispatch both events: DocumentCreated + DocumentProcessingRequested
        await _dispatcher.DispatchAsync(document.DomainEvents, ct);

        return Result<DocumentId>.Success(documentId);
    }
}

public class ArchiveDocumentRequest
{
    public Guid DocumentId { get; set; }
}

public class ArchiveDocumentValidator : Validator<ArchiveDocumentRequest>
{
    public ArchiveDocumentValidator()
    {
        RuleFor(x => x.DocumentId)
            .NotEmpty()
            .WithMessage("DocumentId is required.");
    }
}

public class ArchiveDocumentEndpoint
    : Endpoint<ArchiveDocumentRequest>
{
    private readonly ArchiveDocumentHandler _handler;
    private readonly IArchiveResolver _archiveResolver;

    public ArchiveDocumentEndpoint(
        ArchiveDocumentHandler handler,
        IArchiveResolver archiveResolver)
    {
        _handler = handler;
        _archiveResolver = archiveResolver;
    }

    public override void Configure()
    {
        Post("/api/documents/{DocumentId}/archive");
        Description(b => b
            .Produces(200)
            .Produces(400)
            .Produces(403)
            .Produces(404)
            .WithTags("Documents"));
    }

    public override async Task HandleAsync(
        ArchiveDocumentRequest req, CancellationToken ct)
    {
        // Resolve the current user's BlueRobinId from the JWT
        var userId = new UserId(_archiveResolver.GetBlueRobinId(HttpContext));

        // Delegate to the Application Service
        var result = await _handler.HandleAsync(
            new DocumentId(req.DocumentId),
            userId,
            ct);

        // Map Result to HTTP response
        switch (result)
        {
            case { IsSuccess: true }:
                await SendOkAsync(ct);
                break;
            case { IsNotFound: true }:
                await SendNotFoundAsync(ct);
                break;
            case { IsForbidden: true }:
                await SendForbiddenAsync(ct);
                break;
            default:
                ThrowError(result.Error!);
                break;
        }
    }
}

public class CreateDocumentRequest
{
    public string Filename { get; set; } = default!;
}

public class CreateDocumentValidator : Validator<CreateDocumentRequest>
{
    public CreateDocumentValidator()
    {
        RuleFor(x => x.Filename)
            .NotEmpty()
            .MaximumLength(255)
            .WithMessage("Filename is required and must be under 255 characters.");
    }
}

public class CreateDocumentEndpoint
    : Endpoint<CreateDocumentRequest>
{
    private readonly CreateDocumentHandler _handler;
    private readonly IArchiveResolver _archiveResolver;

    public CreateDocumentEndpoint(
        CreateDocumentHandler handler,
        IArchiveResolver archiveResolver)
    {
        _handler = handler;
        _archiveResolver = archiveResolver;
    }

    public override void Configure()
    {
        Post("/api/documents");
        Description(b => b
            .Produces<CreateDocumentResponse>(201)
            .Produces(400)
            .WithTags("Documents"));
    }

    public override async Task HandleAsync(
        CreateDocumentRequest req, CancellationToken ct)
    {
        var userId = new UserId(_archiveResolver.GetBlueRobinId(HttpContext));
        var filename = new Filename(req.Filename);

        var result = await _handler.HandleAsync(userId, filename, ct);

        if (result.IsSuccess)
        {
            await SendAsync(
                new CreateDocumentResponse { DocumentId = result.Value!.Value },
                201,
                ct);
        }
        else
        {
            ThrowError(result.Error!);
        }
    }
}

public class CreateDocumentResponse
{
    public Guid DocumentId { get; set; }
}

public class DocumentAggregateTests
{
    private static Document CreateTestDocument(
        DocumentStatus targetStatus = DocumentStatus.Processed)
    {
        var doc = Document.Create(
            DocumentId.New(),
            new UserId("abc12345"),
            new Filename("report.pdf"));

        if (targetStatus >= DocumentStatus.Processing)
            doc.RequestProcessing();

        if (targetStatus >= DocumentStatus.Processed)
            doc.MarkAsProcessed("Test Report", "A summary.");

        // Clear events from setup so tests only see new events
        doc.ClearDomainEvents();
        return doc;
    }

    [Fact]
    public void Create_SetsInitialState_Correctly()
    {
        var doc = Document.Create(
            DocumentId.New(),
            new UserId("abc12345"),
            new Filename("report.pdf"));

        Assert.Equal(DocumentStatus.Draft, doc.Status);
        Assert.Null(doc.ArchivedAt);
        Assert.Null(doc.ProcessedAt);
        Assert.Single(doc.DomainEvents);
        Assert.IsType<DocumentCreated>(doc.DomainEvents[0]);
    }

    [Fact]
    public void Archive_FromProcessed_Succeeds()
    {
        var doc = CreateTestDocument(DocumentStatus.Processed);

        doc.Archive();

        Assert.Equal(DocumentStatus.Archived, doc.Status);
        Assert.NotNull(doc.ArchivedAt);
        Assert.Single(doc.DomainEvents);
        Assert.IsType<DocumentArchived>(doc.DomainEvents[0]);
    }

    [Fact]
    public void Archive_WhenAlreadyArchived_Throws()
    {
        var doc = CreateTestDocument(DocumentStatus.Processed);
        doc.Archive();
        doc.ClearDomainEvents();

        var ex = Assert.Throws<DomainException>(() => doc.Archive());

        Assert.Contains("already archived", ex.Message);
    }

    [Fact]
    public void Archive_WhenProcessing_Throws()
    {
        var doc = CreateTestDocument(DocumentStatus.Processing);

        var ex = Assert.Throws<DomainException>(() => doc.Archive());

        Assert.Contains("processing", ex.Message.ToLower());
    }

    [Fact]
    public void Archive_WhenDraft_Throws()
    {
        var doc = CreateTestDocument(DocumentStatus.Draft);

        var ex = Assert.Throws<DomainException>(() => doc.Archive());

        Assert.Contains("hasn't been processed", ex.Message);
    }

    [Fact]
    public void RequestProcessing_FromDraft_Succeeds()
    {
        var doc = CreateTestDocument(DocumentStatus.Draft);

        doc.RequestProcessing();

        Assert.Equal(DocumentStatus.Processing, doc.Status);
    }

    [Fact]
    public void RequestProcessing_FromProcessed_Throws()
    {
        var doc = CreateTestDocument(DocumentStatus.Processed);

        var ex = Assert.Throws<DomainException>(
            () => doc.RequestProcessing());

        Assert.Contains("Processed", ex.Message);
    }

    [Fact]
    public void UpdateMetadata_WhenArchived_Throws()
    {
        var doc = CreateTestDocument(DocumentStatus.Processed);
        doc.Archive();
        doc.ClearDomainEvents();

        var ex = Assert.Throws<DomainException>(
            () => doc.UpdateMetadata("New Title", null));

        Assert.Contains("archived", ex.Message.ToLower());
    }

    [Fact]
    public void UpdateMetadata_WhenProcessed_UpdatesFields()
    {
        var doc = CreateTestDocument(DocumentStatus.Processed);

        doc.UpdateMetadata("Updated Title", "Updated Summary");

        Assert.Equal("Updated Title", doc.Title);
        Assert.Equal("Updated Summary", doc.Summary);
    }
}