add xmldoc comments

web/backend/Infrastructure/Infrastructure.Repository/Auth/AuthRepository.cs

@@ -6,10 +6,34 @@ using Microsoft.Data.SqlClient;
 
 namespace Infrastructure.Repository.Auth;
 
+/// <summary>
+/// ADO.NET-based implementation of <see cref="IAuthRepository"/> backed by SQL Server stored procedures,
+/// handling user registration, credential lookup/rotation, and account verification.
+/// </summary>
+/// <param name="connectionFactory">The factory used to create database connections.</param>
 public class AuthRepository(ISqlConnectionFactory connectionFactory)
     : Repository<Domain.Entities.UserAccount>(connectionFactory),
         IAuthRepository
 {
+    /// <summary>
+    /// Registers a new user account and initial credential using the <c>USP_RegisterUser</c> stored
+    /// procedure, then fetches and returns the newly created user.
+    /// </summary>
+    /// <remarks>
+    /// The stored procedure's scalar result (expected to be the new user's ID) is parsed defensively:
+    /// it may be returned as a <see cref="Guid"/>, a parseable <see cref="string"/>, or a 16-byte array.
+    /// If the result cannot be interpreted, <see cref="Guid.Empty"/> is used, which will cause the
+    /// subsequent lookup to fail.
+    /// </remarks>
+    /// <param name="username">Unique username for the user</param>
+    /// <param name="firstName">User's first name</param>
+    /// <param name="lastName">User's last name</param>
+    /// <param name="email">User's email address</param>
+    /// <param name="dateOfBirth">User's date of birth</param>
+    /// <param name="passwordHash">Hashed password</param>
+    /// <returns>The newly created UserAccount with generated ID</returns>
+    /// <exception cref="Exception">Thrown when the newly registered user cannot be retrieved after registration.</exception>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount> RegisterUserAsync(
         string username,
         string firstName,
@@ -68,6 +92,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await GetUserByIdAsync(userAccountId) ?? throw new Exception("Failed to retrieve newly registered user.");
     }
 
+    /// <summary>
+    /// Retrieves a user account by email address (typically used for login) using the
+    /// <c>usp_GetUserAccountByEmail</c> stored procedure.
+    /// </summary>
+    /// <param name="email">Email address to search for</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByEmailAsync(
         string email
     )
@@ -83,6 +114,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves a user account by username (typically used for login) using the
+    /// <c>usp_GetUserAccountByUsername</c> stored procedure.
+    /// </summary>
+    /// <param name="username">Username to search for</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByUsernameAsync(
         string username
     )
@@ -98,6 +136,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves the active (non-revoked) credential for a user account using the
+    /// <c>USP_GetActiveUserCredentialByUserAccountId</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>Active UserCredential if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<UserCredential?> GetActiveCredentialByUserAccountIdAsync(
         Guid userAccountId
     )
@@ -113,6 +158,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToCredentialEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Rotates a user's credential by invalidating all existing credentials and creating a new one,
+    /// using the <c>USP_RotateUserCredential</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <param name="newPasswordHash">New hashed password</param>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task RotateCredentialAsync(
         Guid userAccountId,
         string newPasswordHash
@@ -129,6 +181,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         await command.ExecuteNonQueryAsync();
     }
 
+    /// <summary>
+    /// Retrieves a user account by ID using the <c>usp_GetUserAccountById</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>UserAccount if found, null otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetUserByIdAsync(
         Guid userAccountId
     )
@@ -144,6 +202,15 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Marks a user account as confirmed by creating a verification record via the
+    /// <c>USP_CreateUserVerification</c> stored procedure. If the user is already verified, this is a
+    /// no-op and the existing user is returned (idempotent). If a concurrent request verifies the user
+    /// first, the resulting duplicate-key SQL exception (error 2601/2627) is swallowed.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account to confirm</param>
+    /// <returns>The confirmed <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if the user account does not exist.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails for a reason other than a duplicate verification record.</exception>
     public async Task<Domain.Entities.UserAccount?> ConfirmUserAccountAsync(
         Guid userAccountId
     )
@@ -180,6 +247,13 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return await GetUserByIdAsync(userAccountId);
     }
 
+    /// <summary>
+    /// Checks whether a user account has been verified by querying the
+    /// <c>dbo.UserVerification</c> table for a matching record.
+    /// </summary>
+    /// <param name="userAccountId">ID of the user account</param>
+    /// <returns>True if the user has a verification record, false otherwise</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<bool> IsUserVerifiedAsync(Guid userAccountId)
     {
         await using var connection = await CreateConnection();
@@ -194,6 +268,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
         return result != null && result != DBNull.Value;
     }
 
+    /// <summary>
+    /// Determines whether a <see cref="SqlException"/> represents a duplicate key violation
+    /// (SQL Server error 2601 or 2627), used to detect a concurrent duplicate verification insert.
+    /// </summary>
+    /// <param name="ex">The SQL exception to inspect.</param>
+    /// <returns>True if the exception represents a duplicate key violation, false otherwise.</returns>
     private static bool IsDuplicateVerificationViolation(SqlException ex)
     {
         // 2601/2627 are duplicate key violations in SQL Server.
@@ -204,6 +284,8 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     /// <summary>
     /// Maps a data reader row to a UserAccount entity.
     /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="Domain.Entities.UserAccount"/> instance.</returns>
     protected override Domain.Entities.UserAccount MapToEntity(
         DbDataReader reader
     )
@@ -227,8 +309,11 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     }
 
     /// <summary>
-    /// Maps a data reader row to a UserCredential entity.
+    /// Maps a data reader row to a UserCredential entity. The <c>Timer</c> column is mapped only if
+    /// present in the reader's schema, allowing this method to support result sets that omit it.
     /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="UserCredential"/> instance.</returns>
     private static UserCredential MapToCredentialEntity(DbDataReader reader)
     {
         var entity = new UserCredential
@@ -265,8 +350,12 @@ public class AuthRepository(ISqlConnectionFactory connectionFactory)
     }
 
     /// <summary>
-    /// Helper method to add a parameter to a database command.
+    /// Helper method to add a parameter to a database command, converting <c>null</c> values to
+    /// <see cref="DBNull.Value"/>.
     /// </summary>
+    /// <param name="command">The command to add the parameter to.</param>
+    /// <param name="name">The parameter name (including any prefix, e.g. "@Username").</param>
+    /// <param name="value">The parameter value, or <c>null</c> to bind <see cref="DBNull.Value"/>.</param>
     private static void AddParameter(
         DbCommand command,
         string name,

web/backend/Infrastructure/Infrastructure.Repository/Auth/IAuthRepository.cs

@@ -65,8 +65,7 @@ public interface IAuthRepository
     /// Marks a user account as confirmed.
     /// </summary>
     /// <param name="userAccountId">ID of the user account to confirm</param>
-    /// <returns>The confirmed UserAccount entity</returns>
-    /// <exception cref="UnauthorizedException">If user account not found</exception>
+    /// <returns>The confirmed UserAccount entity, or null if the user account does not exist</returns>
     Task<Domain.Entities.UserAccount?> ConfirmUserAccountAsync(Guid userAccountId);
 
     /// <summary>

web/backend/Infrastructure/Infrastructure.Repository/Breweries/BreweryRepository.cs

@@ -4,11 +4,22 @@ using Infrastructure.Repository.Sql;
 
 namespace Infrastructure.Repository.Breweries;
 
+/// <summary>
+/// ADO.NET-based implementation of <see cref="IBreweryRepository"/> backed by SQL Server stored
+/// procedures.
+/// </summary>
+/// <param name="connectionFactory">The factory used to create database connections.</param>
 public class BreweryRepository(ISqlConnectionFactory connectionFactory)
     : Repository<BreweryPost>(connectionFactory), IBreweryRepository
 {
     private readonly ISqlConnectionFactory _connectionFactory = connectionFactory;
 
+    /// <summary>
+    /// Retrieves a brewery post by ID using the <c>USP_GetBreweryById</c> stored procedure.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post.</param>
+    /// <returns>The matching <see cref="BreweryPost"/>, or <c>null</c> if not found.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<BreweryPost?> GetByIdAsync(Guid id)
     {
         await using var connection = await CreateConnection();
@@ -26,21 +37,44 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         return null;
     }
 
+    /// <summary>
+    /// Not yet implemented.
+    /// </summary>
+    /// <param name="limit">The maximum number of records to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of records to skip, or <c>null</c> for no offset.</param>
+    /// <returns>Never returns; always throws.</returns>
+    /// <exception cref="NotImplementedException">Always thrown.</exception>
     public Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset)
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Not yet implemented.
+    /// </summary>
+    /// <param name="brewery">The brewery post containing updated values.</param>
+    /// <exception cref="NotImplementedException">Always thrown.</exception>
     public Task UpdateAsync(BreweryPost brewery)
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Not yet implemented.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post to delete.</param>
+    /// <exception cref="NotImplementedException">Always thrown.</exception>
     public Task DeleteAsync(Guid id)
     {
         throw new NotImplementedException();
     }
 
+    /// <summary>
+    /// Creates a new brewery post and its location using the <c>USP_CreateBrewery</c> stored procedure.
+    /// </summary>
+    /// <param name="brewery">The brewery post to create. Must have a non-null <c>Location</c>.</param>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="brewery"/>.<c>Location</c> is <c>null</c>.</exception>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task CreateAsync(BreweryPost brewery)
     {
         await using var connection = await CreateConnection();
@@ -66,6 +100,13 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
 
     }
 
+    /// <summary>
+    /// Maps the current row of a data reader to a <see cref="BreweryPost"/> entity, including its
+    /// rowversion <c>Timer</c> field and, if location columns are present in the result set, its
+    /// associated <see cref="BreweryPostLocation"/>.
+    /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="BreweryPost"/> instance.</returns>
     protected override BreweryPost MapToEntity(DbDataReader reader)
     {
         var brewery = new BreweryPost();
@@ -133,6 +174,13 @@ public class BreweryRepository(ISqlConnectionFactory connectionFactory)
         return brewery;
     }
 
+    /// <summary>
+    /// Helper method to add a parameter to a database command, converting <c>null</c> values to
+    /// <see cref="DBNull.Value"/>.
+    /// </summary>
+    /// <param name="command">The command to add the parameter to.</param>
+    /// <param name="name">The parameter name (including any prefix, e.g. "@BreweryName").</param>
+    /// <param name="value">The parameter value, or <c>null</c> to bind <see cref="DBNull.Value"/>.</param>
     private static void AddParameter(
         DbCommand command,
         string name,

web/backend/Infrastructure/Infrastructure.Repository/Breweries/IBreweryRepository.cs

@@ -2,11 +2,42 @@ using Domain.Entities;
 
 namespace Infrastructure.Repository.Breweries;
 
+/// <summary>
+/// Repository for CRUD operations on brewery post records.
+/// </summary>
 public interface IBreweryRepository
 {
+    /// <summary>
+    /// Retrieves a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post.</param>
+    /// <returns>The matching <see cref="BreweryPost"/>, or <c>null</c> if not found.</returns>
     Task<BreweryPost?> GetByIdAsync(Guid id);
+
+    /// <summary>
+    /// Retrieves all brewery posts, optionally paginated.
+    /// </summary>
+    /// <param name="limit">The maximum number of records to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of records to skip, or <c>null</c> for no offset.</param>
+    /// <returns>The collection of matching <see cref="BreweryPost"/> records.</returns>
     Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset);
+
+    /// <summary>
+    /// Updates an existing brewery post.
+    /// </summary>
+    /// <param name="brewery">The brewery post containing updated values.</param>
     Task UpdateAsync(BreweryPost brewery);
+
+    /// <summary>
+    /// Deletes a brewery post by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the brewery post to delete.</param>
     Task DeleteAsync(Guid id);
+
+    /// <summary>
+    /// Creates a new brewery post, including its location details.
+    /// </summary>
+    /// <param name="brewery">The brewery post to create. Must have a non-null <c>Location</c>.</param>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="brewery"/> has no <c>Location</c>.</exception>
     Task CreateAsync(BreweryPost brewery);
 }

web/backend/Infrastructure/Infrastructure.Repository/Repository.cs

@@ -3,9 +3,20 @@ using Infrastructure.Repository.Sql;
 
 namespace Infrastructure.Repository;
 
+/// <summary>
+/// Base class for ADO.NET-based repositories, providing shared connection creation and
+/// entity-mapping infrastructure for derived repository implementations.
+/// </summary>
+/// <typeparam name="T">The entity type managed by the repository.</typeparam>
+/// <param name="connectionFactory">The factory used to create database connections.</param>
 public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
     where T : class
 {
+    /// <summary>
+    /// Creates and opens a new database connection using the configured <see cref="ISqlConnectionFactory"/>.
+    /// </summary>
+    /// <returns>An open <see cref="DbConnection"/> ready for use.</returns>
+    /// <exception cref="DbException">Thrown when the connection cannot be opened.</exception>
     protected async Task<DbConnection> CreateConnection()
     {
         var connection = connectionFactory.CreateConnection();
@@ -13,5 +24,10 @@ public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
         return connection;
     }
 
+    /// <summary>
+    /// Maps the current row of a data reader to an instance of <typeparamref name="T"/>.
+    /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped entity instance.</returns>
     protected abstract T MapToEntity(DbDataReader reader);
 }

web/backend/Infrastructure/Infrastructure.Repository/Sql/DefaultSqlConnectionFactory.cs

@@ -4,6 +4,11 @@ using Microsoft.Extensions.Configuration;
 
 namespace Infrastructure.Repository.Sql;
 
+/// <summary>
+/// Default <see cref="ISqlConnectionFactory"/> implementation that creates SQL Server connections,
+/// resolving the connection string from environment variables or application configuration.
+/// </summary>
+/// <param name="configuration">The application configuration, used as a fallback source for the connection string.</param>
 public class DefaultSqlConnectionFactory(IConfiguration configuration)
     : ISqlConnectionFactory
 {
@@ -11,6 +16,17 @@ public class DefaultSqlConnectionFactory(IConfiguration configuration)
         configuration
     );
 
+    /// <summary>
+    /// Resolves the SQL Server connection string, preferring (in order): the <c>DB_CONNECTION_STRING</c>
+    /// environment variable, a connection string built from individual <c>DB_*</c> environment variables
+    /// via <see cref="SqlConnectionStringHelper.BuildConnectionString"/>, and finally the <c>"Default"</c>
+    /// connection string from <paramref name="configuration"/>.
+    /// </summary>
+    /// <param name="configuration">The application configuration to fall back to.</param>
+    /// <returns>The resolved SQL Server connection string.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when no connection string can be resolved from any of the supported sources.
+    /// </exception>
     private static string GetConnectionString(IConfiguration configuration)
     {
         // Check for full connection string first
@@ -42,6 +58,10 @@ public class DefaultSqlConnectionFactory(IConfiguration configuration)
         }
     }
 
+    /// <summary>
+    /// Creates a new, unopened <see cref="SqlConnection"/> using the resolved connection string.
+    /// </summary>
+    /// <returns>A new <see cref="SqlConnection"/> instance.</returns>
     public DbConnection CreateConnection()
     {
         return new SqlConnection(_connectionString);

web/backend/Infrastructure/Infrastructure.Repository/Sql/ISqlConnectionFactory.cs

@@ -2,7 +2,14 @@ using System.Data.Common;
 
 namespace Infrastructure.Repository.Sql;
 
+/// <summary>
+/// Factory for creating database connections used by repositories.
+/// </summary>
 public interface ISqlConnectionFactory
 {
+    /// <summary>
+    /// Creates a new, unopened database connection.
+    /// </summary>
+    /// <returns>A new <see cref="DbConnection"/> instance.</returns>
     DbConnection CreateConnection();
 }

web/backend/Infrastructure/Infrastructure.Repository/Sql/SqlConnectionStringHelper.cs

@@ -2,6 +2,9 @@ using Microsoft.Data.SqlClient;
 
 namespace Infrastructure.Repository.Sql;
 
+/// <summary>
+/// Helper for building SQL Server connection strings from environment variables.
+/// </summary>
 public static class SqlConnectionStringHelper
 {
     /// <summary>

web/backend/Infrastructure/Infrastructure.Repository/UserAccount/IUserAccountRepository.cs

@@ -1,14 +1,51 @@
 namespace Infrastructure.Repository.UserAccount;
 
+/// <summary>
+/// Repository for CRUD operations on user account records.
+/// </summary>
 public interface IUserAccountRepository
 {
+    /// <summary>
+    /// Retrieves a user account by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the user account.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
     Task<Domain.Entities.UserAccount?> GetByIdAsync(Guid id);
+
+    /// <summary>
+    /// Retrieves all user accounts, optionally paginated.
+    /// </summary>
+    /// <param name="limit">The maximum number of records to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of records to skip, or <c>null</c> for no offset.</param>
+    /// <returns>The collection of matching <see cref="Domain.Entities.UserAccount"/> records.</returns>
     Task<IEnumerable<Domain.Entities.UserAccount>> GetAllAsync(
         int? limit,
         int? offset
     );
+
+    /// <summary>
+    /// Updates an existing user account's details.
+    /// </summary>
+    /// <param name="userAccount">The user account containing updated values. Must have a valid <c>UserAccountId</c>.</param>
     Task UpdateAsync(Domain.Entities.UserAccount userAccount);
+
+    /// <summary>
+    /// Deletes a user account by its unique identifier.
+    /// </summary>
+    /// <param name="id">The unique identifier of the user account to delete.</param>
     Task DeleteAsync(Guid id);
+
+    /// <summary>
+    /// Retrieves a user account by username.
+    /// </summary>
+    /// <param name="username">The username to search for.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
     Task<Domain.Entities.UserAccount?> GetByUsernameAsync(string username);
+
+    /// <summary>
+    /// Retrieves a user account by email address.
+    /// </summary>
+    /// <param name="email">The email address to search for.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
     Task<Domain.Entities.UserAccount?> GetByEmailAsync(string email);
 }

web/backend/Infrastructure/Infrastructure.Repository/UserAccount/UserAccountRepository.cs

@@ -4,10 +4,21 @@ using Infrastructure.Repository.Sql;
 
 namespace Infrastructure.Repository.UserAccount;
 
+/// <summary>
+/// ADO.NET-based implementation of <see cref="IUserAccountRepository"/> backed by SQL Server
+/// stored procedures.
+/// </summary>
+/// <param name="connectionFactory">The factory used to create database connections.</param>
 public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
     : Repository<Domain.Entities.UserAccount>(connectionFactory),
         IUserAccountRepository
 {
+    /// <summary>
+    /// Retrieves a user account by ID using the <c>usp_GetUserAccountById</c> stored procedure.
+    /// </summary>
+    /// <param name="id">The unique identifier of the user account.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetByIdAsync(Guid id)
     {
         await using var connection = await CreateConnection();
@@ -21,6 +32,15 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves all user accounts, optionally paginated, using the <c>usp_GetAllUserAccounts</c>
+    /// stored procedure. The <c>@Limit</c> and <c>@Offset</c> parameters are only added when their
+    /// corresponding argument has a value.
+    /// </summary>
+    /// <param name="limit">The maximum number of records to return, or <c>null</c> for no limit.</param>
+    /// <param name="offset">The number of records to skip, or <c>null</c> for no offset.</param>
+    /// <returns>The collection of matching <see cref="Domain.Entities.UserAccount"/> records.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<IEnumerable<Domain.Entities.UserAccount>> GetAllAsync(
         int? limit,
         int? offset
@@ -48,6 +68,12 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         return users;
     }
 
+    /// <summary>
+    /// Updates a user account's username, first name, last name, email, and date of birth using
+    /// the <c>usp_UpdateUserAccount</c> stored procedure.
+    /// </summary>
+    /// <param name="userAccount">The user account containing updated values. Must have a valid <c>UserAccountId</c>.</param>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task UpdateAsync(Domain.Entities.UserAccount userAccount)
     {
         await using var connection = await CreateConnection();
@@ -65,6 +91,11 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         await command.ExecuteNonQueryAsync();
     }
 
+    /// <summary>
+    /// Deletes a user account by ID using the <c>usp_DeleteUserAccount</c> stored procedure.
+    /// </summary>
+    /// <param name="id">The unique identifier of the user account to delete.</param>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task DeleteAsync(Guid id)
     {
         await using var connection = await CreateConnection();
@@ -76,6 +107,12 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         await command.ExecuteNonQueryAsync();
     }
 
+    /// <summary>
+    /// Retrieves a user account by username using the <c>usp_GetUserAccountByUsername</c> stored procedure.
+    /// </summary>
+    /// <param name="username">The username to search for.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetByUsernameAsync(
         string username
     )
@@ -91,6 +128,12 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Retrieves a user account by email address using the <c>usp_GetUserAccountByEmail</c> stored procedure.
+    /// </summary>
+    /// <param name="email">The email address to search for.</param>
+    /// <returns>The matching <see cref="Domain.Entities.UserAccount"/>, or <c>null</c> if not found.</returns>
+    /// <exception cref="Microsoft.Data.SqlClient.SqlException">Thrown when the database command fails.</exception>
     public async Task<Domain.Entities.UserAccount?> GetByEmailAsync(
         string email
     )
@@ -106,6 +149,11 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         return await reader.ReadAsync() ? MapToEntity(reader) : null;
     }
 
+    /// <summary>
+    /// Maps the current row of a data reader to a <see cref="Domain.Entities.UserAccount"/> entity.
+    /// </summary>
+    /// <param name="reader">The data reader positioned on the row to map.</param>
+    /// <returns>The mapped <see cref="Domain.Entities.UserAccount"/> instance.</returns>
     protected override Domain.Entities.UserAccount MapToEntity(
         DbDataReader reader
     )
@@ -128,6 +176,13 @@ public class UserAccountRepository(ISqlConnectionFactory connectionFactory)
         };
     }
 
+    /// <summary>
+    /// Helper method to add a parameter to a database command, converting <c>null</c> values to
+    /// <see cref="DBNull.Value"/>.
+    /// </summary>
+    /// <param name="command">The command to add the parameter to.</param>
+    /// <param name="name">The parameter name (including any prefix, e.g. "@Username").</param>
+    /// <param name="value">The parameter value, or <c>null</c> to bind <see cref="DBNull.Value"/>.</param>
     private static void AddParameter(
         DbCommand command,
         string name,