Move dotnet api into new directory

web/backend/API/API.Core/API.Core.csproj

@@ -0,0 +1,43 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <RootNamespace>API.Core</RootNamespace>
+        <DockerDefaultTargetOS>Linux</DockerDefaultTargetOS>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference
+            Include="Microsoft.AspNetCore.OpenApi"
+            Version="9.0.11"
+        />
+        <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
+        <PackageReference
+            Include="FluentValidation.AspNetCore"
+            Version="11.3.0"
+        />
+    </ItemGroup>
+
+    <ItemGroup>
+        <Folder Include="Infrastructure\" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\Domain\Domain.Entities\Domain.Entities.csproj" />
+        <ProjectReference Include="..\..\Domain\Domain.Exceptions\Domain.Exceptions.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Email\Infrastructure.Email.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Email.Templates\Infrastructure.Email.Templates.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Repository\Infrastructure.Repository.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Jwt\Infrastructure.Jwt.csproj" />
+        <ProjectReference Include="..\..\Service\Service.Auth\Service.Auth.csproj" />
+        <ProjectReference Include="..\..\Service\Service.Breweries\Service.Breweries.csproj" />
+        <ProjectReference Include="..\..\Service\Service.UserManagement\Service.UserManagement.csproj" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <Content Include="..\..\.dockerignore">
+            <Link>.dockerignore</Link>
+        </Content>
+    </ItemGroup>
+</Project>

web/backend/API/API.Core/Authentication/JwtAuthenticationHandler.cs

@@ -0,0 +1,86 @@
+using System.Security.Claims;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using API.Core.Contracts.Common;
+using Infrastructure.Jwt;
+using Microsoft.AspNetCore.Authentication;
+using Microsoft.Extensions.Options;
+
+namespace API.Core.Authentication;
+
+public class JwtAuthenticationHandler(
+    IOptionsMonitor<JwtAuthenticationOptions> options,
+    ILoggerFactory logger,
+    UrlEncoder encoder,
+    ITokenInfrastructure tokenInfrastructure,
+    IConfiguration configuration
+) : AuthenticationHandler<JwtAuthenticationOptions>(options, logger, encoder)
+{
+    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
+    {
+        // Use the same access-token secret source as TokenService to avoid mismatched validation.
+        var secret = Environment.GetEnvironmentVariable("ACCESS_TOKEN_SECRET");
+        if (string.IsNullOrWhiteSpace(secret))
+        {
+            secret = configuration["Jwt:SecretKey"];
+        }
+
+        if (string.IsNullOrWhiteSpace(secret))
+        {
+            return AuthenticateResult.Fail("JWT secret is not configured");
+        }
+
+        // Check if Authorization header exists
+        if (
+            !Request.Headers.TryGetValue(
+                "Authorization",
+                out var authHeaderValue
+            )
+        )
+        {
+            return AuthenticateResult.Fail("Authorization header is missing");
+        }
+
+        var authHeader = authHeaderValue.ToString();
+        if (
+            !authHeader.StartsWith(
+                "Bearer ",
+                StringComparison.OrdinalIgnoreCase
+            )
+        )
+        {
+            return AuthenticateResult.Fail(
+                "Invalid authorization header format"
+            );
+        }
+
+        var token = authHeader.Substring("Bearer ".Length).Trim();
+
+        try
+        {
+            var claimsPrincipal = await tokenInfrastructure.ValidateJwtAsync(
+                token,
+                secret
+            );
+            var ticket = new AuthenticationTicket(claimsPrincipal, Scheme.Name);
+            return AuthenticateResult.Success(ticket);
+        }
+        catch (Exception ex)
+        {
+            return AuthenticateResult.Fail(
+                $"Token validation failed: {ex.Message}"
+            );
+        }
+    }
+
+    protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
+    {
+        Response.ContentType = "application/json";
+        Response.StatusCode = 401;
+
+        var response = new ResponseBody { Message = "Unauthorized: Invalid or missing authentication token" };
+        await Response.WriteAsJsonAsync(response);
+    }
+}
+
+public class JwtAuthenticationOptions : AuthenticationSchemeOptions { }

web/backend/API/API.Core/Contracts/Auth/AuthDTO.cs

@@ -0,0 +1,21 @@
+using Domain.Entities;
+using Org.BouncyCastle.Asn1.Cms;
+
+namespace API.Core.Contracts.Auth;
+
+public record LoginPayload(
+    Guid UserAccountId,
+    string Username,
+    string RefreshToken,
+    string AccessToken
+);
+
+public record RegistrationPayload(
+    Guid UserAccountId,
+    string Username,
+    string RefreshToken,
+    string AccessToken,
+    bool ConfirmationEmailSent
+);
+
+public record ConfirmationPayload(Guid UserAccountId, DateTime ConfirmedDate);

web/backend/API/API.Core/Contracts/Auth/Login.cs

@@ -0,0 +1,20 @@
+using API.Core.Contracts.Common;
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record LoginRequest
+{
+    public string Username { get; init; } = default!;
+    public string Password { get; init; } = default!;
+}
+
+public class LoginRequestValidator : AbstractValidator<LoginRequest>
+{
+    public LoginRequestValidator()
+    {
+        RuleFor(x => x.Username).NotEmpty().WithMessage("Username is required");
+
+        RuleFor(x => x.Password).NotEmpty().WithMessage("Password is required");
+    }
+}

web/backend/API/API.Core/Contracts/Auth/RefreshToken.cs

@@ -0,0 +1,19 @@
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record RefreshTokenRequest
+{
+    public string RefreshToken { get; init; } = default!;
+}
+
+public class RefreshTokenRequestValidator
+    : AbstractValidator<RefreshTokenRequest>
+{
+    public RefreshTokenRequestValidator()
+    {
+        RuleFor(x => x.RefreshToken)
+            .NotEmpty()
+            .WithMessage("Refresh token is required");
+    }
+}

web/backend/API/API.Core/Contracts/Auth/Register.cs

@@ -0,0 +1,71 @@
+using API.Core.Contracts.Common;
+using FluentValidation;
+
+namespace API.Core.Contracts.Auth;
+
+public record RegisterRequest(
+    string Username,
+    string FirstName,
+    string LastName,
+    string Email,
+    DateTime DateOfBirth,
+    string Password
+);
+
+public class RegisterRequestValidator : AbstractValidator<RegisterRequest>
+{
+    public RegisterRequestValidator()
+    {
+        RuleFor(x => x.Username)
+            .NotEmpty()
+            .WithMessage("Username is required")
+            .Length(3, 64)
+            .WithMessage("Username must be between 3 and 64 characters")
+            .Matches("^[a-zA-Z0-9._-]+$")
+            .WithMessage(
+                "Username can only contain letters, numbers, dots, underscores, and hyphens"
+            );
+
+        RuleFor(x => x.FirstName)
+            .NotEmpty()
+            .WithMessage("First name is required")
+            .MaximumLength(128)
+            .WithMessage("First name cannot exceed 128 characters");
+
+        RuleFor(x => x.LastName)
+            .NotEmpty()
+            .WithMessage("Last name is required")
+            .MaximumLength(128)
+            .WithMessage("Last name cannot exceed 128 characters");
+
+        RuleFor(x => x.Email)
+            .NotEmpty()
+            .WithMessage("Email is required")
+            .EmailAddress()
+            .WithMessage("Invalid email format")
+            .MaximumLength(128)
+            .WithMessage("Email cannot exceed 128 characters");
+
+        RuleFor(x => x.DateOfBirth)
+            .NotEmpty()
+            .WithMessage("Date of birth is required")
+            .LessThan(DateTime.Today.AddYears(-19))
+            .WithMessage("You must be at least 19 years old to register");
+
+        RuleFor(x => x.Password)
+            .NotEmpty()
+            .WithMessage("Password is required")
+            .MinimumLength(8)
+            .WithMessage("Password must be at least 8 characters")
+            .Matches("[A-Z]")
+            .WithMessage("Password must contain at least one uppercase letter")
+            .Matches("[a-z]")
+            .WithMessage("Password must contain at least one lowercase letter")
+            .Matches("[0-9]")
+            .WithMessage("Password must contain at least one number")
+            .Matches("[^a-zA-Z0-9]")
+            .WithMessage(
+                "Password must contain at least one special character"
+            );
+    }
+}

web/backend/API/API.Core/Contracts/Breweries/BreweryCreateRequestValidator.cs

@@ -0,0 +1,50 @@
+using FluentValidation;
+
+namespace API.Core.Contracts.Breweries;
+
+public class BreweryCreateDtoValidator : AbstractValidator<BreweryCreateDto>
+{
+    public BreweryCreateDtoValidator()
+    {
+        RuleFor(x => x.PostedById)
+            .NotEmpty()
+            .WithMessage("PostedById is required.");
+
+        RuleFor(x => x.BreweryName)
+            .NotEmpty()
+            .WithMessage("Brewery name is required.")
+            .MaximumLength(256)
+            .WithMessage("Brewery name cannot exceed 256 characters.");
+
+        RuleFor(x => x.Description)
+            .NotEmpty()
+            .WithMessage("Description is required.")
+            .MaximumLength(512)
+            .WithMessage("Description cannot exceed 512 characters.");
+
+        RuleFor(x => x.Location)
+            .NotNull()
+            .WithMessage("Location is required.");
+
+        RuleFor(x => x.Location.CityId)
+            .NotEmpty()
+            .When(x => x.Location is not null)
+            .WithMessage("CityId is required.");
+
+        RuleFor(x => x.Location.AddressLine1)
+            .NotEmpty()
+            .When(x => x.Location is not null)
+            .WithMessage("Address line 1 is required.")
+            .MaximumLength(256)
+            .When(x => x.Location is not null)
+            .WithMessage("Address line 1 cannot exceed 256 characters.");
+
+        RuleFor(x => x.Location.PostalCode)
+            .NotEmpty()
+            .When(x => x.Location is not null)
+            .WithMessage("Postal code is required.")
+            .MaximumLength(20)
+            .When(x => x.Location is not null)
+            .WithMessage("Postal code cannot exceed 20 characters.");
+    }
+}

web/backend/API/API.Core/Contracts/Breweries/BreweryDto.cs

@@ -0,0 +1,41 @@
+namespace API.Core.Contracts.Breweries;
+
+public class BreweryLocationCreateDto
+{
+    public Guid CityId { get; set; }
+    public string AddressLine1 { get; set; } = string.Empty;
+    public string? AddressLine2 { get; set; }
+    public string PostalCode { get; set; } = string.Empty;
+    public byte[]? Coordinates { get; set; }
+}
+
+public class BreweryLocationDto
+{
+    public Guid BreweryPostLocationId { get; set; }
+    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;
+    public byte[]? Coordinates { get; set; }
+}
+
+public class BreweryCreateDto
+{
+    public Guid PostedById { get; set; }
+    public string BreweryName { get; set; } = string.Empty;
+    public string Description { get; set; } = string.Empty;
+    public BreweryLocationCreateDto Location { get; set; } = null!;
+}
+
+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; }
+    public byte[]? Timer { get; set; }
+    public BreweryLocationDto? Location { get; set; }
+}

web/backend/API/API.Core/Contracts/Common/ResponseBody.cs

@@ -0,0 +1,12 @@
+namespace API.Core.Contracts.Common;
+
+public record ResponseBody<T>
+{
+    public required string Message { get; init; }
+    public required T Payload { get; init; }
+}
+
+public record ResponseBody
+{
+    public required string Message { get; init; }
+}

web/backend/API/API.Core/Controllers/AuthController.cs

@@ -0,0 +1,118 @@
+using API.Core.Contracts.Auth;
+using API.Core.Contracts.Common;
+using Domain.Entities;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Service.Auth;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    [Authorize(AuthenticationSchemes = "JWT")]
+    public class AuthController(
+        IRegisterService registerService,
+        ILoginService loginService,
+        IConfirmationService confirmationService,
+        ITokenService tokenService
+    ) : ControllerBase
+    {
+        [AllowAnonymous]
+        [HttpPost("register")]
+        public async Task<ActionResult<UserAccount>> Register(
+            [FromBody] RegisterRequest req
+        )
+        {
+            var rtn = await registerService.RegisterAsync(
+                new UserAccount
+                {
+                    UserAccountId = Guid.Empty,
+                    Username = req.Username,
+                    FirstName = req.FirstName,
+                    LastName = req.LastName,
+                    Email = req.Email,
+                    DateOfBirth = req.DateOfBirth,
+                },
+                req.Password
+            );
+
+            var response = new ResponseBody<RegistrationPayload>
+            {
+                Message = "User registered successfully.",
+                Payload = new RegistrationPayload(
+                    rtn.UserAccount.UserAccountId,
+                    rtn.UserAccount.Username,
+                    rtn.RefreshToken,
+                    rtn.AccessToken,
+                    rtn.EmailSent
+                ),
+            };
+            return Created("/", response);
+        }
+
+        [AllowAnonymous]
+        [HttpPost("login")]
+        public async Task<ActionResult> Login([FromBody] LoginRequest req)
+        {
+            var rtn = await loginService.LoginAsync(req.Username, req.Password);
+
+            return Ok(
+                new ResponseBody<LoginPayload>
+                {
+                    Message = "Logged in successfully.",
+                    Payload = new LoginPayload(
+                        rtn.UserAccount.UserAccountId,
+                        rtn.UserAccount.Username,
+                        rtn.RefreshToken,
+                        rtn.AccessToken
+                    ),
+                }
+            );
+        }
+
+        [HttpPost("confirm")]
+        public async Task<ActionResult> Confirm([FromQuery] string token)
+        {
+            var rtn = await confirmationService.ConfirmUserAsync(token);
+            return Ok(
+                new ResponseBody<ConfirmationPayload>
+                {
+                    Message = "User with ID " + rtn.UserId + " is confirmed.",
+                    Payload = new ConfirmationPayload(
+                        rtn.UserId,
+                        rtn.ConfirmedAt
+                    ),
+                }
+            );
+        }
+
+        [HttpPost("confirm/resend")]
+        public async Task<ActionResult> ResendConfirmation([FromQuery] Guid userId)
+        {
+            await confirmationService.ResendConfirmationEmailAsync(userId);
+            return Ok(new ResponseBody { Message = "confirmation email has been resent" });
+        }
+
+        [AllowAnonymous]
+        [HttpPost("refresh")]
+        public async Task<ActionResult> Refresh(
+            [FromBody] RefreshTokenRequest req
+        )
+        {
+            var rtn = await tokenService.RefreshTokenAsync(req.RefreshToken);
+
+            return Ok(
+                new ResponseBody<LoginPayload>
+                {
+                    Message = "Token refreshed successfully.",
+                    Payload = new LoginPayload(
+                        rtn.UserAccount.UserAccountId,
+                        rtn.UserAccount.Username,
+                        rtn.RefreshToken,
+                        rtn.AccessToken
+                    ),
+                }
+            );
+        }
+    }
+}

web/backend/API/API.Core/Controllers/BreweryController.cs

@@ -0,0 +1,129 @@
+using API.Core.Contracts.Breweries;
+using API.Core.Contracts.Common;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+using Service.Breweries;
+
+namespace API.Core.Controllers;
+
+[ApiController]
+[Route("api/[controller]")]
+[Authorize(AuthenticationSchemes = "JWT")]
+public class BreweryController(IBreweryService breweryService) : ControllerBase
+{
+    [AllowAnonymous]
+    [HttpGet("{id:guid}")]
+    public async Task<ActionResult<ResponseBody<BreweryDto>>> GetById(Guid id)
+    {
+        var brewery = await breweryService.GetByIdAsync(id);
+        if (brewery is null)
+            return NotFound(new ResponseBody { Message = $"Brewery with ID {id} not found." });
+
+        return Ok(new ResponseBody<BreweryDto>
+        {
+            Message = "Brewery retrieved successfully.",
+            Payload = MapToDto(brewery),
+        });
+    }
+
+    [AllowAnonymous]
+    [HttpGet]
+    public async Task<ActionResult<ResponseBody<IEnumerable<BreweryDto>>>> GetAll(
+        [FromQuery] int? limit,
+        [FromQuery] int? offset)
+    {
+        var breweries = await breweryService.GetAllAsync(limit, offset);
+        return Ok(new ResponseBody<IEnumerable<BreweryDto>>
+        {
+            Message = "Breweries retrieved successfully.",
+            Payload = breweries.Select(MapToDto),
+        });
+    }
+
+    [HttpPost]
+    public async Task<ActionResult<ResponseBody<BreweryDto>>> Create([FromBody] BreweryCreateDto dto)
+    {
+        var request = new BreweryCreateRequest(
+            dto.PostedById,
+            dto.BreweryName,
+            dto.Description,
+            new BreweryLocationCreateRequest(
+                dto.Location.CityId,
+                dto.Location.AddressLine1,
+                dto.Location.AddressLine2,
+                dto.Location.PostalCode,
+                dto.Location.Coordinates
+            )
+        );
+
+        var result = await breweryService.CreateAsync(request);
+        if (!result.Success)
+            return BadRequest(new ResponseBody { Message = result.Message });
+
+        return Created($"/api/brewery/{result.Brewery.BreweryPostId}", new ResponseBody<BreweryDto>
+        {
+            Message = "Brewery created successfully.",
+            Payload = MapToDto(result.Brewery),
+        });
+    }
+
+    [HttpPut("{id:guid}")]
+    public async Task<ActionResult<ResponseBody<BreweryDto>>> Update(Guid id, [FromBody] BreweryDto dto)
+    {
+        if (dto.BreweryPostId != id)
+            return BadRequest(new ResponseBody { Message = "Route ID does not match payload ID." });
+
+        var request = new BreweryUpdateRequest(
+            dto.BreweryPostId,
+            dto.PostedById,
+            dto.BreweryName,
+            dto.Description,
+            dto.Location is null ? null : new BreweryLocationUpdateRequest(
+                dto.Location.BreweryPostLocationId,
+                dto.Location.CityId,
+                dto.Location.AddressLine1,
+                dto.Location.AddressLine2,
+                dto.Location.PostalCode,
+                dto.Location.Coordinates
+            )
+        );
+
+        var result = await breweryService.UpdateAsync(request);
+        if (!result.Success)
+            return BadRequest(new ResponseBody { Message = result.Message });
+
+        return Ok(new ResponseBody<BreweryDto>
+        {
+            Message = "Brewery updated successfully.",
+            Payload = MapToDto(result.Brewery),
+        });
+    }
+
+    [HttpDelete("{id:guid}")]
+    public async Task<ActionResult<ResponseBody>> Delete(Guid id)
+    {
+        await breweryService.DeleteAsync(id);
+        return Ok(new ResponseBody { Message = "Brewery deleted successfully." });
+    }
+
+    private static BreweryDto MapToDto(Domain.Entities.BreweryPost b) => new()
+    {
+        BreweryPostId = b.BreweryPostId,
+        PostedById = b.PostedById,
+        BreweryName = b.BreweryName,
+        Description = b.Description,
+        CreatedAt = b.CreatedAt,
+        UpdatedAt = b.UpdatedAt,
+        Timer = b.Timer,
+        Location = b.Location is null ? null : new BreweryLocationDto
+        {
+            BreweryPostLocationId = b.Location.BreweryPostLocationId,
+            BreweryPostId = b.Location.BreweryPostId,
+            CityId = b.Location.CityId,
+            AddressLine1 = b.Location.AddressLine1,
+            AddressLine2 = b.Location.AddressLine2,
+            PostalCode = b.Location.PostalCode,
+            Coordinates = b.Location.Coordinates,
+        },
+    };
+}

web/backend/API/API.Core/Controllers/NotFoundController.cs

@@ -0,0 +1,16 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [ApiExplorerSettings(IgnoreApi = true)]
+    [Route("error")] // required
+    public class NotFoundController : ControllerBase
+    {
+        [HttpGet("404")] //required
+        public IActionResult Handle404()
+        {
+            return NotFound(new { message = "Route not found." });
+        }
+    }
+}

web/backend/API/API.Core/Controllers/ProtectedController.cs

@@ -0,0 +1,27 @@
+using System.Security.Claims;
+using API.Core.Contracts.Common;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.AspNetCore.Mvc;
+
+namespace API.Core.Controllers;
+
+[ApiController]
+[Route("api/[controller]")]
+[Authorize(AuthenticationSchemes = "JWT")]
+public class ProtectedController : ControllerBase
+{
+    [HttpGet]
+    public ActionResult<ResponseBody<object>> Get()
+    {
+        var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
+        var username = User.FindFirst(ClaimTypes.Name)?.Value;
+
+        return Ok(
+            new ResponseBody<object>
+            {
+                Message = "Protected endpoint accessed successfully",
+                Payload = new { userId, username },
+            }
+        );
+    }
+}

web/backend/API/API.Core/Controllers/UserController.cs

@@ -0,0 +1,28 @@
+using Domain.Entities;
+using Microsoft.AspNetCore.Mvc;
+using Service.UserManagement.User;
+
+namespace API.Core.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    public class UserController(IUserService userService) : ControllerBase
+    {
+        [HttpGet]
+        public async Task<ActionResult<IEnumerable<UserAccount>>> GetAll(
+            [FromQuery] int? limit,
+            [FromQuery] int? offset
+        )
+        {
+            var users = await userService.GetAllAsync(limit, offset);
+            return Ok(users);
+        }
+
+        [HttpGet("{id:guid}")]
+        public async Task<ActionResult<UserAccount>> GetById(Guid id)
+        {
+            var user = await userService.GetByIdAsync(id);
+            return Ok(user);
+        }
+    }
+}

web/backend/API/API.Core/Dockerfile

@@ -0,0 +1,32 @@
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
+ARG APP_UID=1000
+USER $APP_UID
+WORKDIR /app
+EXPOSE 8080
+EXPOSE 8081
+
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+ARG BUILD_CONFIGURATION=Release
+WORKDIR /src
+COPY ["API/API.Core/API.Core.csproj", "API/API.Core/"]
+COPY ["Domain/Domain.Entities/Domain.Entities.csproj", "Domain.Entities/"]
+COPY ["Domain/Domain.Exceptions/Domain.Exceptions.csproj", "Domain.Exceptions/"]
+COPY ["Infrastructure/Infrastructure.Repository/Infrastructure.Repository.csproj", "Infrastructure/Infrastructure.Repository/"]
+COPY ["Infrastructure/Infrastructure.Jwt/Infrastructure.Jwt.csproj", "Infrastructure/Infrastructure.Jwt/"]
+COPY ["Infrastructure/Infrastructure.PasswordHashing/Infrastructure.PasswordHashing.csproj", "Infrastructure/Infrastructure.PasswordHashing/"]
+COPY ["Infrastructure/Infrastructure.Email/Infrastructure.Email.csproj", "Infrastructure/Infrastructure.Email/"]
+COPY ["Service/Service.Auth/Service.Auth.csproj", "Service/Service.Auth/"]
+COPY ["Service/Service.UserManagement/Service.UserManagement.csproj", "Service/Service.UserManagement/"]
+RUN dotnet restore "API/API.Core/API.Core.csproj"
+COPY . .
+WORKDIR "/src/API/API.Core"
+RUN dotnet build "./API.Core.csproj" -c $BUILD_CONFIGURATION -o /app/build
+
+FROM build AS publish
+ARG BUILD_CONFIGURATION=Release
+RUN dotnet publish "./API.Core.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false
+
+FROM base AS final
+WORKDIR /app
+COPY --from=publish /app/publish .
+ENTRYPOINT ["dotnet", "API.Core.dll"]

web/backend/API/API.Core/GlobalException.cs

@@ -0,0 +1,109 @@
+// API.Core/Filters/GlobalExceptionFilter.cs
+
+using API.Core.Contracts.Common;
+using Domain.Exceptions;
+using FluentValidation;
+using Microsoft.Data.SqlClient;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.Filters;
+
+namespace API.Core;
+
+public class GlobalExceptionFilter(ILogger<GlobalExceptionFilter> logger)
+    : IExceptionFilter
+{
+    public void OnException(ExceptionContext context)
+    {
+        logger.LogError(context.Exception, "Unhandled exception occurred");
+
+        switch (context.Exception)
+        {
+            case FluentValidation.ValidationException fluentValidationException:
+                var errors = fluentValidationException
+                    .Errors.GroupBy(e => e.PropertyName)
+                    .ToDictionary(
+                        g => g.Key,
+                        g => g.Select(e => e.ErrorMessage).ToArray()
+                    );
+
+                context.Result = new BadRequestObjectResult(
+                    new { message = "Validation failed", errors }
+                );
+                context.ExceptionHandled = true;
+                break;
+
+            case ConflictException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = ex.Message }
+                )
+                {
+                    StatusCode = 409,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            case NotFoundException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = ex.Message }
+                )
+                {
+                    StatusCode = 404,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            case UnauthorizedException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = ex.Message }
+                )
+                {
+                    StatusCode = 401,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            case ForbiddenException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = ex.Message }
+                )
+                {
+                    StatusCode = 403,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            case SqlException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = "A database error occurred." }
+                )
+                {
+                    StatusCode = 503,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            case Domain.Exceptions.ValidationException ex:
+                context.Result = new ObjectResult(
+                    new ResponseBody { Message = ex.Message }
+                )
+                {
+                    StatusCode = 400,
+                };
+                context.ExceptionHandled = true;
+                break;
+
+            default:
+                context.Result = new ObjectResult(
+                    new ResponseBody
+                    {
+                        Message = "An unexpected error occurred",
+                    }
+                )
+                {
+                    StatusCode = 500,
+                };
+                context.ExceptionHandled = true;
+                break;
+        }
+    }
+}

web/backend/API/API.Core/Program.cs

@@ -0,0 +1,104 @@
+using API.Core;
+using API.Core.Authentication;
+using FluentValidation;
+using FluentValidation.AspNetCore;
+using Infrastructure.Email;
+using Infrastructure.Email.Templates.Rendering;
+using Infrastructure.Jwt;
+using Infrastructure.PasswordHashing;
+using Infrastructure.Repository.Auth;
+using Infrastructure.Repository.Sql;
+using Infrastructure.Repository.UserAccount;
+using Infrastructure.Repository.Breweries;
+using Service.Auth;
+using Service.Emails;
+using Service.UserManagement.User;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Global Exception Filter
+builder.Services.AddControllers(options =>
+{
+    options.Filters.Add<GlobalExceptionFilter>();
+});
+
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+builder.Services.AddOpenApi();
+
+// Add FluentValidation
+builder.Services.AddValidatorsFromAssemblyContaining<Program>();
+builder.Services.AddFluentValidationAutoValidation();
+
+// Add health checks
+builder.Services.AddHealthChecks();
+
+// Configure logging for container output
+builder.Logging.ClearProviders();
+builder.Logging.AddConsole();
+if (!builder.Environment.IsProduction())
+{
+    builder.Logging.AddDebug();
+}
+
+// Configure Dependency Injection -------------------------------------------------------------------------------------
+
+builder.Services.AddSingleton<
+    ISqlConnectionFactory,
+    DefaultSqlConnectionFactory
+>();
+
+builder.Services.AddScoped<IUserAccountRepository, UserAccountRepository>();
+builder.Services.AddScoped<IAuthRepository, AuthRepository>();
+builder.Services.AddScoped<IBreweryRepository, BreweryRepository>();
+
+builder.Services.AddScoped<IUserService, UserService>();
+builder.Services.AddScoped<ILoginService, LoginService>();
+builder.Services.AddScoped<IRegisterService, RegisterService>();
+builder.Services.AddScoped<ITokenService, TokenService>();
+
+builder.Services.AddScoped<ITokenInfrastructure, JwtInfrastructure>();
+builder.Services.AddScoped<IPasswordInfrastructure, Argon2Infrastructure>();
+builder.Services.AddScoped<IEmailProvider, SmtpEmailProvider>();
+builder.Services.AddScoped<IEmailTemplateProvider, EmailTemplateProvider>();
+builder.Services.AddScoped<IEmailService, EmailService>();
+builder.Services.AddScoped<IConfirmationService, ConfirmationService>();
+
+// Register the exception filter
+builder.Services.AddScoped<GlobalExceptionFilter>();
+
+// Configure JWT Authentication
+builder
+    .Services.AddAuthentication("JWT")
+    .AddScheme<JwtAuthenticationOptions, JwtAuthenticationHandler>(
+        "JWT",
+        options => { }
+    );
+
+builder.Services.AddAuthorization();
+
+var app = builder.Build();
+
+app.UseSwagger();
+app.UseSwaggerUI();
+app.MapOpenApi();
+
+app.UseHttpsRedirection();
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Health check endpoint (used by Docker health checks and orchestrators)
+app.MapHealthChecks("/health");
+
+app.MapControllers();
+app.MapFallbackToController("Handle404", "NotFound");
+
+// Graceful shutdown handling
+var lifetime = app.Services.GetRequiredService<IHostApplicationLifetime>();
+lifetime.ApplicationStopping.Register(() =>
+{
+    app.Logger.LogInformation("Application is shutting down gracefully...");
+});
+
+app.Run();

web/backend/API/API.Core/appsettings.Development.json

@@ -0,0 +1,19 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Information",
+      "Microsoft.EntityFrameworkCore": "Information"
+    },
+    "Console": {
+      "IncludeScopes": true,
+      "TimestampFormat": "yyyy-MM-ddTHH:mm:ss.fffZ"
+    }
+  },
+  "AllowedHosts": "*",
+  "Jwt": {
+    "ExpirationMinutes": 120,
+    "Issuer": "biergarten-api",
+    "Audience": "biergarten-users"
+  }
+}

web/backend/API/API.Core/appsettings.Production.json

@@ -0,0 +1,19 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Warning",
+      "Microsoft.AspNetCore": "Warning",
+      "Microsoft.EntityFrameworkCore": "Error"
+    },
+    "Console": {
+      "IncludeScopes": false,
+      "TimestampFormat": "yyyy-MM-ddTHH:mm:ss.fffZ"
+    }
+  },
+  "AllowedHosts": "*",
+  "Jwt": {
+    "ExpirationMinutes": 60,
+    "Issuer": "biergarten-api",
+    "Audience": "biergarten-users"
+  }
+}

web/backend/API/API.Core/appsettings.json

@@ -0,0 +1,24 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Microsoft.EntityFrameworkCore": "Information"
+    },
+    "Console": {
+      "IncludeScopes": true,
+      "TimestampFormat": "yyyy-MM-ddTHH:mm:ss.fffZ"
+    }
+  },
+  "AllowedHosts": "*",
+  "ConnectionStrings": {
+    "DefaultConnection": ""
+  },
+  "Jwt": {
+    "SecretKey": "",
+    "ExpirationMinutes": 60,
+    "Issuer": "biergarten-api",
+    "Audience": "biergarten-users"
+  }
+}
+

web/backend/API/API.Specs/API.Specs.csproj

@@ -0,0 +1,46 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+        <IsPackable>false</IsPackable>
+        <RootNamespace>API.Specs</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+        <PackageReference Include="xunit" Version="2.9.2" />
+        <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+        <PackageReference Include="FluentAssertions" Version="6.9.0" />
+        <PackageReference Include="dbup" Version="5.0.41" />
+
+        <!-- Reqnroll core, xUnit adapter and code-behind generator -->
+        <PackageReference Include="Reqnroll" Version="3.3.3" />
+        <PackageReference Include="Reqnroll.xUnit" Version="3.3.3" />
+        <PackageReference
+            Include="Reqnroll.Tools.MsBuild.Generation"
+            Version="3.3.3"
+            PrivateAssets="all"
+        />
+
+        <!-- ASP.NET Core integration testing -->
+        <PackageReference
+            Include="Microsoft.AspNetCore.Mvc.Testing"
+            Version="9.0.1"
+        />
+    </ItemGroup>
+
+    <ItemGroup>
+        <!-- Ensure feature files are included in the project -->
+        <None Include="Features\**\*.feature" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <Using Include="Xunit" />
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\API.Core\API.Core.csproj" />
+        <ProjectReference Include="..\..\Infrastructure\Infrastructure.Email\Infrastructure.Email.csproj" />
+    </ItemGroup>
+</Project>

web/backend/API/API.Specs/Dockerfile

@@ -0,0 +1,25 @@
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
+ARG BUILD_CONFIGURATION=Release
+WORKDIR /src
+COPY ["API/API.Core/API.Core.csproj", "API/API.Core/"]
+COPY ["API/API.Specs/API.Specs.csproj", "API/API.Specs/"]
+COPY ["Domain/Domain.Entities/Domain.Entities.csproj", "Domain.Entities/"]
+COPY ["Domain/Domain.Exceptions/Domain.Exceptions.csproj", "Domain.Exceptions/"]
+COPY ["Infrastructure/Infrastructure.Repository/Infrastructure.Repository.csproj", "Infrastructure/Infrastructure.Repository/"]
+COPY ["Infrastructure/Infrastructure.Jwt/Infrastructure.Jwt.csproj", "Infrastructure/Infrastructure.Jwt/"]
+COPY ["Infrastructure/Infrastructure.PasswordHashing/Infrastructure.PasswordHashing.csproj", "Infrastructure/Infrastructure.PasswordHashing/"]
+COPY ["Infrastructure/Infrastructure.Email/Infrastructure.Email.csproj", "Infrastructure/Infrastructure.Email/"]
+COPY ["Service/Service.Auth/Service.Auth.csproj", "Service/Service.Auth/"]
+COPY ["Service/Service.UserManagement/Service.UserManagement.csproj", "Service/Service.UserManagement/"]
+RUN dotnet restore "API/API.Specs/API.Specs.csproj"
+COPY . .
+WORKDIR "/src/API/API.Specs"
+RUN dotnet build "./API.Specs.csproj" -c $BUILD_CONFIGURATION -o /app/build
+
+FROM build AS final
+ARG BUILD_CONFIGURATION=Release
+WORKDIR /src
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
+RUN mkdir -p /app/test-results/api-specs
+WORKDIR /src/API/API.Specs
+ENTRYPOINT ["dotnet", "test", "API.Specs.csproj", "-c", "Release", "--logger", "trx;LogFileName=/app/test-results/api-specs/results.trx"]

web/backend/API/API.Specs/Features/AccessTokenValidation.feature

@@ -0,0 +1,51 @@
+Feature: Protected Endpoint Access Token Validation
+   As a backend developer
+   I want protected endpoints to validate access tokens
+   So that unauthorized requests are rejected
+
+   Scenario: Protected endpoint accepts valid access token
+      Given the API is running
+      And I have an existing account
+      And I am logged in
+      When I submit a request to a protected endpoint with a valid access token
+      Then the response has HTTP status 200
+
+   Scenario: Protected endpoint rejects missing access token
+      Given the API is running
+      When I submit a request to a protected endpoint without an access token
+      Then the response has HTTP status 401
+
+   Scenario: Protected endpoint rejects invalid access token
+      Given the API is running
+      When I submit a request to a protected endpoint with an invalid access token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Unauthorized"
+
+   Scenario: Protected endpoint rejects expired access token
+      Given the API is running
+      And I have an existing account
+      And I am logged in with an immediately-expiring access token
+      When I submit a request to a protected endpoint with the expired token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Unauthorized"
+
+   Scenario: Protected endpoint rejects token signed with wrong secret
+      Given the API is running
+      And I have an access token signed with the wrong secret
+      When I submit a request to a protected endpoint with the tampered token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Unauthorized"
+
+   Scenario: Protected endpoint rejects refresh token as access token
+      Given the API is running
+      And I have an existing account
+      And I am logged in
+      When I submit a request to a protected endpoint with my refresh token instead of access token
+      Then the response has HTTP status 401
+
+   Scenario: Protected endpoint rejects confirmation token as access token
+      Given the API is running
+      And I have registered a new account
+      And I have a valid confirmation token
+      When I submit a request to a protected endpoint with my confirmation token instead of access token
+      Then the response has HTTP status 401

web/backend/API/API.Specs/Features/Confirmation.feature

@@ -0,0 +1,76 @@
+Feature: User Account Confirmation
+   As a newly registered user
+   I want to confirm my email address via a validation token
+   So that my account is fully activated
+   Scenario: Successful confirmation with valid token
+      Given the API is running
+      And I have registered a new account
+      And I have a valid confirmation token for my account
+      And I have a valid access token for my account
+      When I submit a confirmation request with the valid token
+      Then the response has HTTP status 200
+      And the response JSON should have "message" containing "is confirmed"
+
+   Scenario: Re-confirming an already verified account remains successful
+      Given the API is running
+      And I have registered a new account
+      And I have a valid confirmation token for my account
+      And I have a valid access token for my account
+      When I submit a confirmation request with the valid token
+      And I submit the same confirmation request again
+      Then the response has HTTP status 200
+      And the response JSON should have "message" containing "is confirmed"
+
+   Scenario: Confirmation fails with invalid token
+      Given the API is running
+      And I have registered a new account
+      And I have a valid access token for my account
+      When I submit a confirmation request with an invalid token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid token"
+
+   Scenario: Confirmation fails with expired token
+      Given the API is running
+      And I have registered a new account
+      And I have an expired confirmation token for my account
+      And I have a valid access token for my account
+      When I submit a confirmation request with the expired token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid token"
+
+   Scenario: Confirmation fails with tampered token (wrong secret)
+      Given the API is running
+      And I have registered a new account
+      And I have a confirmation token signed with the wrong secret
+      And I have a valid access token for my account
+      When I submit a confirmation request with the tampered token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid token"
+
+   Scenario: Confirmation fails when token is missing
+      Given the API is running
+      And I have registered a new account
+      And I have a valid access token for my account
+      When I submit a confirmation request with a missing token
+      Then the response has HTTP status 400
+
+   Scenario: Confirmation endpoint only accepts POST requests
+      Given the API is running
+      And I have a valid confirmation token
+      When I submit a confirmation request using an invalid HTTP method
+      Then the response has HTTP status 404
+
+   Scenario: Confirmation fails with malformed token
+      Given the API is running
+      And I have registered a new account
+      And I have a valid access token for my account
+      When I submit a confirmation request with a malformed token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid token"
+
+   Scenario: Confirmation fails without an access token
+      Given the API is running
+      And I have registered a new account
+      And I have a valid confirmation token for my account
+      When I submit a confirmation request with the valid token without an access token
+      Then the response has HTTP status 401

web/backend/API/API.Specs/Features/Login.feature

@@ -0,0 +1,39 @@
+Feature: User Login
+As a registered user
+I want to log in to my account
+So that I receive an authentication token to access authenticated routes
+
+    Scenario: Successful login with valid credentials
+        Given the API is running
+        And I have an existing account
+        When I submit a login request with a username and password
+        Then the response has HTTP status 200
+        And the response JSON should have "message" equal "Logged in successfully."
+        And the response JSON should have an access token
+
+    Scenario: Login fails with invalid credentials
+        Given the API is running
+        And I do not have an existing account
+        When I submit a login request with a username and password
+        Then the response has HTTP status 401
+        And the response JSON should have "message" equal "Invalid username or password."
+
+    Scenario: Login fails when required missing username
+        Given the API is running
+        When I submit a login request with a missing username
+        Then the response has HTTP status 400
+
+    Scenario: Login fails when required missing password
+        Given the API is running
+        When I submit a login request with a missing password
+        Then the response has HTTP status 400
+
+    Scenario: Login fails when both username and password are missing
+        Given the API is running
+        When I submit a login request with both username and password missing
+        Then the response has HTTP status 400
+
+    Scenario: Login endpoint only accepts POST requests
+        Given the API is running
+        When I submit a login request using a GET request
+        Then the response has HTTP status 404

web/backend/API/API.Specs/Features/NotFound.feature

@@ -0,0 +1,10 @@
+Feature: NotFound Responses
+As a client of the API
+I want consistent 404 responses
+So that consumers can gracefully handle missing routes
+
+    Scenario: GET request to an invalid route returns 404
+        Given the API is running
+        When I send an HTTP request "GET" to "/invalid-route"
+        Then the response has HTTP status 404
+        And the response JSON should have "message" equal "Route not found."

web/backend/API/API.Specs/Features/Registration.feature

@@ -0,0 +1,60 @@
+Feature: User Registration
+  As a new user
+  I want to register an account
+  So that I can log in and access authenticated routes
+
+  Scenario: Successful registration with valid details
+    Given the API is running
+    When I submit a registration request with values:
+      | Username | FirstName | LastName | Email               | DateOfBirth | Password   |
+      | newuser  | New       | User     | newuser@example.com | 1990-01-01  | Password1! |
+    Then the response has HTTP status 201
+    And the response JSON should have "message" equal "User registered successfully."
+    And the response JSON should have an access token
+
+  Scenario: Registration fails with existing username
+    Given the API is running
+    When I submit a registration request with values:
+      | Username  | FirstName | LastName | Email               | DateOfBirth | Password   |
+      | test.user | Test      | User     | example@example.com | 2001-11-11  | Password1! |
+    Then the response has HTTP status 409
+
+  Scenario: Registration fails with existing email
+    Given the API is running
+    When I submit a registration request with values:
+      | Username | FirstName | LastName | Email                       | DateOfBirth | Password   |
+      | newuser  | New       | User     | test.user@thebiergarten.app | 1990-01-01  | Password1! |
+    Then the response has HTTP status 409
+
+  Scenario: Registration fails with missing required fields
+    Given the API is running
+    When I submit a registration request with values:
+      | Username | FirstName | LastName | Email | DateOfBirth | Password   |
+      |          | New       | User     |       |             | Password1! |
+    Then the response has HTTP status 400
+
+  Scenario: Registration fails with invalid email format
+    Given the API is running
+    When I submit a registration request with values:
+      | Username | FirstName | LastName | Email        | DateOfBirth | Password   |
+      | newuser  | New       | User     | invalidemail | 1990-01-01  | Password1! |
+    Then the response has HTTP status 400
+
+  Scenario: Registration fails with weak password
+    Given the API is running
+    When I submit a registration request with values:
+      | Username | FirstName | LastName | Email               | DateOfBirth | Password |
+      | newuser  | New       | User     | newuser@example.com | 1990-01-01  | weakpass |
+    Then the response has HTTP status 400
+
+  Scenario: Cannot register a user younger than 19 years of age (regulatory requirement)
+    Given the API is running
+    When I submit a registration request with values:
+      | Username  | FirstName | LastName | Email                 | DateOfBirth     | Password   |
+      | younguser | Young     | User     | younguser@example.com | {underage_date} | Password1! |
+    Then the response has HTTP status 400
+
+  Scenario: Registration endpoint only accepts POST requests
+    Given the API is running
+    When I submit a registration request using a GET request
+    Then the response has HTTP status 404

web/backend/API/API.Specs/Features/ResendConfirmation.feature

@@ -0,0 +1,36 @@
+Feature: Resend Confirmation Email
+   As a user who did not receive the confirmation email
+   I want to request a resend of the confirmation email
+   So that I can obtain a working confirmation link while preventing abuse
+
+   Scenario: Legitimate resend for an unconfirmed user
+      Given the API is running
+      And I have registered a new account
+      And I have a valid access token for my account
+      When I submit a resend confirmation request for my account
+      Then the response has HTTP status 200
+      And the response JSON should have "message" containing "confirmation email has been resent"
+
+   Scenario: Resend is a no-op for an already confirmed user
+      Given the API is running
+      And I have registered a new account
+      And I have a valid confirmation token for my account
+      And I have a valid access token for my account
+      And I have confirmed my account
+      When I submit a resend confirmation request for my account
+      Then the response has HTTP status 200
+      And the response JSON should have "message" containing "confirmation email has been resent"
+
+   Scenario: Resend is a no-op for a non-existent user
+      Given the API is running
+      And I have registered a new account
+      And I have a valid access token for my account
+      When I submit a resend confirmation request for a non-existent user
+      Then the response has HTTP status 200
+      And the response JSON should have "message" containing "confirmation email has been resent"
+
+   Scenario: Resend requires authentication
+      Given the API is running
+      And I have registered a new account
+      When I submit a resend confirmation request without an access token
+      Then the response has HTTP status 401

web/backend/API/API.Specs/Features/TokenRefresh.feature

@@ -0,0 +1,39 @@
+Feature: Token Refresh
+   As an authenticated user
+   I want to refresh my access token using my refresh token
+   So that I can maintain my session without logging in again
+
+   Scenario: Successful token refresh with valid refresh token
+      Given the API is running
+      And I have an existing account
+      And I am logged in
+      When I submit a refresh token request with a valid refresh token
+      Then the response has HTTP status 200
+      And the response JSON should have "message" equal "Token refreshed successfully."
+      And the response JSON should have a new access token
+      And the response JSON should have a new refresh token
+
+   Scenario: Token refresh fails with invalid refresh token
+      Given the API is running
+      When I submit a refresh token request with an invalid refresh token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid"
+
+   Scenario: Token refresh fails with expired refresh token
+      Given the API is running
+      And I have an existing account
+      And I am logged in with an immediately-expiring refresh token
+      When I submit a refresh token request with the expired refresh token
+      Then the response has HTTP status 401
+      And the response JSON should have "message" containing "Invalid token"
+
+   Scenario: Token refresh fails when refresh token is missing
+      Given the API is running
+      When I submit a refresh token request with a missing refresh token
+      Then the response has HTTP status 400
+
+   Scenario: Token refresh endpoint only accepts POST requests
+      Given the API is running
+      And I have a valid refresh token
+      When I submit a refresh token request using a GET request
+      Then the response has HTTP status 404

web/backend/API/API.Specs/Mocks/MockEmailProvider.cs

@@ -0,0 +1,68 @@
+using Infrastructure.Email;
+
+namespace API.Specs.Mocks;
+
+/// <summary>
+/// Mock email provider for testing that doesn't actually send emails.
+/// Tracks sent emails for verification in tests if needed.
+/// </summary>
+public class MockEmailProvider : IEmailProvider
+{
+    public List<SentEmail> SentEmails { get; } = new();
+
+    public Task SendAsync(
+        string to,
+        string subject,
+        string body,
+        bool isHtml = true
+    )
+    {
+        SentEmails.Add(
+            new SentEmail
+            {
+                To = [to],
+                Subject = subject,
+                Body = body,
+                IsHtml = isHtml,
+                SentAt = DateTime.UtcNow,
+            }
+        );
+
+        return Task.CompletedTask;
+    }
+
+    public Task SendAsync(
+        IEnumerable<string> to,
+        string subject,
+        string body,
+        bool isHtml = true
+    )
+    {
+        SentEmails.Add(
+            new SentEmail
+            {
+                To = to.ToList(),
+                Subject = subject,
+                Body = body,
+                IsHtml = isHtml,
+                SentAt = DateTime.UtcNow,
+            }
+        );
+
+        return Task.CompletedTask;
+    }
+
+    public void Clear()
+    {
+        SentEmails.Clear();
+    }
+
+    public class SentEmail
+    {
+        public List<string> To { get; init; } = new();
+        public string Subject { get; init; } = string.Empty;
+        public string Body { get; init; } = string.Empty;
+        public bool IsHtml { get; init; }
+        public DateTime SentAt { get; init; }
+    }
+}

web/backend/API/API.Specs/Mocks/MockEmailService.cs

@@ -0,0 +1,65 @@
+using Domain.Entities;
+using Service.Emails;
+
+namespace API.Specs.Mocks;
+
+public class MockEmailService : IEmailService
+{
+    public List<RegistrationEmail> SentRegistrationEmails { get; } = new();
+
+    public List<ResendConfirmationEmail> SentResendConfirmationEmails { get; } = new();
+
+    public Task SendRegistrationEmailAsync(
+        UserAccount createdUser,
+        string confirmationToken
+    )
+    {
+        SentRegistrationEmails.Add(
+            new RegistrationEmail
+            {
+                UserAccount = createdUser,
+                ConfirmationToken = confirmationToken,
+                SentAt = DateTime.UtcNow,
+            }
+        );
+
+        return Task.CompletedTask;
+    }
+
+    public Task SendResendConfirmationEmailAsync(
+        UserAccount user,
+        string confirmationToken
+    )
+    {
+        SentResendConfirmationEmails.Add(
+            new ResendConfirmationEmail
+            {
+                UserAccount = user,
+                ConfirmationToken = confirmationToken,
+                SentAt = DateTime.UtcNow,
+            }
+        );
+
+        return Task.CompletedTask;
+    }
+
+    public void Clear()
+    {
+        SentRegistrationEmails.Clear();
+        SentResendConfirmationEmails.Clear();
+    }
+
+    public class RegistrationEmail
+    {
+        public UserAccount UserAccount { get; init; } = null!;
+        public string ConfirmationToken { get; init; } = string.Empty;
+        public DateTime SentAt { get; init; }
+    }
+
+    public class ResendConfirmationEmail
+    {
+        public UserAccount UserAccount { get; init; } = null!;
+        public string ConfirmationToken { get; init; } = string.Empty;
+        public DateTime SentAt { get; init; }
+    }
+}

web/backend/API/API.Specs/Steps/ApiGeneralSteps.cs

@@ -0,0 +1,209 @@
+using System.Text.Json;
+using API.Specs;
+using FluentAssertions;
+using Reqnroll;
+
+namespace API.Specs.Steps;
+
+[Binding]
+public class ApiGeneralSteps(ScenarioContext scenario)
+{
+    private const string ClientKey = "client";
+    private const string FactoryKey = "factory";
+    private const string ResponseKey = "response";
+    private const string ResponseBodyKey = "responseBody";
+
+    private HttpClient GetClient()
+    {
+        if (scenario.TryGetValue<HttpClient>(ClientKey, out var client))
+        {
+            return client;
+        }
+
+        var factory = scenario.TryGetValue<TestApiFactory>(
+            FactoryKey,
+            out var f
+        )
+            ? f
+            : new TestApiFactory();
+        scenario[FactoryKey] = factory;
+
+        client = factory.CreateClient();
+        scenario[ClientKey] = client;
+        return client;
+    }
+
+    [Given("the API is running")]
+    public void GivenTheApiIsRunning()
+    {
+        GetClient();
+    }
+
+    [When("I send an HTTP request {string} to {string} with body:")]
+    public async Task WhenISendAnHttpRequestStringToStringWithBody(
+        string method,
+        string url,
+        string jsonBody
+    )
+    {
+        var client = GetClient();
+
+        var requestMessage = new HttpRequestMessage(new HttpMethod(method), url)
+        {
+            Content = new StringContent(
+                jsonBody,
+                System.Text.Encoding.UTF8,
+                "application/json"
+            ),
+        };
+
+        var response = await client.SendAsync(requestMessage);
+        var responseBody = await response.Content.ReadAsStringAsync();
+
+        scenario[ResponseKey] = response;
+        scenario[ResponseBodyKey] = responseBody;
+    }
+
+    [When("I send an HTTP request {string} to {string}")]
+    public async Task WhenISendAnHttpRequestStringToString(
+        string method,
+        string url
+    )
+    {
+        var client = GetClient();
+        var requestMessage = new HttpRequestMessage(
+            new HttpMethod(method),
+            url
+        );
+        var response = await client.SendAsync(requestMessage);
+        var responseBody = await response.Content.ReadAsStringAsync();
+
+        scenario[ResponseKey] = response;
+        scenario[ResponseBodyKey] = responseBody;
+    }
+
+    [Then("the response status code should be {int}")]
+    public void ThenTheResponseStatusCodeShouldBeInt(int expected)
+    {
+        scenario
+            .TryGetValue<HttpResponseMessage>(ResponseKey, out var response)
+            .Should()
+            .BeTrue();
+        ((int)response!.StatusCode).Should().Be(expected);
+    }
+
+    [Then("the response has HTTP status {int}")]
+    public void ThenTheResponseHasHttpStatusInt(int expectedCode)
+    {
+        scenario
+            .TryGetValue<HttpResponseMessage>(ResponseKey, out var response)
+            .Should()
+            .BeTrue("No response was received from the API");
+        ((int)response!.StatusCode).Should().Be(expectedCode);
+    }
+
+    [Then("the response JSON should have {string} equal {string}")]
+    public void ThenTheResponseJsonShouldHaveStringEqualString(
+        string field,
+        string expected
+    )
+    {
+        scenario
+            .TryGetValue<HttpResponseMessage>(ResponseKey, out var response)
+            .Should()
+            .BeTrue();
+        scenario
+            .TryGetValue<string>(ResponseBodyKey, out var responseBody)
+            .Should()
+            .BeTrue();
+
+        using var doc = JsonDocument.Parse(responseBody!);
+        var root = doc.RootElement;
+
+        if (!root.TryGetProperty(field, out var value))
+        {
+            root.TryGetProperty("payload", out var payloadElem)
+                .Should()
+                .BeTrue(
+                    "Expected field '{0}' to be present either at the root or inside 'payload'",
+                    field
+                );
+            payloadElem
+                .ValueKind.Should()
+                .Be(JsonValueKind.Object, "payload must be an object");
+            payloadElem
+                .TryGetProperty(field, out value)
+                .Should()
+                .BeTrue(
+                    "Expected field '{0}' to be present inside 'payload'",
+                    field
+                );
+        }
+
+        value
+            .ValueKind.Should()
+            .Be(
+                JsonValueKind.String,
+                "Expected field '{0}' to be a string",
+                field
+            );
+        value.GetString().Should().Be(expected);
+    }
+
+    [Then("the response JSON should have {string} containing {string}")]
+    public void ThenTheResponseJsonShouldHaveStringContainingString(
+        string field,
+        string expectedSubstring
+    )
+    {
+        scenario
+            .TryGetValue<HttpResponseMessage>(ResponseKey, out var response)
+            .Should()
+            .BeTrue();
+        scenario
+            .TryGetValue<string>(ResponseBodyKey, out var responseBody)
+            .Should()
+            .BeTrue();
+
+        using var doc = JsonDocument.Parse(responseBody!);
+        var root = doc.RootElement;
+
+        if (!root.TryGetProperty(field, out var value))
+        {
+            root.TryGetProperty("payload", out var payloadElem)
+                .Should()
+                .BeTrue(
+                    "Expected field '{0}' to be present either at the root or inside 'payload'",
+                    field
+                );
+            payloadElem
+                .ValueKind.Should()
+                .Be(JsonValueKind.Object, "payload must be an object");
+            payloadElem
+                .TryGetProperty(field, out value)
+                .Should()
+                .BeTrue(
+                    "Expected field '{0}' to be present inside 'payload'",
+                    field
+                );
+        }
+
+        value
+            .ValueKind.Should()
+            .Be(
+                JsonValueKind.String,
+                "Expected field '{0}' to be a string",
+                field
+            );
+        var actualValue = value.GetString();
+        actualValue
+            .Should()
+            .Contain(
+                expectedSubstring,
+                "Expected field '{0}' to contain '{1}' but was '{2}'",
+                field,
+                expectedSubstring,
+                actualValue
+            );
+    }
+}

web/backend/API/API.Specs/TestApiFactory.cs

@@ -0,0 +1,46 @@
+using System.Collections.Generic;
+using API.Specs.Mocks;
+using Infrastructure.Email;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Mvc.Testing;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+using Service.Emails;
+
+namespace API.Specs
+{
+    public class TestApiFactory : WebApplicationFactory<Program>
+    {
+        protected override void ConfigureWebHost(IWebHostBuilder builder)
+        {
+            builder.UseEnvironment("Testing");
+
+            builder.ConfigureServices(services =>
+            {
+                // Replace the real email provider with mock for testing
+                var emailProviderDescriptor = services.SingleOrDefault(d =>
+                    d.ServiceType == typeof(IEmailProvider)
+                );
+
+                if (emailProviderDescriptor != null)
+                {
+                    services.Remove(emailProviderDescriptor);
+                }
+
+                services.AddScoped<IEmailProvider, MockEmailProvider>();
+
+                // Replace the real email service with mock for testing
+                var emailServiceDescriptor = services.SingleOrDefault(d =>
+                    d.ServiceType == typeof(IEmailService)
+                );
+
+                if (emailServiceDescriptor != null)
+                {
+                    services.Remove(emailServiceDescriptor);
+                }
+
+                services.AddScoped<IEmailService, MockEmailService>();
+            });
+        }
+    }
+}

web/backend/API/API.Specs/reqnroll.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://raw.githubusercontent.com/reqnroll/Reqnroll/main/Reqnroll.Configuration/reqnroll.schema.json",
+  "language": {
+    "feature": "en-US"
+  },
+  "bindingCulture": {
+    "name": "en-US"
+  },
+  "trace": {
+    "level": "Verbose"
+  },
+  "runtime": {
+    "stopAtFirstError": false
+  }
+}