feat: Add structured configuration for API endpoints, JSON serialization, Marten event store, and projections via new extension methods.

Author: aalmada

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/ApplicationServicesExtensions.cs

@@ -0,0 +1,79 @@
+using Microsoft.Extensions.Options;
+
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for configuring application services
+/// </summary>
+public static class ApplicationServicesExtensions
+{
+    /// <summary>
+    /// Configures all application services including pagination, OpenAPI, versioning, localization, etc.
+    /// </summary>
+    public static IServiceCollection AddApplicationServices(
+        this IServiceCollection services,
+        IConfiguration configuration,
+        IHostEnvironment environment)
+    {
+        // Problem details for error handling
+        services.AddProblemDetails();
+
+        // Configure pagination options
+        services.Configure<Models.PaginationOptions>(
+            configuration.GetSection(Models.PaginationOptions.SectionName));
+
+        // Configure OpenAPI with metadata
+        services.AddOpenApi(options => options.AddBookStoreApiDocumentation());
+
+        // Configure API Versioning (header-based)
+        AddApiVersioning(services);
+
+        // Configure localization
+        AddLocalization(services, configuration);
+
+        // Add SignalR for real-time notifications
+        services.AddSignalR();
+
+        // Add Blob Storage service
+        services.AddSingleton<Services.BlobStorageService>();
+
+        // Add Marten health checks
+        services.AddHealthChecks()
+            .AddNpgSql(configuration.GetConnectionString("bookstore")!);
+
+        // Add response caching for performance
+        services.AddResponseCaching();
+        services.AddOutputCache();
+
+        return services;
+    }
+
+    static void AddApiVersioning(IServiceCollection services)
+    {
+        services.AddApiVersioning(options =>
+        {
+            options.DefaultApiVersion = new Asp.Versioning.ApiVersion(1, 0);
+            options.AssumeDefaultVersionWhenUnspecified = true;
+            options.ReportApiVersions = true;
+            options.ApiVersionReader = new Asp.Versioning.HeaderApiVersionReader("api-version");
+        });
+    }
+
+    static void AddLocalization(IServiceCollection services, IConfiguration configuration)
+    {
+        // Configure localization from appsettings.json
+        services.Configure<Models.LocalizationOptions>(
+            configuration.GetSection(Models.LocalizationOptions.SectionName));
+
+        services.AddLocalization();
+        services.AddOptions<RequestLocalizationOptions>()
+            .Configure<IOptions<Models.LocalizationOptions>>((options, localizationOptions) =>
+            {
+                var localization = localizationOptions.Value;
+
+                _ = options.SetDefaultCulture(localization.DefaultCulture)
+                    .AddSupportedCultures(localization.SupportedCultures)
+                    .AddSupportedUICultures(localization.SupportedCultures);
+            });
+    }
+}

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/EndpointMappingExtensions.cs

@@ -0,0 +1,89 @@
+using BookStore.ApiService.Endpoints;
+using BookStore.ApiService.Endpoints.Admin;
+using Scalar.AspNetCore;
+
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for mapping API endpoints
+/// </summary>
+public static class EndpointMappingExtensions
+{
+    /// <summary>
+    /// Maps all API endpoints including public, admin, and system endpoints
+    /// </summary>
+    public static WebApplication MapApiEndpoints(this WebApplication app)
+    {
+        // Root endpoint
+        _ = app.MapGet("/", () => "Book Store API is running. Visit /api-reference for API documentation.")
+            .ExcludeFromDescription();
+
+        // Create API version set for v1
+        var apiVersionSet = app.NewApiVersionSet()
+            .HasApiVersion(new Asp.Versioning.ApiVersion(1))
+            .ReportApiVersions()
+            .Build();
+
+        // Map public and admin endpoints
+        MapPublicEndpoints(app, apiVersionSet);
+        MapAdminEndpoints(app, apiVersionSet);
+
+        // Map default endpoints (health checks, metrics, etc.)
+        app.MapDefaultEndpoints();
+
+        // Map SignalR hub for real-time notifications
+        app.MapHub<Wolverine.SignalR.WolverineHub>("/hub/bookstore");
+
+        return app;
+    }
+
+    static void MapPublicEndpoints(WebApplication app, Asp.Versioning.Builder.ApiVersionSet apiVersionSet)
+    {
+        // Public API endpoints (v1)
+        var publicApi = app.MapGroup("/api")
+            .WithApiVersionSet(apiVersionSet);
+
+        _ = publicApi.MapGroup("/books")
+            .MapBookEndpoints()
+            .WithTags("Books");
+
+        _ = publicApi.MapGroup("/authors")
+            .MapAuthorEndpoints()
+            .WithTags("Authors");
+
+        _ = publicApi.MapGroup("/categories")
+            .MapCategoryEndpoints()
+            .WithTags("Categories");
+
+        _ = publicApi.MapGroup("/publishers")
+            .MapPublisherEndpoints()
+            .WithTags("Publishers");
+    }
+
+    static void MapAdminEndpoints(WebApplication app, Asp.Versioning.Builder.ApiVersionSet apiVersionSet)
+    {
+        // Admin API endpoints (v1)
+        var adminApi = app.MapGroup("/api/admin")
+            .WithApiVersionSet(apiVersionSet);
+
+        _ = adminApi.MapGroup("/books")
+            .MapAdminBookEndpoints()
+            .WithTags("Admin - Books");
+
+        _ = adminApi.MapGroup("/authors")
+            .MapAdminAuthorEndpoints()
+            .WithTags("Admin - Authors");
+
+        _ = adminApi.MapGroup("/categories")
+            .MapAdminCategoryEndpoints()
+            .WithTags("Admin - Categories");
+
+        _ = adminApi.MapGroup("/publishers")
+            .MapAdminPublisherEndpoints()
+            .WithTags("Admin - Publishers");
+
+        _ = adminApi.MapGroup("/projections")
+            .MapProjectionEndpoints()
+            .WithTags("Admin - System");
+    }
+}

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/JsonConfigurationExtensions.cs

@@ -0,0 +1,33 @@
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for configuring JSON serialization
+/// </summary>
+public static class JsonConfigurationExtensions
+{
+    /// <summary>
+    /// Configures JSON serialization options for HTTP responses
+    /// </summary>
+    public static IServiceCollection AddJsonConfiguration(
+        this IServiceCollection services,
+        IHostEnvironment environment)
+    {
+        services.ConfigureHttpJsonOptions(options =>
+        {
+            // Use web defaults (camelCase properties)
+            options.SerializerOptions.PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase;
+
+            // Serialize enums as strings (not integers) for better readability and API evolution
+            options.SerializerOptions.Converters.Add(
+                new System.Text.Json.Serialization.JsonStringEnumConverter(System.Text.Json.JsonNamingPolicy.CamelCase));
+
+            // Pretty print in development for easier debugging
+            options.SerializerOptions.WriteIndented = environment.IsDevelopment();
+
+            // ISO 8601 date/time format is default in System.Text.Json
+            // DateTimeOffset automatically serializes as: "2025-12-26T17:16:09.123Z"
+        });
+
+        return services;
+    }
+}

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/MartenConfigurationExtensions.cs

@@ -0,0 +1,129 @@
+using BookStore.ApiService.Projections;
+using JasperFx.Events;
+using JasperFx.Events.Projections;
+using Marten;
+using Marten.Events.Daemon;
+using Marten.Events.Projections;
+using Weasel.Core;
+using Wolverine.Marten;
+
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for configuring Marten event store
+/// </summary>
+public static class MartenConfigurationExtensions
+{
+    /// <summary>
+    /// Configures Marten for event sourcing with projections and indexes
+    /// </summary>
+    public static IServiceCollection AddMartenEventStore(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        _ = services.AddMarten(sp =>
+        {
+            // Get connection string from Aspire
+            var connectionString = configuration.GetConnectionString("bookstore")!;
+
+            var options = new StoreOptions();
+            options.Connection(connectionString);
+
+            ConfigureEventMetadata(options);
+            ConfigureJsonSerialization(options);
+            RegisterEventTypes(options);
+            RegisterProjections(options);
+            ConfigureIndexes(options);
+
+            return options;
+        })
+        .UseLightweightSessions()
+        .IntegrateWithWolverine(cfg => cfg.UseWolverineManagedEventSubscriptionDistribution = true);
+
+        return services;
+    }
+
+    static void ConfigureEventMetadata(StoreOptions options)
+    {
+        // Enable metadata storage for correlation/causation tracking
+        options.Events.MetadataConfig.CorrelationIdEnabled = true;
+        options.Events.MetadataConfig.CausationIdEnabled = true;
+        options.Events.MetadataConfig.HeadersEnabled = true;
+    }
+
+    static void ConfigureJsonSerialization(StoreOptions options)
+    {
+        // Configure JSON serialization for Marten (database storage)
+        // Enums stored as strings for readability and camelCase for JSON properties
+        options.UseSystemTextJsonForSerialization(EnumStorage.AsString, Casing.CamelCase);
+
+        // Enable NGram search with unaccent for multilingual text search
+        // This automatically enables pg_trgm and unaccent extensions
+        options.Advanced.UseNGramSearchWithUnaccent = true;
+    }
+
+    static void RegisterEventTypes(StoreOptions options)
+    {
+        // Book events
+        _ = options.Events.AddEventType<Events.BookAdded>();
+        _ = options.Events.AddEventType<Events.BookUpdated>();
+        _ = options.Events.AddEventType<Events.BookSoftDeleted>();
+        _ = options.Events.AddEventType<Events.BookRestored>();
+        _ = options.Events.AddEventType<Events.BookCoverUpdated>();
+
+        // Author events
+        _ = options.Events.AddEventType<Events.AuthorAdded>();
+        _ = options.Events.AddEventType<Events.AuthorUpdated>();
+        _ = options.Events.AddEventType<Events.AuthorSoftDeleted>();
+        _ = options.Events.AddEventType<Events.AuthorRestored>();
+
+        // Category events
+        _ = options.Events.AddEventType<Events.CategoryAdded>();
+        _ = options.Events.AddEventType<Events.CategoryUpdated>();
+        _ = options.Events.AddEventType<Events.CategorySoftDeleted>();
+        _ = options.Events.AddEventType<Events.CategoryRestored>();
+
+        // Publisher events
+        _ = options.Events.AddEventType<Events.PublisherAdded>();
+        _ = options.Events.AddEventType<Events.PublisherUpdated>();
+        _ = options.Events.AddEventType<Events.PublisherSoftDeleted>();
+        _ = options.Events.AddEventType<Events.PublisherRestored>();
+    }
+
+    static void RegisterProjections(StoreOptions options)
+    {
+        // Configure projections - using AddAsync for async projections managed by Wolverine
+        // Register projection builders explicitly with async lifecycle
+        options.Projections.Add<AuthorProjectionBuilder>(ProjectionLifecycle.Async);
+        options.Projections.Add<CategoryProjectionBuilder>(ProjectionLifecycle.Async);
+        options.Projections.Add<PublisherProjectionBuilder>(ProjectionLifecycle.Async);
+        options.Projections.Add<BookSearchProjectionBuilder>(ProjectionLifecycle.Async);
+    }
+
+    static void ConfigureIndexes(StoreOptions options)
+    {
+        // Configure indexes for search performance
+        // Note: Trigram indexes for fuzzy search will be created via SQL migration
+
+        // BookSearchProjection indexes
+        _ = options.Schema.For<BookSearchProjection>()
+            .Index(x => x.PublisherId)  // Standard B-tree index for exact matches
+            .Index(x => x.Title)        // B-tree index for sorting
+            .GinIndexJsonData()        // GIN index for JSON fields
+            .NgramIndex(x => x.Title)           // NGram search on title
+            .NgramIndex(x => x.AuthorNames);    // NGram search on authors
+
+        // AuthorProjection indexes
+        _ = options.Schema.For<AuthorProjection>()
+            .Index(x => x.Name)         // B-tree index for sorting
+            .NgramIndex(x => x.Name);           // NGram search on author name
+
+        // Note: CategoryProjection no longer has a Name field - uses Translations dictionary
+        // No indexes configured for CategoryProjection
+
+        // PublisherProjection indexes
+        _ = options.Schema.For<PublisherProjection>()
+            .Index(x => x.Name)         // B-tree index for sorting
+            .NgramIndex(x => x.Name);           // NGram search on publisher name
+    }
+}

src/ApiService/BookStore.ApiService/Infrastructure/Extensions/WolverineConfigurationExtensions.cs

@@ -0,0 +1,54 @@
+using Wolverine;
+using Wolverine.SignalR;
+
+namespace BookStore.ApiService.Infrastructure.Extensions;
+
+/// <summary>
+/// Extension methods for configuring Wolverine messaging
+/// </summary>
+public static class WolverineConfigurationExtensions
+{
+    /// <summary>
+    /// Configures Wolverine with command/handler pattern and SignalR integration
+    /// </summary>
+    public static IServiceCollection AddWolverineMessaging(this IServiceCollection services)
+    {
+        _ = services.AddWolverine(opts =>
+        {
+            // Auto-discover handlers in this assembly
+            _ = opts.Discovery.IncludeAssembly(typeof(Program).Assembly);
+
+            // Explicitly include static handler classes for discovery
+            RegisterHandlers(opts);
+
+            // Enable SignalR transport for real-time notifications
+            _ = opts.UseSignalR();
+
+            // Route domain event notifications to SignalR
+            ConfigureEventPublishing(opts);
+
+            // Policies for automatic behavior
+            opts.Policies.AutoApplyTransactions();
+        });
+
+        return services;
+    }
+
+    static void RegisterHandlers(WolverineOptions opts)
+    {
+        _ = opts.Discovery.IncludeType(typeof(Handlers.Authors.AuthorHandlers));
+        _ = opts.Discovery.IncludeType(typeof(Handlers.Books.BookHandlers));
+        _ = opts.Discovery.IncludeType(typeof(Handlers.Books.BookCoverHandlers));
+        _ = opts.Discovery.IncludeType(typeof(Handlers.Categories.CategoryHandlers));
+        _ = opts.Discovery.IncludeType(typeof(Handlers.Publishers.PublisherHandlers));
+    }
+
+    static void ConfigureEventPublishing(WolverineOptions opts)
+    {
+        opts.Publish(x =>
+        {
+            x.MessagesImplementing<Events.Notifications.IDomainEventNotification>();
+            _ = x.ToSignalR();
+        });
+    }
+}