From 5add866733850c95e47a13350e06f6d669fec34e Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 01:58:02 +0000
Subject: [PATCH 1/8] docs: Add XML documentation to Caching module

- ICacheService: Document all interface methods
- CacheServiceExtensions: Document GetOrSet patterns
- Extensions: Document AddHeroCaching DI registration
- DistributedCacheService: Document implementation details
- HybridCacheService: Document L1/L2 caching strategy

Part of #1176
---
 .../Caching/CacheServiceExtensions.cs         | 29 ++++++++-
 .../Caching/DistributedCacheService.cs        | 36 ++++++++++-
 src/BuildingBlocks/Caching/Extensions.cs      | 19 +++++-
 .../Caching/HybridCacheService.cs             | 53 ++++++++++++++++
 src/BuildingBlocks/Caching/ICacheService.cs   | 62 ++++++++++++++++++-
 5 files changed, 192 insertions(+), 7 deletions(-)

diff --git a/src/BuildingBlocks/Caching/CacheServiceExtensions.cs b/src/BuildingBlocks/Caching/CacheServiceExtensions.cs
index e97d66ced6..b8527254d9 100644
--- a/src/BuildingBlocks/Caching/CacheServiceExtensions.cs
+++ b/src/BuildingBlocks/Caching/CacheServiceExtensions.cs
@@ -1,6 +1,20 @@
-namespace FSH.Framework.Caching;
+namespace FSH.Framework.Caching;
+
+/// <summary>
+/// Extension methods for <see cref="ICacheService"/> providing cache-aside pattern implementations.
+/// </summary>
 public static class CacheServiceExtensions
 {
+    /// <summary>
+    /// Gets an item from cache, or sets it using the provided callback if not found.
+    /// Implements the cache-aside pattern synchronously.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached item.</typeparam>
+    /// <param name="cache">The cache service instance.</param>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="getItemCallback">A callback function to retrieve the item if not in cache.</param>
+    /// <param name="slidingExpiration">Optional sliding expiration for the cached item.</param>
+    /// <returns>The cached item or the newly retrieved and cached item.</returns>
     public static T? GetOrSet<T>(this ICacheService cache, string key, Func<T?> getItemCallback, TimeSpan? slidingExpiration = null)
     {
         ArgumentNullException.ThrowIfNull(cache);
@@ -23,6 +37,17 @@ public static class CacheServiceExtensions
         return value;
     }
 
+    /// <summary>
+    /// Asynchronously gets an item from cache, or sets it using the provided task if not found.
+    /// Implements the cache-aside pattern asynchronously.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached item.</typeparam>
+    /// <param name="cache">The cache service instance.</param>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="task">An async function to retrieve the item if not in cache.</param>
+    /// <param name="slidingExpiration">Optional sliding expiration for the cached item.</param>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>The cached item or the newly retrieved and cached item.</returns>
     public static async Task<T?> GetOrSetAsync<T>(this ICacheService cache, string key, Func<Task<T>> task, TimeSpan? slidingExpiration = null, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(cache);
@@ -44,4 +69,4 @@ public static class CacheServiceExtensions
 
         return value;
     }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Caching/DistributedCacheService.cs b/src/BuildingBlocks/Caching/DistributedCacheService.cs
index 1e6fd7f00f..839ee52073 100644
--- a/src/BuildingBlocks/Caching/DistributedCacheService.cs
+++ b/src/BuildingBlocks/Caching/DistributedCacheService.cs
@@ -1,10 +1,15 @@
-using Microsoft.Extensions.Caching.Distributed;
+using Microsoft.Extensions.Caching.Distributed;
 using Microsoft.Extensions.Logging;
 using Microsoft.Extensions.Options;
 using System.Text;
 using System.Text.Json;
 
 namespace FSH.Framework.Caching;
+
+/// <summary>
+/// Implementation of <see cref="ICacheService"/> using distributed cache (Redis or in-memory).
+/// Provides JSON serialization for cached objects with configurable expiration policies.
+/// </summary>
 public sealed class DistributedCacheService : ICacheService
 {
     private static readonly Encoding Utf8 = Encoding.UTF8;
@@ -14,6 +19,12 @@ public sealed class DistributedCacheService : ICacheService
     private readonly ILogger<DistributedCacheService> _logger;
     private readonly CachingOptions _opts;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="DistributedCacheService"/>.
+    /// </summary>
+    /// <param name="cache">The underlying distributed cache implementation.</param>
+    /// <param name="logger">Logger for cache operations.</param>
+    /// <param name="opts">Caching configuration options.</param>
     public DistributedCacheService(
         IDistributedCache cache,
         ILogger<DistributedCacheService> logger,
@@ -26,6 +37,7 @@ public DistributedCacheService(
         _opts = opts.Value;
     }
 
+    /// <inheritdoc />
     public async Task<T?> GetItemAsync<T>(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -42,6 +54,7 @@ public DistributedCacheService(
         }
     }
 
+    /// <inheritdoc />
     public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = default, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -57,6 +70,7 @@ public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = defau
         }
     }
 
+    /// <inheritdoc />
     public async Task RemoveItemAsync(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -65,6 +79,7 @@ public async Task RemoveItemAsync(string key, CancellationToken ct = default)
         { _logger.LogWarning(ex, "Cache remove failed for {Key}", key); }
     }
 
+    /// <inheritdoc />
     public async Task RefreshItemAsync(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -76,11 +91,24 @@ public async Task RefreshItemAsync(string key, CancellationToken ct = default)
         catch (Exception ex) when (ex is not OperationCanceledException)
         { _logger.LogWarning(ex, "Cache refresh failed for {Key}", key); }
     }
+
+    /// <inheritdoc />
     public T? GetItem<T>(string key) => GetItemAsync<T>(key).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void SetItem<T>(string key, T value, TimeSpan? sliding = default) => SetItemAsync(key, value, sliding).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void RemoveItem(string key) => RemoveItemAsync(key).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void RefreshItem(string key) => RefreshItemAsync(key).GetAwaiter().GetResult();
 
+    /// <summary>
+    /// Builds cache entry options with configured expiration settings.
+    /// </summary>
+    /// <param name="sliding">Optional sliding expiration override.</param>
+    /// <returns>Configured cache entry options.</returns>
     private DistributedCacheEntryOptions BuildEntryOptions(TimeSpan? sliding)
     {
         var o = new DistributedCacheEntryOptions();
@@ -96,6 +124,12 @@ private DistributedCacheEntryOptions BuildEntryOptions(TimeSpan? sliding)
         return o;
     }
 
+    /// <summary>
+    /// Normalizes the cache key by applying the configured prefix.
+    /// </summary>
+    /// <param name="key">The original cache key.</param>
+    /// <returns>The normalized key with prefix applied.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when key is null or whitespace.</exception>
     private string Normalize(string key)
     {
         if (string.IsNullOrWhiteSpace(key)) throw new ArgumentNullException(nameof(key));
diff --git a/src/BuildingBlocks/Caching/Extensions.cs b/src/BuildingBlocks/Caching/Extensions.cs
index 4857f6a982..49446091d2 100644
--- a/src/BuildingBlocks/Caching/Extensions.cs
+++ b/src/BuildingBlocks/Caching/Extensions.cs
@@ -1,12 +1,27 @@
-using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Configuration;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
 using StackExchange.Redis;
 
 namespace FSH.Framework.Caching;
 
+/// <summary>
+/// Extension methods for registering caching services in the dependency injection container.
+/// </summary>
 public static class Extensions
 {
+    /// <summary>
+    /// Adds FullStackHero caching services to the service collection.
+    /// Configures a hybrid L1/L2 cache with in-memory (L1) and Redis or distributed memory (L2).
+    /// </summary>
+    /// <param name="services">The service collection to add caching services to.</param>
+    /// <param name="configuration">The application configuration containing caching options.</param>
+    /// <returns>The service collection for chaining.</returns>
+    /// <remarks>
+    /// If Redis connection string is configured in <see cref="CachingOptions"/>, Redis is used for L2 cache.
+    /// Otherwise, falls back to in-memory distributed cache for L2.
+    /// The <see cref="HybridCacheService"/> is registered to provide both sync and async cache operations.
+    /// </remarks>
     public static IServiceCollection AddHeroCaching(this IServiceCollection services, IConfiguration configuration)
     {
         ArgumentNullException.ThrowIfNull(configuration);
@@ -47,4 +62,4 @@ public static IServiceCollection AddHeroCaching(this IServiceCollection services
 
         return services;
     }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Caching/HybridCacheService.cs b/src/BuildingBlocks/Caching/HybridCacheService.cs
index ed8eb20a09..bf170ca4de 100644
--- a/src/BuildingBlocks/Caching/HybridCacheService.cs
+++ b/src/BuildingBlocks/Caching/HybridCacheService.cs
@@ -7,6 +7,15 @@
 
 namespace FSH.Framework.Caching;
 
+/// <summary>
+/// A hybrid cache implementation combining L1 (in-memory) and L2 (distributed) caching.
+/// Provides fast local access with distributed cache backup for multi-instance scenarios.
+/// </summary>
+/// <remarks>
+/// The hybrid approach uses memory cache for fast L1 access and automatically populates
+/// it from the L2 distributed cache on cache misses. Write operations update both caches.
+/// Memory cache uses 80% of the distributed cache sliding expiration for faster refresh.
+/// </remarks>
 public sealed class HybridCacheService : ICacheService
 {
     private static readonly Encoding Utf8 = Encoding.UTF8;
@@ -17,6 +26,13 @@ public sealed class HybridCacheService : ICacheService
     private readonly ILogger<HybridCacheService> _logger;
     private readonly CachingOptions _opts;
 
+    /// <summary>
+    /// Initializes a new instance of <see cref="HybridCacheService"/>.
+    /// </summary>
+    /// <param name="memoryCache">The L1 in-memory cache.</param>
+    /// <param name="distributedCache">The L2 distributed cache (Redis or memory-based).</param>
+    /// <param name="logger">Logger for cache operations.</param>
+    /// <param name="opts">Caching configuration options.</param>
     public HybridCacheService(
         IMemoryCache memoryCache,
         IDistributedCache distributedCache,
@@ -31,6 +47,11 @@ public HybridCacheService(
         _opts = opts.Value;
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// First checks L1 memory cache, then falls back to L2 distributed cache.
+    /// If found in L2, the item is automatically populated into L1 for subsequent fast access.
+    /// </remarks>
     public async Task<T?> GetItemAsync<T>(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -66,6 +87,10 @@ public HybridCacheService(
         }
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// Writes to both L1 memory cache and L2 distributed cache simultaneously.
+    /// </remarks>
     public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = default, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -86,6 +111,10 @@ public async Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = defau
         }
     }
 
+    /// <inheritdoc />
+    /// <remarks>
+    /// Removes from both L1 memory cache and L2 distributed cache.
+    /// </remarks>
     public async Task RemoveItemAsync(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -102,6 +131,7 @@ public async Task RemoveItemAsync(string key, CancellationToken ct = default)
         }
     }
 
+    /// <inheritdoc />
     public async Task RefreshItemAsync(string key, CancellationToken ct = default)
     {
         key = Normalize(key);
@@ -116,11 +146,23 @@ public async Task RefreshItemAsync(string key, CancellationToken ct = default)
         }
     }
 
+    /// <inheritdoc />
     public T? GetItem<T>(string key) => GetItemAsync<T>(key).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void SetItem<T>(string key, T value, TimeSpan? sliding = default) => SetItemAsync(key, value, sliding).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void RemoveItem(string key) => RemoveItemAsync(key).GetAwaiter().GetResult();
+
+    /// <inheritdoc />
     public void RefreshItem(string key) => RefreshItemAsync(key).GetAwaiter().GetResult();
 
+    /// <summary>
+    /// Builds distributed cache entry options with configured expiration settings.
+    /// </summary>
+    /// <param name="sliding">Optional sliding expiration override.</param>
+    /// <returns>Configured distributed cache entry options.</returns>
     private DistributedCacheEntryOptions BuildDistributedEntryOptions(TimeSpan? sliding)
     {
         var o = new DistributedCacheEntryOptions();
@@ -136,6 +178,11 @@ private DistributedCacheEntryOptions BuildDistributedEntryOptions(TimeSpan? slid
         return o;
     }
 
+    /// <summary>
+    /// Gets memory cache expiration options, set to 80% of distributed cache expiration
+    /// for faster refresh cycles.
+    /// </summary>
+    /// <returns>Memory cache entry options with sliding expiration.</returns>
     private MemoryCacheEntryOptions GetMemoryCacheExpiration()
     {
         var options = new MemoryCacheEntryOptions();
@@ -147,6 +194,12 @@ private MemoryCacheEntryOptions GetMemoryCacheExpiration()
         return options;
     }
 
+    /// <summary>
+    /// Normalizes the cache key by applying the configured prefix.
+    /// </summary>
+    /// <param name="key">The original cache key.</param>
+    /// <returns>The normalized key with prefix applied.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when key is null or whitespace.</exception>
     private string Normalize(string key)
     {
         if (string.IsNullOrWhiteSpace(key)) throw new ArgumentNullException(nameof(key));
diff --git a/src/BuildingBlocks/Caching/ICacheService.cs b/src/BuildingBlocks/Caching/ICacheService.cs
index fbc00dfadc..9e8fa95a9e 100644
--- a/src/BuildingBlocks/Caching/ICacheService.cs
+++ b/src/BuildingBlocks/Caching/ICacheService.cs
@@ -1,12 +1,70 @@
-namespace FSH.Framework.Caching;
+namespace FSH.Framework.Caching;
+
+/// <summary>
+/// Provides caching operations for storing and retrieving items from cache.
+/// Supports both synchronous and asynchronous operations.
+/// </summary>
 public interface ICacheService
 {
+    /// <summary>
+    /// Asynchronously retrieves an item from the cache.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached item.</typeparam>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
+    /// <returns>The cached item if found; otherwise, null.</returns>
     Task<T?> GetItemAsync<T>(string key, CancellationToken ct = default);
+
+    /// <summary>
+    /// Asynchronously stores an item in the cache.
+    /// </summary>
+    /// <typeparam name="T">The type of the item to cache.</typeparam>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="value">The value to cache.</param>
+    /// <param name="sliding">Optional sliding expiration. Uses default if not specified.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
     Task SetItemAsync<T>(string key, T value, TimeSpan? sliding = default, CancellationToken ct = default);
+
+    /// <summary>
+    /// Asynchronously removes an item from the cache.
+    /// </summary>
+    /// <param name="key">The unique cache key to remove.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
     Task RemoveItemAsync(string key, CancellationToken ct = default);
+
+    /// <summary>
+    /// Asynchronously refreshes the sliding expiration of a cached item.
+    /// </summary>
+    /// <param name="key">The unique cache key to refresh.</param>
+    /// <param name="ct">Cancellation token for the operation.</param>
     Task RefreshItemAsync(string key, CancellationToken ct = default);
+
+    /// <summary>
+    /// Retrieves an item from the cache synchronously.
+    /// </summary>
+    /// <typeparam name="T">The type of the cached item.</typeparam>
+    /// <param name="key">The unique cache key.</param>
+    /// <returns>The cached item if found; otherwise, null.</returns>
     T? GetItem<T>(string key);
+
+    /// <summary>
+    /// Stores an item in the cache synchronously.
+    /// </summary>
+    /// <typeparam name="T">The type of the item to cache.</typeparam>
+    /// <param name="key">The unique cache key.</param>
+    /// <param name="value">The value to cache.</param>
+    /// <param name="sliding">Optional sliding expiration. Uses default if not specified.</param>
     void SetItem<T>(string key, T value, TimeSpan? sliding = default);
+
+    /// <summary>
+    /// Removes an item from the cache synchronously.
+    /// </summary>
+    /// <param name="key">The unique cache key to remove.</param>
     void RemoveItem(string key);
+
+    /// <summary>
+    /// Refreshes the sliding expiration of a cached item synchronously.
+    /// </summary>
+    /// <param name="key">The unique cache key to refresh.</param>
     void RefreshItem(string key);
-}
\ No newline at end of file
+}

From 598967993569b0e902178979b29a70e30b5436a3 Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:01:54 +0000
Subject: [PATCH 2/8] docs: Add XML documentation to Core/Domain module

- IEntity, BaseEntity, AggregateRoot: Entity and DDD base types
- IDomainEvent, DomainEvent, IHasDomainEvents: Domain event patterns
- IAuditableEntity: Audit metadata interface
- ISoftDeletable: Soft delete support
- IHasTenant: Multi-tenancy marker

Generated by Codex CLI with --full-auto flag

Part of #1176
---
 .../Core/Domain/AggregateRoot.cs              |  5 +++++
 src/BuildingBlocks/Core/Domain/BaseEntity.cs  | 19 ++++++++++++++++-
 src/BuildingBlocks/Core/Domain/DomainEvent.cs | 15 ++++++++++++-
 .../Core/Domain/IAuditableEntity.cs           | 21 ++++++++++++++++++-
 .../Core/Domain/IDomainEvent.cs               | 21 ++++++++++++++++++-
 src/BuildingBlocks/Core/Domain/IEntity.cs     | 10 ++++++++-
 .../Core/Domain/IHasDomainEvents.cs           | 13 +++++++++++-
 src/BuildingBlocks/Core/Domain/IHasTenant.cs  |  9 +++++++-
 .../Core/Domain/ISoftDeletable.cs             | 15 +++++++++++++
 9 files changed, 121 insertions(+), 7 deletions(-)

diff --git a/src/BuildingBlocks/Core/Domain/AggregateRoot.cs b/src/BuildingBlocks/Core/Domain/AggregateRoot.cs
index 8f0d2f8349..db4b19c689 100644
--- a/src/BuildingBlocks/Core/Domain/AggregateRoot.cs
+++ b/src/BuildingBlocks/Core/Domain/AggregateRoot.cs
@@ -1,4 +1,9 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Represents an aggregate root in the domain model.
+/// </summary>
+/// <typeparam name="TId">The type of the aggregate identifier.</typeparam>
 public abstract class AggregateRoot<TId> : BaseEntity<TId>
 {
     // Put aggregate-wide behaviors/helpers here if needed
diff --git a/src/BuildingBlocks/Core/Domain/BaseEntity.cs b/src/BuildingBlocks/Core/Domain/BaseEntity.cs
index 18c5b3d2bc..be973c5792 100644
--- a/src/BuildingBlocks/Core/Domain/BaseEntity.cs
+++ b/src/BuildingBlocks/Core/Domain/BaseEntity.cs
@@ -1,15 +1,32 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Provides a base implementation for entities with identity and domain events.
+/// </summary>
+/// <typeparam name="TId">The type of the entity identifier.</typeparam>
 public abstract class BaseEntity<TId> : IEntity<TId>, IHasDomainEvents
 {
     private readonly List<IDomainEvent> _domainEvents = [];
 
+    /// <summary>
+    /// Gets the entity identifier.
+    /// </summary>
     public TId Id { get; protected set; } = default!;
 
+    /// <summary>
+    /// Gets the domain events raised by this entity.
+    /// </summary>
     public IReadOnlyCollection<IDomainEvent> DomainEvents => _domainEvents;
 
-    /// <summary>Raise and record a domain event for later dispatch.</summary>
+    /// <summary>
+    /// Raises and records a domain event for later dispatch.
+    /// </summary>
+    /// <param name="event">The domain event to add.</param>
     protected void AddDomainEvent(IDomainEvent @event)
         => _domainEvents.Add(@event);
 
+    /// <summary>
+    /// Clears all recorded domain events.
+    /// </summary>
     public void ClearDomainEvents() => _domainEvents.Clear();
 }
diff --git a/src/BuildingBlocks/Core/Domain/DomainEvent.cs b/src/BuildingBlocks/Core/Domain/DomainEvent.cs
index 0553965f9b..3fc83733f0 100644
--- a/src/BuildingBlocks/Core/Domain/DomainEvent.cs
+++ b/src/BuildingBlocks/Core/Domain/DomainEvent.cs
@@ -1,5 +1,12 @@
 namespace FSH.Framework.Core.Domain;
-/// <summary>Base domain event with correlation and tenant context.</summary>
+
+/// <summary>
+/// Base domain event with correlation and tenant context.
+/// </summary>
+/// <param name="EventId">The unique event identifier.</param>
+/// <param name="OccurredOnUtc">The UTC timestamp when the event occurred.</param>
+/// <param name="CorrelationId">The optional correlation identifier.</param>
+/// <param name="TenantId">The optional tenant identifier.</param>
 public abstract record DomainEvent(
     Guid EventId,
     DateTimeOffset OccurredOnUtc,
@@ -7,6 +14,12 @@ public abstract record DomainEvent(
     string? TenantId = null
 ) : IDomainEvent
 {
+    /// <summary>
+    /// Creates a new domain event using the provided factory.
+    /// </summary>
+    /// <typeparam name="T">The domain event type to create.</typeparam>
+    /// <param name="factory">Factory to create the event using the generated id and timestamp.</param>
+    /// <returns>The created domain event.</returns>
     public static T Create<T>(Func<Guid, DateTimeOffset, T> factory)
         where T : DomainEvent
     {
diff --git a/src/BuildingBlocks/Core/Domain/IAuditableEntity.cs b/src/BuildingBlocks/Core/Domain/IAuditableEntity.cs
index 5925f4d426..98538eb2ba 100644
--- a/src/BuildingBlocks/Core/Domain/IAuditableEntity.cs
+++ b/src/BuildingBlocks/Core/Domain/IAuditableEntity.cs
@@ -1,8 +1,27 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Defines audit metadata for an entity.
+/// </summary>
 public interface IAuditableEntity
 {
+    /// <summary>
+    /// Gets the UTC timestamp when the entity was created.
+    /// </summary>
     DateTimeOffset CreatedOnUtc { get; }
+
+    /// <summary>
+    /// Gets the identifier of the creator.
+    /// </summary>
     string? CreatedBy { get; }
+
+    /// <summary>
+    /// Gets the UTC timestamp when the entity was last modified.
+    /// </summary>
     DateTimeOffset? LastModifiedOnUtc { get; }
+
+    /// <summary>
+    /// Gets the identifier of the last modifier.
+    /// </summary>
     string? LastModifiedBy { get; }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Core/Domain/IDomainEvent.cs b/src/BuildingBlocks/Core/Domain/IDomainEvent.cs
index c886257dbd..3c24ae30d7 100644
--- a/src/BuildingBlocks/Core/Domain/IDomainEvent.cs
+++ b/src/BuildingBlocks/Core/Domain/IDomainEvent.cs
@@ -1,8 +1,27 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Represents a domain event with correlation and tenant context.
+/// </summary>
 public interface IDomainEvent
 {
+    /// <summary>
+    /// Gets the unique event identifier.
+    /// </summary>
     Guid EventId { get; }
+
+    /// <summary>
+    /// Gets the UTC timestamp when the event occurred.
+    /// </summary>
     DateTimeOffset OccurredOnUtc { get; }
+
+    /// <summary>
+    /// Gets the correlation identifier for tracing across boundaries.
+    /// </summary>
     string? CorrelationId { get; }
+
+    /// <summary>
+    /// Gets the tenant identifier associated with the event.
+    /// </summary>
     string? TenantId { get; }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Core/Domain/IEntity.cs b/src/BuildingBlocks/Core/Domain/IEntity.cs
index adffcdab19..dd23e7a578 100644
--- a/src/BuildingBlocks/Core/Domain/IEntity.cs
+++ b/src/BuildingBlocks/Core/Domain/IEntity.cs
@@ -1,5 +1,13 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Represents an entity with a strongly-typed identifier.
+/// </summary>
+/// <typeparam name="TId">The type of the entity identifier.</typeparam>
 public interface IEntity<out TId>
 {
+    /// <summary>
+    /// Gets the entity identifier.
+    /// </summary>
     TId Id { get; }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Core/Domain/IHasDomainEvents.cs b/src/BuildingBlocks/Core/Domain/IHasDomainEvents.cs
index 48a3ce0ba2..4d875334f9 100644
--- a/src/BuildingBlocks/Core/Domain/IHasDomainEvents.cs
+++ b/src/BuildingBlocks/Core/Domain/IHasDomainEvents.cs
@@ -1,6 +1,17 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Exposes domain events raised by an entity.
+/// </summary>
 public interface IHasDomainEvents
 {
+    /// <summary>
+    /// Gets the collection of raised domain events.
+    /// </summary>
     IReadOnlyCollection<IDomainEvent> DomainEvents { get; }
+
+    /// <summary>
+    /// Clears the stored domain events.
+    /// </summary>
     void ClearDomainEvents();
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Core/Domain/IHasTenant.cs b/src/BuildingBlocks/Core/Domain/IHasTenant.cs
index b7f579b309..70f4c4d007 100644
--- a/src/BuildingBlocks/Core/Domain/IHasTenant.cs
+++ b/src/BuildingBlocks/Core/Domain/IHasTenant.cs
@@ -1,5 +1,12 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Associates an entity with a tenant.
+/// </summary>
 public interface IHasTenant
 {
+    /// <summary>
+    /// Gets the tenant identifier.
+    /// </summary>
     string TenantId { get; }
-}
\ No newline at end of file
+}
diff --git a/src/BuildingBlocks/Core/Domain/ISoftDeletable.cs b/src/BuildingBlocks/Core/Domain/ISoftDeletable.cs
index 35f841268e..46426403fc 100644
--- a/src/BuildingBlocks/Core/Domain/ISoftDeletable.cs
+++ b/src/BuildingBlocks/Core/Domain/ISoftDeletable.cs
@@ -1,7 +1,22 @@
 namespace FSH.Framework.Core.Domain;
+
+/// <summary>
+/// Marks an entity as supporting soft deletion.
+/// </summary>
 public interface ISoftDeletable
 {
+    /// <summary>
+    /// Gets a value indicating whether the entity is deleted.
+    /// </summary>
     bool IsDeleted { get; }
+
+    /// <summary>
+    /// Gets the UTC timestamp when the entity was deleted.
+    /// </summary>
     DateTimeOffset? DeletedOnUtc { get; }
+
+    /// <summary>
+    /// Gets the identifier of the user who deleted the entity.
+    /// </summary>
     string? DeletedBy { get; }
 }

From d50f7b80ef924a84951577f8d4c5b9a4d8350325 Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:08:14 +0000
Subject: [PATCH 3/8] docs: Add XML documentation to Exceptions module

---
 .../Core/Exceptions/CustomException.cs        | 31 +++++++++++++++++++
 .../Core/Exceptions/ForbiddenException.cs     | 17 ++++++++++
 .../Core/Exceptions/NotFoundException.cs      | 17 ++++++++++
 .../Core/Exceptions/UnauthorizedException.cs  | 17 ++++++++++
 4 files changed, 82 insertions(+)

diff --git a/src/BuildingBlocks/Core/Exceptions/CustomException.cs b/src/BuildingBlocks/Core/Exceptions/CustomException.cs
index 1c3a51a9b0..48a8a3b41d 100644
--- a/src/BuildingBlocks/Core/Exceptions/CustomException.cs
+++ b/src/BuildingBlocks/Core/Exceptions/CustomException.cs
@@ -19,21 +19,39 @@ public class CustomException : Exception
     /// </summary>
     public HttpStatusCode StatusCode { get; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with default message and internal server error status.
+    /// </summary>
     public CustomException()
         : this("An error occurred.", Enumerable.Empty<string>(), HttpStatusCode.InternalServerError)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with specified message.
+    /// </summary>
+    /// <param name="message">The error message.</param>
     public CustomException(string message)
         : this(message, Enumerable.Empty<string>(), HttpStatusCode.InternalServerError)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with specified message and inner exception.
+    /// </summary>
+    /// <param name="message">The error message.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
     public CustomException(string message, Exception innerException)
         : this(message, innerException, Enumerable.Empty<string>(), HttpStatusCode.InternalServerError)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with message, errors, and status code.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="errors">Collection of detailed error messages.</param>
+    /// <param name="statusCode">The HTTP status code associated with this exception.</param>
     public CustomException(
         string message,
         IEnumerable<string>? errors,
@@ -44,6 +62,13 @@ public CustomException(
         StatusCode = statusCode;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with full parameters.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
+    /// <param name="errors">Collection of detailed error messages.</param>
+    /// <param name="statusCode">The HTTP status code associated with this exception.</param>
     public CustomException(
         string message,
         Exception innerException,
@@ -55,6 +80,12 @@ public CustomException(
         StatusCode = statusCode;
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="CustomException"/> class with message, inner exception, and status code.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
+    /// <param name="statusCode">The HTTP status code associated with this exception.</param>
     public CustomException(
         string message,
         Exception innerException,
diff --git a/src/BuildingBlocks/Core/Exceptions/ForbiddenException.cs b/src/BuildingBlocks/Core/Exceptions/ForbiddenException.cs
index e1ef0705d9..384cdad248 100644
--- a/src/BuildingBlocks/Core/Exceptions/ForbiddenException.cs
+++ b/src/BuildingBlocks/Core/Exceptions/ForbiddenException.cs
@@ -6,21 +6,38 @@ namespace FSH.Framework.Core.Exceptions;
 /// </summary>
 public class ForbiddenException : CustomException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ForbiddenException"/> class with default message.
+    /// </summary>
     public ForbiddenException()
         : base("Unauthorized access.", Array.Empty<string>(), HttpStatusCode.Forbidden)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ForbiddenException"/> class with specified message.
+    /// </summary>
+    /// <param name="message">The error message describing the forbidden action.</param>
     public ForbiddenException(string message)
         : base(message, Array.Empty<string>(), HttpStatusCode.Forbidden)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ForbiddenException"/> class with message and error details.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="errors">Collection of detailed error messages.</param>
     public ForbiddenException(string message, IEnumerable<string> errors)
         : base(message, errors.ToList(), HttpStatusCode.Forbidden)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ForbiddenException"/> class with message and inner exception.
+    /// </summary>
+    /// <param name="message">The error message describing the forbidden action.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
     public ForbiddenException(string message, Exception innerException)
         : base(message, innerException, HttpStatusCode.Forbidden)
     {
diff --git a/src/BuildingBlocks/Core/Exceptions/NotFoundException.cs b/src/BuildingBlocks/Core/Exceptions/NotFoundException.cs
index 78b1532b54..53e3f21b64 100644
--- a/src/BuildingBlocks/Core/Exceptions/NotFoundException.cs
+++ b/src/BuildingBlocks/Core/Exceptions/NotFoundException.cs
@@ -7,21 +7,38 @@ namespace FSH.Framework.Core.Exceptions;
 /// </summary>
 public class NotFoundException : CustomException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NotFoundException"/> class with default message.
+    /// </summary>
     public NotFoundException()
         : base("Resource not found.", Array.Empty<string>(), HttpStatusCode.NotFound)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NotFoundException"/> class with specified message.
+    /// </summary>
+    /// <param name="message">The error message describing what resource was not found.</param>
     public NotFoundException(string message)
         : base(message, Array.Empty<string>(), HttpStatusCode.NotFound)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NotFoundException"/> class with message and error details.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="errors">Collection of detailed error messages.</param>
     public NotFoundException(string message, IEnumerable<string> errors)
         : base(message, errors.ToList(), HttpStatusCode.NotFound)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NotFoundException"/> class with message and inner exception.
+    /// </summary>
+    /// <param name="message">The error message describing what resource was not found.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
     public NotFoundException(string message, Exception innerException)
         : base(message, innerException, HttpStatusCode.NotFound)
     {
diff --git a/src/BuildingBlocks/Core/Exceptions/UnauthorizedException.cs b/src/BuildingBlocks/Core/Exceptions/UnauthorizedException.cs
index a6c745b95d..4ed86490d7 100644
--- a/src/BuildingBlocks/Core/Exceptions/UnauthorizedException.cs
+++ b/src/BuildingBlocks/Core/Exceptions/UnauthorizedException.cs
@@ -6,21 +6,38 @@ namespace FSH.Framework.Core.Exceptions;
 /// </summary>
 public class UnauthorizedException : CustomException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnauthorizedException"/> class with default message.
+    /// </summary>
     public UnauthorizedException()
         : base("Authentication failed.", Array.Empty<string>(), HttpStatusCode.Unauthorized)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnauthorizedException"/> class with specified message.
+    /// </summary>
+    /// <param name="message">The error message describing the authentication failure.</param>
     public UnauthorizedException(string message)
         : base(message, Array.Empty<string>(), HttpStatusCode.Unauthorized)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnauthorizedException"/> class with message and error details.
+    /// </summary>
+    /// <param name="message">The main error message.</param>
+    /// <param name="errors">Collection of detailed error messages.</param>
     public UnauthorizedException(string message, IEnumerable<string> errors)
         : base(message, errors.ToList(), HttpStatusCode.Unauthorized)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnauthorizedException"/> class with message and inner exception.
+    /// </summary>
+    /// <param name="message">The error message describing the authentication failure.</param>
+    /// <param name="innerException">The inner exception that caused this exception.</param>
     public UnauthorizedException(string message, Exception innerException)
         : base(message, innerException, HttpStatusCode.Unauthorized)
     {

From 8f387dd56227051862ef383f49a66a0ad7881d70 Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:09:00 +0000
Subject: [PATCH 4/8] docs: Add XML documentation to Context module

---
 .../Core/Context/ICurrentUser.cs              | 32 +++++++++++++++++++
 .../Core/Context/ICurrentUserInitializer.cs   | 12 +++++++
 2 files changed, 44 insertions(+)

diff --git a/src/BuildingBlocks/Core/Context/ICurrentUser.cs b/src/BuildingBlocks/Core/Context/ICurrentUser.cs
index 2784294c1f..2a70135b21 100644
--- a/src/BuildingBlocks/Core/Context/ICurrentUser.cs
+++ b/src/BuildingBlocks/Core/Context/ICurrentUser.cs
@@ -1,19 +1,51 @@
 using System.Security.Claims;
 
 namespace FSH.Framework.Core.Context;
+
+/// <summary>
+/// Represents the current authenticated user context with access to user information and claims.
+/// </summary>
 public interface ICurrentUser
 {
+    /// <summary>
+    /// Gets the display name of the current user.
+    /// </summary>
     string? Name { get; }
 
+    /// <summary>
+    /// Gets the unique identifier of the current user.
+    /// </summary>
+    /// <returns>The user's unique identifier.</returns>
     Guid GetUserId();
 
+    /// <summary>
+    /// Gets the email address of the current user.
+    /// </summary>
+    /// <returns>The user's email address, or null if not available.</returns>
     string? GetUserEmail();
 
+    /// <summary>
+    /// Gets the tenant identifier that the current user belongs to.
+    /// </summary>
+    /// <returns>The tenant identifier, or null if not in a multi-tenant context.</returns>
     string? GetTenant();
 
+    /// <summary>
+    /// Determines whether the current user is authenticated.
+    /// </summary>
+    /// <returns>true if the user is authenticated; otherwise, false.</returns>
     bool IsAuthenticated();
 
+    /// <summary>
+    /// Determines whether the current user is in the specified role.
+    /// </summary>
+    /// <param name="role">The role to check for.</param>
+    /// <returns>true if the user is in the specified role; otherwise, false.</returns>
     bool IsInRole(string role);
 
+    /// <summary>
+    /// Gets all claims associated with the current user.
+    /// </summary>
+    /// <returns>A collection of user claims, or null if no claims are available.</returns>
     IEnumerable<Claim>? GetUserClaims();
 }
\ No newline at end of file
diff --git a/src/BuildingBlocks/Core/Context/ICurrentUserInitializer.cs b/src/BuildingBlocks/Core/Context/ICurrentUserInitializer.cs
index 9e94530a0f..2a8dafb9b8 100644
--- a/src/BuildingBlocks/Core/Context/ICurrentUserInitializer.cs
+++ b/src/BuildingBlocks/Core/Context/ICurrentUserInitializer.cs
@@ -1,9 +1,21 @@
 using System.Security.Claims;
 
 namespace FSH.Framework.Core.Context;
+
+/// <summary>
+/// Provides methods to initialize and set the current user context.
+/// </summary>
 public interface ICurrentUserInitializer
 {
+    /// <summary>
+    /// Sets the current user from a claims principal.
+    /// </summary>
+    /// <param name="user">The claims principal representing the authenticated user.</param>
     void SetCurrentUser(ClaimsPrincipal user);
 
+    /// <summary>
+    /// Sets the current user identifier directly.
+    /// </summary>
+    /// <param name="userId">The unique identifier of the user.</param>
     void SetCurrentUserId(string userId);
 }
\ No newline at end of file

From 5922504cf84ae61c406cf3a251b1c81dc6e8e166 Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:09:25 +0000
Subject: [PATCH 5/8] docs: Add XML documentation to Common module

---
 src/BuildingBlocks/Core/Common/QueryStringKeys.cs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/BuildingBlocks/Core/Common/QueryStringKeys.cs b/src/BuildingBlocks/Core/Common/QueryStringKeys.cs
index 8252eb5949..1b724d279a 100644
--- a/src/BuildingBlocks/Core/Common/QueryStringKeys.cs
+++ b/src/BuildingBlocks/Core/Common/QueryStringKeys.cs
@@ -1,6 +1,17 @@
 namespace FSH.Framework.Core.Common;
+
+/// <summary>
+/// Constants for commonly used query string parameter names.
+/// </summary>
 public static class QueryStringKeys
 {
+    /// <summary>
+    /// Query string key for authentication or verification codes.
+    /// </summary>
     public const string Code = "code";
+
+    /// <summary>
+    /// Query string key for user identifier parameter.
+    /// </summary>
     public const string UserId = "userId";
 }
\ No newline at end of file

From 83fd58ccf126375cce49f07f88c8eeb18724236c Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:09:43 +0000
Subject: [PATCH 6/8] docs: Add XML documentation to Abstractions module

---
 .../Core/Abstractions/IAppUser.cs             | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/BuildingBlocks/Core/Abstractions/IAppUser.cs b/src/BuildingBlocks/Core/Abstractions/IAppUser.cs
index d50318d64c..b49e0e6157 100644
--- a/src/BuildingBlocks/Core/Abstractions/IAppUser.cs
+++ b/src/BuildingBlocks/Core/Abstractions/IAppUser.cs
@@ -1,10 +1,37 @@
 namespace FSH.Framework.Core.Abstractions;
+
+/// <summary>
+/// Represents a basic application user with common properties.
+/// </summary>
 public interface IAppUser
 {
+    /// <summary>
+    /// Gets the first name of the user.
+    /// </summary>
     string? FirstName { get; }
+
+    /// <summary>
+    /// Gets the last name of the user.
+    /// </summary>
     string? LastName { get; }
+
+    /// <summary>
+    /// Gets the URL of the user's profile image.
+    /// </summary>
     Uri? ImageUrl { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether the user account is active.
+    /// </summary>
     bool IsActive { get; }
+
+    /// <summary>
+    /// Gets the refresh token for the user's authentication session.
+    /// </summary>
     string? RefreshToken { get; }
+
+    /// <summary>
+    /// Gets the expiry time of the refresh token.
+    /// </summary>
     DateTime RefreshTokenExpiryTime { get; }
 }
\ No newline at end of file

From b012bc232b2123d7d85bd86797133e574a38207f Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:11:47 +0000
Subject: [PATCH 7/8] docs: Add XML documentation to Persistence core module

---
 .../Persistence/ConnectionStringValidator.cs  |  5 ++++
 .../Persistence/Context/BaseDbContext.cs      | 24 +++++++++++++++++++
 .../DatabaseOptionsStartupLogger.cs           | 18 ++++++++++++++
 .../Persistence/IConnectionStringValidator.cs |  9 +++++++
 .../Persistence/IDbInitializer.cs             | 14 +++++++++++
 .../Persistence/ModelBuilderExtensions.cs     | 10 ++++++++
 .../Persistence/OptionsBuilderExtensions.cs   | 14 +++++++++++
 .../Persistence/PersistenceExtensions.cs      | 17 +++++++++++++
 8 files changed, 111 insertions(+)

diff --git a/src/BuildingBlocks/Persistence/ConnectionStringValidator.cs b/src/BuildingBlocks/Persistence/ConnectionStringValidator.cs
index 54a54e0d95..21686f32f2 100644
--- a/src/BuildingBlocks/Persistence/ConnectionStringValidator.cs
+++ b/src/BuildingBlocks/Persistence/ConnectionStringValidator.cs
@@ -6,6 +6,11 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Validates database connection strings for supported providers (PostgreSQL, SQL Server).
+/// </summary>
+/// <param name="dbSettings">Database configuration options.</param>
+/// <param name="logger">Logger instance for error tracking.</param>
 public sealed class ConnectionStringValidator(IOptions<DatabaseOptions> dbSettings, ILogger<ConnectionStringValidator> logger) : IConnectionStringValidator
 {
     private readonly DatabaseOptions _dbSettings = dbSettings.Value;
diff --git a/src/BuildingBlocks/Persistence/Context/BaseDbContext.cs b/src/BuildingBlocks/Persistence/Context/BaseDbContext.cs
index 0bbab352d8..be63ccc24c 100644
--- a/src/BuildingBlocks/Persistence/Context/BaseDbContext.cs
+++ b/src/BuildingBlocks/Persistence/Context/BaseDbContext.cs
@@ -9,6 +9,13 @@
 
 namespace FSH.Framework.Persistence.Context;
 
+/// <summary>
+/// Base database context with multi-tenancy and soft delete support.
+/// </summary>
+/// <param name="multiTenantContextAccessor">Accessor for multi-tenant context information.</param>
+/// <param name="options">Database context options.</param>
+/// <param name="settings">Database configuration settings.</param>
+/// <param name="environment">Host environment information.</param>
 public class BaseDbContext(IMultiTenantContextAccessor<AppTenantInfo> multiTenantContextAccessor,
     DbContextOptions options,
     IOptions<DatabaseOptions> settings,
@@ -17,12 +24,23 @@ public class BaseDbContext(IMultiTenantContextAccessor<AppTenantInfo> multiTenan
 {
     private readonly DatabaseOptions _settings = settings.Value;
 
+    /// <summary>
+    /// Configures the model by applying global query filters for soft delete functionality.
+    /// </summary>
+    /// <param name="modelBuilder">The model builder used to configure the database schema.</param>
+    /// <exception cref="ArgumentNullException">Thrown when modelBuilder is null.</exception>
     protected override void OnModelCreating(ModelBuilder modelBuilder)
     {
         ArgumentNullException.ThrowIfNull(modelBuilder);
         modelBuilder.AppendGlobalQueryFilter<ISoftDeletable>(s => !s.IsDeleted);
         base.OnModelCreating(modelBuilder);
     }
+
+    /// <summary>
+    /// Configures the database connection using tenant-specific connection string if available.
+    /// </summary>
+    /// <param name="optionsBuilder">The options builder for configuring the database connection.</param>
+    /// <exception cref="ArgumentNullException">Thrown when optionsBuilder is null.</exception>
     protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
     {
         ArgumentNullException.ThrowIfNull(optionsBuilder);
@@ -36,6 +54,12 @@ protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
                 environment.IsDevelopment());
         }
     }
+
+    /// <summary>
+    /// Saves all changes made in this context to the database with tenant overwrite mode.
+    /// </summary>
+    /// <param name="cancellationToken">A cancellation token to cancel the save operation.</param>
+    /// <returns>The number of state entries written to the database.</returns>
     public override async Task<int> SaveChangesAsync(CancellationToken cancellationToken = default)
     {
         TenantNotSetMode = TenantNotSetMode.Overwrite;
diff --git a/src/BuildingBlocks/Persistence/DatabaseOptionsStartupLogger.cs b/src/BuildingBlocks/Persistence/DatabaseOptionsStartupLogger.cs
index 16fba87cc6..40c76db210 100644
--- a/src/BuildingBlocks/Persistence/DatabaseOptionsStartupLogger.cs
+++ b/src/BuildingBlocks/Persistence/DatabaseOptionsStartupLogger.cs
@@ -5,11 +5,19 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Hosted service that logs database configuration options during application startup.
+/// </summary>
 public sealed class DatabaseOptionsStartupLogger : IHostedService
 {
     private readonly ILogger<DatabaseOptionsStartupLogger> _logger;
     private readonly IOptions<DatabaseOptions> _options;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DatabaseOptionsStartupLogger"/> class.
+    /// </summary>
+    /// <param name="logger">Logger instance for writing startup information.</param>
+    /// <param name="options">Database configuration options.</param>
     public DatabaseOptionsStartupLogger(
         ILogger<DatabaseOptionsStartupLogger> logger,
         IOptions<DatabaseOptions> options)
@@ -18,6 +26,11 @@ public DatabaseOptionsStartupLogger(
         _options = options;
     }
 
+    /// <summary>
+    /// Logs database configuration information when the service starts.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A completed task.</returns>
     public Task StartAsync(CancellationToken cancellationToken)
     {
         var options = _options.Value;
@@ -27,6 +40,11 @@ public Task StartAsync(CancellationToken cancellationToken)
         return Task.CompletedTask;
     }
 
+    /// <summary>
+    /// Performs no operation when the service stops.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A completed task.</returns>
     public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
 }
 
diff --git a/src/BuildingBlocks/Persistence/IConnectionStringValidator.cs b/src/BuildingBlocks/Persistence/IConnectionStringValidator.cs
index 65ef8612a1..8d3402a712 100644
--- a/src/BuildingBlocks/Persistence/IConnectionStringValidator.cs
+++ b/src/BuildingBlocks/Persistence/IConnectionStringValidator.cs
@@ -1,6 +1,15 @@
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Interface for validating database connection strings.
+/// </summary>
 public interface IConnectionStringValidator
 {
+    /// <summary>
+    /// Validates the specified connection string format and accessibility.
+    /// </summary>
+    /// <param name="connectionString">The connection string to validate.</param>
+    /// <param name="dbProvider">Optional database provider type for provider-specific validation.</param>
+    /// <returns>true if the connection string is valid; otherwise, false.</returns>
     bool TryValidate(string connectionString, string? dbProvider = null);
 }
\ No newline at end of file
diff --git a/src/BuildingBlocks/Persistence/IDbInitializer.cs b/src/BuildingBlocks/Persistence/IDbInitializer.cs
index 5aaca67093..e37f8c8610 100644
--- a/src/BuildingBlocks/Persistence/IDbInitializer.cs
+++ b/src/BuildingBlocks/Persistence/IDbInitializer.cs
@@ -1,7 +1,21 @@
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Interface for database initialization operations including migrations and seeding.
+/// </summary>
 public interface IDbInitializer
 {
+    /// <summary>
+    /// Applies pending database migrations.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     Task MigrateAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Seeds the database with initial data.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     Task SeedAsync(CancellationToken cancellationToken);
 }
\ No newline at end of file
diff --git a/src/BuildingBlocks/Persistence/ModelBuilderExtensions.cs b/src/BuildingBlocks/Persistence/ModelBuilderExtensions.cs
index 397db064d8..2a7ea67353 100644
--- a/src/BuildingBlocks/Persistence/ModelBuilderExtensions.cs
+++ b/src/BuildingBlocks/Persistence/ModelBuilderExtensions.cs
@@ -4,8 +4,18 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Internal extension methods for Entity Framework ModelBuilder configuration.
+/// </summary>
 internal static class ModelBuilderExtensions
 {
+    /// <summary>
+    /// Applies a global query filter to all entities that implement the specified interface.
+    /// </summary>
+    /// <typeparam name="TInterface">The interface type to filter entities by.</typeparam>
+    /// <param name="modelBuilder">The ModelBuilder instance to configure.</param>
+    /// <param name="filter">The filter expression to apply to all matching entities.</param>
+    /// <returns>The ModelBuilder for method chaining.</returns>
     public static ModelBuilder AppendGlobalQueryFilter<TInterface>(this ModelBuilder modelBuilder, Expression<Func<TInterface, bool>> filter)
     {
         // get a list of entities without a baseType that implement the interface TInterface
diff --git a/src/BuildingBlocks/Persistence/OptionsBuilderExtensions.cs b/src/BuildingBlocks/Persistence/OptionsBuilderExtensions.cs
index 4f4e7daf4a..16caf9a45e 100644
--- a/src/BuildingBlocks/Persistence/OptionsBuilderExtensions.cs
+++ b/src/BuildingBlocks/Persistence/OptionsBuilderExtensions.cs
@@ -4,8 +4,22 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Extension methods for configuring Entity Framework DbContextOptionsBuilder.
+/// </summary>
 public static class OptionsBuilderExtensions
 {
+    /// <summary>
+    /// Configures the database provider and connection for the Hero framework.
+    /// </summary>
+    /// <param name="builder">The DbContextOptionsBuilder to configure.</param>
+    /// <param name="dbProvider">The database provider (PostgreSQL, MSSQL).</param>
+    /// <param name="connectionString">The database connection string.</param>
+    /// <param name="migrationsAssembly">The assembly containing database migrations.</param>
+    /// <param name="isDevelopment">Whether the application is running in development mode.</param>
+    /// <returns>The configured DbContextOptionsBuilder for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when builder is null or dbProvider is null/whitespace.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when an unsupported database provider is specified.</exception>
     public static DbContextOptionsBuilder ConfigureHeroDatabase(
         this DbContextOptionsBuilder builder,
         string dbProvider,
diff --git a/src/BuildingBlocks/Persistence/PersistenceExtensions.cs b/src/BuildingBlocks/Persistence/PersistenceExtensions.cs
index 06f01a9460..ef3f2b83b3 100644
--- a/src/BuildingBlocks/Persistence/PersistenceExtensions.cs
+++ b/src/BuildingBlocks/Persistence/PersistenceExtensions.cs
@@ -8,8 +8,18 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Extension methods for configuring persistence services and database contexts.
+/// </summary>
 public static class PersistenceExtensions
 {
+    /// <summary>
+    /// Adds database configuration options to the service collection with validation.
+    /// </summary>
+    /// <param name="services">The service collection to add options to.</param>
+    /// <param name="configuration">The configuration instance containing database settings.</param>
+    /// <returns>The service collection for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when configuration is null.</exception>
     public static IServiceCollection AddHeroDatabaseOptions(this IServiceCollection services, IConfiguration configuration)
     {
         ArgumentNullException.ThrowIfNull(configuration);
@@ -22,6 +32,13 @@ public static IServiceCollection AddHeroDatabaseOptions(this IServiceCollection
         return services;
     }
 
+    /// <summary>
+    /// Adds a configured Entity Framework DbContext to the service collection.
+    /// </summary>
+    /// <typeparam name="TContext">The type of the DbContext to configure.</typeparam>
+    /// <param name="services">The service collection to add the context to.</param>
+    /// <returns>The service collection for method chaining.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when services is null.</exception>
     public static IServiceCollection AddHeroDbContext<TContext>(this IServiceCollection services)
         where TContext : DbContext
     {

From 5c83da2b253409aadffccb57cdc2d4325254ee50 Mon Sep 17 00:00:00 2001
From: jarvis <jarvis@codewithmukesh.com>
Date: Sat, 31 Jan 2026 02:13:37 +0000
Subject: [PATCH 8/8] docs: Add XML documentation to Persistence
 specifications, pagination, and interceptors

---
 .../Inteceptors/DomainEventsInterceptor.cs    | 23 +++++++++++++++++++
 .../Pagination/PaginationExtensions.cs        | 12 ++++++++++
 .../Specifications/SpecificationEvaluator.cs  | 17 ++++++++++++++
 3 files changed, 52 insertions(+)

diff --git a/src/BuildingBlocks/Persistence/Inteceptors/DomainEventsInterceptor.cs b/src/BuildingBlocks/Persistence/Inteceptors/DomainEventsInterceptor.cs
index 8ffdb4483b..4f951828cf 100644
--- a/src/BuildingBlocks/Persistence/Inteceptors/DomainEventsInterceptor.cs
+++ b/src/BuildingBlocks/Persistence/Inteceptors/DomainEventsInterceptor.cs
@@ -5,17 +5,32 @@
 
 namespace FSH.Framework.Persistence.Inteceptors;
 
+/// <summary>
+/// Entity Framework interceptor that automatically publishes domain events after saving changes.
+/// </summary>
 public sealed class DomainEventsInterceptor : SaveChangesInterceptor
 {
     private readonly IPublisher _publisher;
     private readonly ILogger<DomainEventsInterceptor> _logger;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DomainEventsInterceptor"/> class.
+    /// </summary>
+    /// <param name="publisher">The mediator publisher for publishing domain events.</param>
+    /// <param name="logger">Logger for tracking domain event publication.</param>
     public DomainEventsInterceptor(IPublisher publisher, ILogger<DomainEventsInterceptor> logger)
     {
         _publisher = publisher;
         _logger = logger;
     }
 
+    /// <summary>
+    /// Called before changes are saved to the database.
+    /// </summary>
+    /// <param name="eventData">Contextual information about the DbContext being saved.</param>
+    /// <param name="result">The result to be returned from SaveChanges.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
     public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
         DbContextEventData eventData,
         InterceptionResult<int> result,
@@ -24,6 +39,14 @@ public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
         return await base.SavingChangesAsync(eventData, result, cancellationToken);
     }
 
+    /// <summary>
+    /// Called after changes have been saved to the database. Publishes all domain events from tracked entities.
+    /// </summary>
+    /// <param name="eventData">Contextual information about the completed save operation.</param>
+    /// <param name="result">The number of state entries written to the database.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>The number of state entries written to the database.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when eventData is null.</exception>
     public override async ValueTask<int> SavedChangesAsync(
         SaveChangesCompletedEventData eventData,
         int result,
diff --git a/src/BuildingBlocks/Persistence/Pagination/PaginationExtensions.cs b/src/BuildingBlocks/Persistence/Pagination/PaginationExtensions.cs
index 4d888ece17..6e1c92ada8 100644
--- a/src/BuildingBlocks/Persistence/Pagination/PaginationExtensions.cs
+++ b/src/BuildingBlocks/Persistence/Pagination/PaginationExtensions.cs
@@ -4,11 +4,23 @@
 
 namespace FSH.Framework.Persistence;
 
+/// <summary>
+/// Extension methods for converting IQueryable results to paginated responses.
+/// </summary>
 public static class PaginationExtensions
 {
     private const int DefaultPageSize = 20;
     private const int MaxPageSize = 100;
 
+    /// <summary>
+    /// Converts an IQueryable to a paged response with the specified pagination parameters.
+    /// </summary>
+    /// <typeparam name="T">The type of items in the query.</typeparam>
+    /// <param name="source">The queryable source to paginate.</param>
+    /// <param name="pagination">The pagination parameters including page number and page size.</param>
+    /// <param name="cancellationToken">Cancellation token to cancel the operation.</param>
+    /// <returns>A paged response containing the requested page of data and pagination metadata.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when source or pagination is null.</exception>
     public static Task<PagedResponse<T>> ToPagedResponseAsync<T>(
         this IQueryable<T> source,
         IPagedQuery pagination,
diff --git a/src/BuildingBlocks/Persistence/Specifications/SpecificationEvaluator.cs b/src/BuildingBlocks/Persistence/Specifications/SpecificationEvaluator.cs
index 511f9b0182..308b9d2aad 100644
--- a/src/BuildingBlocks/Persistence/Specifications/SpecificationEvaluator.cs
+++ b/src/BuildingBlocks/Persistence/Specifications/SpecificationEvaluator.cs
@@ -7,6 +7,14 @@ namespace FSH.Framework.Persistence;
 /// </summary>
 internal static class SpecificationEvaluator
 {
+    /// <summary>
+    /// Evaluates a specification against an input query to produce a configured IQueryable.
+    /// </summary>
+    /// <typeparam name="T">The entity type.</typeparam>
+    /// <param name="inputQuery">The base queryable to apply the specification to.</param>
+    /// <param name="specification">The specification containing query configuration.</param>
+    /// <returns>A configured queryable with all specification rules applied.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when inputQuery or specification is null.</exception>
     public static IQueryable<T> GetQuery<T>(
         IQueryable<T> inputQuery,
         ISpecification<T> specification)
@@ -25,6 +33,15 @@ public static IQueryable<T> GetQuery<T>(
         return query;
     }
 
+    /// <summary>
+    /// Evaluates a specification with projection against an input query.
+    /// </summary>
+    /// <typeparam name="T">The entity type.</typeparam>
+    /// <typeparam name="TResult">The projected result type.</typeparam>
+    /// <param name="inputQuery">The base queryable to apply the specification to.</param>
+    /// <param name="specification">The specification containing query configuration and projection.</param>
+    /// <returns>A configured queryable with specification rules and projection applied.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when inputQuery or specification is null.</exception>
     public static IQueryable<TResult> GetQuery<T, TResult>(
         IQueryable<T> inputQuery,
         ISpecification<T, TResult> specification)