Catalog Features

Feature Organization

Each feature in the Catalog service follows a consistent vertical slice pattern with three main components:

Handler - Contains business logic and data access
Endpoint - Defines HTTP route and maps requests/responses
Validator - Validates commands/queries (where applicable)

Create Product

Create a new product in the catalog.

Handler Implementation

Products/CreateProduct/CreateProductHandler.cs

public record CreateProductCommand(
    string Name, 
    List<string> Category, 
    string Description, 
    string ImageFile, 
    decimal Price
) : ICommand<CreateProductResult>;

public record CreateProductResult(Guid Id);

public class CreateProductCommandValidator : AbstractValidator<CreateProductCommand>
{
    public CreateProductCommandValidator()
    {
        RuleFor(x => x.Name).NotEmpty().WithMessage("Name is required");
        RuleFor(x => x.Category).NotEmpty().WithMessage("Category is required");
        RuleFor(x => x.ImageFile).NotEmpty().WithMessage("ImageFile is required");
        RuleFor(x => x.Price).GreaterThan(0).WithMessage("Price must be greater than 0");
    }
}

internal class CreateProductCommandHandler(
    IDocumentSession session
) : ICommandHandler<CreateProductCommand, CreateProductResult>
{
    public async Task<CreateProductResult> Handle(
        CreateProductCommand command, 
        CancellationToken cancellationToken)
    {
        var product = new Product
        {
            Name = command.Name,
            Category = command.Category,
            Description = command.Description,
            ImageFile = command.ImageFile,
            Price = command.Price
        };
        
        session.Store(product);
        await session.SaveChangesAsync(cancellationToken);

        return new CreateProductResult(product.Id);
    }
}

Endpoint Implementation

Products/CreateProduct/CreateProductEndpoint.cs

public record CreateProductRequest(
    string Name, 
    List<string> Category, 
    string Description, 
    string ImageFile, 
    decimal Price
);

public record CreateProductResponse(Guid Id);

public class CreateProductEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/products",
            async (CreateProductRequest request, ISender sender) =>
        {
            var command = request.Adapt<CreateProductCommand>();
            var result = await sender.Send(command);
            var response = result.Adapt<CreateProductResponse>();

            return Results.Created($"/products/{response.Id}", response);
        })
        .WithName("CreateProduct")
        .Produces<CreateProductResponse>(StatusCodes.Status201Created)
        .ProducesProblem(StatusCodes.Status400BadRequest)
        .WithSummary("Create Product")
        .WithDescription("Create Product");
    }
}

Key Points

Auto-generated ID: Marten automatically generates a GUID for new products
Validation: FluentValidation rules ensure data integrity before persistence
Mapster: Used for object mapping between DTOs and domain objects
HTTP 201: Returns Created status with location header

Get Products (Paginated)

Retrieve a paginated list of all products.

Handler Implementation

Products/GetProducts/GetProductsHandler.cs

public record GetProductsQuery(
    int? PageNumber = 1, 
    int? PageSize = 10
) : IQuery<GetProductsResult>;

public record GetProductsResult(IEnumerable<Product> Products);

internal class GetProductsQueryHandler(
    IDocumentSession session
) : IQueryHandler<GetProductsQuery, GetProductsResult>
{
    public async Task<GetProductsResult> Handle(
        GetProductsQuery query, 
        CancellationToken cancellationToken)
    {
        var products = await session.Query<Product>()
            .ToPagedListAsync(
                query.PageNumber ?? 1, 
                query.PageSize ?? 10, 
                cancellationToken
            );

        return new GetProductsResult(products);
    }
}

Endpoint Implementation

Products/GetProducts/GetProductsEndpoint.cs

public record GetProductsRequest(int? PageNumber = 1, int? PageSize = 10);
public record GetProductsResponse(IEnumerable<Product> Products);

public class GetProductsEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/products", async ([AsParameters] GetProductsRequest request, ISender sender) =>
        {
            var query = request.Adapt<GetProductsQuery>();
            var result = await sender.Send(query);
            var response = result.Adapt<GetProductsResponse>();

            return Results.Ok(response);
        })
        .WithName("GetProducts")
        .Produces<GetProductsResponse>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status400BadRequest)
        .WithSummary("Get Products")
        .WithDescription("Get Products");
    }
}

Key Points

Pagination: Uses Marten’s ToPagedListAsync extension method
Default Values: PageNumber defaults to 1, PageSize defaults to 10
Query Parameters: Bound using [AsParameters] attribute

Get Product By ID

Retrieve a single product by its unique identifier.

Handler Implementation

Products/GetProductById/GetProductByIdHandler.cs

public record GetProductByIdQuery(Guid Id) : IQuery<GetProductByIdResult>;
public record GetProductByIdResult(Product Product);

internal class GetProductByIdQueryHandler(
    IDocumentSession session
) : IQueryHandler<GetProductByIdQuery, GetProductByIdResult>
{
    public async Task<GetProductByIdResult> Handle(
        GetProductByIdQuery query, 
        CancellationToken cancellationToken)
    {
        var product = await session.LoadAsync<Product>(query.Id, cancellationToken);

        if (product is null)
        {
            throw new ProductNotFoundException(query.Id);
        }

        return new GetProductByIdResult(product);
    }
}

Endpoint Implementation

Products/GetProductById/GetProductByIdEndpoint.cs

public record GetProductByIdResponse(Product Product);

public class GetProductByIdEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/products/{id}", async (Guid id, ISender sender) =>
        {
            var result = await sender.Send(new GetProductByIdQuery(id));
            var response = result.Adapt<GetProductByIdResponse>();

            return Results.Ok(response);
        })
        .WithName("GetProductById")
        .Produces<GetProductByIdResponse>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status400BadRequest)
        .WithSummary("Get Product By Id")
        .WithDescription("Get Product By Id");
    }
}

Key Points

LoadAsync: Optimized Marten method for loading by ID
Exception Handling: Throws ProductNotFoundException for missing products
Route Parameter: ID extracted from URL path

Get Products By Category

Retrieve all products in a specific category.

Handler Implementation

Products/GetProductByCategory/GetProductByCategoryHandler.cs

public record GetProductByCategoryQuery(string Category) : IQuery<GetProductByCategoryResult>;
public record GetProductByCategoryResult(IEnumerable<Product> Products);

internal class GetProductByCategoryQueryHandler(
    IDocumentSession session
) : IQueryHandler<GetProductByCategoryQuery, GetProductByCategoryResult>
{
    public async Task<GetProductByCategoryResult> Handle(
        GetProductByCategoryQuery query, 
        CancellationToken cancellationToken)
    {
        var products = await session.Query<Product>()
            .Where(p => p.Category.Contains(query.Category))
            .ToListAsync(cancellationToken);

        return new GetProductByCategoryResult(products);
    }
}

Endpoint Implementation

Products/GetProductByCategory/GetProductByCategoryEndpoint.cs

public record GetProductByCategoryResponse(IEnumerable<Product> Products);

public class GetProductByCategoryEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapGet("/products/category/{category}", 
            async (string category, ISender sender) =>
        {
            var result = await sender.Send(new GetProductByCategoryQuery(category));
            var response = result.Adapt<GetProductByCategoryResponse>();
            
            return Results.Ok(response);
        })
        .WithName("GetProductByCategory")
        .Produces<GetProductByCategoryResponse>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status400BadRequest)
        .WithSummary("Get Product By Category")
        .WithDescription("Get Product By Category");
    }
}

Key Points

LINQ Query: Uses standard LINQ with Marten
Contains Check: Searches in the Category list property
String Matching: Category parameter is case-sensitive

Update Product

Update an existing product’s information.

Handler Implementation

Products/UpdateProduct/UpdateProductHandler.cs

public record UpdateProductCommand(
    Guid Id, 
    string Name, 
    List<string> Category, 
    string Description, 
    string ImageFile, 
    decimal Price
) : ICommand<UpdateProductResult>;

public record UpdateProductResult(bool IsSuccess);

public class UpdateProductCommandValidator : AbstractValidator<UpdateProductCommand>
{
    public UpdateProductCommandValidator()
    {
        RuleFor(command => command.Id).NotEmpty().WithMessage("Product ID is required");
        RuleFor(command => command.Name)
            .NotEmpty().WithMessage("Name is required")
            .Length(2, 150).WithMessage("Name must be between 2 and 150 characters");
        RuleFor(command => command.Price)
            .GreaterThan(0).WithMessage("Price must be greater than 0");
    }
}

internal class UpdateProductCommandHandler(
    IDocumentSession session
) : ICommandHandler<UpdateProductCommand, UpdateProductResult>
{
    public async Task<UpdateProductResult> Handle(
        UpdateProductCommand command, 
        CancellationToken cancellationToken)
    {
        var product = await session.LoadAsync<Product>(command.Id, cancellationToken);

        if (product is null)
        {
            throw new ProductNotFoundException(command.Id);
        }

        product.Name = command.Name;
        product.Category = command.Category;
        product.Description = command.Description;
        product.ImageFile = command.ImageFile;
        product.Price = command.Price;

        session.Update(product);
        await session.SaveChangesAsync(cancellationToken);

        return new UpdateProductResult(true);
    }
}

Endpoint Implementation

Products/UpdateProduct/UpdateProductEndpoint.cs

public record UpdateProductRequest(
    Guid Id, 
    string Name, 
    List<string> Category, 
    string Description, 
    string ImageFile, 
    decimal Price
);

public record UpdateProductResponse(bool IsSuccess);

public class UpdateProductEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPut("/products", 
            async (UpdateProductRequest request, ISender sender) =>
            {
                var command = request.Adapt<UpdateProductCommand>();
                var result = await sender.Send(command);
                var response = result.Adapt<UpdateProductResponse>();

                return Results.Ok(response);
            })
            .WithName("UpdateProduct")
            .Produces<UpdateProductResponse>(StatusCodes.Status200OK)
            .ProducesProblem(StatusCodes.Status400BadRequest)
            .ProducesProblem(StatusCodes.Status404NotFound)
            .WithSummary("Update Product")
            .WithDescription("Update Product");
    }
}

Key Points

Load and Update: Loads existing product, modifies properties, updates in session
Validation: More restrictive rules including length constraints
404 Response: Returns NotFound if product doesn’t exist

Delete Product

Delete a product from the catalog.

Handler Implementation

Products/DeleteProduct/DeleteProductHandler.cs

public record DeleteProductCommand(Guid Id) : ICommand<DeleteProductResult>;
public record DeleteProductResult(bool IsSuccess);

public class DeleteProductCommandValidator : AbstractValidator<DeleteProductCommand>
{
    public DeleteProductCommandValidator()
    {
        RuleFor(x => x.Id).NotEmpty().WithMessage("Product ID is required");
    }
}

internal class DeleteProductCommandHandler(
    IDocumentSession session
) : ICommandHandler<DeleteProductCommand, DeleteProductResult>
{
    public async Task<DeleteProductResult> Handle(
        DeleteProductCommand command, 
        CancellationToken cancellationToken)
    {
        session.Delete<Product>(command.Id);
        await session.SaveChangesAsync(cancellationToken);

        return new DeleteProductResult(true);
    }
}

Endpoint Implementation

Products/DeleteProduct/DeleteProductEndpoint.cs

public record DeleteProductResponse(bool IsSuccess);

public class DeleteProductEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapDelete("/products/{id}", async (Guid id, ISender sender) =>
        {
            var result = await sender.Send(new DeleteProductCommand(id));
            var response = result.Adapt<DeleteProductResponse>();

            return Results.Ok(response);
        })
        .WithName("DeleteProduct")
        .Produces<DeleteProductResponse>(StatusCodes.Status200OK)
        .ProducesProblem(StatusCodes.Status400BadRequest)
        .ProducesProblem(StatusCodes.Status404NotFound)
        .WithSummary("Delete Product")
        .WithDescription("Delete Product");
    }
}

Key Points

Soft Delete Available: Marten supports soft deletes if configured
Simple Operation: Direct delete by ID
No Verification: Doesn’t check if product exists before deletion

Common Patterns

Object Mapping with Mapster

All endpoints use Mapster for mapping between DTOs:

var command = request.Adapt<CreateProductCommand>();
var response = result.Adapt<CreateProductResponse>();

Dependency Injection

Handlers receive dependencies via primary constructor:

internal class CreateProductCommandHandler(
    IDocumentSession session
) : ICommandHandler<CreateProductCommand, CreateProductResult>

MediatR Integration

All endpoints use ISender to dispatch commands and queries:

var result = await sender.Send(command);

Carter Route Registration

All endpoints implement ICarterModule and register routes:

public class CreateProductEndpoint : ICarterModule
{
    public void AddRoutes(IEndpointRouteBuilder app)
    {
        app.MapPost("/products", async (request, sender) => { ... });
    }
}

Catalog Service

Basket Service

Discount Service

Ordering Service

Feature Organization

Create Product

Handler Implementation

Endpoint Implementation

Key Points

Get Products (Paginated)

Handler Implementation

Endpoint Implementation

Key Points

Get Product By ID

Handler Implementation

Endpoint Implementation

Key Points

Get Products By Category

Handler Implementation

Endpoint Implementation

Key Points

Update Product

Handler Implementation

Endpoint Implementation

Key Points

Delete Product

Handler Implementation

Endpoint Implementation

Key Points

Common Patterns

Object Mapping with Mapster

Dependency Injection

MediatR Integration

Carter Route Registration

Build docs developers (and LLMs) love

Catalog Service

Basket Service

Discount Service

Ordering Service

​Feature Organization

​Create Product

​Handler Implementation

​Endpoint Implementation

​Key Points

​Get Products (Paginated)

​Handler Implementation

​Endpoint Implementation

​Key Points

​Get Product By ID

​Handler Implementation

​Endpoint Implementation

​Key Points

​Get Products By Category

​Handler Implementation

​Endpoint Implementation

​Key Points

​Update Product

​Handler Implementation

​Endpoint Implementation

​Key Points

​Delete Product

​Handler Implementation

​Endpoint Implementation

​Key Points

​Common Patterns

​Object Mapping with Mapster

​Dependency Injection

​MediatR Integration

​Carter Route Registration

Build docs developers (and LLMs) love

Feature Organization

Create Product

Handler Implementation

Endpoint Implementation

Key Points

Get Products (Paginated)

Handler Implementation

Endpoint Implementation

Key Points

Get Product By ID

Handler Implementation

Endpoint Implementation

Key Points

Get Products By Category

Handler Implementation

Endpoint Implementation

Key Points

Update Product

Handler Implementation

Endpoint Implementation

Key Points

Delete Product

Handler Implementation

Endpoint Implementation

Key Points

Common Patterns

Object Mapping with Mapster

Dependency Injection

MediatR Integration

Carter Route Registration