Documentation modifications

2026-06-27 15:23:26 -07:00
parent a633fe6c06
commit a19fb90902
218 changed files with 2882 additions and 0 deletions
@@ -22,6 +22,12 @@ public class CalculatedObservations : ICalculatedObservations
    private readonly List<string> _nonInvasiveVentilation = [];
    private readonly Lazy<IObservationService> _observationService;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="CalculatedObservations"/> class by resolving its required dependencies from the supplied <see cref="IServiceProvider"/> and loading the configured high-frequency, invasive, and non-invasive ventilation category lists from <see cref="ApiSettings"/>.
+    /// </summary>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to resolve <see cref="IOptions{ApiSettings}"/>, <see cref="ILogger{CalculatedObservations}"/>, and a <see cref="Lazy{IObservationService}"/>.</param>
+    /// <exception cref="InvalidOperationException">Thrown when a required dependency cannot be resolved from <paramref name="serviceProvider"/>.</exception>
+    /// <!-- aidoc:v1 sig=409f903 body=98d5900 -->
    public CalculatedObservations(IServiceProvider serviceProvider)
    {
        var apiSettings = serviceProvider.GetRequiredService<IOptions<ApiSettings>>().Value;
@@ -35,6 +35,11 @@ public class CalculatedObservations : ICalculatedObservations

    private readonly Lazy<ITreatmentService> _treatmentService;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="CalculatedObservations"/> class, which provides calculated observations derived from treatment and medicine data, by resolving its required service dependencies and medication reference lists from <paramref name="serviceProvider"/>.
+    /// </summary>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to resolve the required service dependencies and configuration options.</param>
+    /// <!-- aidoc:v1 sig=409f903 body=10ae507 -->
    public CalculatedObservations(IServiceProvider serviceProvider)
    {
        _treatmentService = serviceProvider.GetRequiredService<Lazy<ITreatmentService>>();
@@ -38,6 +38,12 @@ public class CalculatedObservations : ICalculatedObservations
    private readonly Lazy<ITreatmentService> _treatmentService;


+    /// <summary>
+    /// Initializes a new instance of the <see cref="CalculatedObservations"/> class by resolving its treatment, medicine, observation, logging, and mapping dependencies from the supplied <see cref="IServiceProvider"/>.
+    /// </summary>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to obtain the dependencies required by this instance.</param>
+    /// <exception cref="InvalidOperationException">Thrown when a required service cannot be resolved from <paramref name="serviceProvider"/>.</exception>
+    /// <!-- aidoc:v1 sig=409f903 body=5dd8024 -->
    public CalculatedObservations(IServiceProvider serviceProvider)
    {
        _treatmentService = serviceProvider.GetRequiredService<Lazy<ITreatmentService>>();
@@ -7,6 +7,13 @@ using Serilog;

 namespace adas_core.Application.Providers;

+/// <summary>
+/// Represents an ADAS (Advanced Driver Assistance Systems) data provider that retrieves driver assistance observations through the shared infrastructure defined by <see cref="BaseProvider"/>.
+/// </summary>
+/// <remarks>
+/// The constructor forwards the supplied <paramref name="providerSettings"/> of type <see cref="IOptions{ProvidersSettings}"/> and the <paramref name="httpClientFactory"/> of type <see cref="IHttpClientFactory"/> to <see cref="BaseProvider"/>, ensuring consistent configuration and HTTP client management across all providers.
+/// </remarks>
+/// <!-- aidoc:v1 sig=42c9a02 -->
 public class AdasProvider(IOptions<ProvidersSettings> providerSettings, IHttpClientFactory httpClientFactory)
    : BaseProvider(providerSettings, httpClientFactory)
 {
@@ -5,6 +5,10 @@ using Microsoft.Extensions.Options;

 namespace adas_core.Application.Providers;

+/// <summary>
+/// Provides an abstract base class for provider implementations that consume configuration through <see cref="IOptions{ProvidersSettings}"/> and create HTTP clients via <see cref="IHttpClientFactory"/>.
+/// </summary>
+/// <!-- aidoc:v1 sig=e744862 -->
 public abstract class BaseProvider(
    IOptions<ProvidersSettings> providerSettings,
    IHttpClientFactory httpClientFactory)
@@ -13,6 +13,13 @@ using Patient = adas_core.Domain.Models.MongoModels.Patient;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Provides the administrative panel operations defined by <see cref="IAdminPanelService"/>, integrating patient, admission, discharge, authentication, medicine, point-of-care, unit, display, and configurable observation services.
+/// </summary>
+/// <remarks>
+/// The service receives its collaborators through primary constructor injection, including <see cref="IPatientService"/>, <see cref="IAdmissionService"/>, <see cref="IDischargeService"/>, <see cref="IAuthService"/>, <see cref="IMedicineService"/>, <see cref="IPointOfCareService"/>, <see cref="IUnitService"/>, <see cref="IDisplayService"/>, and <see cref="IConfigObservationService"/>, along with configuration via <see cref="IOptions{ApiSettings}"/> and logging through <see cref="ILogger{AdminPanelService}"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=29af4d8 -->
 public class AdminPanelService(
    IOptions<ApiSettings> apiSettings,
    IPatientService patientService,
@@ -205,6 +212,12 @@ public class AdminPanelService(
            return true;
        }

+    /// <summary>
+    /// Updates the location of a patient identified by the source location in <paramref name="request"/>, relocating any occupant of the target location to the <see cref="VirtualPointOfCare.Pushed"/> point of care and creating a new <see cref="Patient"/> record when no matching patient is found.
+    /// </summary>
+    /// <param name="request">The <see cref="AdmPanelRequest"/> containing the original and the target <see cref="PatientLocation"/> values used to find and reassign the patient.</param>
+    /// <returns>A <see cref="Task{Boolean}"/> that resolves to <c>true</c> once the update or insertion has completed.</returns>
+    /// <!-- aidoc:v1 sig=d2e1ae3 body=d053266 -->
    public async Task<bool> UpdatePatientLocation(AdmPanelRequest request)
    {
        var patient = await patientService.FindByLocation(request.OldLocation);
@@ -14,6 +14,13 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Provides admission-related operations and coordinates persistence, messaging, and clinical context services to manage the admission workflow.
+/// </summary>
+/// <remarks>
+/// This service implements <see cref="IAdmissionService"/> and composes logging, subscriber notifications, admission data access, client messaging, unit, patient, point-of-care, display, discharge, patient archive, HTTP context, local audit, and master list factory collaborators to fulfill its contract.
+/// </remarks>
+/// <!-- aidoc:v1 sig=f8f49ce -->
 public class AdmissionService(
    ILogger<AdmissionService> logger,
    ISubscribersService subscribersService,
@@ -51,6 +51,28 @@ public class AlarmService : IAlarmService

    private TimeSpan _interval;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="AlarmService"/> class, injecting required dependencies for alarm processing and optionally starting the internal alarm timer when <paramref name="startTimer"/> is <see langword="true"/>.
+    /// </summary>
+    /// <param name="alarmRepository">The <see cref="IAlarmRepository"/> used to persist and retrieve alarm data.</param>
+    /// <param name="logger">The <see cref="ILogger{AlarmService}"/> used for diagnostic logging.</param>
+    /// <param name="patientService">The <see cref="IPatientService"/> used to access patient information.</param>
+    /// <param name="configObservationService">The <see cref="IConfigObservationService"/> used to retrieve observation configuration.</param>
+    /// <param name="observationService">A <see cref="Lazy{IObservationService}"/> providing deferred access to observation data.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to publish client notifications.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage alarm subscribers.</param>
+    /// <param name="calculatedObservationsService">A <see cref="Lazy{ICalculatedObservationsService}"/> providing deferred access to calculated observations.</param>
+    /// <param name="lightBeaconService">A <see cref="Lazy{ILightBeaconService}"/> providing deferred access to the light beacon service.</param>
+    /// <param name="recordingService">A <see cref="Lazy{IRecordingService}"/> providing deferred access to the recording service.</param>
+    /// <param name="relayService">A <see cref="Lazy{IRelayService}"/> providing deferred access to the relay service.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing access to API configuration.</param>
+    /// <param name="unitService">The <see cref="IUnitService"/> used to manage unit information.</param>
+    /// <param name="pocService">The <see cref="IPointOfCareService"/> used to access point-of-care information.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record audit entries.</param>
+    /// <param name="startTimer">A <see cref="bool"/> indicating whether the alarm timer should be started during construction.</param>
+    /// <exception cref="System.Exception">Thrown when <paramref name="apiSettings"/> is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=15ef9b7 body=6126462 -->
    public AlarmService(IAlarmRepository alarmRepository,
        ILogger<AlarmService> logger,
        IPatientService patientService,
@@ -14,6 +14,13 @@ using Patient = adas_core.Domain.Models.MongoModels.Patient;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IAppointmentService"/> to coordinate appointment management operations, persisting data through <see cref="IAppointmentRepository"/> and <see cref="IAppointmentArchiveRepository"/> while integrating supporting services such as <see cref="IPatientService"/>, <see cref="IObservationService"/>, <see cref="IDiagnosisService"/>, and <see cref="IUnitService"/>.
+/// </summary>
+/// <remarks>
+/// Defers initialization of <see cref="IPatientService"/> and <see cref="IObservationService"/> via <see cref="Lazy{T}"/>, reads configuration through <see cref="IOptions{TOptions}"/> bound to <c>ApiSettings</c> and <c>CacheSettings</c>, logs diagnostics with <see cref="ILogger{TCategoryName}"/>, and accesses the current request through <see cref="IHttpContextAccessor"/>. It also relies on <see cref="ILocalAuditService"/>, <see cref="IPointOfCareService"/>, <see cref="ISubscribersService"/>, <see cref="IClientMessageService"/>, and <see cref="ICacheService"/> to support auditing, point-of-care workflows, subscriber notifications, messaging, and caching.
+/// </remarks>
+/// <!-- aidoc:v1 sig=7de86ff -->
 public class AppointmentService(
    IAppointmentRepository appointmentRepository,
    IAppointmentArchiveRepository appointmentArchiveRepository,
@@ -7,6 +7,14 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IArchivePatientCarePlanService"/> to provide the application service responsible for archiving patient care plans.
+/// Collaborates with <see cref="IArchivePatientCarePlanRepository"/> for data access, <see cref="ILogger{ArchivePatientCarePlanService}"/> for diagnostics, <see cref="IHttpContextAccessor"/> for HTTP context retrieval, and <see cref="ILocalAuditService"/> for local auditing.
+/// </summary>
+/// <remarks>
+/// The collaborators are supplied through the primary constructor, allowing the service to fulfill the contract defined by <see cref="IArchivePatientCarePlanService"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=6829647 -->
 public class ArchivePatientCarePlanService(
    IArchivePatientCarePlanRepository archivedPatientRepository,
    ILogger<ArchivePatientCarePlanService> logger,
@@ -5,6 +5,13 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IArchivedPatientObservationService"/> to archive patient observations through the supplied <see cref="IObservationArchiveRepository"/>.
+/// </summary>
+/// <remarks>
+/// The archive repository dependency is provided via the primary constructor and is used to perform the underlying archiving operations.
+/// </remarks>
+/// <!-- aidoc:v1 sig=a0ae303 -->
 public class ArchivePatientObservationsService(IObservationArchiveRepository archivedPatientObservationService)
    : IArchivedPatientObservationService
 {
@@ -5,6 +5,10 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IArchivedPatientTreatmentService"/> and provides archived patient treatment operations using an injected <see cref="ITreatmentArchiveRepository"/>.
+/// </summary>
+/// <!-- aidoc:v1 sig=e336127 -->
 public class ArchivedPatientTreatmentService(ITreatmentArchiveRepository archivedPatientTreatmentService)
    : IArchivedPatientTreatmentService
 {
@@ -24,6 +24,14 @@ public class AuthService : IAuthService

    //private LoginResponse? _loginResponse;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="AuthService"/> class, capturing the recording settings, logger, and authority repository required for authentication operations.
+    /// </summary>
+    /// <param name="recordingSettings">The <see cref="IOptions{RecordingSettings}"/> providing access to the configured <see cref="RecordingSettings"/>.</param>
+    /// <param name="logger">The <see cref="ILogger{AuthService}"/> used to log authentication activity.</param>
+    /// <param name="authorityRepository">The <see cref="IAuthorityRepository"/> used to access authority data.</param>
+    /// <exception cref="Exception">Thrown when <paramref name="recordingSettings"/>.Value is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=acf40f6 body=d2bb62a -->
    public AuthService(IOptions<RecordingSettings> recordingSettings, ILogger<AuthService> logger,
        IAuthorityRepository authorityRepository)
    {
@@ -115,6 +115,16 @@ namespace adas_core.Application.Services.Caching
        // GET OR SET - STRING KEY
        // ============================================================

+        /// <summary>
+        /// Retrieves or creates an object asynchronously. When the cache mode is NONE, this method bypasses caching entirely and always invokes <paramref name="factory"/> to produce the result.
+        /// </summary>
+        /// <typeparam name="T">The type of the object to retrieve or create.</typeparam>
+        /// <param name="key">The cache key used to identify the cached object.</param>
+        /// <param name="factory">The asynchronous factory delegate that produces the value when no cached entry exists.</param>
+        /// <param name="ttl">An optional <see cref="TimeSpan"/> indicating the time-to-live for the cache entry.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
+        /// <returns>A <see cref="Task{T}"/> containing the value produced by <paramref name="factory"/>.</returns>
+        /// <!-- aidoc:v1 sig=df20281 body=93d29eb -->
        public async Task<T> GetOrSetObjectAsync<T>(
            string key,
            Func<Task<T>> factory,
@@ -145,6 +155,16 @@ namespace adas_core.Application.Services.Caching
        // GET OR SET - GroupedField + patientId
        // ============================================================

+        /// <summary>
+        /// Retrieves or creates an object asynchronously for the specified patient. This implementation does not perform caching and always invokes the supplied <paramref name="factory"/> to produce the result, corresponding to the disabled-cache (NONE) mode.
+        /// </summary>
+        /// <param name="groupedField">The grouped field that categorizes the object being retrieved.</param>
+        /// <param name="patientId">The identifier of the patient to whom the object belongs.</param>
+        /// <param name="factory">The asynchronous factory delegate invoked to produce the object.</param>
+        /// <param name="ttl">An optional time-to-live for the cached entry. Ignored because caching is disabled.</param>
+        /// <param name="cancellationToken">The token used to observe cancellation of the factory invocation.</param>
+        /// <returns>A task that yields the object produced by <paramref name="factory"/>.</returns>
+        /// <!-- aidoc:v1 sig=f122a12 body=93d29eb -->
        public async Task<T> GetOrSetObjectAsync<T>(
            GroupedField groupedField,
            ObjectId patientId,
@@ -28,6 +28,13 @@ namespace adas_core.Application.Services.Caching
        public IDatabase? Database => _database;
        private bool _isRedisAvailable;

+        /// <summary>
+        /// Initializes a new instance of <see cref="RedisService"/>, capturing the bound <see cref="CacheSettings"/>, <see cref="ILogger{RedisService}"/>, and <see cref="LockManagerService"/> dependencies, and starting asynchronous Redis connection setup when a connection string is configured.
+        /// </summary>
+        /// <param name="options">The <see cref="IOptions{CacheSettings}"/> that exposes the bound <see cref="CacheSettings"/> whose Redis section drives connection initialization.</param>
+        /// <param name="logger">The <see cref="ILogger{RedisService}"/> used for diagnostic logging.</param>
+        /// <param name="lockManager">The <see cref="LockManagerService"/> used to coordinate distributed locks on the Redis instance.</param>
+        /// <!-- aidoc:v1 sig=2d613ee body=66db01c -->
        public RedisService(
            IOptions<CacheSettings> options,
            ILogger<RedisService> logger,
@@ -17,6 +17,13 @@ public class CalculatedObservationsService : ICalculatedObservationsService
    private readonly ILogger<CalculatedObservationsService>? _logger;


+    /// <summary>
+    /// Initializes a new instance of the <see cref="CalculatedObservationsService"/>, resolving the internal <see cref="ICalculatedObservations"/> implementation from the configured customization or falling back to <see cref="DefaultCalculatedObservations"/>.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the customization name used to locate the calculation implementation type.</param>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> supplied to the resolved customization type's constructor.</param>
+    /// <param name="logger">The <see cref="ILogger{CalculatedObservationsService}"/> used to log warnings when the customization cannot be resolved.</param>
+    /// <!-- aidoc:v1 sig=f22feaa body=18f989f -->
    public CalculatedObservationsService(
        IOptions<ApiSettings> apiSettings,
        IServiceProvider serviceProvider,
@@ -50,6 +50,18 @@ public class ConfigObservationService : IConfigObservationService
    private bool IgnoreUnknownObservation =>
        _apiSettings.Value.ConfigObservation?.IgnoreUnknownObservation ?? false;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConfigObservationService"/> class, storing its required dependencies and reading configuration values from the supplied <see cref="IOptions{TOptions}"/> instances to establish internal operational defaults such as the refresh timeout, unknown treatment handling, and retention policy.
+    /// </summary>
+    /// <param name="configObservationRepository">The <see cref="IConfigObservationRepository"/> used to access configuration observation data.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing API configuration values, including the refresh interval and retention policy defaults.</param>
+    /// <param name="cacheSettings">The <see cref="IOptions{CacheSettings}"/> providing cache configuration values.</param>
+    /// <param name="logger">The <see cref="ILogger{ConfigObservationService}"/> used for diagnostic logging.</param>
+    /// <param name="unitService">The <see cref="IUnitService"/> used to perform unit-related operations.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="cacheService">The <see cref="ICacheService"/> used for caching operations.</param>
+    /// <!-- aidoc:v1 sig=85a9f25 body=f5101e8 -->
    public ConfigObservationService(
        IConfigObservationRepository configObservationRepository,
        IOptions<ApiSettings> apiSettings,
@@ -12,6 +12,14 @@ using Microsoft.Extensions.Options;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements the <see cref="IConfigPumpsService"/> contract to manage configuration operations for pumps.
+/// </summary>
+/// <remarks>
+/// This service relies on an <see cref="IConfigPumpsRepository"/> for data access, an <see cref="IOptions{ApiSettings}"/> for API configuration,
+/// an <see cref="ILogger{ConfigPumpsService}"/> for diagnostics, an <see cref="IHttpContextAccessor"/> for HTTP context retrieval, and an <see cref="ILocalAuditService"/> for auditing operations.
+/// </remarks>
+/// <!-- aidoc:v1 sig=abae5d0 -->
 public class ConfigPumpsService(
    IConfigPumpsRepository configPumpsRepository,
    IOptions<ApiSettings> apiSettings,
@@ -10,6 +10,13 @@ using Microsoft.Extensions.Options;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IConfigUnitsService"/> to manage configuration units,
+/// using <paramref name="configUnitsRepository"/> for data persistence,
+/// <paramref name="apiSettings"/> for API configuration values,
+/// and <paramref name="logger"/> for diagnostic logging.
+/// </summary>
+/// <!-- aidoc:v1 sig=cc78d0f -->
 public class ConfigUnitsService(
    IConfigUnitsRepository configUnitsRepository,
    IOptions<ApiSettings> apiSettings,
@@ -22,6 +22,16 @@ public class DeviceService : IDeviceService
    private readonly IPointOfCareService _pointOfCareService;
    private readonly ILogger<DeviceService> _logger;
    
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DeviceService"/> class, injecting the required collaborators used to manage device-related domain operations.
+    /// </summary>
+    /// <param name="deviceRepository">The <see cref="IDeviceRepository"/> that provides persistence access for devices.</param>
+    /// <param name="pointOfCareService">The <see cref="IPointOfCareService"/> used to coordinate point-of-care operations.</param>
+    /// <param name="logger">The <see cref="ILogger{DeviceService}"/> used to emit diagnostic and operational logs.</param>
+    /// <param name="observationService">The <see cref="IObservationService"/> used to record and query observations.</param>
+    /// <param name="configObservationService">The <see cref="IConfigObservationService"/> used to manage configured observation rules.</param>
+    /// <param name="alarmService">The <see cref="IAlarmService"/> used to raise and resolve alarms.</param>
+    /// <!-- aidoc:v1 sig=ec3ca5b body=22d30a4 -->
    public DeviceService(
        IDeviceRepository deviceRepository,
        IPointOfCareService pointOfCareService,
@@ -37,6 +37,21 @@ public class DiagnosisService : IDiagnosisService
    private readonly IUnitService _unitService;


+    /// <summary>
+    /// Initializes a new instance of the <see cref="DiagnosisService"/>, which provides operations for managing diagnoses and their archives. The constructor stores injected collaborators and seeds the diagnosis system identifier and configured diagnosis codes from <paramref name="apiSettings"/>.
+    /// </summary>
+    /// <param name="patientService">A <see cref="Lazy{T}"/> that resolves an <see cref="IPatientService"/> for patient lookups.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{TOptions}"/> of <see cref="ApiSettings"/> providing configuration such as the diagnosis system and diagnosis codes.</param>
+    /// <param name="diagnosisRepository">The <see cref="IDiagnosisRepository"/> used to read and persist diagnoses.</param>
+    /// <param name="diagnosisArchiveRepository">The <see cref="IDiagnosisArchiveRepository"/> used to read and persist archived diagnoses.</param>
+    /// <param name="logger">The <see cref="ILogger{TCategoryName}"/> used to record diagnostic information.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to deliver messages to clients.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to notify subscribers of diagnosis events.</param>
+    /// <param name="calculatedObservations">A <see cref="Lazy{T}"/> that resolves an <see cref="ICalculatedObservationsService"/> for derived observations.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> providing access to the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="unitService">The <see cref="IUnitService"/> used to manage measurement units.</param>
+    /// <!-- aidoc:v1 sig=ff6d776 body=0fbbf26 -->
    public DiagnosisService(
        Lazy<IPatientService> patientService,
        IOptions<ApiSettings> apiSettings,
@@ -35,6 +35,20 @@ public class DischargeService : IDischargeService
    private readonly ISubscribersService _subscribersService;
    private readonly IUnitService _unitService;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="DischargeService"/> class, which coordinates discharge-related operations by injecting its required collaborators into private fields for logging, persistence, patient access, messaging, auditing, and unit/master list resolution.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger{TCategoryName}"/> used to record diagnostic information for the <see cref="DischargeService"/>.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers tied to discharge events.</param>
+    /// <param name="dischargeRepository">The <see cref="IDischargeRepository"/> used to persist and retrieve discharge records.</param>
+    /// <param name="patientServiceLazy">The <see cref="Lazy{T}"/> wrapping <see cref="IPatientService"/> to defer patient service resolution.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to send client-facing messages.</param>
+    /// <param name="pointOfCareService">The <see cref="IPointOfCareService"/> used to interact with point-of-care operations.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="unitService">The <see cref="IUnitService"/> used to look up unit-related information.</param>
+    /// <param name="masterListServiceFactory">The <see cref="IMasterListServiceFactory"/> used to create master list services on demand.</param>
+    /// <!-- aidoc:v1 sig=5a98484 body=4f2b947 -->
    public DischargeService(ILogger<DischargeService> logger,
        ISubscribersService subscribersService,
        IDischargeRepository dischargeRepository,
@@ -281,6 +295,11 @@ public class DischargeService : IDischargeService
    }


+    /// <summary>
+    /// Processes an <see cref="ApiRequest"/> for patient discharge operations. Based on <paramref name="apiRequest"/>.Type it handles three cases: "NewDischarge" inserts a new discharge, creates an audit log, and sends a discharge broadcast (only when the patient status is "Altable"); "UpdateDischarge" updates the existing discharge; "DeleteDischarge" deletes the discharge (only when the patient status is "NoAltable"). The method returns early and logs an error when the discharge or patient is null, when the patient cannot be found, or when the corresponding discharge-status validation fails.
+    /// </summary>
+    /// <param name="apiRequest">The API request containing the discharge payload and the operation type to perform.</param>
+    /// <!-- aidoc:v1 sig=229d8cd body=acbd395 -->
    public async Task SaveRequest(ApiRequest apiRequest)
    {
        try
@@ -18,6 +18,13 @@ using DisplayConfig = adas_core.Domain.Models.MongoModels.DisplayConfig;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IDisplayConfigService"/> to coordinate display configuration operations across multiple repositories and supporting services.
+/// </summary>
+/// <remarks>
+/// The service composes card, detail, and chart configuration repositories with display, subscriber, messaging, auditing, and master list services to manage display configuration workflows. It receives <see cref="IHttpContextAccessor"/> for accessing the current HTTP context and uses <see cref="Lazy{T}"/> of <see cref="IDisplayService"/> to defer initialization of the display service dependency.
+/// </remarks>
+/// <!-- aidoc:v1 sig=f2c684c -->
 public class DisplayConfigService(
    IDisplayConfigRepository displayConfigRepository,
    Lazy<IDisplayService> displayService,
@@ -19,6 +19,13 @@ using MongoDB.Driver;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IDisplayService"/>, coordinating display management operations
+/// across data access (<see cref="IDisplayRepository"/>), configuration (<see cref="IDisplayConfigService"/>),
+/// authentication (<see cref="IAuthService"/>), audit (<see cref="ILocalAuditService"/>),
+/// and caching (<see cref="ICacheService"/>) concerns.
+/// </summary>
+/// <!-- aidoc:v1 sig=010754e -->
 public class DisplayService(
    IDisplayRepository displayRepository,
    IPointOfCareService pointOfCareService,
@@ -21,6 +21,12 @@ public class FileService : IFileService
    private readonly ILogger<FileService> _logger;
    private readonly string? _updateDirectory;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileService"/> class, configuring the file system paths used to read update files and display assets and storing the logger used for diagnostic output. <see cref="FileService"/> provides file-related operations backed by the supplied configuration.
+    /// </summary>
+    /// <param name="apiSettings">The bound application settings exposed via <see cref="IOptions{ApiSettings}"/>; supplies the <see cref="ApiSettings.PathUpdateFiles"/> and <see cref="ApiSettings.PathToDisplayAssets"/> paths used to build the working directories.</param>
+    /// <param name="logger">The <see cref="ILogger{FileService}"/> retained for recording diagnostic and operational events.</param>
+    /// <!-- aidoc:v1 sig=715c341 body=f27c630 -->
    public FileService(
        IOptions<ApiSettings> apiSettings,
        ILogger<FileService> logger
@@ -25,6 +25,16 @@ public class GroupedObservationService : IGroupedObservationService
    private readonly ILogger<GroupedObservationService> _logger;
    private readonly IObservationRepository _observationRepository;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="GroupedObservationService"/>, which coordinates the retrieval, configuration, caching, and logging of grouped observation data, by capturing the supplied dependencies.
+    /// </summary>
+    /// <param name="observationRepository">The <see cref="IObservationRepository"/> used to access underlying observation records.</param>
+    /// <param name="configObservationService">The <see cref="IConfigObservationService"/> used to resolve observation configuration.</param>
+    /// <param name="logger">The <see cref="ILogger{GroupedObservationService}"/> used to record diagnostic and operational messages.</param>
+    /// <param name="cacheService">The <see cref="ICacheService"/> used to read from and write to the application cache.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing configurable API options.</param>
+    /// <param name="cacheSettings">The <see cref="IOptions{CacheSettings}"/> whose <see cref="IOptions{TOptions}.Value"/> is stored as the resolved cache configuration.</param>
+    /// <!-- aidoc:v1 sig=3ffcb4f body=0e26b9d -->
    public GroupedObservationService(
        IObservationRepository observationRepository,
        IConfigObservationService configObservationService,
@@ -10,6 +10,13 @@ using MongoDB.Driver;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Provides operations for retrieving and managing historical configuration changes, delegating data access to an <see cref="IHistoricalConfigChangesRepository"/> and coordinating logging, HTTP context, and auditing concerns.
+/// </summary>
+/// <remarks>
+/// Implements <see cref="IHistoricalConfigChangesService"/> and uses <paramref name="historicalConfigChangesRepository"/> for persistence, <paramref name="logger"/> for diagnostics, <paramref name="httpContextAccessor"/> for request context, and <paramref name="auditService"/> to record local audit entries.
+/// </remarks>
+/// <!-- aidoc:v1 sig=757183c -->
 public class HistoricalConfigChangesService(
    IHistoricalConfigChangesRepository historicalConfigChangesRepository,
    ILogger<HistoricalConfigChangesService> logger,
@@ -5,6 +5,10 @@ using Microsoft.Extensions.Logging;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements the local auditing behavior defined by <see cref="ILocalAuditService"/>, forwarding audit operations to an inner <see cref="IAuditService"/> and recording diagnostic information via an <see cref="ILogger{LocalAuditService}"/>.
+/// </summary>
+/// <!-- aidoc:v1 sig=e6cdfbf -->
 public class LocalAuditService(
    IAuditService auditService,
    ILogger<LocalAuditService> logger)
@@ -38,6 +38,22 @@ public class MasterListService<T> : IMasterListService<T> where T : MasterList,
    private readonly ISubscribersService _subscribersService;
    private readonly Lazy<IUnitService> _unitService;

+    /// <summary>
+    /// Initializes a new instance of <see cref="MasterListService{T}"/>, a service that coordinates display, patient, unit, admission, discharge, subscriber and client messaging operations. The constructor stores the injected collaborators and, when <paramref name="apiSettings"/> specifies a display assets path, computes the assets directory via <see cref="Path.Combine(System.String[])"/>.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger{T}"/> used by the service to emit diagnostic messages.</param>
+    /// <param name="serviceProvider">The <see cref="IServiceProvider"/> used to resolve additional services at runtime.</param>
+    /// <param name="clientMessageService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IClientMessageService"/> until it is first accessed.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers.</param>
+    /// <param name="unitService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IUnitService"/> until it is first accessed.</param>
+    /// <param name="displayService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IDisplayService"/> until it is first accessed.</param>
+    /// <param name="patientService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IPatientService"/> until it is first accessed.</param>
+    /// <param name="dischargeService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IDischargeService"/> until it is first accessed.</param>
+    /// <param name="admissionService">A <see cref="Lazy{T}"/> that defers creation of the <see cref="IAdmissionService"/> until it is first accessed.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{T}"/> providing access to the configured <see cref="ApiSettings"/>; its <see cref="ApiSettings.PathToDisplayAssets"/> property initializes the assets directory when not null.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record audit entries.</param>
+    /// <!-- aidoc:v1 sig=2960814 body=4451a9b -->
    public MasterListService(
        ILogger<MasterListService<T>> logger,
        IServiceProvider serviceProvider,
@@ -11,6 +11,13 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Factory class responsible for creating instances of master list services based on the supplied <see cref="ListSettings"/>.
+/// </summary>
+/// <remarks>
+/// Implements <see cref="IMasterListServiceFactory"/> and uses <see cref="IServiceProvider"/> for dependency resolution along with <see cref="ILogger{MasterListServiceFactory}"/> for diagnostic logging.
+/// </remarks>
+/// <!-- aidoc:v1 sig=fefed1b -->
 public class MasterListServiceFactory(
    IServiceProvider serviceProvider,
    ILogger<MasterListServiceFactory> logger,
@@ -14,6 +14,13 @@ using MongoDB.Driver;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IMedicineService"/> and provides the application service responsible for medicine-related operations, coordinating <see cref="IMedicineRepository"/> and <see cref="ITreatmentService"/>.
+/// </summary>
+/// <remarks>
+/// Configured via <see cref="IOptions{ApiSettings}"/>, instrumented with <see cref="ILogger{MedicineService}"/>, supplied with the current HTTP context through <see cref="IHttpContextAccessor"/>, and audited by <see cref="ILocalAuditService"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=34a02a6 -->
 public class MedicineService(
    IMedicineRepository medicineRepository,
    ITreatmentService treatmentService,
@@ -10,6 +10,17 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="INoticeService"/>, providing the coordination logic for managing
+/// notices and delivering them through the configured subscriber, messaging, display, and audit subsystems.
+/// </summary>
+/// <remarks>
+/// Instances are created through a primary constructor that receives <see cref="ILogger{NoticeService}"/>,
+/// <see cref="ISubscribersService"/>, <see cref="INoticeRepository"/>, <see cref="IClientMessageService"/>,
+/// <see cref="IDisplayService"/>, <see cref="IHttpContextAccessor"/>, and <see cref="ILocalAuditService"/>
+/// as injected collaborators.
+/// </remarks>
+/// <!-- aidoc:v1 sig=3ccc883 -->
 public class NoticeService(
    ILogger<NoticeService> logger,
    ISubscribersService subscribersService,
@@ -8,6 +8,13 @@ using adas_core.Domain.Utils;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Provides a demo implementation of <see cref="IObservationDemoService"/> that coordinates observation handling using <see cref="IConfigObservationService"/> for configuration and a <see cref="Lazy{T}"/> of <see cref="IAlarmService"/> for deferred alarm access.
+/// </summary>
+/// <remarks>
+/// The service is constructed with an <see cref="IConfigObservationService"/> for observation configuration and a lazily-initialized <see cref="IAlarmService"/> so that alarm functionality is created only on first use.
+/// </remarks>
+/// <!-- aidoc:v1 sig=fc27ac9 -->
 public class ObservationDemoService(
    IConfigObservationService configObservationService,
    Lazy<IAlarmService> alarmService)
@@ -74,6 +74,33 @@ public class ObservationService : IObservationService
    private readonly ISubscribersService _subscribersService;


+    /// <summary>
+    /// Initializes a new instance of the <see cref="ObservationService"/> class, storing the supplied collaborators in private fields and loading observation-code and cache configuration from the provided options.
+    /// </summary>
+    /// <param name="patientService">Provides access to patient data.</param>
+    /// <param name="configObservationService">Provides observation configuration values.</param>
+    /// <param name="observationRepository">Persists and retrieves observations.</param>
+    /// <param name="observationArchiveRepository">Accesses archived observations.</param>
+    /// <param name="configUnitsService">Provides unit configuration.</param>
+    /// <param name="diagnosisService">Performs diagnosis-related operations.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> whose values seed the observation code settings.</param>
+    /// <param name="cacheSettings">The <see cref="IOptions{CacheSettings}"/> whose values configure caching behavior.</param>
+    /// <param name="lightBeaconService">Controls light beacon devices.</param>
+    /// <param name="relayService">Operates relay hardware.</param>
+    /// <param name="recordingService">Manages recordings.</param>
+    /// <param name="logger">Logs <see cref="ObservationService"/> activity.</param>
+    /// <param name="groupedObservationService">Handles grouped observation logic.</param>
+    /// <param name="alarmService">Raises and manages alarms.</param>
+    /// <param name="clientMessageService">Publishes messages to clients.</param>
+    /// <param name="subscribersService">Tracks observation subscribers.</param>
+    /// <param name="subscriberGroupedService">Manages grouped observation subscribers.</param>
+    /// <param name="calculatedObservationsService">Defers creation of the calculated observations dependency.</param>
+    /// <param name="httpContextAccessor">Exposes the current HTTP context.</param>
+    /// <param name="auditService">Writes local audit entries.</param>
+    /// <param name="pointOfCareService">Handles point-of-care operations.</param>
+    /// <param name="cacheService">Reads from and writes to the cache.</param>
+    /// <exception cref="Exception">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=50945c1 body=e153242 -->
    public ObservationService(
        IPatientService patientService,
        IConfigObservationService configObservationService,
@@ -22,6 +22,16 @@ public class PatientCarePlanService : IPatientCarePlanService
    private readonly IPatientCarePlanRepository _patientCarePlanRepository;
    private readonly IUserRepository _userRepository;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientCarePlanService"/> class, wiring in the dependencies required to manage, archive, and audit patient care plans.
+    /// </summary>
+    /// <param name="logger">The <see cref="ILogger{PatientCarePlanService}"/> used to record operational and diagnostic information.</param>
+    /// <param name="patientCarePlanRepository">The <see cref="IPatientCarePlanRepository"/> used to access patient care plan data.</param>
+    /// <param name="userRepository">The <see cref="IUserRepository"/> used to access user information.</param>
+    /// <param name="archivePatientCarePlanService">The <see cref="IArchivePatientCarePlanService"/> used to archive patient care plans.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit information.</param>
+    /// <!-- aidoc:v1 sig=8f3d58d body=0a1cfb1 -->
    public PatientCarePlanService(
        ILogger<PatientCarePlanService> logger,
        IPatientCarePlanRepository patientCarePlanRepository,
@@ -70,6 +70,36 @@ public class PatientService : IPatientService
    private readonly bool _updatePatientDataWithOru;
    private readonly bool _updatePatientLocationWithOru;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientService"/> class, storing its required repositories, services and helpers, and reading configuration values from <see cref="ApiSettings"/> and <see cref="ListSettings"/>.
+    /// </summary>
+    /// <param name="patientRepository">The <see cref="IPatientRepository"/> used to access patient data.</param>
+    /// <param name="patientArchiveRepository">The <see cref="IPatientArchiveRepository"/> used to access archived patient data.</param>
+    /// <param name="observationService">The lazily resolved <see cref="Lazy{IObservationService}"/> providing observation operations.</param>
+    /// <param name="treatmentService">The lazily resolved <see cref="Lazy{ITreatmentService}"/> providing treatment operations.</param>
+    /// <param name="pocMappingService">The <see cref="IPoCMappingService"/> used for point-of-care mappings.</param>
+    /// <param name="diagnosisService">The <see cref="IDiagnosisService"/> used to manage diagnoses.</param>
+    /// <param name="appointmentService">The <see cref="IAppointmentService"/> used to manage appointments.</param>
+    /// <param name="pumpService">The lazily resolved <see cref="Lazy{IPumpService}"/> providing pump operations.</param>
+    /// <param name="recordingAlertService">The <see cref="IRecordingAlertService"/> used to handle recording alerts.</param>
+    /// <param name="dischargeService">The <see cref="IDischargeService"/> used to manage discharges.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> exposing archive and HL7 related configuration values.</param>
+    /// <param name="listSettings">The <see cref="IOptions{ListSettings}"/> exposing list related configuration values.</param>
+    /// <param name="logger">The <see cref="ILogger{PatientService}"/> used to log diagnostics.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to send client messages.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers.</param>
+    /// <param name="subscriberGroupedService">The <see cref="ISubscriberGroupedService}"/> used to manage grouped subscribers.</param>
+    /// <param name="unitService">The <see cref="IUnitService"/> used to manage units.</param>
+    /// <param name="displayService">The <see cref="IDisplayService"/> used to manage displays.</param>
+    /// <param name="pointOfCareService">The <see cref="IPointOfCareService"/> used to manage point-of-care data.</param>
+    /// <param name="admissionService">The lazily resolved <see cref="Lazy{IAdmissionService}"/> providing admission operations.</param>
+    /// <param name="displayConfigService">The <see cref="IDisplayConfigService"/> used to manage display configuration.</param>
+    /// <param name="groupedObservationService">The <see cref="IGroupedObservationService"/> used to manage grouped observations.</param>
+    /// <param name="patientCarePlanService">The <see cref="IPatientCarePlanService"/> used to manage patient care plans.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="masterListServiceFactory">The <see cref="IMasterListServiceFactory}"/> used to create master list services.</param>
+    /// <!-- aidoc:v1 sig=1949cfe body=98328ad -->
    public PatientService(
        IPatientRepository patientRepository,
        IPatientArchiveRepository patientArchiveRepository,
@@ -10,6 +10,11 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IPermissionService"/> to evaluate user permissions from the configured <see cref="PermissionSettings"/> and the available authority data stores.
+/// Resolves <see cref="IDisplayService"/>, <see cref="IUserRepository"/>, and <see cref="IAuthorityRepository"/> through <see cref="Lazy{T}"/> so their construction is deferred until needed.
+/// </summary>
+/// <!-- aidoc:v1 sig=62dd81d -->
 public class PermissionService(
    IOptions<PermissionSettings> permissionsConfig,
    ILogger<PermissionService> logger,
@@ -21,6 +21,12 @@ public class PoCMappingService : IPoCMappingService
    private PoCMapping? _mapping;
    private DateTime _nextRefresh = DateTime.MinValue;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PoCMappingService"/> class, storing the supplied repository and capturing point-of-care mapping configuration values from <paramref name="apiSettings"/>.
+    /// </summary>
+    /// <param name="pocMappingRepository">The <see cref="IPoCMappingRepository"/> used by the service to access mapping data.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing access to the point-of-care mapping settings.</param>
+    /// <!-- aidoc:v1 sig=3865e0c body=4a11e38 -->
    public PoCMappingService(IPoCMappingRepository pocMappingRepository, IOptions<ApiSettings> apiSettings)
    {
        _pocMappingRepository = pocMappingRepository;
@@ -17,6 +17,20 @@ using MongoDB.Driver;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IPointOfCareService"/> to provide point-of-care business logic that
+/// coordinates persistence, patient, unit, admission, messaging, audit, and caching concerns
+/// through its injected collaborators.
+/// </summary>
+/// <remarks>
+/// The service uses <see cref="IPointOfCareRepository"/> for data access and <see cref="ILogger{T}"/>
+/// for logging. <see cref="IPatientService"/>, <see cref="IUnitService"/>,
+/// <see cref="IClientMessageService"/>, and <see cref="IAdmissionService"/> are resolved lazily
+/// via <see cref="Lazy{T}"/>. Additional collaborators include <see cref="ISubscribersService"/>,
+/// <see cref="ILocalAuditService"/>, <see cref="ICacheService"/>, <see cref="IHttpContextAccessor"/>,
+/// and <see cref="IOptions{TOptions}"/> bound to CacheSettings.
+/// </remarks>
+/// <!-- aidoc:v1 sig=0a9722c -->
 public class PointOfCareService(
    ILogger<PointOfCareService> logger,
    IPointOfCareRepository pointOfCareRepository,
@@ -10,6 +10,13 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IRecordingAlertService"/> to manage recording alerts, coordinating patient lookup, observation configuration, alert persistence, client messaging, subscribers, auditing, and HTTP context access.
+/// </summary>
+/// <remarks>
+/// Uses <see cref="IRecordingAlertRepository"/> and <see cref="IRecordingAlertArchiveRepository"/> for alert persistence, and lazily resolves <see cref="IPatientService"/> through <paramref name="patientService"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=6c23cec -->
 public class RecordingAlertService(
    Lazy<IPatientService> patientService,
    IConfigObservationService configObservationService,
@@ -38,6 +38,21 @@ public class RecordingService : IRecordingService

    private AccessGrant? _accessGrant;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="RecordingService"/> class, resolving configuration options and service dependencies required to coordinate recording operations over HTTP and RabbitMQ.
+    /// </summary>
+    /// <param name="rabbitMqSettings">The RabbitMQ configuration options used to derive the recording queue name from <see cref="RabbitMqSettings.RecordingQueue"/>.</param>
+    /// <param name="recordingSettings">The recording configuration options providing the API URL and HTTP client timeout; must be supplied.</param>
+    /// <param name="logger">The logger used to record diagnostic information.</param>
+    /// <param name="httpClientFactory">The factory used to create the underlying <see cref="HttpClient"/>.</param>
+    /// <param name="publisherService">The service used to publish messages.</param>
+    /// <param name="authService">The authentication service used to obtain access grants.</param>
+    /// <param name="apiSettings">The API configuration options; provides the <see cref="ApiSettings.StartRecordingWithoutPatientNumber"/> flag.</param>
+    /// <param name="clientMessageService">The service used to handle client messages.</param>
+    /// <param name="subscribersService">The service used to manage subscribers.</param>
+    /// <param name="patientService">The lazily resolved patient service used to look up patient information.</param>
+    /// <exception cref="Exception">Thrown when <paramref name="recordingSettings"/> does not provide a value.</exception>
+    /// <!-- aidoc:v1 sig=7f5a5e7 body=7787634 -->
    public RecordingService(IOptions<RabbitMqSettings> rabbitMqSettings,
        IOptions<RecordingSettings> recordingSettings,
        ILogger<RecordingService> logger,
@@ -8,6 +8,13 @@ using MongoDB.Bson;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IServiceConfigService"/>, coordinating service configuration operations by persisting data through <see cref="IServiceConfigRepository"/> and emitting diagnostics via <see cref="ILogger{ServiceConfigService}"/>.
+/// </summary>
+/// <remarks>
+/// The class receives its <see cref="IServiceConfigRepository"/> collaborator and <see cref="ILogger{ServiceConfigService}"/> via the primary constructor parameters <paramref name="serviceConfigRepository"/> and <paramref name="logger"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=8c82e54 -->
 public class ServiceConfigService(
    IServiceConfigRepository serviceConfigRepository,
    ILogger<ServiceConfigService> logger)
@@ -16,6 +16,13 @@ using Serilog;

 namespace adas_core.Application.Services;

+/// <summary>
+/// Implements <see cref="IUnitService"/>, coordinating unit-related operations by persisting data through <see cref="IUnitRepository"/> and integrating with patient, master list, subscriber, client messaging, point-of-care, and auditing services.
+/// </summary>
+/// <remarks>
+/// Collaborators exposed as <see cref="Lazy{T}"/> (<see cref="IPatientService"/> and <see cref="IClientMessageService"/>) are instantiated on demand. The service uses <see cref="ILogger{T}"/> for structured logging, <see cref="IHttpContextAccessor"/> to access the current HTTP context, and <see cref="ILocalAuditService"/> to record audit entries.
+/// </remarks>
+/// <!-- aidoc:v1 sig=690f007 -->
 public class UnitService(
    IUnitRepository unitRepository,
    Lazy<IPatientService> patientService,
@@ -20,6 +20,16 @@ public class WsSubscriberGrouped
 {
    private readonly EventHandler<string> _sendEvent;

+    /// <summary>
+    /// Initializes a new instance of <see cref="WsSubscriberGrouped"/> that registers <paramref name="wsId"/> in the shared WsSubscriber collection and copies the grouping configuration from <paramref name="gf"/>. The constructor also seeds the last-observation state through <see cref="UpdateLastGo"/>, computes the identity hash via <see cref="CryptoAdas.CreateMd5GroupedObs"/>, and starts the internal <see cref="Timer"/> that drives periodic emission through <paramref name="sendEvent"/>.
+    /// </summary>
+    /// <param name="patientId">The <see cref="ObjectId"/> of the patient whose grouped observations this subscriber tracks.</param>
+    /// <param name="wsId">The web socket subscriber identifier added to the shared WsSubscriber list and used as the key in the per-instance group dictionary.</param>
+    /// <param name="timeZoneId">The Windows or IANA time zone identifier applied to the observations; when null, falls back to Romance Standard Time.</param>
+    /// <param name="gf">The <see cref="GroupedField"/> providing the grouping configuration consumed for names, max, since, start time shift, regularity, result, and group key.</param>
+    /// <param name="lastGroupedObservationObs">The most recent <see cref="GroupedObservation"/> passed to <see cref="UpdateLastGo"/> to initialize the last-observation state.</param>
+    /// <param name="sendEvent">The <see cref="EventHandler{String}"/> invoked by the timer to forward outgoing messages to the subscriber.</param>
+    /// <!-- aidoc:v1 sig=16f9dfc body=cc103b1 -->
    public WsSubscriberGrouped(ObjectId patientId, string wsId, string? timeZoneId,
        GroupedField gf, GroupedObservation lastGroupedObservationObs, EventHandler<string> sendEvent)
    {
@@ -82,6 +92,12 @@ public class WsSubscriberGrouped
            }
        }

+    /// <summary>
+    /// Handles the timer elapsed event by stopping the timer, checking whether any cached grouped observation matches the current time at the configured <see cref="GroupedObservationEnum.Regularity"/> granularity (second, minute, day, or hour by default), invoking the send event when no match is found, and restarting the timer.
+    /// </summary>
+    /// <param name="sender">The source of the timer elapsed event.</param>
+    /// <param name="e">The <see cref="System.Timers.ElapsedEventArgs"/> instance containing the elapsed event data.</param>
+    /// <!-- aidoc:v1 sig=168f657 body=7634f8f -->
    private void Timer_Elapsed(object? sender, ElapsedEventArgs e)
    {
        var currentDateTime = DateTime.Now;
@@ -5,6 +5,14 @@ using Microsoft.AspNetCore.Mvc.Filters;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Specifies an authorization filter attribute that restricts access to decorated methods based on a required role of type <see cref="PermissionEnum.RolesType"/>.
+/// Inherits from <see cref="Attribute"/> and implements <see cref="IAuthorizationFilter"/> to participate in the authorization pipeline.
+/// </summary>
+/// <remarks>
+/// Constrained by <see cref="System.AttributeUsageAttribute"/> to <see cref="AttributeTargets.Method"/>, the attribute is configured at construction with the required <paramref name="type"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=b5093e9 -->
 [AttributeUsage(AttributeTargets.Method)]
 public class AuthorizeRolesAttribute(PermissionEnum.RolesType type) : Attribute, IAuthorizationFilter
 {
@@ -4,6 +4,13 @@ using Microsoft.AspNetCore.Mvc.Filters;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Represents an authorization attribute that enforces permission-based access control using the injected <see cref="IUserService"/>.
+/// </summary>
+/// <remarks>
+/// Inherits from <see cref="Attribute"/> and implements <see cref="IAuthorizationFilter"/>, allowing it to be applied to controllers or actions and integrated into the request filtering pipeline.
+/// </remarks>
+/// <!-- aidoc:v1 sig=28ee847 -->
 public class AuthorizePermissionsAttribute(
    IUserService userService)
    : Attribute, IAuthorizationFilter
@@ -9,6 +9,14 @@ using Microsoft.Extensions.DependencyInjection;

 namespace adas_core.Authentication.Attributes;

+/// <summary>
+/// Represents an authorization attribute that evaluates permissions using a configured source and an optional resource identifier header.
+/// </summary>
+/// <remarks>
+/// Extends <see cref="AuthorizeAttribute"/> and implements <see cref="IAsyncAuthorizationFilter"/> to support asynchronous authorization filtering.
+/// The primary constructor parameter <paramref name="source"/> specifies the permission source, while the optional <paramref name="resourceIdHeader"/> identifies the header that carries the resource identifier.
+/// </remarks>
+/// <!-- aidoc:v1 sig=e97022a -->
 public class PermissionAuthorizeAttribute(string source, string? resourceIdHeader = null)
    : AuthorizeAttribute, IAsyncAuthorizationFilter
 {
@@ -8,6 +8,12 @@ using Serilog;

 namespace adas_core.Authentication;

+/// <summary>
+/// Implements <see cref="IAuthorityService"/>, coordinating authority-related operations through
+/// <see cref="IAuthorityRepository"/> for data access, <see cref="IHttpContextAccessor"/> for
+/// HTTP context access, and <see cref="ILocalAuditService"/> for local auditing.
+/// </summary>
+/// <!-- aidoc:v1 sig=5aafd48 -->
 public class AuthorityService(
    IAuthorityRepository authorityRepository,
    IHttpContextAccessor httpContextAccessor,
@@ -6,10 +6,20 @@
 /// <typeparam name="T">The type of the response payload.</typeparam>
 public class UciResponse<T>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UciResponse"/> class with default values.
+    /// This protected parameterless constructor enables the <see cref="UciResponse"/> type to be instantiated by derived classes.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=bc935a2 body=4448e1d -->
    protected UciResponse()
    {
    }

+    /// <summary>
+    /// Initializes a successful instance of the <see cref="UciResponse{T}"/> class, which wraps an entity as a response payload. The constructor assigns <paramref name="entity"/> to <see cref="UciResponse{T}.Data"/>, sets <see cref="UciResponse{T}.Success"/> to <c>true</c>, and clears <see cref="UciResponse{T}.Message"/> and <see cref="UciResponse{T}.Error"/>.
+    /// </summary>
+    /// <param name="entity">The payload to encapsulate in the response, stored in the <see cref="UciResponse{T}.Data"/> property.</param>
+    /// <!-- aidoc:v1 sig=5205995 body=dd7f9e7 -->
    protected UciResponse(T entity)
    {
        Success = true;
@@ -47,6 +47,25 @@ public class UserService : IUserService
    private readonly ISubscribersService _subscribersService;
    private readonly IClientMessageService _clientMessageService;
    private readonly Lazy<IPermissionService> _permissionService;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserService"/> class, capturing the supplied authentication, authorization, user data and logging collaborators for use by subsequent operations.
+    /// </summary>
+    /// <param name="loginServices">The collection of <see cref="ILoginService"/> implementations used to enumerate available login methods.</param>
+    /// <param name="configuration">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.LoginMethods"/> define the supported login methods.</param>
+    /// <param name="validGroups">The <see cref="IOptions{ValidGroupsConfig}"/> wrapper providing the configured valid user groups.</param>
+    /// <param name="usersWhiteList">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.UsersWhiteListConfig"/> supplies the users white list.</param>
+    /// <param name="jwt">The <see cref="IOptions{AuthSettings}"/> wrapper whose <see cref="AuthSettings.JwtConfig"/> supplies the JWT configuration.</param>
+    /// <param name="httpContextAccessor">The <see cref="IHttpContextAccessor"/> used to access the current HTTP context.</param>
+    /// <param name="userRepository">The <see cref="IUserRepository"/> used to read and persist user data.</param>
+    /// <param name="authorityService">The <see cref="IAuthorityService"/> used to perform authority and authorization operations.</param>
+    /// <param name="auditService">The <see cref="ILocalAuditService"/> used to record local audit entries.</param>
+    /// <param name="displayService">A <see cref="Lazy{IDisplayService}"/> wrapper providing deferred access to display services.</param>
+    /// <param name="logger">The <see cref="ILogger{UserService}"/> used to log diagnostics for the <see cref="UserService"/>.</param>
+    /// <param name="subscribersService">The <see cref="ISubscribersService"/> used to manage subscribers.</param>
+    /// <param name="clientMessageService">The <see cref="IClientMessageService"/> used to send messages to clients.</param>
+    /// <param name="permissionService">A <see cref="Lazy{IPermissionService}"/> wrapper providing deferred access to permission checks.</param>
+    /// <exception cref="System.Exception">Thrown when the JWT configuration provided by <paramref name="jwt"/> is not configured.</exception>
+    /// <!-- aidoc:v1 sig=8c3130e body=79f6643 -->
    public UserService(
        IEnumerable<ILoginService> loginServices,
        IOptions<AuthSettings> configuration,
@@ -150,6 +169,13 @@ public class UserService : IUserService
            }
        }

+    /// <summary>
+    /// Retrieves a <see cref="User"/> based on the username extracted from the provided <paramref name="jwtToken"/>.
+    /// Returns <see langword="null"/> when the token is null or the user cannot be found, clears the retrieved user's password before returning, and lazily loads authorization data from the authority service when it is not already populated.
+    /// </summary>
+    /// <param name="jwtToken">The <see cref="JwtSecurityToken"/> containing the user identity claims, or <see langword="null"/> to indicate no token was supplied.</param>
+    /// <returns>A <see cref="Task{User}"/> that resolves to the matching <see cref="User"/> with its password cleared and authorization loaded if required, or <see langword="null"/> when the token is missing or no user matches the extracted username.</returns>
+    /// <!-- aidoc:v1 sig=29f6fec body=a7970c3 -->
    public async Task<User?> GetUserByToken(JwtSecurityToken? jwtToken)
    {
        User? user = null;
@@ -7,10 +7,22 @@ namespace adas_core.Domain.Exceptions;
 /// </summary>
 public class BusinessException : AggregateException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BusinessException"/> class with the supplied <see cref="HttpStatusCode"/> and message, forwarding their combined textual representation to the base exception constructor. <see cref="BusinessException"/> represents errors raised by business logic that are associated with an HTTP status.
+    /// </summary>
+    /// <param name="status">The <see cref="HttpStatusCode"/> that identifies the nature of the business error.</param>
+    /// <param name="message">The descriptive message that provides additional context for the error.</param>
+    /// <!-- aidoc:v1 sig=0825145 body=4448e1d -->
    public BusinessException(HttpStatusCode status, string message) : base($"{status}: {message}")
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="BusinessException"/> class, which represents errors in business logic, by passing the specified error message and inner <see cref="Exception"/> to the base class constructor.
+    /// </summary>
+    /// <param name="message">The error message that describes the reason for the exception.</param>
+    /// <param name="exception">The inner <see cref="Exception"/> that is the cause of the current exception, or <see langword="null"/> if no inner exception is specified.</param>
+    /// <!-- aidoc:v1 sig=cd57c0c body=4448e1d -->
    public BusinessException(string message, Exception exception) : base(message, exception)
    {
    }
@@ -11,11 +11,22 @@ namespace adas_core.Domain.Exceptions;
 /// </remarks>
 public class LoginServicesException : BusinessException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LoginServicesException"/> class with a descriptive error message, forwarding it to the base exception together with an HTTP <see cref="HttpStatusCode.BadRequest"/> status code.
+    /// </summary>
+    /// <param name="message">The error message that describes the login service failure.</param>
+    /// <!-- aidoc:v1 sig=16739ff body=4448e1d -->
    public LoginServicesException(string message) :
        base(HttpStatusCode.BadRequest, $"Login service error: {message}")
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="LoginServicesException"/> class, which represents errors that occur in the login service. The supplied <paramref name="message"/> is prefixed with a service-context note and the underlying <paramref name="exception"/> is preserved as the inner exception.
+    /// </summary>
+    /// <param name="message">The error message describing the login service failure.</param>
+    /// <param name="exception">The inner <see cref="System.Exception"/> that caused the current exception.</param>
+    /// <!-- aidoc:v1 sig=83e8d73 body=4448e1d -->
    public LoginServicesException(string message, Exception exception) : base($"Login service error: {message}",
        exception)
    {
@@ -2,5 +2,12 @@

 namespace adas_core.Domain.Exceptions;

+/// <summary>
+/// Represents the exception that is thrown when no login services are available to handle authentication requests.
+/// </summary>
+/// <remarks>
+/// This exception derives from <see cref="BusinessException"/> and is raised with the <see cref="HttpStatusCode.Forbidden"/> status code and the message "No login services available".
+/// </remarks>
+/// <!-- aidoc:v1 sig=e23ced3 -->
 public class LoginServicesNotFoundException()
    : BusinessException(HttpStatusCode.Forbidden, "No login services available");
@@ -10,11 +10,22 @@ namespace adas_core.Domain.Exceptions;
 /// </remarks>
 public class UserNotFoundException : BusinessException
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserNotFoundException"/> class with a <see cref="HttpStatusCode.NotFound"/> status code and a message identifying the missing <paramref name="username"/>.
+    /// </summary>
+    /// <param name="username">The username of the user that could not be found.</param>
+    /// <!-- aidoc:v1 sig=3e9ae01 body=4448e1d -->
    public UserNotFoundException(string username) :
        base(HttpStatusCode.NotFound, $"USER with username {username} not found")
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserNotFoundException"/> class with the username that could not be found and a wrapped inner <see cref="Exception"/>.
+    /// </summary>
+    /// <param name="username">The username that was not found.</param>
+    /// <param name="exception">The inner <see cref="Exception"/> that caused this exception to be raised.</param>
+    /// <!-- aidoc:v1 sig=2ed5f9f body=4448e1d -->
    public UserNotFoundException(string username, Exception exception) : base(
        $"USER with username {username} not found", exception)
    {
@@ -70,6 +70,10 @@ public class UsersWhiteListConfig : List<string>
 /// <remarks>
 /// This type serves as a container or marker for grouping validation logic within a broader validation framework.
 /// </remarks>
+/// <summary>
+/// Represents a group that has been validated as meeting the required criteria.
+/// </summary>
+/// <!-- aidoc:v1 sig=1cee181 -->
 public class ValidGroupsConfig : List<ValidGroup>
 {
    /// <summary>
@@ -272,6 +272,13 @@ public class PermissionSettings
    );
 }

+/// <summary>
+/// Represents a set of permissions for a source, grouping the unit-level and display-level <see cref="DisplayPermissionTypes"/> together with the corresponding <see cref="PanelPermissionTypes"/>.
+/// </summary>
+/// <remarks>
+/// The primary constructor captures <paramref name="unit"/> and <paramref name="display"/> permissions as <see cref="DisplayPermissionTypes"/>, and <paramref name="panel"/> permissions as <see cref="PanelPermissionTypes"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=74dcf70 -->
 public class SourcePermissions(
    DisplayPermissionTypes unit,
    DisplayPermissionTypes display,
@@ -282,6 +289,13 @@ public class SourcePermissions(
    public PanelPermissionTypes Panel { get; set; } = panel;
 }

+/// <summary>
+/// Encapsulates a collection of <see cref="UserActions"/> that govern the display permissions for clinical and administrative areas such as admissions, discharges, observations, demographic data, box blocking, notices, and cell management.
+/// </summary>
+/// <remarks>
+/// The <paramref name="useDemoMode"/> flag indicates whether the permission configuration should be evaluated in demonstration mode.
+/// </remarks>
+/// <!-- aidoc:v1 sig=5c32eb7 -->
 public class DisplayPermissionTypes(
    UserActions admissions,
    UserActions discharges,
@@ -302,6 +316,13 @@ public class DisplayPermissionTypes(
    public bool UseDemoMode { get; set; } = useDemoMode;
 }

+/// <summary>
+/// Encapsulates the <see cref="UserActions"/> permissions available for each application panel, such as <paramref name="units"/>, <paramref name="patients"/>, and <paramref name="observations"/>, along with the <paramref name="useDemoMode"/> flag.
+/// </summary>
+/// <remarks>
+/// A dedicated <see cref="UserActions"/> value is supplied for every panel — units, displays, display configurations, master lists, treatments, patients, medicines, pumps, users, configuration observations, observations, and audits — so that the access rights for each section can be evaluated independently. The <paramref name="useDemoMode"/> parameter indicates whether the system is operating in demo mode.
+/// </remarks>
+/// <!-- aidoc:v1 sig=3d15620 -->
 public class PanelPermissionTypes(
    UserActions units,
    UserActions displays,
@@ -9,11 +9,21 @@ namespace adas_core.Domain.Models.DTO;
 /// </summary>
 public class UnitInfoDto
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UnitInfoDto"/> data transfer object, enabling JSON deserialization via the <see cref="JsonConstructorAttribute"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=e9065d4 body=4448e1d -->
    [JsonConstructor]
    public UnitInfoDto()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of <see cref="UnitInfoDto"/> from the supplied <paramref name="unit"/>,
+    /// projecting its identifier and name into the DTO with safe empty-string defaults for the display fields.
+    /// </summary>
+    /// <param name="unit">The optional <see cref="Unit"/> whose values populate the DTO; when null, the string properties default to <see cref="string.Empty"/>.</param>
+    /// <!-- aidoc:v1 sig=98aa992 body=1d6ed29 -->
    public UnitInfoDto(Unit? unit)
    {
        Id = unit?.Id;
@@ -2,10 +2,21 @@

 public record PaginationFilter
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PaginationFilter"/> class, which encapsulates the parameters used to paginate query results.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=2ec7383 body=4448e1d -->
    public PaginationFilter()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PaginationFilter"/> class with sanitized pagination values and an optional <see cref="FilteredRequest"/>.
+    /// </summary>
+    /// <param name="pageNumber">The requested page number; values less than 1 are clamped to 1.</param>
+    /// <param name="pageSize">The requested page size; values less than or equal to 0 default to 100.</param>
+    /// <param name="filtered">The optional <see cref="FilteredRequest"/> providing additional filtering criteria.</param>
+    /// <!-- aidoc:v1 sig=9004f63 body=c312b00 -->
    public PaginationFilter(int pageNumber, int pageSize, FilteredRequest? filtered)
    {
        PageNumber = pageNumber < 1 ? 1 : pageNumber;
@@ -10,10 +10,28 @@ namespace adas_core.Domain.Models.GroupedObservations;
 /// </remarks>
 public class GroupedField
 {
+    /// <summary>
+    /// Initializes a new default instance of the <see cref="GroupedField"/> class, representing a field that aggregates related items into a single addressable group.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=703c28d body=4448e1d -->
    public GroupedField()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of <see cref="GroupedField"/>, which represents a configurable field for grouped observations with identifiers, scheduling offsets, and result selection.
+    /// Null collection parameters are normalized to empty lists, and <paramref name="result"/> defaults to a list containing <see cref="GroupedObservationEnum.Result.First"/> when omitted.
+    /// </summary>
+    /// <param name="name">The primary identifier of the field, or null when only the <paramref name="names"/> collection is used.</param>
+    /// <param name="names">The alternative identifiers for the field; when null, an empty <see cref="List{String}"/> is stored.</param>
+    /// <param name="group">The grouping key that associates the field with a logical group, or null if unspecified.</param>
+    /// <param name="startTimeShift">The list of schedule offsets applied to the field; when null, an empty <see cref="List{String}"/> is stored.</param>
+    /// <param name="max">The maximum number of observations retained for the field.</param>
+    /// <param name="regularity">The optional <see cref="GroupedObservationEnum.Regularity"/> that governs how observations are spaced.</param>
+    /// <param name="since">The <see cref="GroupedObservationEnum.Since"/> value that defines the schedule's starting reference.</param>
+    /// <param name="result">The list of <see cref="GroupedObservationEnum.Result"/> values the field should produce; when null, a list containing <see cref="GroupedObservationEnum.Result.First"/> is stored.</param>
+    /// <param name="labelList">The labels associated with the field, or null when no labels are provided.</param>
+    /// <!-- aidoc:v1 sig=8ca95e4 body=4742386 -->
    public GroupedField(
        string? name,
        List<string>? names,
@@ -19,6 +19,13 @@ public class HistoricalLocation : IEquatable<HistoricalLocation>
    public HistoricalLocation() { }

    // Tu constructor actual
+    /// <summary>
+    /// Initializes a new instance of <see cref="HistoricalLocation"/> with the specified admission time and <see cref="PatientLocation"/>, representing a historical record of a patient's location.
+    /// </summary>
+    /// <param name="admTime">The admission time assigned to <see cref="HistoricalLocation.AdmTime"/>.</param>
+    /// <param name="patientLocation">The <see cref="PatientLocation"/> assigned to <see cref="HistoricalLocation.PatientLocation"/>; cannot be <see langword="null"/>.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="patientLocation"/> is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=eaeda50 body=ebde455 -->
    public HistoricalLocation(DateTime admTime, PatientLocation patientLocation)
    {
        AdmTime = admTime;
@@ -22,6 +22,12 @@ public class MasterList
    public LocaleEnum? DefaultLocale { get; set; }
    public List<OptionList> Options { get; set; } = [];

+    /// <summary>
+    /// Returns a copy of this <see cref="MasterList"/> with each option name in <see cref="MasterList.Options"/> localized to the requested <paramref name="localeToReturn"/>, falling back to the original name when no translation is found.
+    /// </summary>
+    /// <param name="localeToReturn">Target <see cref="LocaleEnum"/> used to look up a translated name via reflection on <see cref="OptionList.LocaleItems"/>. When <c>null</c>, the current instance is returned unchanged.</param>
+    /// <returns>A new <see cref="MasterList"/> with localized option names when <paramref name="localeToReturn"/> is provided; otherwise the current instance.</returns>
+    /// <!-- aidoc:v1 sig=803939c body=2054117 -->
    public MasterList ReturnMasterListOptionsInLocaleIfExist(LocaleEnum? localeToReturn)
    {
        if (localeToReturn == null) return this;
@@ -184,6 +184,12 @@ public class SmartDisplay : DisplayConfig
        }

    // TO TEST
+    /// <summary>
+    /// Compares the values of the public properties of <see cref="SmartDisplay"/> between the current instance and <paramref name="other"/>, and returns the names of the properties that differ. The <see cref="SmartDisplay.ColorConfig"/> property is also included when it is not null and not equal to the one in <paramref name="other"/>.
+    /// </summary>
+    /// <param name="other">The <see cref="SmartDisplay"/> instance to compare against; may be null.</param>
+    /// <returns>A <see cref="List{String}"/> containing the names of the properties that have different values between the two instances.</returns>
+    /// <!-- aidoc:v1 sig=5d5d974 body=db6cf7c -->
    public List<string> GetDifferentProperties(SmartDisplay? other)
    {
        // Obtiene las propiedades públicas de la clase SmartDisplay
@@ -858,6 +864,10 @@ public class AxisLabel
 /// <summary>
 /// Represents a line associated with an axis, typically used in charting or graphing scenarios to render or define axis-related visual elements.
 /// </summary>
+/// <summary>
+/// Represents a line associated with an axis, typically used to render or define the visual structure of an axis in a chart or graph.
+/// </summary>
+/// <!-- aidoc:v1 sig=5e39639 -->
 public class AxisLineStyle
 {
    public string? Color { get; set; }
@@ -1030,6 +1040,10 @@ public class Piece
 // /// <summary>
 // /// Represents a candle entity within the system.
 // /// </summary>
+// /// <summary>
+// /// Represents a single <c>candlestick</c> data point, typically used in financial charting to encapsulate price information for a discrete time interval.
+// /// </summary>
+// /// <!-- aidoc:v1 sig=59009c7 -->
 // public class CandlestickSeriesConfig : SeriesConfigBase
 // {
 //     public List<Candle>? CandleKeyList { get; set; }
@@ -7,10 +7,20 @@ namespace adas_core.Domain.Models;
 /// </summary>
 public class ObservatitonRetentionResult
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ObservatitonRetentionResult"/> class, which represents the outcome of an observation retention operation.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=4f5f5d1 body=4448e1d -->
    public ObservatitonRetentionResult()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="ObservatitonRetentionResult"/> class, which represents the outcome of a retention evaluation, by storing the supplied <paramref name="retentionPolicy"/> and its associated <paramref name="retentionPolicyValue"/>.
+    /// </summary>
+    /// <param name="retentionPolicy">The <see cref="RetentionPolicy"/> that was evaluated to produce the result.</param>
+    /// <param name="retentionPolicyValue">The optional numeric value paired with the <paramref name="retentionPolicy"/>, or <see langword="null"/> when no value is required.</param>
+    /// <!-- aidoc:v1 sig=d280e78 body=d032d9b -->
    public ObservatitonRetentionResult(RetentionPolicy retentionPolicy, int? retentionPolicyValue)
    {
        RetentionPolicy = retentionPolicy;
@@ -11,10 +11,20 @@ namespace adas_core.Domain.Models.Observations;
 /// </remarks>
 public class Medication : Observation
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Medication"/> class with default values.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=bb98407 body=4448e1d -->
    public Medication()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="Medication"/> class, which represents medication delivery state, by reading pump-related properties from <paramref name="obj"/> when their MDC codes are present and assigning <paramref name="id"/> to <see cref="Medication.Id"/>.
+    /// </summary>
+    /// <param name="id">The identifier stored in <see cref="Medication.Id"/>.</param>
+    /// <param name="obj">A <see cref="Dictionary{TKey,TValue}"/> of <see cref="PumpElement"/> entries keyed by MDC code, consulted via <see cref="Dictionary{TKey,TValue}.TryGetValue"/>.</param>
+    /// <!-- aidoc:v1 sig=b107edc body=3412539 -->
    public Medication(string id, Dictionary<string, PumpElement> obj)
    {
        if (obj.TryGetValue("MDC_184504", out var mode)) PumpMode = new PumpMode(mode);
@@ -57,10 +67,20 @@ public class Medication : Observation
 /// </summary>
 public class DrugValue
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DrugValue"/> class using default values. The <see cref="DrugValue"/> type represents the value associated with a drug.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=b79012f body=4448e1d -->
    public DrugValue()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="DrugValue"/> class by copying the medication-related values from the specified <see cref="PumpElement"/>.
+    /// This constructor populates the properties <see cref="DrugValue.Id"/>, <see cref="DrugValue.Text"/>, <see cref="DrugValue.Time"/>, <see cref="DrugValue.Units"/>, <see cref="DrugValue.CodingSystem"/>, and <see cref="DrugValue.Result"/> from the source element.
+    /// </summary>
+    /// <param name="pumpElement">The <see cref="PumpElement"/> from which to copy the medication data.</param>
+    /// <!-- aidoc:v1 sig=8c84a69 body=a72ec1a -->
    public DrugValue(PumpElement pumpElement)
    {
        Id = pumpElement.Id;
@@ -101,6 +121,11 @@ public class DrugValue
 /// </remarks>
 public abstract class DrugDoubleValue : DrugValue
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DrugDoubleValue"/> class by forwarding <paramref name="pumpElement"/> to the base constructor and parsing its textual value as a <see cref="double"/> to set the Value property when the conversion succeeds.
+    /// </summary>
+    /// <param name="pumpElement">The <see cref="PumpElement"/> whose string representation is parsed as a <see cref="double"/> to initialize the Value property.</param>
+    /// <!-- aidoc:v1 sig=d14bd75 body=29c2c0d -->
    protected DrugDoubleValue(PumpElement pumpElement) : base(pumpElement)
    {
        if (double.TryParse(pumpElement.Value?.ToString(), out var valueParsed))
@@ -175,6 +200,11 @@ public class Drug(PumpElement pumpElement) : DrugStringValue(pumpElement);
 /// </summary>
 public class PumpMode : DrugStringValue
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PumpMode"/> class by forwarding the supplied <see cref="PumpElement"/> to the base constructor and computing the normalized mode identifier from its raw value. The type represents a pump mode value extracted from a pump element.
+    /// </summary>
+    /// <param name="pumpElement">The source element providing the raw mode text that is normalized to produce the mode identifier.</param>
+    /// <!-- aidoc:v1 sig=97f7b03 body=bdf432f -->
    public PumpMode(PumpElement pumpElement) : base(pumpElement)
    {
        Value = pumpElement.Value?.ToString()?.SubstringAfter("pump-mode-").Replace("-", "_");
@@ -186,6 +216,11 @@ public class PumpMode : DrugStringValue
 /// </summary>
 public class PumpStatus : DrugStringValue
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PumpStatus"/> class from the specified <paramref name="pumpElement"/>, deriving the <see cref="PumpStatus.Value"/> by stripping the "pump-status-" prefix and normalizing dashes to underscores.
+    /// </summary>
+    /// <param name="pumpElement">The <see cref="PumpElement"/> whose value is parsed to populate the status.</param>
+    /// <!-- aidoc:v1 sig=526c2d6 body=d13ab1e -->
    public PumpStatus(PumpElement pumpElement) : base(pumpElement)
    {
        Value = pumpElement.Value?.ToString()?.SubstringAfter("pump-status-").Replace("-", "_");
@@ -6,6 +6,13 @@
 /// </summary>
 public class PatientLocation : IEquatable<PatientLocation>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientLocation"/> class, which represents a patient's location within a care unit, using the specified unit name, bed, and room values.
+    /// </summary>
+    /// <param name="unitName">The name of the care unit assigned to <see cref="PatientLocation.UnitName"/>, or <see langword="null"/>.</param>
+    /// <param name="bed">The bed identifier assigned to <see cref="PatientLocation.Bed"/>, or <see langword="null"/>.</param>
+    /// <param name="room">The room identifier assigned to <see cref="PatientLocation.Room"/>, or <see langword="null"/>.</param>
+    /// <!-- aidoc:v1 sig=401fc97 body=2b1784e -->
    public PatientLocation(string? unitName, string? bed, string? room)
    {
        UnitName = unitName;
@@ -13,6 +20,12 @@ public class PatientLocation : IEquatable<PatientLocation>
        Room = room;
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientLocation"/> class, storing the supplied unit name and bed, and using the bed value as the room identifier.
+    /// </summary>
+    /// <param name="unitName">The unit name to assign to <see cref="PatientLocation.UnitName"/>, or <see langword="null"/> if unspecified.</param>
+    /// <param name="bed">The bed identifier to assign to <see cref="PatientLocation.Bed"/> and <see cref="PatientLocation.Room"/>, or <see langword="null"/> if unspecified.</param>
+    /// <!-- aidoc:v1 sig=44a90e4 body=fbafeea -->
    public PatientLocation(string? unitName, string? bed)
    {
        UnitName = unitName;
@@ -20,6 +33,11 @@ public class PatientLocation : IEquatable<PatientLocation>
        Room = bed;
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientLocation"/> class without performing explicit initialization of its members.
+    /// The <see cref="PatientLocation"/> type represents the location of a patient.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=0911aca body=4448e1d -->
    public PatientLocation()
    {
        // Constructor vacío
@@ -15,10 +15,21 @@ public class PatientObservation : BasePatientObservationValue
 {
    private string? _result;

+    /// <summary>
+    /// Initializes a new default instance of the <see cref="PatientObservation"/> class, which represents a clinical observation recorded for a patient.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=5c55204 body=4448e1d -->
    public PatientObservation()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientObservation"/> class, which represents an observation linked to a patient, with the specified identifier, value, and name.
+    /// </summary>
+    /// <param name="patientId">The <see cref="ObjectId"/> identifying the patient associated with the observation.</param>
+    /// <param name="value">The value recorded for the observation.</param>
+    /// <param name="name">The name of the observation, or <see langword="null"/>.</param>
+    /// <!-- aidoc:v1 sig=6b8c74d body=a32087f -->
    public PatientObservation(ObjectId patientId, object value, string? name)
    {
        PatientId = patientId;
@@ -12,10 +12,20 @@ namespace adas_core.Domain.Models.Responses;
 /// </remarks>
 public class DisplayConfigMinimalResponse
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DisplayConfigMinimalResponse"/> class, which represents a minimal response payload carrying display configuration data.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=722895f body=4448e1d -->
    public DisplayConfigMinimalResponse()
    {
    }

+    /// <summary>
+    /// Initializes a new <see cref="DisplayConfigMinimalResponse"/>, a minimal response view of a display configuration, from the supplied <paramref name="displayConfig"/> and optional <paramref name="isInUse"/> flag.
+    /// </summary>
+    /// <param name="displayConfig">The source <see cref="DisplayConfigSummary"/> whose <see cref="DisplayConfigSummary.Id"/>, <see cref="DisplayConfigSummary.Type"/>, and <see cref="DisplayConfigSummary.Name"/> populate the response.</param>
+    /// <param name="isInUse">The nullable boolean indicating whether the display configuration is in use, stored in <see cref="DisplayConfigMinimalResponse.IsInUse"/>.</param>
+    /// <!-- aidoc:v1 sig=017b17e body=422f274 -->
    public DisplayConfigMinimalResponse(DisplayConfigSummary displayConfig, bool? isInUse = false)
    {
        Id = displayConfig.Id;
@@ -6,6 +6,14 @@
 /// <typeparam name="T">The type of the items contained in the paginated response.</typeparam>
 public class PaginationResponse<T>
 {
+    /// <summary>
+    /// Initializes a new instance of <see cref="PaginationResponse{T}"/> with the supplied page items and pagination metadata, deriving the total page count from <paramref name="totalRecords"/> and <paramref name="pageSize"/>.
+    /// </summary>
+    /// <param name="data">The <see cref="List{T}"/> of items included in the current page.</param>
+    /// <param name="pageNumber">The number of the current page.</param>
+    /// <param name="pageSize">The maximum number of items per page.</param>
+    /// <param name="totalRecords">The total number of records available across all pages.</param>
+    /// <!-- aidoc:v1 sig=bbc53e5 body=c9e44a7 -->
    public PaginationResponse(List<T> data, int pageNumber, int pageSize, long totalRecords)
    {
        PageNumber = pageNumber;
@@ -2,6 +2,10 @@ using adas_core.Domain.Models.MongoModels;

 namespace adas_core.Domain.Models.Responses;

+/// <summary>
+/// Encapsulates the outcome of a <see cref="Patient"/> lookup, bundling the matched <see cref="Patient"/>, the corresponding archived <see cref="Patient"/>, the related <see cref="Admission"/>, and flags that indicate archive status and result availability.
+/// </summary>
+/// <!-- aidoc:v1 sig=461ed22 -->
 public class PatientSearch(
    Patient? patient,
    Patient? archivePatient,
@@ -6,10 +6,19 @@
 /// <typeparam name="T">The type of the payload contained within the response.</typeparam>
 public class Response<T>
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="Response"/> class using default values.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=c192431 body=4448e1d -->
    public Response()
    {
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="Response{T}"/> class representing a successful result, setting <see cref="Response{T}.Succeeded"/> to <c>true</c>, <see cref="Response{T}.Message"/> to an empty string, <see cref="Response{T}.Errors"/> to <c>null</c>, and storing the supplied payload in <see cref="Response{T}.Data"/>.
+    /// </summary>
+    /// <param name="data">The payload to expose through <see cref="Response{T}.Data"/>.</param>
+    /// <!-- aidoc:v1 sig=f4d0833 body=8db513f -->
    public Response(T data)
    {
        Succeeded = true;
@@ -12,11 +12,19 @@ public sealed class AuthUtils
 {
    private LoginResponse _loginResponse = new();

+    /// <summary>
+    /// Static constructor that initializes the static <see cref="AuthUtils.InternalInstance"/> field of the <see cref="AuthUtils"/> class by assigning a new <see cref="AuthUtils"/> instance if it has not already been set.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=b1904e8 body=05a5e0c -->
    static AuthUtils()
    {
        InternalInstance ??= new AuthUtils();
    }

+    /// <summary>
+    /// Initializes a new instance of the <see cref="AuthUtils"/> authentication utility class and stores a self-reference in <see cref="AuthUtils.InternalInstance"/>, allowing callers to retrieve the active instance through that property.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=cfb2f97 body=ec96561 -->
    public AuthUtils()
    {
        InternalInstance = this;
@@ -140,6 +140,13 @@ namespace adas_core.Domain.Utils
        public static string ConfigObservationsAll()
                    => "configObservations:all";

+        /// <summary>
+        /// Returns the cache key and its associated time-to-live (TTL) for caching the complete collection of configuration observations.
+        /// The TTL is resolved by <see cref="CacheKeyTtl.ResolveForEntity"/> using <paramref name="settings"/> and <see cref="CacheEnum.EntityType.ConfigObservations"/>.
+        /// </summary>
+        /// <param name="settings">Optional cache configuration used to resolve the TTL; may be <see langword="null"/>.</param>
+        /// <returns>A tuple containing the cache key and the resolved TTL as a <see cref="Nullable{TimeSpan}"/>.</returns>
+        /// <!-- aidoc:v1 sig=4708037 body=5108bf4 -->
        public static (string Key, TimeSpan? Ttl) ConfigObservationsAllKeyWithTtl(
            CacheSettings? settings)
        {
@@ -11,6 +11,14 @@ namespace adas_core.Domain.Utils;
 public static class CardConfigExtensions
 {
    // Método principal para extraer todos los nombres
+    /// <summary>
+    /// Retrieves all unique observation names defined within the rows and cells of the specified <see cref="CardConfig"/>.
+    /// Returns an empty list when <paramref name="config"/> has no <see cref="CardConfig.Rows"/>, and skips any row whose <c>Cells</c> collection is <see langword="null"/>.
+    /// Observation names are extracted recursively from each cell, with duplicates removed.
+    /// </summary>
+    /// <param name="config">The <see cref="CardConfig"/> whose cell observation names should be collected.</param>
+    /// <returns>A <see cref="List{T}"/> of distinct observation names found across all cells of <paramref name="config"/>, or an empty list if no rows are defined.</returns>
+    /// <!-- aidoc:v1 sig=2538759 body=b24f5d8 -->
    public static List<string> GetAllObservationNames(this CardConfig config)
    {
        if (config.Rows == null) return [];
@@ -28,6 +36,12 @@ public static class CardConfigExtensions
    }

    // Método auxiliar RECURSIVO para extraer nombres de una Cell y sus SubObs
+    /// <summary>
+    /// Extracts observation names from the specified <paramref name="cell"/>, yielding the values in <see cref="Cell.ObservationName"/> when present and recursively collecting names from each <see cref="Cell.SubObs"/>.
+    /// </summary>
+    /// <param name="cell">The <see cref="Cell"/> whose observation names and nested sub-observations are traversed.</param>
+    /// <returns>An <see cref="IEnumerable{String}"/> of observation names from the <paramref name="cell"/> and its sub-observations.</returns>
+    /// <!-- aidoc:v1 sig=0831490 body=43bfafd -->
    private static IEnumerable<string> ExtractObservationNames(Cell cell)
    {
        // 1. Si la Cell tiene ObservationName, devolver esos nombres.
@@ -26,6 +26,14 @@ public partial class ComplexObjectValueTypeSerializer : SerializerBase<object>
    [GeneratedRegex("ObjectId\\((.[a-f0-9]{24}.)\\)")]
        private static partial Regex ObjectIdRegex();

+    /// <summary>
+    /// Deserializes a BSON value into a .NET <see cref="object"/>, handling primitive <see cref="BsonType"/> values directly, marker types (Null, EndOfDocument, Undefined, MinKey, MaxKey) as <c>false</c>, embedded <see cref="BsonDocument"/> instances by resolving the <c>_t</c> type discriminator with legacy namespace normalization (mapping <c>adas-core.Models</c> to <c>adas-core.Domain.Models</c>), and <see cref="BsonArray"/> values as a <see cref="List{T}"/> of the inferred element type after cleaning <c>$oid</c> wrappers from the intermediate JSON.
+    /// </summary>
+    /// <param name="context">The <see cref="BsonDeserializationContext"/> whose <see cref="BsonDeserializationContext.Reader"/> supplies the BSON tokens to read.</param>
+    /// <param name="args">The <see cref="BsonDeserializationArgs"/> carrying additional deserialization configuration.</param>
+    /// <returns>An <see cref="object"/> representing the deserialized value: a primitive returned directly, <c>false</c> for marker types, an instance of the type indicated by the <c>_t</c> field for documents, or a typed <see cref="List{T}"/> for arrays.</returns>
+    /// <exception cref="Exception">Thrown when a <see cref="BsonDocument"/> lacks a <c>_t</c> discriminator or a <c>_v</c> array payload, the referenced <see cref="Type"/> cannot be resolved via <see cref="Type.GetType(string)"/>, the element type of a non-empty <see cref="BsonArray"/> cannot be determined, the current <see cref="BsonType"/> is unhandled, or any inner step via <see cref="JsonConvert.DeserializeObject(string, System.Type, JsonSerializerSettings)"/> fails.</exception>
+    /// <!-- aidoc:v1 sig=b805219 body=fc5d56f -->
    public override object Deserialize(BsonDeserializationContext context, BsonDeserializationArgs args)
    {
        try
@@ -11,6 +11,13 @@ namespace adas_core.Domain.Utils;
 public static class DetailConfigExtension
 {
    // Método principal para iniciar la extracción
+    /// <summary>
+    /// Retrieves all unique observation names defined in the nurse rows of the specified <paramref name="config"/>.
+    /// Returns an empty list when <see cref="CardDetailsConfig.NurseRows"/> is null.
+    /// </summary>
+    /// <param name="config">The <see cref="CardDetailsConfig"/> extension target whose nurse rows are inspected.</param>
+    /// <returns>A <see cref="List{String}"/> containing the distinct observation names extracted from the nurse rows; an empty list when no nurse rows are defined.</returns>
+    /// <!-- aidoc:v1 sig=1a41350 body=9520d6e -->
    public static List<string> GetAllObservationNames(this CardDetailsConfig config)
    {
        if (config.NurseRows == null) return [];
@@ -24,6 +31,12 @@ public static class DetailConfigExtension
    }

    // --- Auxiliar 1: Recorre la anidación de Filas (RowDetailsConfig) ---
+    /// <summary>
+    /// Recursively extracts names from a collection of <see cref="RowDetailsConfig"/> entries, traversing both the <see cref="RowDetailsConfig.Cells"/> and nested <see cref="RowDetailsConfig.Rows"/> of each row.
+    /// </summary>
+    /// <param name="rows">The list of <see cref="RowDetailsConfig"/> instances to process.</param>
+    /// <returns>An <see cref="IEnumerable{T}"/> of <see cref="string"/> containing all names collected from the cells and nested rows.</returns>
+    /// <!-- aidoc:v1 sig=4148c6b body=c6277a5 -->
    private static IEnumerable<string> ExtractNamesFromRows(List<RowDetailsConfig> rows)
    {
        foreach (var row in rows)
@@ -43,6 +56,12 @@ public static class DetailConfigExtension
    }

    // --- Auxiliar 2: Recorre la anidación de Celdas (CellDetails) ---
+    /// <summary>
+    /// Recursively extracts every observation name from a <see cref="CellDetails"/>, yielding names from the current cell as well as from all its nested <see cref="CellDetails.Cells"/>. Null <see cref="CellDetails.ObservationName"/> and null <see cref="CellDetails.Cells"/> collections are safely skipped without yielding any elements.
+    /// </summary>
+    /// <param name="cell">The <see cref="CellDetails"/> whose observation names, including those of its descendant cells, should be collected.</param>
+    /// <returns>A lazily evaluated <see cref="IEnumerable{T}"/> of <see cref="string"/> containing every observation name found in <paramref name="cell"/> and its nested cells.</returns>
+    /// <!-- aidoc:v1 sig=a01fdc1 body=25dff85 -->
    private static IEnumerable<string> ExtractNamesFromCells(CellDetails cell)
    {
        // 1. EXTRAER nombres del nivel actual
@@ -1,5 +1,14 @@
 namespace adas_core.Domain.Utils;

+/// <summary>
+/// Represents a sealed dictionary that inherits from <see cref="Dictionary{TKey,TValue}"/> and provides equality comparison with <see cref="ComparableDictionary{TKey,TValue}"/> instances through <see cref="IEquatable{T}"/>.
+/// </summary>
+/// <typeparam name="TKey">The type of the keys stored in the dictionary, constrained to be non-null.</typeparam>
+/// <typeparam name="TValue">The type of the values stored in the dictionary, constrained to be non-null.</typeparam>
+/// <remarks>
+/// The <see cref="IEquatable{T}"/> implementation targets <see cref="ComparableDictionary{TKey,TValue}"/> rather than the declaring <see cref="EquatableDictionary{TKey,TValue}"/> type, enabling cross-type equality semantics between the two dictionary variants.
+/// </remarks>
+/// <!-- aidoc:v1 sig=c2a0a45 -->
 public sealed class EquatableDictionary<TKey, TValue>
    : Dictionary<TKey, TValue>, IEquatable<ComparableDictionary<TKey, TValue>>
    where TKey : notnull where TValue : notnull
@@ -3,12 +3,24 @@ using System.Reflection;

 namespace adas_core.Domain.Utils;

+/// <summary>
+/// Provides a static mapping utility for instances of the reference type <typeparamref name="T"/>.
+/// </summary>
+/// <typeparam name="T">The reference type that this mapper operates on, constrained to reference types via the <c>class</c> constraint.</typeparam>
+/// <remarks>
+/// As indicated by the <c>where T : class</c> constraint, only reference types can be supplied as the generic argument for <typeparamref name="T"/>.
+/// </remarks>
+/// <!-- aidoc:v1 sig=4a87291 -->
 public static class Mapper<T>
    // We can only use reference types
    where T : class
 {
    private static readonly Dictionary<string, PropertyInfo> PropertyMap;

+    /// <summary>
+    /// Initializes the static <see cref="Mapper{T}.PropertyMap"/> cache used by the mapper to look up <see cref="System.Reflection.PropertyInfo"/> entries for the type parameter T by their lowercased property name.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=ed9693b body=3dc0e55 -->
    static Mapper()
    {
        // At this point we can convert each
@@ -13,6 +13,11 @@ public sealed class MappingUtils : IMappingUtils
    private readonly List<MappingInterventions>? _cccData;
    private bool _isTransformedValue;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="MappingUtils"/> class by loading the CCC mapping interventions from the supplied <see cref="ApiSettings"/> and resetting the transformed-value flag.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{TOptions}"/> wrapper whose <see cref="IOptions{TOptions}.Value"/> provides the <see cref="ApiSettings"/> whose <see cref="ApiSettings.MappingInterventions"/> data is stored in this instance.</param>
+    /// <!-- aidoc:v1 sig=396ced4 body=2be44b9 -->
    public MappingUtils(IOptions<ApiSettings> apiSettings)
    {
        var cccMappingData = apiSettings.Value.MappingInterventions;
@@ -46,6 +51,13 @@ public sealed class MappingUtils : IMappingUtils

        return null; // No se encontro el code
    }*/
+    /// <summary>
+    /// Searches for an entry matching the supplied <paramref name="code"/> within the given <paramref name="category"/> and returns its associated type, name, and group. The <paramref name="code"/> may be a <see cref="double"/> (matched as an exact value or within a numeric range) or a <see cref="string"/> (parsed as a <see cref="double"/> when possible, otherwise compared as text). Returns <see langword="null"/> when no matching entry is found.
+    /// </summary>
+    /// <param name="code">The code to look up. Accepts a <see cref="double"/> for numeric matching and a <see cref="string"/> for text matching or numeric parsing.</param>
+    /// <param name="category">The category used to filter the entries; only entries whose category matches this value are considered.</param>
+    /// <returns>A tuple containing the <c>type</c>, <c>name</c>, and <c>group</c> of the matching entry, or <see langword="null"/> when no match is found.</returns>
+    /// <!-- aidoc:v1 sig=b69e7ef body=e42117e -->
    public (string type, string name, string group)? SearchByCode(object code, string category)
    {
        // esta funcion conviete a double los string que permitan conversion si no se puede los deja como string
@@ -10,6 +10,12 @@ namespace adas_core.Domain.Utils;
 /// </summary>
 public class RelayHelper
 {
+    /// <summary>
+    /// Retrieves the current status of a <see cref="Relay"/> by calling a local REST API endpoint built from its connection parameters, returning <see langword="true"/> when the relay is reported as active and <see langword="false"/> when the response is not <see cref="HttpStatusCode.OK"/>, the payload cannot be converted to a boolean, or any exception is raised during the request.
+    /// </summary>
+    /// <param name="relay">The <see cref="Relay"/> whose status is queried; its <see cref="Relay.RelayNumber"/> is used in the URL path while <see cref="Relay.Driver"/>, <see cref="Relay.Ip"/>, and <see cref="Relay.Port"/> are passed as query parameters.</param>
+    /// <returns><see langword="true"/> if the API responds with <see cref="HttpStatusCode.OK"/> and the response body converts to a boolean value of <see langword="true"/>; otherwise, <see langword="false"/>.</returns>
+    /// <!-- aidoc:v1 sig=0240829 body=a1db00d -->
    public static bool GetRelayStatusFromApiRest(Relay relay)
    {
        UriBuilder builder = new()
@@ -94,6 +100,12 @@ public class RelayHelper
            PowerRelay(relay, builder);
        }

+    /// <summary>
+    /// Sends an HTTP POST request to power a <see cref="Relay"/> through the endpoint described by <paramref name="builder"/>, enriching the query string with the relay's driver, IP address, port, and a fixed channel count of 8. Logs an information message when the response status is not <see cref="HttpStatusCode.OK"/> and logs any exception raised during the call at debug level instead of propagating it.
+    /// </summary>
+    /// <param name="relay">The relay to power, whose <see cref="Relay.Driver"/>, <see cref="Relay.Ip"/> and <see cref="Relay.Port"/> values are written into the request query string.</param>
+    /// <param name="builder">The <see cref="UriBuilder"/> whose query string is populated and whose <see cref="UriBuilder.Uri"/> identifies the target endpoint of the POST request.</param>
+    /// <!-- aidoc:v1 sig=01d6944 body=089ce17 -->
    private static void PowerRelay(Relay relay, UriBuilder builder)
    {
        var query = HttpUtility.ParseQueryString(builder.Query);
@@ -13,12 +13,20 @@ namespace adas_core.Infrastructure.Migrations.MongoMigrations;
 /// </remarks>
 public class U_0_1_0_UpdateDataPatien : Migration
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="U_0_1_0_UpdateDataPatien"/> migration, passing the version <c>10</c> to the base constructor and assigning the Description that explains how person historical identifiers and locations are transformed into date-indexed arrays and merged into patients.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=ccd8376 body=50d3df0 -->
    public U_0_1_0_UpdateDataPatien() : base(10)
    {
        Description =
            "Transforma person.historicalIds y historicalLocations en arrays con fechas y realiza merge sobre patients.";
    }

+    /// <summary>
+    /// Migrates <c>person.historicalIds</c> and <c>historicalLocations</c> fields in the <c>patients</c>, <c>admissions</c>, and <c>archive_patient</c> MongoDB collections from a document representation to an array of objects, converting each key (a date string) into a <c>Date</c> value via <c>$dateFromString</c>. If a field is already an array it is preserved unchanged; otherwise it is reshaped using <c>$objectToArray</c> and <c>$map</c>, and the result is merged back into the same collection with <c>$merge</c>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=2ec5b05 body=7693e10 -->
    public override void Update()
    {
        var collectionPatient = Database.GetCollection<BsonDocument>("patients");
@@ -231,6 +239,10 @@ public class U_0_1_0_UpdateDataPatien : Migration

    // NO usado por MongoMigrations.Core
    // Solo para ejecución manual si hiciera falta
+    /// <summary>
+    /// Reverts a schema migration on the <c>patients</c>, <c>admissions</c>, and <c>archive_patient</c> MongoDB collections by converting array representations of <c>person.historicalIds</c> and <c>historicalLocations</c> back into documents keyed by an ISO-8601 timestamp. When the target fields are already documents they are left unchanged via a <c>$cond</c> guard, and each aggregation result is persisted back to its source collection using <c>$merge</c> with <c>whenMatched: replace</c>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=6a4f4d3 body=e02e3dc -->
    public void Down()
    {
        var collectionPatient = Database.GetCollection<BsonDocument>("patients");
@@ -12,6 +12,10 @@ namespace adas_core.Infrastructure.Migrations.MongoMigrations;
 /// </remarks>
 public class U_0_1_2_UpdatePointOfCareConfig : Migration
 {
+    /// <summary>
+    /// Initializes a new instance of <see cref="U_0_1_2_UpdatePointOfCareConfig"/>, assigning a Description stating that it removes the PointOfCare configuration elements for poc, relay, camera, and beacon while keeping the placeholder for the new model, and passing 12 to the base constructor.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=9495cc3 body=582e2e0 -->
    public U_0_1_2_UpdatePointOfCareConfig() : base(12)
    {
        Description =
@@ -9,12 +9,20 @@ namespace adas_core.Infrastructure.Migrations.MongoMigrations;
 /// </summary>
 public class U_0_1_3_UpdateLanguageBarrier : Migration
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="U_0_1_3_UpdateLanguageBarrier"/> class, passing identifier <c>13</c> to the base constructor and assigning the Description property to describe the removal of poc, relay, camera and beacon configuration elements for the new model.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=5e97941 body=582e2e0 -->
    public U_0_1_3_UpdateLanguageBarrier() : base(13)
    {
        Description =
            "Borra los elementos de configuracion de poc, relay, camera y beacon y deja el place holder del nuevo modelo";
    }

+    /// <summary>
+    /// Converts the <c>languageBarrier</c> field in the <c>patients</c> and <c>admissions</c> collections from a scalar value into a <see cref="MongoDB.Bson.BsonArray"/>, preserving the original value as the first element when it is not null. Documents where the field is already an array are left untouched, and null values are replaced with an empty array.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=2ec5b05 body=932d7f9 -->
    public override void Update()
    {
        string[] collectionsToUpdate = { "patients", "admissions" };
@@ -23,6 +23,13 @@ public class AdmissionRepository : MongoRepository<Admission>, IAdmissionReposit
    private readonly ApiSettings _apiSettings;

    
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AdmissionRepository"/> class, passing the MongoDB database to the base repository and storing the API configuration values used by the repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the <see cref="ApiSettings"/> values required by the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base repository constructor.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=b1a21dd body=d2b18a3 -->
    public AdmissionRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -13,6 +13,12 @@ public class PoCMappingRepository : MongoRepository<PoCMapping>, IPoCMappingRepo
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PoCMappingRepository"/> class, storing the resolved <see cref="ApiSettings"/> and forwarding the supplied <see cref="IMongoDatabase"/> to the base repository to support persistence of PoC mappings.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapper that exposes the application's <see cref="ApiSettings"/>.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> instance passed to the base class to establish the MongoDB connection.</param>
+    /// <!-- aidoc:v1 sig=443b0db body=12fddac -->
    public PoCMappingRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        _apiSettings = apiSettings.Value;
@@ -39,6 +39,12 @@ public class PatientCarePlanRepository : MongoRepository<PatientCarePlan>, IPati

    

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PatientCarePlanRepository"/> class with the supplied API configuration and MongoDB database connection, forwarding the database to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the <see cref="ApiSettings"/> assigned to the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> connection passed to the base class for data access.</param>
+    /// <!-- aidoc:v1 sig=ab4ee14 body=12fddac -->
    public PatientCarePlanRepository(
        IOptions<ApiSettings> apiSettings,
        IMongoDatabase database
@@ -22,6 +22,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of <see cref="PatientRepository"/>, a MongoDB-backed data repository, capturing API configuration from <see cref="IOptions{ApiSettings}"/> and forwarding the <see cref="IMongoDatabase"/> to the base repository constructor.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> whose value supplies the repository's API configuration.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> connection passed to the base class constructor.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=113519f body=d2b18a3 -->
    public PatientRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -279,6 +286,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        }


+    /// <summary>
+    /// Finds a <see cref="Patient"/> by <paramref name="patientNumber"/>, preferring the most recently admitted active patient (one whose <see cref="Patient.DisTime"/> is null) and falling back to the <see cref="Patient"/> record with the most recent non-null <see cref="Patient.DisTime"/> when no active admission exists. Returns null when <paramref name="patientNumber"/> is null, empty, or whitespace, or when no matching record is found.
+    /// </summary>
+    /// <param name="patientNumber">The patient number used to locate the <see cref="Patient"/> record.</param>
+    /// <returns>A <see cref="Task{Patient}"/> that resolves to the matching <see cref="Patient"/>, or null when no record is found.</returns>
+    /// <!-- aidoc:v1 sig=09c89ab body=91862bd -->
    public async Task<Patient?> FindByPatientNumber(string patientNumber)
    {
        if (string.IsNullOrWhiteSpace(patientNumber)) return null;
@@ -305,6 +318,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return patient;
    }

+    /// <summary>
+    /// Searches for a <see cref="Patient"/> by <paramref name="patientNumber"/> whose <see cref="Patient.UnitId"/> differs from <paramref name="unitId"/>, intended to locate a patient identified at a Point of Care but registered in another unit. Returns <c>null</c> when the patient number is blank, when multiple matches are found (since the patient number may be incomplete), or when no match exists; exceptions are logged and also surface as <c>null</c>.
+    /// </summary>
+    /// <param name="patientNumber">The patient number used to look up the <see cref="Patient"/>.</param>
+    /// <param name="unitId">The <see cref="ObjectId"/> of the unit that must be excluded from the match.</param>
+    /// <returns>A <see cref="Task{Patient}"/> resolving to the matching <see cref="Patient"/>, or <c>null</c> when there is no unique match.</returns>
+    /// <!-- aidoc:v1 sig=382b7c8 body=f2b7752 -->
    public async Task<Patient?> SearchByPatientNumberAndDistinctUnit(string patientNumber, ObjectId unitId)
    {
        try
@@ -328,6 +348,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        }
    }

+    /// <summary>
+    /// Retrieves all <see cref="Patient"/> documents that contain at least one procedure considered finished and eligible for archival. A procedure qualifies when its <c>EndDate</c> is not null and the time elapsed since that <c>EndDate</c> exceeds the supplied grace period of <paramref name="archiveProcedureEndDateAfterMinutes"/> minutes relative to the current UTC time.
+    /// </summary>
+    /// <param name="archiveProcedureEndDateAfterMinutes">The grace period, in minutes, added to a procedure's <c>EndDate</c>; the procedure is treated as finished only when the resulting timestamp is earlier than <see cref="DateTime.UtcNow"/>.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> containing the patients matching the finished-procedure criteria, or an empty list when no patient has a procedure whose archival grace period has elapsed.</returns>
+    /// <!-- aidoc:v1 sig=8527a2e body=acd9bfe -->
    public async Task<List<Patient>> FindAllPatientWithFinishedProcedures(int archiveProcedureEndDateAfterMinutes)
    {
        var currentDateTime = DateTime.UtcNow;
@@ -359,6 +385,13 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return patientsWithFinishedProcedures;
    }

+    /// <summary>
+    /// Retrieves all <see cref="Patient"/> records whose tests have finished and whose end date, offset by the specified archive threshold, is earlier than the current UTC time.
+    /// The initial MongoDB filter keeps tests with a non-null EndDate, and the in-memory filter then retains only those whose EndDate plus <paramref name="archiveTestEndDateAfterMinutes"/> minutes is before <see cref="DateTime.UtcNow"/>.
+    /// </summary>
+    /// <param name="archiveTestEndDateAfterMinutes">The number of minutes added to each test's EndDate to determine whether the test is eligible for archival.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> containing the patients whose tests meet the finished and archive criteria.</returns>
+    /// <!-- aidoc:v1 sig=c7d3a85 body=8559f5d -->
    public async Task<List<Patient>> FindAllPatientWithFinishedTests(int archiveTestEndDateAfterMinutes)
    {
        var currentDateTime = DateTime.UtcNow;
@@ -389,6 +422,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return patientsWithFinishedTests;
    }

+    /// <summary>
+    /// Asynchronously retrieves all patients that have at least one finished <see cref="Patient.Treatment"/> whose <see cref="Treatment.EndDate"/> is older than <paramref name="archiveTreatmentEndDateAfterMinutes"/> minutes relative to the current UTC time, using a MongoDB query combined with an in-memory time threshold filter.
+    /// </summary>
+    /// <param name="archiveTreatmentEndDateAfterMinutes">The grace period in minutes that must elapse after a treatment's <see cref="Treatment.EndDate"/> before the patient qualifies for retrieval.</param>
+    /// <returns>A <see cref="Task{List{Patient}}"/> that resolves to the list of <see cref="Patient"/> records whose treatments satisfy the finished-treatment time threshold.</returns>
+    /// <!-- aidoc:v1 sig=6b43cdf body=429c102 -->
    public async Task<List<Patient>> FindAllPatientWithFinishedTreatment(int archiveTreatmentEndDateAfterMinutes)
    {
        var currentDateTime = DateTime.UtcNow;
@@ -414,6 +453,19 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return patientsWithFinishedTreatments;
    }

+    /// <summary>
+    /// Updates a master list option for all patients belonging to the specified <paramref name="unitIds"/>,
+    /// handling <see cref="MasterListType.DiagnosisList"/>, <see cref="MasterListType.DoctorList"/>,
+    /// and <see cref="MasterListType.OriginList"/> cases by updating the relevant fields and auxiliary fields,
+    /// and returning the updated <see cref="Patient"/> documents. If <paramref name="typeName"/> cannot be parsed
+    /// as a <see cref="MasterListType"/> or the type is not implemented, an empty list is returned.
+    /// </summary>
+    /// <param name="unitIds">The collection of unit identifiers used to scope the update to the affected patients.</param>
+    /// <param name="opt">The DTO containing the existing option and the replacement option values to apply.</param>
+    /// <param name="typeName">The textual name of the <see cref="MasterListType"/> that determines which update path is executed.</param>
+    /// <returns>A <see cref="Task{TResult}"/> containing the updated <see cref="List{Patient}"/> documents,
+    /// or an empty list when no update was performed.</returns>
+    /// <!-- aidoc:v1 sig=afe83cc body=25f24cf -->
    public async Task<List<Patient>> UpdateMasterListOption(List<ObjectId> unitIds, UpdateOptionMasterListDto opt,
        string typeName)
    {
@@ -593,6 +645,14 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        }


+    /// <summary>
+    /// Deletes a master list option from <see cref="Patient"/> documents belonging to the specified units, applying the appropriate update logic based on the resolved <see cref="MasterListType"/>. Returns the affected patients for the supported types (<see cref="MasterListType.DiagnosisList"/>, <see cref="MasterListType.DoctorList"/>, and <see cref="MasterListType.OriginList"/>), or an empty collection when <paramref name="typeName"/> cannot be parsed or the type has no handling logic.
+    /// </summary>
+    /// <param name="unitIds">The collection of <see cref="ObjectId"/> values identifying the units whose patients will be affected by the deletion.</param>
+    /// <param name="opt">The <see cref="OptionList"/> option to remove, matched by its <see cref="OptionList.Name"/> (for diagnosis and origin lists) or its <see cref="OptionList.Id"/> (for the doctor list).</param>
+    /// <param name="typeName">The textual name of the master list type, parsed via <see cref="Enum.TryParse{T}"/> with <typeparamref name="T"/> = <see cref="MasterListType"/> to select the update strategy.</param>
+    /// <returns>A <see cref="Task"/> that yields the <see cref="Patient"/> documents modified for the supported <see cref="MasterListType"/> values, or an empty <see cref="List{Patient}"/> when no updates are performed.</returns>
+    /// <!-- aidoc:v1 sig=800d406 body=d26e8f1 -->
    public async Task<IEnumerable<Patient>> DeleteMasterListOption(List<ObjectId> unitIds, OptionList opt,
        string typeName)
    {
@@ -714,6 +774,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return new List<Patient>();
    }

+    /// <summary>
+    /// Finds the <see cref="Patient"/> associated with the specified <see cref="Patient.PatientId"/>, preferring an active admission (no <see cref="Patient.DisTime"/>) sorted by most recent <see cref="Patient.AdmTime"/>, and falling back to the most recently discharged record when no active admission exists.
+    /// </summary>
+    /// <param name="patientId">The identifier of the patient to locate.</param>
+    /// <returns>A <see cref="Patient"/> instance if found; otherwise, <see langword="null"/> when <paramref name="patientId"/> is null, empty, or whitespace, or when no matching record exists.</returns>
+    /// <!-- aidoc:v1 sig=fca9190 body=71f3c84 -->
    public async Task<Patient?> FindByPatientId(string patientId)
    {
        if (string.IsNullOrWhiteSpace(patientId)) return null;
@@ -729,6 +795,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
        return patient;
    }

+    /// <summary>
+    /// Retrieves the most relevant <see cref="Patient"/> record for the specified identifier, prioritizing an active admission (no discharge time) ordered by the latest <see cref="Patient.AdmTime"/>, and falling back to the most recently discharged patient ordered by <see cref="Patient.DisTime"/> when no active admission exists.
+    /// </summary>
+    /// <param name="patientId">The <see cref="ObjectId"/> of the <see cref="Patient"/> to look up.</param>
+    /// <returns>The matching <see cref="Patient"/> if one is found; otherwise, <see langword="null"/>.</returns>
+    /// <!-- aidoc:v1 sig=b9e9549 body=8f9c8ea -->
    public async Task<Patient?> FindByPatientId(ObjectId patientId)
    {
        //Último paciente admitido
@@ -782,6 +854,11 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
            return await result.ToListAsync();
        }

+    /// <summary>
+    /// Asynchronously retrieves all <see cref="Patient"/> records whose associated point of care is not a virtual <see cref="VirtualPointOfCare"/>, by performing a lookup against the <c>pointOfCares</c> collection and excluding any bed whose value matches a virtual point of care.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that resolves to a <see cref="List{Patient}"/> containing the patients located in active (non-virtual) points of care.</returns>
+    /// <!-- aidoc:v1 sig=2479e43 body=f5b7981 -->
    public async Task<List<Patient>> FindInActivePoC()
    {
        var virtualPointOfCareValues = Enum.GetValues(typeof(VirtualPointOfCare)).Cast<VirtualPointOfCare>()
@@ -812,6 +889,12 @@ public class PatientRepository : MongoRepository<Patient>, IPatientRepository
    }


+    /// <summary>
+    /// Asynchronously retrieves the <see cref="Patient"/> records whose associated point of care has a bed value matching one of the <see cref="VirtualPointOfCare"/> enum values.
+    /// The lookup is performed through a MongoDB aggregation pipeline that joins the patients collection with the point of care collection and filters by the <c>pointOfCareInfo.bed</c> field.
+    /// </summary>
+    /// <returns>A <see cref="Task"/> that yields a <see cref="List{Patient}"/> containing the patients linked to a point of care whose bed matches any <see cref="VirtualPointOfCare"/> value.</returns>
+    /// <!-- aidoc:v1 sig=1a67064 body=3dc3451 -->
    public async Task<List<Patient>> FindInInactivePoC()
    {
        var virtualPointOfCareValues = Enum.GetValues(typeof(VirtualPointOfCare)).Cast<VirtualPointOfCare>()
@@ -18,6 +18,13 @@ public class PoCSettingsRepository : MongoRepository<PoCSettings>, IPoCSettingsR
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of <see cref="PoCSettingsRepository"/>, capturing the API configuration from <paramref name="apiSettings"/> and forwarding the MongoDB database to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapping the <see cref="ApiSettings"/> configuration values.</param>
+    /// <param name="database">The <see cref="MongoDB.Driver.IMongoDatabase"/> passed to the base repository for data access.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=6bccd95 body=d2b18a3 -->
    public PoCSettingsRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -20,6 +20,13 @@ public class PointOfCareRepository : MongoRepository<PointOfCare>, IPointOfCareR
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PointOfCareRepository"/> repository, capturing the configured <see cref="ApiSettings"/> and delegating the <see cref="IMongoDatabase"/> to the base class.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing access to the configured <see cref="ApiSettings"/>.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> forwarded to the base constructor.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is <c>null</c>.</exception>
+    /// <!-- aidoc:v1 sig=5b54ed9 body=99d85d9 -->
    public PointOfCareRepository(IOptions<ApiSettings>? apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings != null)
@@ -242,6 +249,14 @@ public class PointOfCareRepository : MongoRepository<PointOfCare>, IPointOfCareR
            }
        }

+    /// <summary>
+    /// Asynchronously finds a <see cref="PointOfCare"/> matching the specified <paramref name="bed"/> and <paramref name="unitId"/>.
+    /// Returns <see langword="null"/> when the bed is null or empty, when no matching document is found, or when an error occurs.
+    /// </summary>
+    /// <param name="bed">The bed identifier to search for. If null or empty, the method returns <see langword="null"/> without querying.</param>
+    /// <param name="unitId">The unit identifier used to filter the <see cref="PointOfCare"/> documents.</param>
+    /// <returns>A task containing the first matching <see cref="PointOfCare"/>, or <see langword="null"/> if no match is found.</returns>
+    /// <!-- aidoc:v1 sig=03d5e9a body=92ba139 -->
    public async Task<PointOfCare?> FindByBedAndUnitId(string? bed, ObjectId unitId)
    {
        try
@@ -386,6 +401,12 @@ public class PointOfCareRepository : MongoRepository<PointOfCare>, IPointOfCareR
                throw;
            }
        }
+    /// <summary>
+    /// Asynchronously counts the <see cref="PointOfCare"/> records associated with the supplied <paramref name="unitId"/>, applying a filter that targets documents whose Bed value corresponds to one of the inactive <see cref="VirtualPointOfCare"/> states such as Pushed, Unknown, Deleted, NoBed, Cancelled, Recovered, UnitData, or Moved.
+    /// </summary>
+    /// <param name="unitId">The identifier of the unit whose associated <see cref="PointOfCare"/> documents are filtered and counted.</param>
+    /// <returns>A <see cref="Task{Int64}"/> representing the asynchronous operation, with the result being the number of matching <see cref="PointOfCare"/> documents.</returns>
+    /// <!-- aidoc:v1 sig=040b525 body=8d8d306 -->
    public async Task<long> CountVirtualsByUnitId(ObjectId unitId)
    {
        try
@@ -680,6 +701,12 @@ public class PointOfCareRepository : MongoRepository<PointOfCare>, IPointOfCareR
        }

    //Deprecated PatientLocation by UnitName
+    /// <summary>
+    /// Asynchronously searches for the first <see cref="PointOfCare"/> matching the supplied <paramref name="patientLocation"/> criteria, combining equality filters for <see cref="PatientLocation.UnitName"/>, <see cref="PatientLocation.Bed"/> and <see cref="PatientLocation.Room"/> when their values are provided; if no criteria are provided an empty filter is used.
+    /// </summary>
+    /// <param name="patientLocation">The <see cref="PatientLocation"/> whose non-empty fields (<see cref="PatientLocation.UnitName"/>, <see cref="PatientLocation.Bed"/>, <see cref="PatientLocation.Room"/>) are used to build the search filters.</param>
+    /// <returns>A <see cref="Task{PointOfCare}"/> that yields the first matching <see cref="PointOfCare"/>, or <see langword="null"/> when no document matches or when an error is caught and logged.</returns>
+    /// <!-- aidoc:v1 sig=ee884e8 body=c1e5afa -->
    public async Task<PointOfCare?> FindByPatientLocation(PatientLocation patientLocation)
    {
        try
@@ -17,6 +17,12 @@ public class PumpAlarmEventRepository : MongoRepository<PumpAlarmEvent>, IPumpAl
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PumpAlarmEventRepository"/> repository, capturing the configured <see cref="ApiSettings"/> from <paramref name="apiSettings"/> and forwarding <paramref name="database"/> to the base repository for persistence operations.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapper that exposes the application's <see cref="ApiSettings"/>.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base constructor and used to perform MongoDB operations.</param>
+    /// <!-- aidoc:v1 sig=cfddddb body=12fddac -->
    public PumpAlarmEventRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database)
        : base(database)
    {
@@ -25,11 +31,20 @@ public class PumpAlarmEventRepository : MongoRepository<PumpAlarmEvent>, IPumpAl

 

+    /// <summary>
+    /// Retrieves the collection name used for pump alarm events, returning the configured value from _apiSettings.PumpAlarmEvent when set, or falling back to the default "pump_alarm_event".
+    /// </summary>
+    /// <returns>The configured pump alarm event collection name, or the default "pump_alarm_event" when no configuration value is available.</returns>
+    /// <!-- aidoc:v1 sig=94e22ff body=9e4a133 -->
    public override string GetCollectionName()
    {
        return _apiSettings.PumpAlarmEvent ?? "pump_alarm_event";
    }

+    /// <summary>
+    /// Creates the MongoDB indexes for the PumpAlarmEvent collection, optimizing the most common query patterns: device lookup with reverse-chronological time ordering, time-only range queries, patient lookup, and device queries filtered by alarm type.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=4955da2 body=fae571b -->
    public override async Task CreateIndexes()
    {
        var indexModels = new List<CreateIndexModel<PumpAlarmEvent>>
@@ -63,6 +78,11 @@ public class PumpAlarmEventRepository : MongoRepository<PumpAlarmEvent>, IPumpAl
    }


+    /// <summary>
+    /// Asynchronously inserts a new <see cref="PumpAlarmEvent"/> document into the underlying MongoDB collection.
+    /// </summary>
+    /// <param name="alarmEvent">The <see cref="PumpAlarmEvent"/> record to persist.</param>
+    /// <!-- aidoc:v1 sig=5de5fec body=d69d42c -->
    public async Task InsertAsync(PumpAlarmEvent alarmEvent)
    {
        await Collection.InsertOneAsync(alarmEvent);
@@ -85,6 +105,12 @@ public class PumpAlarmEventRepository : MongoRepository<PumpAlarmEvent>, IPumpAl
        return await find.ToListAsync();
    }

+    /// <summary>
+    /// Asynchronously retrieves the most recent <see cref="PumpAlarmEvent"/> for the device identified by <paramref name="deviceId"/>, returning the entry with the latest time stamp, or <c>null</c> if no event exists.
+    /// </summary>
+    /// <param name="deviceId">The identifier of the device whose latest alarm event is being retrieved.</param>
+    /// <returns>A <see cref="Task{PumpAlarmEvent}"/> that yields the latest <see cref="PumpAlarmEvent"/> associated with <paramref name="deviceId"/>, or <c>null</c> if no matching event is found.</returns>
+    /// <!-- aidoc:v1 sig=f0fbfb3 body=088b34a -->
    public async Task<PumpAlarmEvent?> FindLastByDeviceIdAsync(string deviceId)
    {
        return await Collection
@@ -93,12 +119,25 @@ public class PumpAlarmEventRepository : MongoRepository<PumpAlarmEvent>, IPumpAl
            .FirstOrDefaultAsync();
    }

+    /// <summary>
+    /// Asynchronously removes all documents linked to the specified patient by deleting every record whose PatientId matches the supplied <paramref name="patientId"/>.
+    /// </summary>
+    /// <param name="patientId">The <see cref="ObjectId"/> of the patient whose associated documents should be deleted.</param>
+    /// <!-- aidoc:v1 sig=4776e51 body=395df12 -->
    public async Task DeleteByPatientId(ObjectId patientId)
    {
        await Collection.DeleteManyAsync(x => x.PatientId == patientId);
    }
        
        
+    /// <summary>
+    /// Asynchronously updates the value of the specified field across multiple <see cref="PumpAlarmEvent"/> documents, replacing occurrences of <paramref name="oldId"/> with <paramref name="newId"/>, and returns the number of documents that were modified.
+    /// </summary>
+    /// <param name="fieldName">The name of the <see cref="MongoDB.Bson.ObjectId"/> field on <see cref="PumpAlarmEvent"/> whose value should be replaced.</param>
+    /// <param name="newId">The new <see cref="MongoDB.Bson.ObjectId"/> value to assign to the field in matching documents.</param>
+    /// <param name="oldId">The existing <see cref="MongoDB.Bson.ObjectId"/> value used to identify documents to be updated.</param>
+    /// <returns>The number of <see cref="PumpAlarmEvent"/> documents modified by the bulk update.</returns>
+    /// <!-- aidoc:v1 sig=207e960 body=64489e6 -->
    public async Task<long> UpdateManyObjectIdByFiledNameAsync(string fieldName, ObjectId newId, ObjectId oldId)
    {
        var filter = Builders<PumpAlarmEvent>.Filter.Eq(fieldName, oldId);
@@ -15,6 +15,12 @@ public class PumpAlarmStateRepository : MongoRepository<PumpAlarmState>, IPumpAl
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="PumpAlarmStateRepository"/> class, which persists pump alarm state data, by storing the resolved <see cref="ApiSettings"/> and delegating MongoDB initialization to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> instance whose <see cref="IOptions{TOptions}.Value"/> supplies the <see cref="ApiSettings"/> used by the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base constructor to provide the underlying MongoDB connection.</param>
+    /// <!-- aidoc:v1 sig=df28b3e body=12fddac -->
    public PumpAlarmStateRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database)
        : base(database)
    {
@@ -32,6 +38,10 @@ public class PumpAlarmStateRepository : MongoRepository<PumpAlarmState>, IPumpAl
            return _apiSettings.PumpAlarmState ?? "pump_alarm_state";
        }

+    /// <summary>
+    /// Creates the MongoDB indexes required by the <see cref="PumpAlarmState"/> collection: a unique compound index on <see cref="PumpAlarmState.DeviceId"/>, <see cref="PumpAlarmState.AlarmType"/>, and <see cref="PumpAlarmState.AlarmCodeMdc"/> (named <c>ux_device_alarm</c>), plus supporting indexes on <see cref="PumpAlarmState.DeviceId"/> and <see cref="PumpAlarmState.PatientId"/>.
+    /// </summary>
+    /// <!-- aidoc:v1 sig=4955da2 body=cfe5f4a -->
    public override async Task CreateIndexes()
    {
        var indexModels = new List<CreateIndexModel<PumpAlarmState>>
@@ -80,6 +90,15 @@ public class PumpAlarmStateRepository : MongoRepository<PumpAlarmState>, IPumpAl
            return await Collection.Find(filter).FirstOrDefaultAsync();
        }

+    /// <summary>
+    /// Inserts or updates an active <see cref="PumpAlarmState"/> document, reusing the identifier of an
+    /// existing record that already matches the same <see cref="PumpAlarmState.DeviceId"/>, <see cref="PumpAlarmState.AlarmType"/>
+    /// and <see cref="PumpAlarmState.AlarmCodeMdc"/> combination, or generating a new <see cref="ObjectId"/> when
+    /// <paramref name="state"/> does not yet carry one.
+    /// </summary>
+    /// <param name="state">The <see cref="PumpAlarmState"/> to persist; its <see cref="PumpAlarmState.Id"/> is
+    /// populated from the matching document when one is found, or newly generated when it is currently <see cref="ObjectId.Empty"/>.</param>
+    /// <!-- aidoc:v1 sig=9119854 body=4bd6c92 -->
    public async Task UpsertActiveAsync(PumpAlarmState state)
    {
        var filter =
@@ -19,6 +19,12 @@ namespace adas_core.Infrastructure.Repositories
    {
        private readonly ApiSettings _apiSettings;

+        /// <summary>
+        /// Initializes a new instance of the <see cref="PumpArchiveRepository"/> class, forwarding <paramref name="database"/> to the base repository and storing the resolved <see cref="ApiSettings"/> configuration for subsequent operations.
+        /// </summary>
+        /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapper whose <see cref="IOptions{T}.Value"/> supplies the current <see cref="ApiSettings"/>.</param>
+        /// <param name="database">The <see cref="IMongoDatabase"/> connection passed to the base class constructor.</param>
+        /// <!-- aidoc:v1 sig=875c7ca body=12fddac -->
        public PumpArchiveRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database)
            : base(database)
        {
@@ -26,12 +32,21 @@ namespace adas_core.Infrastructure.Repositories
        }


+        /// <summary>
+        /// Returns the agreed MongoDB collection name used to store archived pump observations for patients, falling back to the default value when the corresponding setting is not configured.
+        /// </summary>
+        /// <returns>The collection name to use, either the value configured in <c>ArchivePatientsPumpobservations</c> or the default <c>archive_pumpobservations</c>.</returns>
+        /// <!-- aidoc:v1 sig=94e22ff body=09ed313 -->
        public override string GetCollectionName()
        {
            // Nombre de colección pactado: "archive_pumpobservations"
            return _apiSettings.ArchivePatientsPumpobservations ?? "archive_pumpobservations";
        }

+        /// <summary>
+        /// Creates the MongoDB indexes required by the <see cref="PumpObservation"/> collection: an ascending index on <see cref="PumpObservation.PatientId"/> for patient-based lookups and audits, a compound index on <see cref="PumpObservation.DeviceId"/> (ascending) and <see cref="PumpObservation.Time"/> (descending) for per-device timelines, and a descending index on <see cref="PumpObservation.Time"/> for chronological ordering.
+        /// </summary>
+        /// <!-- aidoc:v1 sig=4955da2 body=2c1d18d -->
        public override async Task CreateIndexes()
        {
            var indexModels = new List<CreateIndexModel<PumpObservation>>
@@ -23,6 +23,12 @@ namespace adas_core.Infrastructure.Repositories

     

+        /// <summary>
+        /// Initializes a new instance of the <see cref="PumpObservationRepository"/> class, capturing the <see cref="ApiSettings"/> configuration and forwarding the <see cref="IMongoDatabase"/> to the base repository to back pump observation data.
+        /// </summary>
+        /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing API configuration values assigned to the repository.</param>
+        /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class to supply the MongoDB connection.</param>
+        /// <!-- aidoc:v1 sig=8a1d3fa body=12fddac -->
        public PumpObservationRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
        {
            _apiSettings = apiSettings.Value;
@@ -37,6 +43,10 @@ namespace adas_core.Infrastructure.Repositories
                    return _apiSettings.PumpObservations ?? "pump_observations";
                }

+        /// <summary>
+        /// Creates the MongoDB indexes for the <see cref="PumpObservation"/> collection, defining a compound index on <see cref="PumpObservation.DeviceId"/> (ascending) and <see cref="PumpObservation.Time"/> (descending) to optimize per-pump timeline queries and a single-field index on <see cref="PumpObservation.PatientId"/> for patient-scoped lookups. A commented TTL index on <see cref="PumpObservation.Time"/> is included as a reference for enabling direct MongoDB retention when needed.
+        /// </summary>
+        /// <!-- aidoc:v1 sig=4955da2 body=e820feb -->
        public override async Task CreateIndexes()
        {
            var indexModels = new List<CreateIndexModel<PumpObservation>>
@@ -149,6 +159,12 @@ namespace adas_core.Infrastructure.Repositories
                    return await query.ToListAsync();
                }
        
+        /// <summary>
+        /// Asynchronously retrieves the most recent observation time for every patient that has at least one observation with a non-null patient identifier, by running a MongoDB aggregation that groups observations by patient and selects the maximum time per group.
+        /// Documents whose grouped identifier is not an <see cref="ObjectId"/> or whose maximum time is not a valid <see cref="DateTime"/> are skipped from the result, and the remaining timestamps are normalized to UTC.
+        /// </summary>
+        /// <returns>A <see cref="Task{Dictionary}"/> that yields a dictionary keyed by the patient's <see cref="ObjectId"/> with the latest observation <see cref="DateTime"/> as the value.</returns>
+        /// <!-- aidoc:v1 sig=9cf32b6 body=db998dd -->
        public async Task<Dictionary<ObjectId, DateTime>> FindAllLastPatientObservationTimeAsync()
        {
            // Pipeline:
@@ -321,6 +337,14 @@ namespace adas_core.Infrastructure.Repositories
                }


+        /// <summary>
+        /// Deletes older <see cref="PumpObservation"/> entries for the specified <paramref name="name"/>, keeping only the <paramref name="maxCount"/> most recent records ordered by <see cref="PumpObservation.Time"/>.
+        /// Returns <c>0</c> when <paramref name="name"/> is null or whitespace, when the existing count does not exceed <paramref name="maxCount"/>, or when there is nothing left to delete after skipping the most recent items.
+        /// </summary>
+        /// <param name="name">Name used to filter the <see cref="PumpObservation"/> documents to be considered for deletion.</param>
+        /// <param name="maxCount">Maximum number of most recent <see cref="PumpObservation"/> entries to retain; any additional older entries will be removed.</param>
+        /// <returns>The number of <see cref="PumpObservation"/> documents deleted, or <c>0</c> when no deletion was required.</returns>
+        /// <!-- aidoc:v1 sig=ae5008a body=6960e61 -->
        public async Task<long> DeleteOlderNumberAsync(string name, int maxCount)
        {
            if (string.IsNullOrWhiteSpace(name))
@@ -15,6 +15,12 @@ namespace adas_core.Infrastructure.Repositories
    {
        private readonly ApiSettings _apiSettings;

+        /// <summary>
+        /// Initializes a new instance of <see cref="PumpStateRepository"/>, storing the resolved <see cref="ApiSettings"/> from <paramref name="apiSettings"/> and passing the <see cref="IMongoDatabase"/> to the base class constructor.
+        /// </summary>
+        /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the <see cref="ApiSettings"/> configuration values used by the repository.</param>
+        /// <param name="database">The <see cref="IMongoDatabase"/> forwarded to the base class to establish the underlying data connection.</param>
+        /// <!-- aidoc:v1 sig=48961b9 body=12fddac -->
        public PumpStateRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database)
            : base(database)
        {
@@ -31,6 +37,10 @@ namespace adas_core.Infrastructure.Repositories
                    return _apiSettings.PumpStates ?? "pump_states";
                }

+        /// <summary>
+        /// Creates the MongoDB indexes required by the <see cref="PumpState"/> collection, including a unique index on <see cref="PumpState.DeviceId"/>, a compound index on <see cref="PumpState.DeviceId"/> and <see cref="PumpState.LastUpdated"/> for time-based queries, and an index on <see cref="PumpState.PatientId"/> for patient-scoped lookups.
+        /// </summary>
+        /// <!-- aidoc:v1 sig=4955da2 body=fd5fa60 -->
        public override async Task CreateIndexes()
        {
            var indexModels = new List<CreateIndexModel<PumpState>>
@@ -14,6 +14,13 @@ public class RecordingAlertArchiveRepository : MongoRepository<PatientRecordingA
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="RecordingAlertArchiveRepository"/> class, which provides repository access to recording alert archive data, by storing the resolved <see cref="ApiSettings"/> configuration and forwarding the supplied <see cref="IMongoDatabase"/> to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> containing the API configuration values assigned to the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class for persistence operations.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=63386fa body=d2b18a3 -->
    public RecordingAlertArchiveRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -18,6 +18,13 @@ public class RecordingAlertRepository : MongoRepository<PatientRecordingAlert>,
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="RecordingAlertRepository"/> class, capturing the API configuration and forwarding the MongoDB database to the base repository to support recording-alert persistence operations.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing access to the <see cref="ApiSettings"/> values.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class constructor.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=a457f4a body=d2b18a3 -->
    public RecordingAlertRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -23,6 +23,12 @@ public class RelayRepository : MongoRepository<Relay>, IRelayRepository
    
  

+    /// <summary>
+    /// Initializes a new instance of the <see cref="RelayRepository"/> class, a MongoDB-backed repository that depends on <see cref="ApiSettings"/>. It forwards the <paramref name="database"/> to the base constructor and stores the configuration obtained from <paramref name="apiSettings"/>.
+    /// </summary>
+    /// <param name="database">The <see cref="IMongoDatabase"/> instance passed to the base class.</param>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapper supplying the active <see cref="ApiSettings"/> configuration.</param>
+    /// <!-- aidoc:v1 sig=f9dbbda body=12fddac -->
    public RelayRepository(IMongoDatabase database, IOptions<ApiSettings> apiSettings) : base(database)
    {
        _apiSettings = apiSettings.Value;
@@ -18,6 +18,13 @@ public class SectionRepository : MongoRepository<Section>, ISectionRepository
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="SectionRepository"/> class, capturing the configured <see cref="ApiSettings"/> and forwarding the <see cref="IMongoDatabase"/> to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the resolved <see cref="ApiSettings"/> used by the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base constructor to enable MongoDB data access.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=02bfd10 body=d2b18a3 -->
    public SectionRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -14,6 +14,13 @@ public class ServiceConfigRepository : MongoRepository<ServiceConfig>, IServiceC
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="ServiceConfigRepository"/> class, capturing the <see cref="ApiSettings"/> from the supplied <see cref="IOptions{ApiSettings}"/> and forwarding the <paramref name="database"/> to the base repository for MongoDB-backed operations.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing access to the API configuration.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is <c>null</c>.</exception>
+    /// <!-- aidoc:v1 sig=e674d73 body=d2b18a3 -->
    public ServiceConfigRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -15,6 +15,13 @@ public class TreatmentArchiveRepository : MongoRepository<PatientTreatment>, ITr
 {
    private readonly ApiSettings _apiSettings;

+    /// <summary>
+    /// Initializes a new instance of the <see cref="TreatmentArchiveRepository"/> class, which manages treatment archive records persisted in MongoDB. The constructor stores the API settings and forwards the <see cref="IMongoDatabase"/> connection to the base repository.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> wrapper exposing the application API settings required by the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> instance passed to the base constructor to provide the storage context.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is <see langword="null"/>.</exception>
+    /// <!-- aidoc:v1 sig=cb353ae body=d2b18a3 -->
    public TreatmentArchiveRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -19,6 +19,13 @@ public class TreatmentRepository : MongoRepository<PatientTreatment>, ITreatment
    private readonly ApiSettings _apiSettings;


+    /// <summary>
+    /// Initializes a new instance of the <see cref="TreatmentRepository"/> class by forwarding the <paramref name="database"/> to the base constructor and caching the <see cref="ApiSettings"/> resolved from <paramref name="apiSettings"/>.
+    /// </summary>
+    /// <param name="apiSettings">The <see cref="IOptions{ApiSettings}"/> providing the <see cref="ApiSettings"/> instance stored by the repository.</param>
+    /// <param name="database">The <see cref="IMongoDatabase"/> passed to the base class for MongoDB access.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="apiSettings"/> is null.</exception>
+    /// <!-- aidoc:v1 sig=3b30d15 body=d2b18a3 -->
    public TreatmentRepository(IOptions<ApiSettings> apiSettings, IMongoDatabase database) : base(database)
    {
        if (apiSettings == null) throw new ArgumentNullException(nameof(apiSettings));
@@ -203,6 +210,12 @@ public class TreatmentRepository : MongoRepository<PatientTreatment>, ITreatment
            return result.ToEnumerable();
        }

+    /// <summary>
+    /// Retrieves a paginated, filterable query of <see cref="PatientTreatment"/> records sorted by <see cref="PatientTreatment.OrderTime"/> in descending order. When <paramref name="filter"/> carries a <c>FilteredRequest</c>, the query is narrowed by <see cref="PatientTreatment.PatientId"/>, an optional date range, and the active-treatments flag; otherwise default time-based filters are applied.
+    /// </summary>
+    /// <param name="filter">The pagination and search criteria used to build the MongoDB filter pipeline.</param>
+    /// <returns>An <see cref="IFindFluent{TSource, TDocument}"/> of <see cref="PatientTreatment"/> that can be paged or iterated.</returns>
+    /// <!-- aidoc:v1 sig=4a06ded body=ea0fa2f -->
    public IFindFluent<PatientTreatment, PatientTreatment> GetPaginatedTreatments(PaginationFilter filter)
    {
        var filterBuilder = Builders<PatientTreatment>.Filter;
--- a/Show More
+++ b/Show More