Merge pull request #105 from Akash29g/docs/xml-doc-comments

docs: XML documentation pass across Domain, Service & API public surface

Author: Akash29g

Directory.Build.props

@@ -1,6 +1,10 @@
 <Project>
   <!-- Coverage gate: applies only to *.Tests projects -->
   <PropertyGroup Condition="$(MSBuildProjectName.EndsWith('.Tests'))">
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <!-- Keep the build green while you document incrementally:
+       CS1591 = "missing XML comment on public member" -->
+    <NoWarn>$(NoWarn);CS1591</NoWarn>
     <Threshold>30</Threshold>
     <ThresholdType>line</ThresholdType>
     <ThresholdStat>total</ThresholdStat>

DocAnalytics.Api/Auth/JwtSettings.cs

@@ -1,9 +1,14 @@
 namespace DocAnalytics.Api.Auth;
 
+/// <summary>Strongly-typed JWT configuration bound from the "Jwt" settings section.</summary>
 public class JwtSettings
 {
+    /// <summary>The token issuer (iss).</summary>
     public string Issuer { get; set; } = null!;
+    /// <summary>The intended token audience (aud).</summary>
     public string Audience { get; set; } = null!;
+    /// <summary>The symmetric signing key.</summary>
     public string Key { get; set; } = null!;
+    /// <summary>Access-token lifetime in minutes.</summary>
     public int ExpiryMinutes { get; set; } = 120;
 }

DocAnalytics.Api/BackgroundServices/AlertEvaluationBackgroundService.cs

@@ -4,20 +4,25 @@
 
 namespace DocAnalytics.Api.BackgroundServices;
 
+/// <summary>Hosted service that periodically evaluates all alert rules (once per minute) via a scoped <see cref="IAlertEvaluator"/>.</summary>
 [ExcludeFromCodeCoverage]
 public sealed class AlertEvaluationBackgroundService : BackgroundService
 {
     private readonly IServiceScopeFactory _scopes;
     private readonly ILogger<AlertEvaluationBackgroundService> _logger;
     private static readonly TimeSpan Interval = TimeSpan.FromMinutes(1);
 
+    /// <summary>Creates the background service with a scope factory and logger.</summary>
+    /// <param name="scopes">Factory used to create a DI scope per tick.</param>
+    /// <param name="logger">The logger.</param>
     public AlertEvaluationBackgroundService(
         IServiceScopeFactory scopes, ILogger<AlertEvaluationBackgroundService> logger)
     {
         _scopes = scopes;
         _logger = logger;
     }
 
+    /// <inheritdoc />
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)
     {
         using var timer = new PeriodicTimer(Interval);

DocAnalytics.Api/BackgroundServices/ExtractionWorker.cs

@@ -11,18 +11,28 @@
 
 namespace DocAnalytics.Api.BackgroundServices;
 
+/// <summary>
+/// Hosted worker that drains the extraction queue and runs the invoice pipeline per file:
+/// download → malware/format security gates → Bedrock extraction → validation → persist header/line items,
+/// updating file/batch state and broadcasting real-time notifications throughout.
+/// </summary>
 [ExcludeFromCodeCoverage]
 public sealed class ExtractionWorker : BackgroundService
 {
     private readonly IExtractionQueue _queue;
     private readonly IServiceScopeFactory _scopes;
     private readonly ILogger<ExtractionWorker> _logger;
 
+    /// <summary>Creates the worker with the shared queue, a scope factory, and a logger.</summary>
+    /// <param name="queue">The extraction queue to consume.</param>
+    /// <param name="scopes">Factory used to create a DI scope per file.</param>
+    /// <param name="logger">The logger.</param>
     public ExtractionWorker(IExtractionQueue queue, IServiceScopeFactory scopes, ILogger<ExtractionWorker> logger)
     {
         _queue = queue; _scopes = scopes; _logger = logger;
     }
 
+    /// <inheritdoc />
     protected override async Task ExecuteAsync(CancellationToken stoppingToken)
     {
         await foreach (var fileId in _queue.DequeueAllAsync(stoppingToken))
@@ -32,6 +42,7 @@ protected override async Task ExecuteAsync(CancellationToken stoppingToken)
         }
     }
 
+    /// <summary>Runs the full extraction pipeline for a single file within its own DI scope.</summary>
     private async Task ProcessAsync(Guid fileId, CancellationToken ct)
     {
         using var scope = _scopes.CreateScope();
@@ -247,6 +258,7 @@ await notifier.NotifyFileStateChangedAsync(file.SiteId,
         }
     }
 
+    /// <summary>Marks a file (and its parent batch counters) as failed with the given error, logs it, and broadcasts the change.</summary>
     private static async Task FailFileAsync(
     AppDbContext db, IPipelineNotifier notifier,
     FileRecord file, Transaction txn, DateTime startedAt,
@@ -294,6 +306,7 @@ await notifier.NotifyFileStateChangedAsync(file.SiteId,
     }
 
 
+    /// <summary>Recomputes the batch state (DT-1): any failure marks the batch Failed, but only once every file is settled.</summary>
     // DT-1 preserved: any file fails → batch Failed. But only finalize once ALL files are settled.
     private static void RecomputeState(Transaction t, DateTime at)
     {

DocAnalytics.Api/Common/ApiResponse.cs

@@ -1,15 +1,56 @@
 namespace DocAnalytics.Api.Common;
 
+/// <summary>Standard response envelope wrapping a payload, optional paging metadata, and an optional error.</summary>
+/// <typeparam name="T">The payload type.</typeparam>
 public class ApiResponse<T>
 {
+    /// <summary>The payload, when the request succeeded.</summary>
     public T? Data { get; set; }
+    /// <summary>Paging metadata, for list responses.</summary>
     public Meta? Meta { get; set; }
+    /// <summary>Error details, when the request failed.</summary>
     public ApiError? Error { get; set; }
 
+    /// <summary>Creates a success envelope for a single payload.</summary>
+    /// <param name="data">The payload.</param>
+    /// <returns>The envelope.</returns>
     public static ApiResponse<T> Ok(T data) => new() { Data = data };
+
+    /// <summary>Creates a success envelope for a list payload with paging metadata.</summary>
+    /// <param name="data">The payload.</param>
+    /// <param name="meta">The paging metadata.</param>
+    /// <returns>The envelope.</returns>
     public static ApiResponse<T> OkList(T data, Meta meta) => new() { Data = data, Meta = meta };
+
+    /// <summary>Creates a failure envelope with an error code, message, and optional details.</summary>
+    /// <param name="code">The machine-readable error code.</param>
+    /// <param name="msg">The human-readable message.</param>
+    /// <param name="details">Optional structured error details.</param>
+    /// <returns>The envelope.</returns>
     public static ApiResponse<T> Fail(string code, string msg, object? details = null)
         => new() { Error = new ApiError { Code = code, Message = msg, Details = details } };
 }
-public class Meta { public int TotalCount { get; set; } public int Page { get; set; } public int PageSize { get; set; } public int TotalPages { get; set; } }
-public class ApiError { public string Code { get; set; } = null!; public string Message { get; set; } = null!; public object? Details { get; set; } }
+
+/// <summary>Paging metadata for list responses.</summary>
+public class Meta
+{
+    /// <summary>Total rows across all pages.</summary>
+    public int TotalCount { get; set; }
+    /// <summary>The 1-based page number.</summary>
+    public int Page { get; set; }
+    /// <summary>Rows per page.</summary>
+    public int PageSize { get; set; }
+    /// <summary>Total number of pages.</summary>
+    public int TotalPages { get; set; }
+}
+
+/// <summary>Structured error information returned in a failure envelope.</summary>
+public class ApiError
+{
+    /// <summary>Machine-readable error code.</summary>
+    public string Code { get; set; } = null!;
+    /// <summary>Human-readable error message.</summary>
+    public string Message { get; set; } = null!;
+    /// <summary>Optional structured details (e.g. validation errors).</summary>
+    public object? Details { get; set; }
+}

DocAnalytics.Api/Common/BaseController.cs

@@ -2,10 +2,21 @@
 
 namespace DocAnalytics.Api.Common;
 
+/// <summary>Base API controller providing helpers to wrap results in the standard <see cref="ApiResponse{T}"/> envelope.</summary>
 [ApiController]
 [Route("api/v1/[controller]")]
 public abstract class BaseController : ControllerBase
 {
+    /// <summary>Wraps a single payload in a success envelope.</summary>
+    /// <typeparam name="T">The payload type.</typeparam>
+    /// <param name="data">The payload.</param>
+    /// <returns>A 200 OK result with the wrapped payload.</returns>
     protected IActionResult Envelope<T>(T data) => Ok(ApiResponse<T>.Ok(data));
+
+    /// <summary>Wraps a list payload plus paging metadata in a success envelope.</summary>
+    /// <typeparam name="T">The payload type.</typeparam>
+    /// <param name="data">The payload.</param>
+    /// <param name="meta">The paging metadata.</param>
+    /// <returns>A 200 OK result with the wrapped payload and metadata.</returns>
     protected IActionResult EnvelopeList<T>(T data, Meta meta) => Ok(ApiResponse<T>.OkList(data, meta));
 }

DocAnalytics.Api/Common/CurrentUser.cs

@@ -2,14 +2,25 @@
 
 namespace DocAnalytics.Api.Common;
 
+/// <summary>Request-scoped <see cref="ICurrentUser"/> implementation, populated from JWT claims by the tenant/site middleware.</summary>
 public class CurrentUser : ICurrentUser
 {
+    /// <inheritdoc />
     public Guid UserId { get; private set; }
+    /// <inheritdoc />
     public Guid TenantId { get; private set; }
+    /// <inheritdoc />
     public Guid SiteId { get; private set; }
+    /// <inheritdoc />
     public string Role { get; private set; } = string.Empty;
+    /// <inheritdoc />
     public bool IsAuthenticated { get; private set; }
 
+    /// <summary>Populates the identity/tenancy context for the current request and marks it authenticated.</summary>
+    /// <param name="userId">The authenticated user's id.</param>
+    /// <param name="tenantId">The active tenant id.</param>
+    /// <param name="siteId">The active site id.</param>
+    /// <param name="role">The user's role.</param>
     public void Set(Guid userId, Guid tenantId, Guid siteId, string role)
     {
         UserId = userId; TenantId = tenantId; SiteId = siteId; Role = role; IsAuthenticated = true;

DocAnalytics.Api/Configuration/RateLimitOptions.cs

@@ -1,18 +1,28 @@
 namespace DocAnalytics.Api.Configuration;
 
+/// <summary>Rate-limiting configuration bound from the "RateLimiting" section (Round 5).</summary>
 public sealed class RateLimitOptions
 {
+    /// <summary>The configuration section name.</summary>
     public const string SectionName = "RateLimiting";
 
+    /// <summary>Master on/off switch for rate limiting.</summary>
     public bool Enabled { get; set; } = true;
+    /// <summary>Limits for the login policy (per client IP).</summary>
     public RateLimitPolicySettings Login { get; set; } = new() { PermitLimit = 5, WindowSeconds = 60 };
+    /// <summary>Limits for read endpoints (per authenticated user).</summary>
     public RateLimitPolicySettings Reads { get; set; } = new() { PermitLimit = 100, WindowSeconds = 60 };
+    /// <summary>Limits for export endpoints (tight, per user).</summary>
     public RateLimitPolicySettings Export { get; set; } = new() { PermitLimit = 3, WindowSeconds = 60 };
 }
 
+/// <summary>Fixed-window limit settings for a single rate-limit policy.</summary>
 public sealed class RateLimitPolicySettings
 {
+    /// <summary>Maximum requests permitted per window.</summary>
     public int PermitLimit { get; set; }
+    /// <summary>Window length in seconds.</summary>
     public int WindowSeconds { get; set; }
+    /// <summary>Queue length for waiting requests; 0 rejects immediately (no queueing).</summary>
     public int QueueLimit { get; set; } = 0;   // 0 = reject immediately, no queueing
 }

DocAnalytics.Api/Configuration/RateLimitingExtensions.cs

@@ -4,12 +4,20 @@
 
 namespace DocAnalytics.Api.Configuration;
 
+/// <summary>Registers the ASP.NET Core rate limiter with login/reads/export policies (Round 5) and a standard 429 envelope.</summary>
 public static class RateLimitingExtensions
 {
+    /// <summary>Policy name for login endpoints (partitioned by client IP).</summary>
     public const string LoginPolicy = "login";
+    /// <summary>Policy name for read endpoints (partitioned by authenticated user).</summary>
     public const string ReadsPolicy = "reads";
+    /// <summary>Policy name for export endpoints (tight, partitioned by user).</summary>
     public const string ExportPolicy = "export";
 
+    /// <summary>Configures the rate limiter, its policies, and the 429 rejection response.</summary>
+    /// <param name="services">The service collection.</param>
+    /// <param name="config">The application configuration (reads the "RateLimiting" section).</param>
+    /// <returns>The same service collection, for chaining.</returns>
     public static IServiceCollection AddRateLimitingFeature(
         this IServiceCollection services, IConfiguration config)
     {

DocAnalytics.Api/Configuration/SecurityFoundationExtensions.cs

@@ -4,6 +4,7 @@
 
 namespace DocAnalytics.Api.Configuration;
 
+/// <summary>Round 0 security foundation wiring: binds <see cref="SecurityOptions"/> and registers CORS, HSTS, and forwarded-headers services.</summary>
 [ExcludeFromCodeCoverage]
 public static class SecurityFoundationExtensions
 {