refactor: migrate Exceptionless.Web to Minimal APIs with Foundatio.Mediator

.agents/skills/backend-architecture/SKILL.md

@@ -22,7 +22,7 @@ aspire run --project src/Exceptionless.AppHost
 ```text
 Exceptionless.Core        → Domain logic, services, repositories, validation
 Exceptionless.Insulation  → Infrastructure implementations (Redis, GeoIP, Mail, HealthChecks)
-Exceptionless.Web         → ASP.NET Core host, controllers, WebSocket hubs
+Exceptionless.Web         → ASP.NET Core host, Minimal API endpoints, Mediator handlers, WebSocket hubs
 Exceptionless.Job         → Background job workers
 ```
 
@@ -89,49 +89,134 @@ public static class AuthorizationRoles
     public const string GlobalAdmin = "global";
 }
 
-// Usage
-[Authorize(Policy = AuthorizationRoles.UserPolicy)]
-public class OrganizationController : RepositoryApiController<...> { }
+// Minimal API endpoint groups (NEW pattern)
+var group = endpoints.MapGroup("api/v2")
+    .RequireAuthorization(AuthorizationRoles.UserPolicy)  // Group default
+    .WithTags("Tokens");
 
-[Authorize(Policy = AuthorizationRoles.GlobalAdminPolicy)]
-public class AdminController : ExceptionlessApiController { }
+// Override on specific endpoints
+group.MapGet("tokens/me", ...).RequireAuthorization(AuthorizationRoles.ClientPolicy);
+group.MapPost("auth/login", ...).AllowAnonymous();
 ```
 
 ## Controller Patterns
 
-Most controllers extend `RepositoryApiController<TRepository, TModel, TViewModel, TNewModel, TUpdateModel>`. Auth/special-case controllers extend `ExceptionlessApiController` directly.
+> **DEPRECATED**: Controllers are being migrated to Minimal API endpoints + Mediator handlers (see below).
+> Do NOT add new controllers. Use the Endpoint + Handler pattern instead.
+
+Legacy controllers extend `RepositoryApiController<TRepository, TModel, TViewModel, TNewModel, TUpdateModel>`. Auth/special-case controllers extend `ExceptionlessApiController` directly.
+
+## Minimal API + Mediator Architecture (NEW)
+
+All new API work uses Minimal API endpoints with Foundatio.Mediator for command/query dispatch.
+
+### Structure
+
+```text
+src/Exceptionless.Web/Api/
+├── Endpoints/          ← Thin HTTP adapters (routing, auth, response mapping)
+├── Messages/           ← Command/query records (mediator messages)
+├── Handlers/           ← Use-case logic (transport-agnostic, return Result<T>)
+├── Middleware/         ← Mediator pipeline middleware (validation, logging)
+├── Filters/            ← Endpoint filters (HTTP-specific cross-cutting)
+├── Results/            ← Result→IResult mapping, pagination, response types
+├── Infrastructure/     ← Shared utilities (validation, pagination, links)
+└── OpenApi/            ← OpenAPI conventions and transformers
+```
+
+### Endpoint Pattern
 
 ```csharp
-[Route(API_PREFIX + "/organizations")]
-[Authorize(Policy = AuthorizationRoles.UserPolicy)]
-public class OrganizationController : RepositoryApiController<IOrganizationRepository, Organization, ViewOrganization, NewOrganization, NewOrganization>
+public static class TokenEndpoints
 {
-    [HttpGet]
-    public async Task<ActionResult<IReadOnlyCollection<ViewOrganization>>> GetAllAsync(string? mode = null)
+    public static IEndpointRouteBuilder MapTokenEndpoints(this IEndpointRouteBuilder endpoints)
     {
-        var organizations = await GetModelsAsync(GetAssociatedOrganizationIds().ToArray());
-        return Ok(await MapCollectionAsync<ViewOrganization>(organizations, true));
+        var group = endpoints.MapGroup("api/v2")
+            .RequireAuthorization(AuthorizationRoles.UserPolicy)
+            .WithTags("Tokens");
+
+        group.MapGet("tokens/{id}", async (string id, IMediator mediator)
+            => (await mediator.InvokeAsync<Result<ViewToken>>(new GetTokenById(id))).ToHttpResult())
+            .WithName("GetTokenById")
+            .Produces<ViewToken>()
+            .ProducesProblem(StatusCodes.Status404NotFound);
+
+        return endpoints;
     }
 }
 ```
 
+### Handler Pattern (CRITICAL: Transport-Agnostic)
+
+Handlers MUST return `Result<T>` or `Result` — NEVER `IResult` or HTTP types.
+
+```csharp
+public class TokenHandler(ITokenRepository repository, ...) : HandlerBase
+{
+    public async Task<Result<ViewToken>> Handle(GetTokenById message)
+    {
+        var model = await repository.GetByIdAsync(message.Id);
+        if (model is null)
+            return Result.NotFound("Token not found.");
+        return mapper.MapToViewToken(model);
+    }
+}
+```
+
+### Result→HTTP Status Code Mapping
+
+| Result Type | HTTP Status | Notes |
+|---|---|---|
+| `Result<T>` success | 200 OK | Default success |
+| `Result<T>.Created(val, loc)` | 201 Created | With Location header |
+| `Result.NotFound(msg)` | 404 | Message in `title` field |
+| `Result.Forbidden(msg)` | 403 | Message in `title` field |
+| `Result.BadRequest(msg)` | 400 | Message in `title` field |
+| `Result.Invalid(ValidationError)` | 422 | Errors in `errors` dict |
+| `Result.Invalid("plan_limit", msg)` | 426 | Upgrade Required |
+| `Result.Invalid("not_implemented", msg)` | 501 | Not Implemented |
+| `Result.Invalid("rate_limit", msg)` | 429 | Too Many Requests |
+| `WorkInProgressResult` | 202 Accepted | Bulk operations |
+| `ModelActionResults` (has failures) | 400 | Per-ID failure details |
+| `PagedResult<T>` | 200 + Link headers | Auto-pagination |
+| `NotModifiedResponse` | 304 | No body |
+
+### Key Rules
+
+- Handlers MUST NOT import `Microsoft.AspNetCore.Http`
+- Handlers CAN accept `HttpContext` as a method parameter (auto-resolved by mediator) for auth
+- Pagination link URLs MUST be built in the endpoint/mapper layer
+- `ProblemDetails` shape MUST be preserved: `instance`, `reference-id`, `errors`, `lower_underscore` keys
+- Messages go in `title` field (NOT `detail`) — matches original controller behavior
+- Use `ApiValidation.ValidateAsync(model, serviceProvider)` at endpoint level (returns 422 by default)
+- Keep v1 legacy route aliases in the same endpoint file as canonical v2 routes
+
 ## ProblemDetails and Error Handling
 
-Return helpers from `ExceptionlessApiController`: `Ok()`, `Created()`, `NoContent()`, `Unauthorized()`, `Forbidden()`, `NotFound()`, `ValidationProblem(ModelState)`.
+### Endpoint-level validation (Minimal API)
+
+Use `ApiValidation.ValidateAsync(model, serviceProvider)` — returns `ValidationProblemDetails` at 422 for DataAnnotation failures. For MVC-model-binding-compatible 400 responses, pass explicit status code or add endpoint-level checks.
+
+### Handler-level errors
 
-Exceptions auto-convert via `ExceptionToProblemDetailsHandler`: `MiniValidatorException`/`ValidationException` → 422, others → 500.
+Return `Result.NotFound()`, `Result.Forbidden()`, `Result.BadRequest()`, or `Result.Invalid(ValidationError)`. The `ResultExtensions.ToHttpResult()` method converts these to proper `IResult` with ProblemDetails shape.
+
+### Exception handling
+
+Exceptions auto-convert via `ExceptionToProblemDetailsHandler`: `MiniValidatorException`/`ValidationException` → 422, `UnauthorizedAccessException` → 401, `VersionConflictDocumentException` → 409, others → 500.
 
 ## OpenAPI Baseline
 
 After any API change (new endpoint, changed status codes, modified request/response models), **always regenerate the OpenAPI baseline**:
 
 ```bash
 # Requires the API to be running (aspire run --project src/Exceptionless.AppHost)
-Invoke-WebRequest -Uri "http://localhost:7110/docs/v2/openapi.json" \
-  -OutFile "tests/Exceptionless.Tests/Controllers/Data/openapi.json"
+curl -s http://localhost:7110/docs/v2/openapi.json | jq . > tests/Exceptionless.Tests/Controllers/Data/openapi.json
 ```
 
-Then include the updated `openapi.json` in the same commit as the API change (or amend). The `OpenApiControllerTests.GetOpenApiJson_Default_ReturnsExpectedBaseline` test will fail if the baseline is stale.
+Then include the updated `openapi.json` in the same commit as the API change. The `OpenApiSnapshotTests.GetOpenApiJson_Default_MatchesSnapshot` test will fail if the baseline is stale.
+
+The endpoint manifest test (`EndpointManifestTests`) verifies all registered routes haven't changed — update `tests/Exceptionless.Tests/Controllers/Data/endpoint-manifest.txt` when adding/removing routes.
 
 ## WebSocket Hubs (NOT SignalR)
 

.gitignore

@@ -84,3 +84,4 @@ debug-storybook.log
 .devcontainer/devcontainer-lock.json
 
 *.lscache
+audit-output/

openspec/changes/minimal-api-mediator-openapi-migration/acceptance.md

@@ -0,0 +1,69 @@
+# Acceptance Criteria: Minimal API + Mediator + OpenAPI Migration
+
+## Route Preservation
+
+- **SHALL** preserve all existing v2 routes with identical HTTP methods, paths, and parameter binding.
+- **SHALL** preserve existing v1 compatibility aliases with identical behavior.
+- **SHALL** produce identical response status codes for all success and error cases.
+- **SHALL** preserve response body shapes (JSON property names, nesting, types).
+- **SHALL** preserve response headers (pagination, configuration version, rate-limit headers).
+- **SHALL** preserve query parameter behavior (filtering, sorting, paging, time ranges).
+
+## Authentication and Authorization
+
+- **SHALL** preserve auth/authorization behavior for all endpoints.
+- **SHALL** preserve `ApiKeyAuthenticationHandler` behavior (API key via header, query string, and bearer token).
+- **SHALL** preserve role-based policies (UserPolicy, GlobalAdminPolicy) on all endpoints.
+- **SHALL** preserve anonymous access on endpoints currently marked `[AllowAnonymous]`.
+
+## Middleware
+
+- **SHALL** preserve `ThrottlingMiddleware` behavior (rate limiting, response codes, headers).
+- **SHALL** preserve `OverageMiddleware` behavior (plan enforcement).
+- **SHALL NOT** replace existing middleware implementations.
+- **SHALL NOT** change middleware pipeline ordering for existing middleware.
+
+## Validation and Error Handling
+
+- **SHALL** preserve ProblemDetails shape: `instance` field, `reference-id` extension, `errors` map.
+- **SHALL** preserve `lower_underscore` error keys in validation error responses.
+- **SHALL** produce 422 for validation failures with errors map.
+- **SHALL** produce 401 for unauthenticated requests.
+- **SHALL** produce 403 for unauthorized requests.
+- **SHALL** produce 404 for not-found resources.
+
+## Patching
+
+- **SHALL** preserve `Delta<T>` patch behavior (partial update semantics, unchanged fields not modified).
+- **SHALL NOT** introduce JSON Patch in this change.
+
+## Event Ingestion
+
+- **SHALL** preserve raw event ingestion behavior (multipart, compressed, raw body).
+- **SHALL** preserve event submission via API key authentication.
+- **SHALL** preserve batch event submission.
+
+## Mediator Pattern
+
+- **SHALL NOT** use generated mediator endpoints (MapMediatorEndpoints) for existing public API routes.
+- **SHALL** use Foundatio.Mediator for command/query dispatch from endpoint lambdas.
+- **SHALL** register all handlers via DI auto-discovery.
+
+## OpenAPI
+
+- **SHALL** preserve `/docs/v2/openapi.json` serving Scalar docs.
+- **SHALL** generate build-time OpenAPI artifact during `dotnet build`.
+- **SHALL** add route manifest snapshot tests that fail on route addition/removal/change.
+- **SHALL** add OpenAPI snapshot tests that fail on schema drift.
+
+## Architecture
+
+- **SHALL** place all new endpoint code under `src/Exceptionless.Web/Api/`.
+- **SHALL** keep v1 legacy aliases in the same endpoint file as the canonical v2 route.
+- **SHALL** remove `AddControllers()` and `MapControllers()` after all controllers are migrated.
+- **SHALL** delete `Controllers/` folder after all controllers are migrated.
+
+## Testing
+
+- **SHALL** pass all existing integration tests without modification (unless test infrastructure needs updating for host changes).
+- **SHALL** update `tests/http/*.http` files if endpoint paths or parameters change (they should not).