Vertical Slice architecture

The problem: one small change, five folders

The sales team wants a new feature: the customer can cancel an order. Our project is organized in folders by layer. So the developer must:

1. Add an action to OrdersController. This controller now has 15 actions.
2. Add a method to OrderService and its interface. This service is 800 lines long.
3. Add a method to OrderRepository.
4. Create a new DTO.
5. Register everything in DI and write tests.

Now we have a few problems:

• The code of one feature is spread out. To understand “how does cancelling an order work?”, you must open five files.
• Shared files grow big. Each feature adds something to OrderService.
• Changing one feature breaks another feature. They all use one service and one repository.
• There are many conflicts (conflict) in Git. Two people who build two different features work on the same file.

The idea: each feature, one slice

Think of the layers like the layers of a cake. A layered structure cuts the cake horizontally: all controllers in one place, all services in one place. A vertical slice cuts the cake vertically: each slice is one feature and has a piece of every layer.

The main idea in one sentence: things that change together should sit together.

Why is this useful?

1. Fast understanding. All the code for cancelling an order is in one file or one folder.
2. Safe changes. A change in cancelling an order does not break placing an order. There is little shared code between them.
3. There are no big shared classes. We no longer have an OrderService with 800 lines.
4. Easy removal. A feature that is no longer needed? Delete its folder.

Each slice, its own approach

One important point of Vertical Slice is this: all slices do not need to look the same. Each slice picks the simplest approach that is enough for its own job.

• Placing an order has many rules. So it uses the Order Aggregate in the domain, the one you saw in the DDD lesson.
• Cancelling an order has one simple rule. It only calls one domain method.
• My orders is read-only. A light query directly on the DbContext is enough. It does not need to go through the domain model.

This is the same idea as CQRS: each slice is either a command or a query.

Code

The folder structure

Shop.Api/
  Features/
    Orders/
      PlaceOrder.cs
      CancelOrder.cs
      GetMyOrders.cs
    Catalog/
      SearchProducts.cs
  Domain/
    Order.cs
  Data/
    ShopDbContext.cs
  Program.cs

A full slice: cancel order

Everything is in one file: the input, the endpoint and the logic.

namespace Shop.Api.Features.Orders;

public static class CancelOrder
{
    public sealed record Request(string Reason);

    public static void Map(IEndpointRouteBuilder app) =>
        app.MapPost("/orders/{id:guid}/cancel", HandleAsync);

    private static async Task<IResult> HandleAsync(
        Guid id, Request request, ShopDbContext db, CancellationToken ct)
    {
        var order = await db.Orders.FindAsync([id], ct);
        if (order is null)
            return TypedResults.NotFound();

        order.Cancel(request.Reason); // the business rule lives in the domain
        await db.SaveChangesAsync(ct);
        return TypedResults.NoContent();
    }
}

A read slice: my orders

namespace Shop.Api.Features.Orders;

public static class GetMyOrders
{
    public sealed record Item(Guid Id, DateTime PlacedAt, OrderStatus Status);

    public static void Map(IEndpointRouteBuilder app) =>
        app.MapGet("/customers/{customerId:guid}/orders", HandleAsync);

    private static Task<List<Item>> HandleAsync(
        Guid customerId, ShopDbContext db, CancellationToken ct) =>
        db.Orders
            .AsNoTracking()
            .Where(o => o.CustomerId == customerId)
            .Select(o => new Item(o.Id, o.PlacedAt, o.Status))
            .ToListAsync(ct);
}

Connecting the slices

var app = builder.Build();

PlaceOrder.Map(app);
CancelOrder.Map(app);
GetMyOrders.Map(app);

app.Run();

Notice a few things:

1. We have no shared OrderService or OrderRepository. Each slice works directly with the DbContext.
2. The business rule is still in the domain. The Cancel method in the Order class checks the rule “a shipped order cannot be cancelled”. The slice only coordinates.
3. You do not need the MediatR library. Many teams build slices with MediatR, but Minimal API alone is enough.

Repetition and shared code

The first worry of teams is: “The code gets repeated!” That is true. Vertical Slice accepts a little repetition, so that features do not get tied together.

• Tolerate repetition that only looks the same. Two queries that look alike today may change tomorrow for different reasons.
• Do not repeat business rules. If a rule is needed in two slices, its place is in the domain.
• Write shared technical work once. Do logging, validation and error handling with middleware or an endpoint filter.

Common mistakes

When to use Vertical Slice?