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/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryCommand.cs

@@ -3,6 +3,8 @@ using MediatR;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
+/// <summary>Location details for a brewery being created.</summary>
+/// <param name="Coordinates">Raw binary representation of the brewery's geographic coordinates.</param>
 public record CreateBreweryLocation(
     Guid CityId,
     string AddressLine1,

web/backend/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryHandler.cs

@@ -5,10 +5,14 @@ using MediatR;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
+/// <summary>Handles <see cref="CreateBreweryCommand" /> by persisting a new brewery post.</summary>
 public class CreateBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<CreateBreweryCommand, BreweryDto>
 {
     /// <summary>Creates a new brewery post, generating new identifiers for the post and its location.</summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when <paramref name="request" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
+    /// </exception>
     public async Task<BreweryDto> Handle(
         CreateBreweryCommand request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Commands/CreateBrewery/CreateBreweryValidator.cs

@@ -2,6 +2,7 @@ using FluentValidation;
 
 namespace Features.Breweries.Commands.CreateBrewery;
 
+/// <summary>Validates <see cref="CreateBreweryCommand" />.</summary>
 public class CreateBreweryValidator : AbstractValidator<CreateBreweryCommand>
 {
     public CreateBreweryValidator()

web/backend/Features/Features.Breweries/Commands/DeleteBrewery/DeleteBreweryCommand.cs

@@ -2,4 +2,5 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
+/// <summary>Deletes a brewery post. Bound directly from the route of <c>DELETE /api/brewery/{id}</c>.</summary>
 public record DeleteBreweryCommand(Guid BreweryPostId) : IRequest;

web/backend/Features/Features.Breweries/Commands/DeleteBrewery/DeleteBreweryHandler.cs

@@ -3,9 +3,13 @@ using MediatR;
 
 namespace Features.Breweries.Commands.DeleteBrewery;
 
+/// <summary>Handles <see cref="DeleteBreweryCommand" /> by deleting the corresponding brewery post.</summary>
 public class DeleteBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<DeleteBreweryCommand>
 {
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when no brewery exists with <paramref name="request" />'s <c>BreweryPostId</c>.
+    /// </exception>
     public Task Handle(DeleteBreweryCommand request, CancellationToken cancellationToken)
     {
         return repository.DeleteAsync(request.BreweryPostId);

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryCommand.cs

@@ -3,6 +3,11 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
+/// <summary>Location details for a brewery being updated.</summary>
+/// <param name="BreweryPostLocationId">
+///     Identifier of the existing location row, if any; a new row is created if none exists yet.
+/// </param>
+/// <param name="Coordinates">Raw binary representation of the brewery's geographic coordinates.</param>
 public record UpdateBreweryLocation(
     Guid BreweryPostLocationId,
     Guid CityId,
@@ -14,10 +19,13 @@ public record UpdateBreweryLocation(
 
 /// <summary>
 ///     Updates an existing brewery post. Bound directly from the request body of <c>PUT /api/brewery/{id}</c>.
-///     A <c>null</c> <see cref="Location" /> clears the brewery's location.
+///     A <c>null</c> <see cref="Location" /> clears the brewery's location. <see cref="RowVersion" /> must be the
+///     row-version last read for this brewery (e.g. from a prior <c>GET</c>); the update is rejected with a
+///     <c>409 Conflict</c> if the brewery was modified since then.
 /// </summary>
 public record UpdateBreweryCommand(
     Guid BreweryPostId,
+    byte[] RowVersion,
     Guid PostedById,
     string BreweryName,
     string Description,

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryHandler.cs

@@ -5,6 +5,7 @@ using MediatR;
 
 namespace Features.Breweries.Commands.UpdateBrewery;
 
+/// <summary>Handles <see cref="UpdateBreweryCommand" /> by persisting changes to an existing brewery post.</summary>
 public class UpdateBreweryHandler(IBreweryRepository repository)
     : IRequestHandler<UpdateBreweryCommand, BreweryDto>
 {
@@ -12,6 +13,14 @@ public class UpdateBreweryHandler(IBreweryRepository repository)
     ///     Updates an existing brewery post. If <paramref name="request" /> has no <c>Location</c>,
     ///     the brewery's location is cleared.
     /// </summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when no brewery exists with <paramref name="request" />'s <c>BreweryPostId</c>, or its
+    ///     location's <c>CityId</c> does not exist.
+    /// </exception>
+    /// <exception cref="Domain.Exceptions.ConflictException">
+    ///     Thrown when the brewery was modified by another request since <paramref name="request" />.
+    ///     <c>RowVersion</c> was read.
+    /// </exception>
     public async Task<BreweryDto> Handle(
         UpdateBreweryCommand request,
         CancellationToken cancellationToken
@@ -23,6 +32,7 @@ public class UpdateBreweryHandler(IBreweryRepository repository)
             PostedById = request.PostedById,
             BreweryName = request.BreweryName,
             Description = request.Description,
+            RowVersion = request.RowVersion,
             UpdatedAt = DateTime.UtcNow,
             Location = request.Location is null
                 ? null
@@ -38,7 +48,7 @@ public class UpdateBreweryHandler(IBreweryRepository repository)
                 },
         };
 
-        await repository.UpdateAsync(entity);
-        return entity.ToDto();
+        BreweryPost updated = await repository.UpdateAsync(entity);
+        return updated.ToDto();
     }
 }

web/backend/Features/Features.Breweries/Commands/UpdateBrewery/UpdateBreweryValidator.cs

@@ -0,0 +1,14 @@
+using FluentValidation;
+
+namespace Features.Breweries.Commands.UpdateBrewery;
+
+/// <summary>Validates <see cref="UpdateBreweryCommand" />.</summary>
+public class UpdateBreweryValidator : AbstractValidator<UpdateBreweryCommand>
+{
+    public UpdateBreweryValidator()
+    {
+        RuleFor(x => x.RowVersion)
+            .NotEmpty()
+            .WithMessage("RowVersion is required to detect conflicting concurrent updates.");
+    }
+}

web/backend/Features/Features.Breweries/Controllers/BreweryController.cs

@@ -11,6 +11,7 @@ using Shared.Contracts;
 
 namespace Features.Breweries.Controllers;
 
+/// <summary>Exposes CRUD operations for brewery posts.</summary>
 /// <remarks>
 ///     Requires JWT authentication by default; <see cref="GetById" /> and <see cref="GetAll" /> opt out via
 ///     <c>[AllowAnonymous]</c>.
@@ -20,6 +21,7 @@ namespace Features.Breweries.Controllers;
 [Authorize(AuthenticationSchemes = "JWT")]
 public class BreweryController(IMediator mediator) : ControllerBase
 {
+    /// <summary>Retrieves a single brewery post by ID.</summary>
     /// <remarks>Allows anonymous access.</remarks>
     /// <returns><c>200 OK</c> with the brewery if found; otherwise <c>404 Not Found</c>.</returns>
     [AllowAnonymous]
@@ -39,6 +41,9 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Retrieves brewery posts, newest first.</summary>
+    /// <param name="limit">Maximum number of breweries to return. Unbounded if <see langword="null"/>.</param>
+    /// <param name="offset">Number of breweries to skip. Treated as zero if <see langword="null"/>.</param>
     /// <remarks>Allows anonymous access.</remarks>
     [AllowAnonymous]
     [HttpGet]
@@ -59,6 +64,7 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Creates a new brewery post.</summary>
     /// <returns><c>201 Created</c> with the newly created brewery.</returns>
     [HttpPost]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> Create(
@@ -76,8 +82,13 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
+    /// <summary>Updates an existing brewery post.</summary>
     /// <param name="id">Must match <paramref name="command" />'s <c>BreweryPostId</c>.</param>
-    /// <returns><c>200 OK</c> with the updated brewery; or <c>400 Bad Request</c> if the route ID does not match the payload ID.</returns>
+    /// <returns>
+    ///     <c>200 OK</c> with the updated brewery; <c>400 Bad Request</c> if the route ID does not match the
+    ///     payload ID; <c>404 Not Found</c> if the brewery or its <c>CityId</c> does not exist; or
+    ///     <c>409 Conflict</c> if the brewery was modified since <c>command.RowVersion</c> was read.
+    /// </returns>
     [HttpPut("{id:guid}")]
     public async Task<ActionResult<ResponseBody<BreweryDto>>> Update(
         Guid id,
@@ -97,7 +108,8 @@ public class BreweryController(IMediator mediator) : ControllerBase
         );
     }
 
-    /// <returns><c>200 OK</c> confirming the deletion.</returns>
+    /// <summary>Deletes a brewery post.</summary>
+    /// <returns><c>200 OK</c> confirming the deletion; <c>404 Not Found</c> if no brewery exists with <paramref name="id" />.</returns>
     [HttpDelete("{id:guid}")]
     public async Task<ActionResult<ResponseBody>> Delete(Guid id)
     {

web/backend/Features/Features.Breweries/DependencyInjection/FeaturesBreweriesServiceCollectionExtensions.cs

@@ -3,11 +3,11 @@ using Microsoft.Extensions.DependencyInjection;
 
 namespace Features.Breweries.DependencyInjection;
 
-/// <summary>
-///     Registers the services owned by the Breweries feature slice.
-/// </summary>
+/// <summary>Registers the services required by the Breweries feature.</summary>
 public static class FeaturesBreweriesServiceCollectionExtensions
 {
+    /// <summary>Registers <see cref="IBreweryRepository" /> and its implementation.</summary>
+    /// <returns><paramref name="services" />, for chaining.</returns>
     public static IServiceCollection AddFeaturesBreweries(this IServiceCollection services)
     {
         services.AddScoped<IBreweryRepository, BreweryRepository>();

web/backend/Features/Features.Breweries/Dtos/BreweryDto.cs

@@ -1,39 +1,32 @@
 namespace Features.Breweries.Dtos;
 
-public class BreweryLocationDto
-{
-    public Guid BreweryPostLocationId { get; set; }
+/// <summary>Location details of a brewery, as returned by the API.</summary>
+/// <param name="Coordinates">The brewery's geographic coordinates, in a raw binary representation.</param>
+public record BreweryLocationDto(
+    Guid BreweryPostLocationId,
+    Guid CityId,
+    string CityName,
+    string StateProvinceName,
+    string StateProvinceCode,
+    string CountryName,
+    string CountryCode,
+    string AddressLine1,
+    string? AddressLine2,
+    string PostalCode,
+    byte[]? Coordinates
+);
 
-    public Guid BreweryPostId { get; set; }
-
-    public Guid CityId { get; set; }
-
-    public string AddressLine1 { get; set; } = string.Empty;
-
-    public string? AddressLine2 { get; set; }
-
-    public string PostalCode { get; set; } = string.Empty;
-
-    /// <summary>Gets or sets the brewery's geographic coordinates, in a raw binary representation.</summary>
-    public byte[]? Coordinates { get; set; }
-}
-
-public class BreweryDto
-{
-    public Guid BreweryPostId { get; set; }
-
-    public Guid PostedById { get; set; }
-
-    public string BreweryName { get; set; } = string.Empty;
-
-    public string Description { get; set; } = string.Empty;
-
-    public DateTime CreatedAt { get; set; }
-
-    public DateTime? UpdatedAt { get; set; }
-
-    /// <summary>Gets or sets the row-version/concurrency token used to detect conflicting concurrent updates.</summary>
-    public byte[]? Timer { get; set; }
-
-    public BreweryLocationDto? Location { get; set; }
-}
+/// <summary>A brewery post, as returned by the API.</summary>
+/// <param name="UpdatedAt">The date and time of the last edit, or <see langword="null"/> if never edited.</param>
+/// <param name="RowVersion">The row-version/concurrency token used to detect conflicting concurrent updates.</param>
+/// <param name="Location">The brewery's location, or <see langword="null"/> if none has been set.</param>
+public record BreweryDto(
+    Guid BreweryPostId,
+    Guid PostedById,
+    string BreweryName,
+    string Description,
+    DateTime CreatedAt,
+    DateTime? UpdatedAt,
+    byte[]? RowVersion,
+    BreweryLocationDto? Location
+);

web/backend/Features/Features.Breweries/Dtos/BreweryDtoMapper.cs

@@ -2,31 +2,42 @@ using Domain.Entities;
 
 namespace Features.Breweries.Dtos;
 
+/// <summary>Maps <see cref="BreweryPost" /> domain entities to <see cref="BreweryDto" />.</summary>
 public static class BreweryDtoMapper
 {
+    /// <summary>
+    ///     Converts a <see cref="BreweryPost" /> to its DTO representation, including its
+    ///     <see cref="BreweryDto.Location" /> if the entity has one.
+    /// </summary>
     public static BreweryDto ToDto(this BreweryPost brewery)
     {
-        return new BreweryDto
-        {
-            BreweryPostId = brewery.BreweryPostId,
-            PostedById = brewery.PostedById,
-            BreweryName = brewery.BreweryName,
-            Description = brewery.Description,
-            CreatedAt = brewery.CreatedAt,
-            UpdatedAt = brewery.UpdatedAt,
-            Timer = brewery.Timer,
-            Location = brewery.Location is null
+        return new BreweryDto(
+            BreweryPostId: brewery.BreweryPostId,
+            PostedById: brewery.PostedById,
+            BreweryName: brewery.BreweryName,
+            Description: brewery.Description,
+            CreatedAt: brewery.CreatedAt,
+            UpdatedAt: brewery.UpdatedAt,
+            RowVersion: brewery.RowVersion,
+            Location: brewery.Location is null
                 ? null
-                : new BreweryLocationDto
-                {
-                    BreweryPostLocationId = brewery.Location.BreweryPostLocationId,
-                    BreweryPostId = brewery.Location.BreweryPostId,
-                    CityId = brewery.Location.CityId,
-                    AddressLine1 = brewery.Location.AddressLine1,
-                    AddressLine2 = brewery.Location.AddressLine2,
-                    PostalCode = brewery.Location.PostalCode,
-                    Coordinates = brewery.Location.Coordinates,
-                },
-        };
+                : new BreweryLocationDto(
+                    BreweryPostLocationId: brewery.Location.BreweryPostLocationId,
+                    CityId: brewery.Location.CityId,
+                    CityName: brewery.Location.City?.CityName ?? string.Empty,
+                    StateProvinceName: brewery.Location.City?.StateProvince?.StateProvinceName
+                        ?? string.Empty,
+                    StateProvinceCode: brewery.Location.City?.StateProvince?.ISO3166_2
+                        ?? string.Empty,
+                    CountryName: brewery.Location.City?.StateProvince?.Country?.CountryName
+                        ?? string.Empty,
+                    CountryCode: brewery.Location.City?.StateProvince?.Country?.ISO3166_1
+                        ?? string.Empty,
+                    AddressLine1: brewery.Location.AddressLine1,
+                    AddressLine2: brewery.Location.AddressLine2,
+                    PostalCode: brewery.Location.PostalCode,
+                    Coordinates: brewery.Location.Coordinates
+                )
+        );
     }
 }

web/backend/Features/Features.Breweries/Features.Breweries.csproj

@@ -12,6 +12,7 @@
 
     <ItemGroup>
         <ProjectReference Include="..\..\Domain\Domain.Entities\Domain.Entities.csproj" />
+        <ProjectReference Include="..\..\Domain\Domain.Exceptions\Domain.Exceptions.csproj" />
         <ProjectReference Include="..\..\Infrastructure\Infrastructure.Sql\Infrastructure.Sql.csproj" />
         <ProjectReference Include="..\..\Shared\Shared.Contracts\Shared.Contracts.csproj" />
         <ProjectReference Include="..\..\Shared\Shared.Application\Shared.Application.csproj" />

web/backend/Features/Features.Breweries/Queries/GetAllBreweries/GetAllBreweriesHandler.cs

@@ -5,9 +5,11 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetAllBreweries;
 
+/// <summary>Handles <see cref="GetAllBreweriesQuery" /> by retrieving brewery posts, newest first.</summary>
 public class GetAllBreweriesHandler(IBreweryRepository repository)
     : IRequestHandler<GetAllBreweriesQuery, IEnumerable<BreweryDto>>
 {
+    /// <summary>Retrieves brewery posts, newest first, applying <see cref="GetAllBreweriesQuery" />'s paging.</summary>
     public async Task<IEnumerable<BreweryDto>> Handle(
         GetAllBreweriesQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetAllBreweries/GetAllBreweriesQuery.cs

@@ -3,7 +3,7 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetAllBreweries;
 
-/// <summary>
-///     Retrieves a paginated list of brewery posts.
-/// </summary>
+/// <summary>Retrieves brewery posts, newest first. Bound directly from the query string of <c>GET /api/brewery</c>.</summary>
+/// <param name="Limit">Maximum number of breweries to return. Unbounded if <see langword="null"/>.</param>
+/// <param name="Offset">Number of breweries to skip. Treated as zero if <see langword="null"/>.</param>
 public record GetAllBreweriesQuery(int? Limit, int? Offset) : IRequest<IEnumerable<BreweryDto>>;

web/backend/Features/Features.Breweries/Queries/GetBreweryById/GetBreweryByIdHandler.cs

@@ -5,9 +5,11 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetBreweryById;
 
+/// <summary>Handles <see cref="GetBreweryByIdQuery" /> by retrieving the matching brewery post.</summary>
 public class GetBreweryByIdHandler(IBreweryRepository repository)
     : IRequestHandler<GetBreweryByIdQuery, BreweryDto?>
 {
+    /// <summary>Retrieves the brewery post, or <see langword="null"/> if none exists with the given ID.</summary>
     public async Task<BreweryDto?> Handle(
         GetBreweryByIdQuery request,
         CancellationToken cancellationToken

web/backend/Features/Features.Breweries/Queries/GetBreweryById/GetBreweryByIdQuery.cs

@@ -3,4 +3,6 @@ using MediatR;
 
 namespace Features.Breweries.Queries.GetBreweryById;
 
+/// <summary>Retrieves a brewery post by ID. Bound directly from the route of <c>GET /api/brewery/{id}</c>.</summary>
+/// <remarks>Yields <see langword="null"/> if no brewery exists with the given <c>BreweryPostId</c>.</remarks>
 public record GetBreweryByIdQuery(Guid BreweryPostId) : IRequest<BreweryDto?>;

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

@@ -1,202 +1,458 @@
-using System.Data;
 using System.Data.Common;
+using Dapper;
 using Domain.Entities;
+using Domain.Exceptions;
 using Infrastructure.Sql;
 
 namespace Features.Breweries.Repository;
 
 /// <summary>
-///     ADO.NET-based implementation of <see cref="IBreweryRepository" /> backed by SQL Server stored
-///     procedures.
+///     Dapper-based implementation of <see cref="IBreweryRepository" />.
 /// </summary>
+/// <remarks>
+///     <c>BreweryPostLocation.Coordinates</c> is a SQL Server <c>GEOGRAPHY</c> column. Dapper's generic
+///     <c>Query&lt;T&gt;</c> deserializer reads columns via <c>IDataRecord.GetValue</c>, which for a UDT
+///     column returns a CLR UDT instance rather than raw bytes and cannot be coerced to <c>byte[]</c>.
+///     The read queries below therefore select <c>CONVERT(varbinary(max), bpl.Coordinates)</c>, which
+///     yields the UDT's serialized bytes as a plain <c>varbinary</c> value that Dapper can bind directly.
+/// </remarks>
 public class BreweryRepository(ISqlConnectionFactory connectionFactory)
     : Repository<BreweryPost>(connectionFactory),
         IBreweryRepository
 {
-    /// <summary>Retrieves a brewery post by ID using the <c>USP_GetBreweryById</c> stored procedure.</summary>
+    /// <inheritdoc/>
     public async Task<BreweryPost?> GetByIdAsync(Guid id)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandType = CommandType.StoredProcedure;
+        IEnumerable<BreweryPost> results = await connection.QueryAsync<
+            BreweryPost,
+            BreweryPostLocation,
+            City,
+            StateProvince,
+            Country,
+            BreweryPost
+        >(
+            """
+            SELECT
+                bp.BreweryPostID,
+                bp.PostedByID,
+                bp.BreweryName,
+                bp.Description,
+                bp.CreatedAt,
+                bp.UpdatedAt,
+                bp.RowVersion,
+                bpl.BreweryPostLocationID,
+                bpl.AddressLine1,
+                bpl.AddressLine2,
+                bpl.PostalCode,
+                CONVERT(varbinary(max), bpl.Coordinates) AS Coordinates,
+                c.CityID,
+                c.CityName,
+                sp.StateProvinceID,
+                sp.StateProvinceName,
+                sp.ISO3166_2,
+                co.CountryID,
+                co.CountryName,
+                co.ISO3166_1
+            FROM dbo.BreweryPost bp
+            LEFT JOIN dbo.BreweryPostLocation bpl ON bp.BreweryPostID = bpl.BreweryPostID
+            LEFT JOIN dbo.City c ON bpl.CityID = c.CityID
+            LEFT JOIN dbo.StateProvince sp ON c.StateProvinceID = sp.StateProvinceID
+            LEFT JOIN dbo.Country co ON sp.CountryID = co.CountryID
+            WHERE bp.BreweryPostID = @BreweryPostId
+            """,
+            MapBreweryRow,
+            new { BreweryPostId = id },
+            splitOn: "BreweryPostLocationID,CityID,StateProvinceID,CountryID"
+        );
 
-        command.CommandText = "USP_GetBreweryById";
-        AddParameter(command, "@BreweryPostID", id);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        if (await reader.ReadAsync())
-            return MapToEntity(reader);
-        return null;
+        return results.SingleOrDefault();
     }
 
-    /// <summary>
-    ///     Retrieves all brewery posts, optionally paginated, using the <c>USP_GetAllBreweries</c>
-    ///     stored procedure. The <c>@Limit</c> and <c>@Offset</c> parameters are only added when their
-    ///     corresponding argument has a value.
-    /// </summary>
-    public async Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset)
+    /// <inheritdoc/>
+    public async Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit,
+        int? offset)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_GetAllBreweries";
-        command.CommandType = CommandType.StoredProcedure;
-
-        if (limit.HasValue)
-            AddParameter(command, "@Limit", limit.Value);
-
-        if (offset.HasValue)
-            AddParameter(command, "@Offset", offset.Value);
-
-        await using DbDataReader reader = await command.ExecuteReaderAsync();
-        List<BreweryPost> breweries = new();
-
-        while (await reader.ReadAsync())
-            breweries.Add(MapToEntity(reader));
-
-        return breweries;
+        return await connection.QueryAsync<
+            BreweryPost,
+            BreweryPostLocation,
+            City,
+            StateProvince,
+            Country,
+            BreweryPost
+        >(
+            """
+            SELECT
+                bp.BreweryPostID,
+                bp.PostedByID,
+                bp.BreweryName,
+                bp.Description,
+                bp.CreatedAt,
+                bp.UpdatedAt,
+                bp.RowVersion,
+                bpl.BreweryPostLocationID,
+                bpl.AddressLine1,
+                bpl.AddressLine2,
+                bpl.PostalCode,
+                CONVERT(varbinary(max), bpl.Coordinates) AS Coordinates,
+                c.CityID,
+                c.CityName,
+                sp.StateProvinceID,
+                sp.StateProvinceName,
+                sp.ISO3166_2,
+                co.CountryID,
+                co.CountryName,
+                co.ISO3166_1
+            FROM dbo.BreweryPost bp
+            LEFT JOIN dbo.BreweryPostLocation bpl ON bp.BreweryPostID = bpl.BreweryPostID
+            LEFT JOIN dbo.City c ON bpl.CityID = c.CityID
+            LEFT JOIN dbo.StateProvince sp ON c.StateProvinceID = sp.StateProvinceID
+            LEFT JOIN dbo.Country co ON sp.CountryID = co.CountryID
+            ORDER BY bp.CreatedAt DESC
+            OFFSET @Offset ROWS FETCH NEXT @Limit ROWS ONLY
+            """,
+            MapBreweryRow,
+            new { Offset = offset ?? 0, Limit = limit ?? int.MaxValue },
+            splitOn: "BreweryPostLocationID,CityID,StateProvinceID,CountryID"
+        );
     }
 
-    /// <summary>
-    ///     Updates a brewery post's name and description, and upserts or clears its location, using the
-    ///     <c>USP_UpdateBrewery</c> stored procedure. When <paramref name="brewery" />.<c>Location</c> is
-    ///     <c>null</c>, any existing location for the brewery is removed.
-    /// </summary>
-    public async Task UpdateAsync(BreweryPost brewery)
+    /// <inheritdoc/>
+    public async Task<BreweryPost> UpdateAsync(BreweryPost brewery)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_UpdateBrewery";
-        command.CommandType = CommandType.StoredProcedure;
+        await using DbTransaction transaction =
+            await connection.BeginTransactionAsync();
 
-        AddParameter(command, "@BreweryPostID", brewery.BreweryPostId);
-        AddParameter(command, "@BreweryName", brewery.BreweryName);
-        AddParameter(command, "@Description", brewery.Description);
-        AddParameter(command, "@BreweryPostLocationID", brewery.Location?.BreweryPostLocationId);
-        AddParameter(command, "@CityID", brewery.Location?.CityId);
-        AddParameter(command, "@AddressLine1", brewery.Location?.AddressLine1);
-        AddParameter(command, "@AddressLine2", brewery.Location?.AddressLine2);
-        AddParameter(command, "@PostalCode", brewery.Location?.PostalCode);
-        AddParameter(command, "@Coordinates", brewery.Location?.Coordinates);
+        try
+        {
+            bool breweryExists =
+                await connection.ExecuteScalarAsync<int?>(
+                        new CommandDefinition(
+                            """
+                            SELECT 1 FROM
+                                dbo.BreweryPost
+                            WHERE
+                                BreweryPostID = @BreweryPostId
+                            """,
+                            new { brewery.BreweryPostId },
+                            transaction
+                        )
+                    )
+                    is not null;
 
-        await command.ExecuteNonQueryAsync();
+            if (!breweryExists)
+                throw new NotFoundException("Brewery not found.");
+
+            if (brewery.Location is not null)
+            {
+                bool cityExists =
+                    await connection.ExecuteScalarAsync<int?>(
+                            new CommandDefinition(
+                                "SELECT 1 FROM dbo.City WHERE CityID = @CityId",
+                                new { brewery.Location.CityId },
+                                transaction
+                            )
+                        )
+                        is not null;
+
+                if (!cityExists)
+                    throw new NotFoundException("City not found.");
+            }
+
+            int updatedRows = await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    UPDATE dbo.BreweryPost
+                    SET BreweryName = @BreweryName,
+                        Description = @Description,
+                        UpdatedAt = GETDATE()
+                    WHERE
+                        BreweryPostID = @BreweryPostId
+                      AND RowVersion = @RowVersion
+                    """,
+                    new
+                    {
+                        brewery.BreweryPostId,
+                        brewery.BreweryName,
+                        brewery.Description,
+                        brewery.RowVersion,
+                    },
+                    transaction
+                )
+            );
+
+            if (updatedRows == 0)
+                throw new ConflictException(
+                    "Brewery was modified by another request. Reload and try again."
+                );
+
+            if (brewery.Location is null)
+            {
+                // No location supplied: clear any existing location for this brewery.
+                await connection.ExecuteAsync(
+                    new CommandDefinition(
+                        """
+                        DELETE FROM
+                            dbo.BreweryPostLocation
+                        WHERE BreweryPostID = @BreweryPostId
+                        """,
+                        new { brewery.BreweryPostId },
+                        transaction
+                    )
+                );
+            }
+            else
+            {
+                bool locationExists =
+                    await connection.ExecuteScalarAsync<int?>(
+                            new CommandDefinition(
+                                """
+                                SELECT 1
+                                FROM dbo.BreweryPostLocation
+                                WHERE BreweryPostID = @BreweryPostId
+                                """,
+                                new { brewery.BreweryPostId },
+                                transaction
+                            )
+                        )
+                        is not null;
+
+                if (locationExists)
+                    await connection.ExecuteAsync(
+                        new CommandDefinition(
+                            """
+                            UPDATE dbo.BreweryPostLocation
+                            SET CityID = @CityId,
+                                AddressLine1 = @AddressLine1,
+                                AddressLine2 = @AddressLine2,
+                                PostalCode = @PostalCode,
+                                Coordinates = @Coordinates
+                            WHERE BreweryPostID = @BreweryPostId
+                            """,
+                            new
+                            {
+                                brewery.BreweryPostId,
+                                brewery.Location.CityId,
+                                brewery.Location.AddressLine1,
+                                brewery.Location.AddressLine2,
+                                brewery.Location.PostalCode,
+                                brewery.Location.Coordinates,
+                            },
+                            transaction
+                        )
+                    );
+                else
+                    await connection.ExecuteAsync(
+                        new CommandDefinition(
+                            """
+                            INSERT INTO dbo.BreweryPostLocation
+                                (BreweryPostLocationID,
+                                 BreweryPostID,
+                                 CityID,
+                                 AddressLine1,
+                                 AddressLine2,
+                                 PostalCode,
+                                 Coordinates)
+                            VALUES
+                                   (@BreweryPostLocationId,
+                                    @BreweryPostId,
+                                    @CityId,
+                                    @AddressLine1,
+                                    @AddressLine2,
+                                    @PostalCode,
+                                    @Coordinates)
+                            """,
+                            new
+                            {
+                                brewery.Location.BreweryPostLocationId,
+                                brewery.BreweryPostId,
+                                brewery.Location.CityId,
+                                brewery.Location.AddressLine1,
+                                brewery.Location.AddressLine2,
+                                brewery.Location.PostalCode,
+                                brewery.Location.Coordinates,
+                            },
+                            transaction
+                        )
+                    );
+            }
+
+            await transaction.CommitAsync();
+        }
+        catch
+        {
+            await transaction.RollbackAsync();
+            throw;
+        }
+
+        return await GetByIdAsync(brewery.BreweryPostId)
+               ?? throw new InvalidOperationException(
+                   $"Brewery '{brewery.BreweryPostId}' was not found after a successful update."
+               );
     }
 
-    /// <summary>
-    ///     Deletes a brewery post by ID using the <c>USP_DeleteBrewery</c> stored procedure. Its location
-    ///     and photos are removed via cascading foreign keys.
-    /// </summary>
+    /// <inheritdoc/>
     public async Task DeleteAsync(Guid id)
     {
         await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-        command.CommandText = "USP_DeleteBrewery";
-        command.CommandType = CommandType.StoredProcedure;
+        int rows = await connection.ExecuteAsync(
+            """
+            DELETE FROM
+                dbo.BreweryPost
+            WHERE
+                BreweryPostID = @BreweryPostId
+            """,
+            new { BreweryPostId = id }
+        );
 
-        AddParameter(command, "@BreweryPostID", id);
-        await command.ExecuteNonQueryAsync();
+        if (rows == 0)
+            throw new NotFoundException("Brewery not found.");
     }
 
-    /// <summary>Creates a new brewery post and its location using the <c>USP_CreateBrewery</c> stored procedure.</summary>
-    /// <exception cref="ArgumentException">Thrown when <paramref name="brewery" />.<c>Location</c> is <c>null</c>.</exception>
+    /// <inheritdoc/>
     public async Task CreateAsync(BreweryPost brewery)
     {
-        await using DbConnection connection = await CreateConnection();
-        await using DbCommand command = connection.CreateCommand();
-
-        command.CommandText = "USP_CreateBrewery";
-        command.CommandType = CommandType.StoredProcedure;
-
         if (brewery.Location is null)
-            throw new ArgumentException("Location must be provided when creating a brewery.");
+            throw new ArgumentException(
+                "Location must be provided when creating a brewery.");
 
-        AddParameter(command, "@BreweryName", brewery.BreweryName);
-        AddParameter(command, "@Description", brewery.Description);
-        AddParameter(command, "@PostedByID", brewery.PostedById);
-        AddParameter(command, "@CityID", brewery.Location?.CityId);
-        AddParameter(command, "@AddressLine1", brewery.Location?.AddressLine1);
-        AddParameter(command, "@AddressLine2", brewery.Location?.AddressLine2);
-        AddParameter(command, "@PostalCode", brewery.Location?.PostalCode);
-        AddParameter(command, "@Coordinates", brewery.Location?.Coordinates);
-        await command.ExecuteNonQueryAsync();
+        await using DbConnection connection = await CreateConnection();
+        await using DbTransaction transaction =
+            await connection.BeginTransactionAsync();
+
+        try
+        {
+            bool userExists =
+                await connection.ExecuteScalarAsync<int?>(
+                        new CommandDefinition(
+                            """
+                                        SELECT 1
+                                        FROM
+                                            dbo.UserAccount
+                                        WHERE
+                                            UserAccountID = @PostedById
+                            """,
+                            new { brewery.PostedById },
+                            transaction
+                        )
+                    )
+                    is not null;
+
+            if (!userExists)
+                throw new NotFoundException("User not found.");
+
+            bool cityExists =
+                await connection.ExecuteScalarAsync<int?>(
+                        new CommandDefinition(
+                            """
+                                        SELECT 1
+                                        FROM
+                                            dbo.City
+                                        WHERE
+                                            CityID = @CityId
+                            """,
+                            new { brewery.Location.CityId },
+                            transaction
+                        )
+                    )
+                    is not null;
+
+            if (!cityExists)
+                throw new NotFoundException("City not found.");
+
+            await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    INSERT INTO dbo.BreweryPost
+                        (BreweryPostID, BreweryName, Description, PostedByID)
+                    VALUES
+                        (@BreweryPostId, @BreweryName, @Description, @PostedById)
+                    """,
+                    new
+                    {
+                        brewery.BreweryPostId,
+                        brewery.BreweryName,
+                        brewery.Description,
+                        brewery.PostedById,
+                    },
+                    transaction
+                )
+            );
+
+            await connection.ExecuteAsync(
+                new CommandDefinition(
+                    """
+                    INSERT INTO dbo.BreweryPostLocation
+                        (BreweryPostLocationID,
+                         BreweryPostID,
+                         CityID,
+                         AddressLine1,
+                         AddressLine2,
+                         PostalCode,
+                         Coordinates)
+                    VALUES (@BreweryPostLocationId,
+                            @BreweryPostId,
+                            @CityId,
+                            @AddressLine1,
+                            @AddressLine2,
+                            @PostalCode,
+                            @Coordinates)
+                    """,
+                    new
+                    {
+                        brewery.Location.BreweryPostLocationId,
+                        brewery.BreweryPostId,
+                        brewery.Location.CityId,
+                        brewery.Location.AddressLine1,
+                        brewery.Location.AddressLine2,
+                        brewery.Location.PostalCode,
+                        brewery.Location.Coordinates,
+                    },
+                    transaction
+                )
+            );
+
+            await transaction.CommitAsync();
+        }
+        catch
+        {
+            await transaction.RollbackAsync();
+            throw;
+        }
     }
 
     /// <summary>
-    ///     Maps the current row of <paramref name="reader" /> to a <see cref="BreweryPost" />, including its
-    ///     associated <see cref="BreweryPostLocation" /> if location columns are present in the result set.
+    ///     Composes a joined row's <see cref="BreweryPost" />, <see cref="BreweryPostLocation" />,
+    ///     <see cref="City" />, <see cref="StateProvince" /> and <see cref="Country" /> fragments into a
+    ///     single populated <see cref="BreweryPost" />. When the row has no location (a left-joined
+    ///     brewery with no address on file), <paramref name="location" /> is a blank instance produced
+    ///     from all-<c>NULL</c> columns; the schema guarantees that whenever a location row was joined
+    ///     in, its City/StateProvince/Country chain was too.
     /// </summary>
-    protected override BreweryPost MapToEntity(DbDataReader reader)
+    private static BreweryPost MapBreweryRow(
+        BreweryPost post,
+        BreweryPostLocation location,
+        City city,
+        StateProvince stateProvince,
+        Country country
+    )
     {
-        BreweryPost brewery = new();
+        if (location.BreweryPostLocationId == Guid.Empty)
+            return post;
 
-        int ordBreweryPostId = reader.GetOrdinal("BreweryPostId");
-        int ordPostedById = reader.GetOrdinal("PostedById");
-        int ordBreweryName = reader.GetOrdinal("BreweryName");
-        int ordDescription = reader.GetOrdinal("Description");
-        int ordCreatedAt = reader.GetOrdinal("CreatedAt");
-        int ordUpdatedAt = reader.GetOrdinal("UpdatedAt");
-        int ordTimer = reader.GetOrdinal("Timer");
+        stateProvince.CountryId = country.CountryId;
+        stateProvince.Country = country;
 
-        brewery.BreweryPostId = reader.GetGuid(ordBreweryPostId);
-        brewery.PostedById = reader.GetGuid(ordPostedById);
-        brewery.BreweryName = reader.GetString(ordBreweryName);
-        brewery.Description = reader.GetString(ordDescription);
-        brewery.CreatedAt = reader.GetDateTime(ordCreatedAt);
+        city.StateProvinceId = stateProvince.StateProvinceId;
+        city.StateProvince = stateProvince;
 
-        brewery.UpdatedAt = reader.IsDBNull(ordUpdatedAt) ? null : reader.GetDateTime(ordUpdatedAt);
+        location.BreweryPostId = post.BreweryPostId;
+        location.CityId = city.CityId;
+        location.City = city;
 
-        // Read timer (varbinary/rowversion) robustly
-        if (reader.IsDBNull(ordTimer))
-            brewery.Timer = null;
-        else
-            try
-            {
-                brewery.Timer = reader.GetFieldValue<byte[]>(ordTimer);
-            }
-            catch
-            {
-                long length = reader.GetBytes(ordTimer, 0, null, 0, 0);
-                byte[] buffer = new byte[length];
-                reader.GetBytes(ordTimer, 0, buffer, 0, (int)length);
-                brewery.Timer = buffer;
-            }
-
-        // Map BreweryPostLocation if columns are present
-        try
-        {
-            int ordLocationId = reader.GetOrdinal("BreweryPostLocationId");
-            if (!reader.IsDBNull(ordLocationId))
-            {
-                BreweryPostLocation location = new()
-                {
-                    BreweryPostLocationId = reader.GetGuid(ordLocationId),
-                    BreweryPostId = reader.GetGuid(reader.GetOrdinal("BreweryPostId")),
-                    CityId = reader.GetGuid(reader.GetOrdinal("CityId")),
-                    AddressLine1 = reader.GetString(reader.GetOrdinal("AddressLine1")),
-                    AddressLine2 = reader.IsDBNull(reader.GetOrdinal("AddressLine2"))
-                        ? null
-                        : reader.GetString(reader.GetOrdinal("AddressLine2")),
-                    PostalCode = reader.GetString(reader.GetOrdinal("PostalCode")),
-                    Coordinates = reader.IsDBNull(reader.GetOrdinal("Coordinates"))
-                        ? null
-                        : reader.GetFieldValue<byte[]>(reader.GetOrdinal("Coordinates")),
-                };
-                brewery.Location = location;
-            }
-        }
-        catch (IndexOutOfRangeException)
-        {
-            // Location columns not present, skip mapping location
-        }
-
-        return brewery;
-    }
-
-    /// <summary>Adds a parameter to <paramref name="command" />, converting <c>null</c> to <see cref="DBNull.Value" />.</summary>
-    private static void AddParameter(DbCommand command, string name, object? value)
-    {
-        DbParameter p = command.CreateParameter();
-        p.ParameterName = name;
-        p.Value = value ?? DBNull.Value;
-        command.Parameters.Add(p);
+        post.Location = location;
+        return post;
     }
 }

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

@@ -7,16 +7,45 @@ namespace Features.Breweries.Repository;
 /// </summary>
 public interface IBreweryRepository
 {
-    /// <summary>Retrieves a brewery post by ID, or <c>null</c> if not found.</summary>
+    /// <summary>
+    ///     Retrieves a brewery post by ID, joined to its location. Returns <c>null</c> if no brewery post
+    ///     exists with the given ID, or if it has no associated location.
+    /// </summary>
     Task<BreweryPost?> GetByIdAsync(Guid id);
 
+    /// <summary>
+    ///     Retrieves all brewery posts, optionally paginated, ordered by creation date descending. Posts
+    ///     without a location are included, with <see cref="BreweryPost.Location" /> left <c>null</c>.
+    /// </summary>
+    /// <param name="limit">Maximum number of rows to return. Unbounded if <see langword="null" />.</param>
+    /// <param name="offset">Number of rows to skip. Treated as zero if <see langword="null" />.</param>
     Task<IEnumerable<BreweryPost>> GetAllAsync(int? limit, int? offset);
 
-    Task UpdateAsync(BreweryPost brewery);
+    /// <summary>
+    ///     Updates a brewery post's name and description, and upserts or clears its location, enforcing
+    ///     optimistic concurrency via <paramref name="brewery" />'s <c>RowVersion</c>: the update is rejected
+    ///     if the row was modified since <c>RowVersion</c> was read. When <paramref name="brewery" />'s
+    ///     <c>Location</c> is <c>null</c>, any existing location for the brewery is removed.
+    ///     Returns the freshly persisted brewery, including its new <c>RowVersion</c>.
+    /// </summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when no brewery exists with the given ID, or the given location's <c>CityId</c> does not
+    ///     exist.
+    /// </exception>
+    /// <exception cref="Domain.Exceptions.ConflictException">
+    ///     Thrown when <paramref name="brewery" />'s <c>RowVersion</c> no longer matches the stored row (it was
+    ///     modified by another request since it was last read).
+    /// </exception>
+    Task<BreweryPost> UpdateAsync(BreweryPost brewery);
 
+    /// <summary>Deletes a brewery post by ID. Its location and photos are removed via cascading foreign keys.</summary>
+    /// <exception cref="Domain.Exceptions.NotFoundException">Thrown when no brewery exists with the given <paramref name="id" />.</exception>
     Task DeleteAsync(Guid id);
 
     /// <summary>Creates a new brewery post, including its location details.</summary>
     /// <exception cref="ArgumentException">Thrown when <paramref name="brewery" /> has no <c>Location</c>.</exception>
+    /// <exception cref="Domain.Exceptions.NotFoundException">
+    ///     Thrown when <paramref name="brewery" />'s <c>PostedById</c> or <c>Location.CityId</c> does not exist.
+    /// </exception>
     Task CreateAsync(BreweryPost brewery);
 }