Migrate Auth/Brewery/Location repositories to pure Dapper; rename Timer to RowVersion (#237)

* Integrate Spectre.Console into seed application, use async data loading

* Replace stored-procedure repositories with Dapper-based repositories

Removes the USP_* stored procedures for Auth, Location, and Brewery
data access in favour of services built with Dapper.

Adds a new Features.Locations slice and optimistic concurrency support
for the Brewery slice.

* Add new documentation for Dapper migration/database schema

* Update FluentAssertions to most recent open source ver

* Update XML doc comment in backend projects

* Modify brewery location dto to include denormalized data

* - Updated column names from 'Timer' to 'RowVersion' in schema.sql for
- Introduced new BeerPost entity and updated BreweryPost and BreweryPostLocation entities to use 'RowVersion' for concurrency.
- Modified UserAccount, UserCredential, UserVerification, City, StateProvince, and Country entities to use 'RowVersion' instead of 'Timer'.
- Updated tests and command handlers to reflect changes in concurrency token from 'Timer' to 'RowVersion'.
- Adjusted BreweryDto and BreweryDtoMapper to include 'RowVersion' and updated mapping logic accordingly.
- Ensured all repository methods and interfaces are aligned with the new concurrency handling approach.

* updates

* Add BeerStyle entity and related properties; refactor BreweryDto to remove BeerPosts

* Fix Api.Specs test failures: stale Timer column refs and missing test.user fixture

* Remove repository tests, usages of registration dto used in repo

* archive old stored procs/functions

* update stale docs

* Add instructions for generating cryptographically secure base64 secrets on macOS/Linux and Windows

web/backend/Infrastructure/Infrastructure.Email.Templates/Rendering/EmailTemplateProvider.cs

@@ -12,6 +12,7 @@ namespace Infrastructure.Email.Templates.Rendering;
 public class EmailTemplateProvider(IServiceProvider serviceProvider, ILoggerFactory loggerFactory)
     : IEmailTemplateProvider
 {
+    /// <inheritdoc/>
     public async Task<string> RenderUserRegisteredEmailAsync(
         string username,
         string confirmationLink
@@ -26,6 +27,7 @@ public class EmailTemplateProvider(IServiceProvider serviceProvider, ILoggerFact
         return await RenderComponentAsync<UserRegistration>(parameters);
     }
 
+    /// <inheritdoc/>
     public async Task<string> RenderResendConfirmationEmailAsync(
         string username,
         string confirmationLink

web/backend/Infrastructure/Infrastructure.Email.Templates/Rendering/IEmailTemplateProvider.cs

@@ -5,19 +5,15 @@ namespace Infrastructure.Email.Templates.Rendering;
 /// </summary>
 public interface IEmailTemplateProvider
 {
-    /// <summary>
-    ///     Renders the UserRegisteredEmail template with the specified parameters.
-    /// </summary>
-    /// <param name="username">The username to include in the email</param>
-    /// <param name="confirmationLink">The email confirmation link</param>
-    /// <returns>The rendered HTML string</returns>
+    /// <summary>Renders the registration confirmation email template.</summary>
+    /// <param name="username">The recipient's username, shown in the greeting.</param>
+    /// <param name="confirmationLink">The URL the recipient follows to confirm their account.</param>
+    /// <returns>A task whose result is the rendered HTML for the email body.</returns>
     Task<string> RenderUserRegisteredEmailAsync(string username, string confirmationLink);
 
-    /// <summary>
-    ///     Renders the ResendConfirmation template with the specified parameters.
-    /// </summary>
-    /// <param name="username">The username to include in the email</param>
-    /// <param name="confirmationLink">The new confirmation link</param>
-    /// <returns>The rendered HTML string</returns>
+    /// <summary>Renders the resend-confirmation email template.</summary>
+    /// <param name="username">The recipient's username, shown in the greeting.</param>
+    /// <param name="confirmationLink">The URL the recipient follows to confirm their account.</param>
+    /// <returns>A task whose result is the rendered HTML for the email body.</returns>
     Task<string> RenderResendConfirmationEmailAsync(string username, string confirmationLink);
 }

web/backend/Infrastructure/Infrastructure.Email/IEmailProvider.cs

@@ -1,11 +1,21 @@
 namespace Infrastructure.Email;
 
 /// <summary>
-///     Service for sending emails via SMTP.
+///     Service for sending emails.
 /// </summary>
 public interface IEmailProvider
 {
+    /// <summary>Sends an email to a single recipient.</summary>
+    /// <param name="to">The recipient's email address.</param>
+    /// <param name="subject">The email subject line.</param>
+    /// <param name="body">The email body content.</param>
+    /// <param name="isHtml">Whether <paramref name="body"/> is HTML; when <see langword="false"/> it is sent as plain text.</param>
     Task SendAsync(string to, string subject, string body, bool isHtml = true);
 
+    /// <summary>Sends an email to multiple recipients.</summary>
+    /// <param name="to">The recipients' email addresses.</param>
+    /// <param name="subject">The email subject line.</param>
+    /// <param name="body">The email body content.</param>
+    /// <param name="isHtml">Whether <paramref name="body"/> is HTML; when <see langword="false"/> it is sent as plain text.</param>
     Task SendAsync(IEnumerable<string> to, string subject, string body, bool isHtml = true);
 }

web/backend/Infrastructure/Infrastructure.Email/SmtpEmailProvider.cs

@@ -51,15 +51,17 @@ public class SmtpEmailProvider : IEmailProvider
         _fromName = Environment.GetEnvironmentVariable("SMTP_FROM_NAME") ?? "The Biergarten";
     }
 
+    /// <inheritdoc/>
     public async Task SendAsync(string to, string subject, string body, bool isHtml = true)
     {
         await SendAsync([to], subject, body, isHtml);
     }
 
-    /// <summary>
+    /// <inheritdoc/>
+    /// <remarks>
     ///     Connects using StartTls when SSL is enabled (or no encryption otherwise), authenticates
     ///     if credentials were configured, sends the message, and disconnects.
-    /// </summary>
+    /// </remarks>
     /// <exception cref="InvalidOperationException">
     ///     Thrown when connecting, authenticating, or sending via SMTP fails, wrapping the original exception.
     /// </exception>

web/backend/Infrastructure/Infrastructure.Jwt/JwtInfrastructure.cs

@@ -12,14 +12,12 @@ namespace Infrastructure.Jwt;
 /// </summary>
 public class JwtInfrastructure : ITokenInfrastructure
 {
-    /// <summary>
-    ///     Generates a signed JWT, signed using HMAC-SHA256 with the provided secret.
-    /// </summary>
+    /// <inheritdoc />
     /// <remarks>
     ///     Sets registered claims <c>sub</c> (userId), <c>unique_name</c> (username), <c>iat</c> (current UTC time),
     ///     <c>exp</c> (expiry), and <c>jti</c> (a newly generated GUID).
     /// </remarks>
-    /// <param name="secret">The symmetric secret used to sign the token (encoded as UTF-8 bytes).</param>
+    /// <param name="secret">The symmetric secret used to sign the token, encoded as UTF-8 bytes.</param>
     public string GenerateJwt(Guid userId, string username, DateTime expiry, string secret)
     {
         JsonWebTokenHandler handler = new();
@@ -52,11 +50,9 @@ public class JwtInfrastructure : ITokenInfrastructure
         return handler.CreateToken(tokenDescriptor);
     }
 
-    /// <summary>
-    ///     Validates a JWT's signature and lifetime (issuer and audience validation are disabled),
-    ///     using the provided secret as the HMAC-SHA256 symmetric signing key.
-    /// </summary>
-    /// <param name="secret">The symmetric secret used to verify the token's signature (encoded as UTF-8 bytes).</param>
+    /// <inheritdoc />
+    /// <remarks>Issuer and audience validation are disabled; only the signature and lifetime are validated.</remarks>
+    /// <param name="secret">The symmetric secret used to verify the token's signature, encoded as UTF-8 bytes.</param>
     /// <exception cref="UnauthorizedException">
     ///     Thrown when the token is invalid, has no claims identity, is expired, or otherwise fails validation.
     /// </exception>

web/backend/Infrastructure/Infrastructure.PasswordHashing/Argon2Infrastructure.cs

@@ -14,9 +14,7 @@ public class Argon2Infrastructure : IPasswordInfrastructure
     private const int ArgonIterations = 4;
     private const int ArgonMemoryKb = 65536; // 64MB
 
-    /// <summary>
-    ///     Hashes a plaintext password using Argon2id with a fresh random salt.
-    /// </summary>
+    /// <inheritdoc />
     /// <returns>A string of the form <c>"{base64Salt}:{base64Hash}"</c>, suitable for storage.</returns>
     public string Hash(string password)
     {
@@ -33,10 +31,8 @@ public class Argon2Infrastructure : IPasswordInfrastructure
         return $"{Convert.ToBase64String(salt)}:{Convert.ToBase64String(hash)}";
     }
 
-    /// <summary>
-    ///     Verifies a plaintext password against a stored salt/hash string, using a fixed-time comparison
-    ///     to mitigate timing attacks.
-    /// </summary>
+    /// <inheritdoc />
+    /// <remarks>Uses a fixed-time comparison to mitigate timing attacks.</remarks>
     /// <returns>
     ///     <c>false</c> if the password doesn't match, if <paramref name="stored" /> is malformed, or if any
     ///     other error occurs during verification.

web/backend/Infrastructure/Infrastructure.Sql/DependencyInjection/InfrastructureSqlServiceCollectionExtensions.cs

@@ -0,0 +1,15 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Infrastructure.Sql.DependencyInjection;
+
+/// <summary>Extension methods for registering SQL infrastructure services with dependency injection.</summary>
+public static class InfrastructureSqlServiceCollectionExtensions
+{
+    /// <summary>Registers <see cref="DefaultSqlConnectionFactory" /> as a singleton <see cref="ISqlConnectionFactory" />.</summary>
+    /// <returns>The same <paramref name="services" /> instance, for chaining.</returns>
+    public static IServiceCollection AddInfrastructureSql(this IServiceCollection services)
+    {
+        services.AddSingleton<ISqlConnectionFactory, DefaultSqlConnectionFactory>();
+        return services;
+    }
+}

web/backend/Infrastructure/Infrastructure.Sql/Infrastructure.Sql.csproj

@@ -6,12 +6,16 @@
         <RootNamespace>Infrastructure.Sql</RootNamespace>
     </PropertyGroup>
     <ItemGroup>
+        <PackageReference Include="Dapper" Version="2.1.79" />
         <PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.2" />
         <PackageReference Include="Microsoft.SqlServer.Types" Version="160.1000.6" />
-        <PackageReference Include="System.Data.SqlClient" Version="4.9.0" />
         <PackageReference
             Include="Microsoft.Extensions.Configuration.Abstractions"
             Version="9.0.0"
         />
+        <PackageReference
+            Include="Microsoft.Extensions.DependencyInjection.Abstractions"
+            Version="10.0.0"
+        />
     </ItemGroup>
 </Project>

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

@@ -3,8 +3,8 @@ using System.Data.Common;
 namespace Infrastructure.Sql;
 
 /// <summary>
-///     Base class for ADO.NET-based repositories, providing shared connection creation and
-///     entity-mapping infrastructure for derived repository implementations.
+///     Base class for Dapper-based repositories, providing shared connection creation for derived
+///     repository implementations.
 /// </summary>
 public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
     where T : class
@@ -19,9 +19,4 @@ public abstract class Repository<T>(ISqlConnectionFactory connectionFactory)
         await connection.OpenAsync();
         return connection;
     }
-
-    /// <summary>
-    ///     Maps the current row of a data reader to an instance of <typeparamref name="T" />.
-    /// </summary>
-    protected abstract T MapToEntity(DbDataReader reader);
 }

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

@@ -14,22 +14,10 @@ public static class SqlConnectionStringHelper
     /// <param name="databaseName">If null, falls back to the DB_NAME environment variable.</param>
     public static string BuildConnectionString(string? databaseName = null)
     {
-        string server =
-            Environment.GetEnvironmentVariable("DB_SERVER")
-            ?? throw new InvalidOperationException("DB_SERVER environment variable is not set");
-
-        string dbName =
-            databaseName
-            ?? Environment.GetEnvironmentVariable("DB_NAME")
-            ?? throw new InvalidOperationException("DB_NAME environment variable is not set");
-
-        string user =
-            Environment.GetEnvironmentVariable("DB_USER")
-            ?? throw new InvalidOperationException("DB_USER environment variable is not set");
-
-        string password =
-            Environment.GetEnvironmentVariable("DB_PASSWORD")
-            ?? throw new InvalidOperationException("DB_PASSWORD environment variable is not set");
+        string server = Required("DB_SERVER");
+        string dbName = databaseName ?? Required("DB_NAME");
+        string user = Required("DB_USER");
+        string password = Required("DB_PASSWORD");
 
         SqlConnectionStringBuilder builder = new()
         {
@@ -37,7 +25,7 @@ public static class SqlConnectionStringHelper
             InitialCatalog = dbName,
             UserID = user,
             Password = password,
-            TrustServerCertificate = true,
+            TrustServerCertificate = ResolveTrustServerCertificate(),
             Encrypt = true,
         };
 
@@ -51,4 +39,23 @@ public static class SqlConnectionStringHelper
     {
         return BuildConnectionString("master");
     }
+
+    /// <summary>
+    ///     Resolves the <c>DB_TRUST_SERVER_CERTIFICATE</c> environment variable, defaulting to
+    ///     <c>true</c> when it is unset or not a valid boolean.
+    /// </summary>
+    private static bool ResolveTrustServerCertificate()
+    {
+        return !bool.TryParse(
+                Environment.GetEnvironmentVariable("DB_TRUST_SERVER_CERTIFICATE"),
+                out bool trustServerCertificate
+            )
+            || trustServerCertificate;
+    }
+
+    private static string Required(string variableName) =>
+        Environment.GetEnvironmentVariable(variableName)
+        ?? throw new InvalidOperationException(
+            $"The {variableName} environment variable is not set."
+        );
 }

web/backend/Infrastructure/Infrastructure.Sql/SqlErrorCodes.cs

@@ -0,0 +1,44 @@
+namespace Infrastructure.Sql;
+
+/// <summary>
+///     Custom SQL Server error numbers (50000+) that a stored procedure could use to signal
+///     domain-level failures via <c>THROW</c>, for a repository to catch as
+///     <see cref="Microsoft.Data.SqlClient.SqlException" /> and translate via <c>ex.Number</c> into
+///     the corresponding <c>Domain.Exceptions</c> type.
+/// </summary>
+/// <remarks>
+///     Currently unused: the schema has no stored procedures, and no repository throws or catches on
+///     these numbers. Repositories instead run their own existence/concurrency checks and throw
+///     <c>Domain.Exceptions</c> directly (see <c>docs/website/database.md</c> for the current
+///     approach). This type is kept in case a future stored procedure reintroduces the pattern; each
+///     number would
+///     identify a category of error shared by every procedure that raises it, not a single call site.
+/// </remarks>
+public static class SqlErrorCodes
+{
+    /// <summary>
+    ///     A stored procedure's own input validation failed (e.g. a required parameter was <c>NULL</c>).
+    ///     Maps to HTTP 400 Bad Request.
+    /// </summary>
+    public const int Validation = 50400;
+
+    /// <summary>
+    ///     A stored procedure could not find a row it required, by primary key or foreign key. Maps to
+    ///     HTTP 404 Not Found.
+    /// </summary>
+    public const int NotFound = 50404;
+
+    /// <summary>
+    ///     A stored procedure detected a conflict: either a duplicate/already-exists row, or a stale
+    ///     optimistic-concurrency token (row-version mismatch). Maps to HTTP 409 Conflict.
+    /// </summary>
+    public const int Conflict = 50409;
+
+    /// <summary>
+    ///     A defensive check inside a stored procedure failed under conditions that should be
+    ///     unreachable in normal operation (e.g. an <c>INSERT</c> that should always affect one row
+    ///     affected zero). Left uncaught by repositories so it falls through to the generic
+    ///     <see cref="Microsoft.Data.SqlClient.SqlException" /> handler. Maps to HTTP 500/503.
+    /// </summary>
+    public const int InternalFailure = 50500;
+}