It's the Project Paradox, and it's how legacy systems are born. You rush past domain exploration, celebrate quick technical progress, and end up building something that doesn't solve the actual business problem.

Event Storming breaks this cycle. It's a collaborative workshop technique created by Alberto Brandolini that puts sticky notes on a wall and forces everyone in the room to confront reality together, before a single line of code gets written.

I've used it on many projects ranging from enterprise platforms to multi-tenant SaaS products. Every time, the same thing happens: people who thought they agreed on how the business process works discover they don't. And that discovery, made on Day 3 instead of Month 6, saves the project.

Domain Events: Why Start There?

An event in Event Storming is a business fact. Something that already happened. Past tense. Always.

Contract Signed. Invoice Sent. Appointment Scheduled. Patient Registered.

This matters because it keeps the conversation grounded. When people write in past tense, they describe reality. When they write in present or future tense, they speculate. And speculation during discovery leads to building features nobody needs.

There's another reason past-tense verbs work so well: they cut through language confusion. Different departments often use the same noun - "Order", "Client", "Contract" - to mean completely different things. But when you say "Order Placed" versus "Order Shipped", the ambiguity disappears. Events reveal hidden boundaries that nouns hide.

Think about the start of your own morning: You heard the alarm -> You switched it off -> You got dressed -> You had breakfast. Each of those is an event. Stringing them together creates a timeline. And that timeline reveals how a process actually works.

Event Storming is, at its core, putting these events on a wall where everyone can see them. You visualize what happens in a business process and then do something with it.

From Events to Domain Modeling

Events are just what you can see on the surface. Underneath them is behavior: the repeating patterns a series of events reveals. Deeper still is system structure, the root causes that drive those patterns.

On one project, a healthcare platform, we started by listing events like "Appointment Requested", "Appointment Confirmed", and "Appointment Cancelled". Simple enough. But when we looked at the pattern, we noticed that "Appointment Cancelled" appeared far more often than anyone expected. That led us to the root cause: the scheduling rules were so rigid that patients couldn't find available slots, so they'd book anything and cancel later. The events told us what was happening. The patterns told us why.

When you run an Event Storming workshop, you start at the surface and work your way down. You're either changing an existing system for the better or designing a new one that produces the events you actually want.

The Toolkit: What You Actually Need

For an in-person Big Picture workshop, the requirements are simple. A long wall, a paper roll to cover it, plenty of orange sticky notes, markers for everyone, food and coffee, and no chairs. Standing keeps energy high. Hunger kills it.

For remote sessions, a collaborative whiteboard like Miro works. But know that remote workshops require extra structure. Split them into 1.5-hour sessions across multiple days, use breakout rooms, and find a co-facilitator. Running a remote Event Storming session alone is a bad idea.

Four sticky note types drive a Big Picture session:

Event

Orange notes for Domain Events. The business facts. The backbone of the entire exercise.

Hot Spot

Red notes for Hot Spots. Questions nobody can answer, risks nobody has addressed, or topics that spark heated disagreement. I pay more attention to these than anything else on the wall - they're the problems that will surface in production if you don't address them now.

External System

Pink notes for External Systems. Payment gateways, third-party APIs, Excel sheets etc. Systems or tools you don't control but that shape your process.

Comment

Yellow notes for Comments. Extra context, clarifications, or observations that don't fit neatly into the other categories.

Keep a visible legend on the wall throughout the session. First-timers forget which color means what, and stopping to explain it five times kills momentum.

Three Levels of Detail

Event Storming isn't a single technique. It scales across three levels, each suited to a different stage of understanding.

Big Picture

Gives you the general overview. You identify key business events, order them in time, and find major pain points. This is where beginners should start, and it's where most of the strategic value lives.

Process Level

Goes deeper. You add detail to the map by adding:

• Actors - who triggers the event?

• Commands - what action is requested?

• Policies - what automated rules apply?

• Read models - what data does someone need to make a decision?

Design Level

The most detailed. Here, participants group related business rules into aggregates, define pre-conditions and post-conditions, and sometimes write pseudo-code directly on sticky notes. At this level, you're approaching code-ready models, the kind that map to actual project folders and feature slices in your solution.

The Big Picture session is where 80% of the strategic insight comes from. It's also where the cross-functional conversations happen between people who rarely talk to each other. Don't skip it by jumping straight into Design Level. That's a common mistake.

Running a Big Picture Workshop: Four Steps

Here's how a typical Big Picture session runs.

Step 1: The Storm

Everyone gets orange sticky notes and markers. Write down every business event you can think of. Post them on the wall. No wrong answers. The goal is volume. One rule: focus on business events, not technical ones. "Contract Signed" belongs. "Button Clicked" or "Request Sent to API" doesn't. Those details are noise at this level.

When you see a note that's clearly technical or too vague, don't call the person out. Just rotate it 45 degrees. That's the signal it needs revisiting. It keeps the energy up without embarrassing anyone.

Step 2: The Timeline

Take all those chaotic orange notes and arrange them chronologically, left to right. The result is a long horizontal line, often called the "snake." This is where gaps become visible. When two events sit next to each other but the team can't explain what connects them, you've found a blind spot.

Do this silently at first. When people talk while sorting, one or two confident voices take over and the timeline reflects their mental model, not the team's. Silent sorting forces everyone to engage physically with the material. Disagreements surface naturally when two people try to place the same event in different spots - that's the conversation you want.

Step 3: Pivotal Events

Identify the turning points in the process. They share two characteristics. First, they mark moments where actions become hard to undo. Once an invoice is sent, reversing it costs real money and effort. Second, they often signal a switch of actors, where responsibility shifts from one person or department to another. Mark these with a vertical separator on the wall.

Step 4: Grouping and Naming

Pivotal events create natural boundaries. The linear snake breaks into meaningful segments. Let the domain experts name these groups. This turns a flat timeline into a high-level map of the business domain. In DDD terms, these named groups map directly to Bounded Contexts.

Before the session ends, do a quick Vote. Give everyone three to five sticky arrows and ask them to mark the area of the board they think is the most critical problem to solve. You don't need consensus. You need to see where attention is clustering. That becomes the input for your next workshop.

Why This Matters for Your Architecture

The groups you discover in Step 4 aren't just organizational labels. They're the starting point for your system's module boundaries.

I've seen teams spend weeks debating module boundaries in meeting rooms, drawing boxes on whiteboards that looked clean but had no connection to how the business actually worked. Event Storming shortcuts that. The groups you discover aren't based on someone's mental model of what the system should look like. They come from how the business actually operates.

And that connects to something I care a lot about in architecture: removability. If your module boundaries match the natural seams of the business, each module becomes replaceable. You can drop a bad idea without the rest of the system collapsing. Not perfect architecture on day one, but architecture that can evolve. That's what you're after. (I wrote about how this plays out in practice in Vertical Slice Architecture Folder Structure: 4 Approaches Compared.

Pre-Workshop Checklist

Before you run your first session, cover these basics:

• Get a sponsor with authority to send the invitation. Not just someone who thinks it's a good idea — someone who will act on the findings afterward. Without that commitment, the wall of sticky notes goes nowhere.

• Define scope to one or two concrete use cases / processes. Don't try to map the entire domain.

• Assemble the right people. Roughly half domain experts, half technical. Keep it under 10 participants.

• Run a 15-30 minute briefing beforehand so everyone arrives with shared context.

• Prepare the physical space. Long wall. Paper roll. Markers. Plenty of orange stickies. Food. No chairs.

Don't Map the Mess

If you're working on a legacy system, don't model the as-is state. I made this mistake early on. We spent an entire session mapping how a healthcare scheduling platform currently worked, and all it did was depress the room. Everyone already knew the system was broken. What they needed was a shared picture of where they were going. Event Storm the target vision. Design the future, don't document the mess.

What You Walk Away With

The single most valuable outcome of an Event Storming session isn't the wall of sticky notes. It's the shared understanding that forms in the minds of everyone who participated.

You could photograph the board and throw the stickies in the bin. The session was still a success if the team is aligned. That alignment — between business and technical, between what the system does and what the business needs — is what makes the difference between architecture that holds up and architecture you're rewriting in two years.

By the end of the workshop, you have a clear map: the subdomains, the boundaries, and where the natural module seams are. That's your starting point for architecture decisions that hold up as the system grows.

Quick-Start Checklist

If you want to run your first Big Picture session this week, here's the short version:

• Get a sponsor to send the invite and commit to acting on the findings

• Set the scope (1-2 use cases max)

• Assemble 6-10 people, half domain experts, half technical

• Run a 15-minute briefing so everyone shows up with shared context

• Storm: everyone writes orange sticky notes with business events (rotate bad ones 45°)

• Timeline: arrange events left to right, silently first - let disagreements surface naturally

• Pivotal Events: mark the turning points with vertical separators

• Group and Name: let domain experts label the segments

• Vote: mark the most critical problem area before leaving the room

• Capture Hot Spots as action items

Event Storming sits between Big Up-Front Design and pure emergent design. Enough structure to align everyone, not so much that you're buried in details before writing a line of code. If your team is about to start a new project, or if your current system has grown into something nobody fully understands, put sticky notes on a wall. The conversations they trigger will save you months of rework.

But here's the question I hear most often after teams run their first workshop: "We have a wall full of sticky notes. Now what?"

And it's exactly what I'll cover in the next article in this series.

If you're planning your first Event Storming session and want a second pair of eyes on your approach, contact me directly and I'll help you set it up right.

I've tried all the common approaches. Some blew up at scale. Others worked fine until someone tried to extract a microservice. Here are four that actually hold up—and when to use each.

The choice depends on your team size, domain complexity, and how much ceremony you're willing to tolerate.

This article is part of the Vertical Slice Architecture Series, which covers implementation patterns, architecture comparisons, and hands-on guides.

Why Folder Structure Matters in VSA

Vertical Slice Architecture promises that code which changes together lives together. Your folder structure is what makes that promise real.

Get it right, and your codebase becomes a "screaming architecture." One look at the folder tree tells you what the system does. Get it wrong, and you end up with "grep architecture," where you need search to find anything.

The difference is stark. In a well-organized VSA project, a new developer can open the solution, see folders like Scheduling, Prescriptions, and Billing, and grasp the business capabilities within seconds. They don't need to ask "where does the appointment booking logic live?" The structure answers that question.

Bad structure, on the other hand, creates friction. You waste time navigating. You accidentally duplicate code because you didn't realize it already existed somewhere else. You hesitate to delete features because you're not sure what depends on what.

Jimmy Bogard, who coined the term Vertical Slice Architecture: take all code related to a single user request—from the UI to the database—and move it to a single location on disk. That's the north star. The four approaches below are different ways to achieve it.

Want my recommendation? Skip to My Recommended Structure. But understanding the trade-offs will help you adapt it to your context.

Approach 1: Feature-Based Folders

This approach creates a separate folder for each feature, with multiple files inside representing different concerns.

Structure Overview

src/
└── Features/
    └── Scheduling/
        └── BookAppointment/
            ├── BookAppointmentCommand.cs
            ├── BookAppointmentHandler.cs
            ├── BookAppointmentValidator.cs
            ├── BookAppointmentEndpoint.cs
            └── BookAppointmentResult.cs

Each feature gets its own folder. Inside, you'll find separate files for the command/query, handler, validator, endpoint, and any DTOs. This mirrors the "one class per file" convention that many .NET teams follow.

Trade-offs

The big win: clear separation makes IDE navigation straightforward. Git diffs show exactly which concern changed (handler vs. validator). Code generation tools that create one file per class work out of the box.

The downside: many small files mean lots of folder drilling to understand a complete feature. For simple CRUD operations, the overhead feels excessive. You'll end up with dozens of folders even for a modest application. And renaming a feature? You're updating multiple files and folders.

When It Works

Large teams where multiple developers work on different aspects of the same feature simultaneously. The file separation creates natural ownership boundaries. It's also a good fit when your features have real complexity—five separate files make sense when each file contains substantial logic. For a handler that's 10 lines, it's overkill.

Approach 2: Single File with Nested Classes

This approach collapses everything for a feature into one file using nested classes.

Structure Overview

src/
└── Application/
    └── Scheduling/
        ├── BookAppointment.cs
        ├── CancelAppointment.cs
        ├── CompleteAppointment.cs
        ├── GetAppointments.cs
        └── GetAppointmentById.cs

One file, one feature. The file contains the command/query record, validator, handler, and endpoint as nested classes inside a static outer class. Here's what it looks like in practice, from my Vertical Slice Architecture template:

public static class BookAppointment
{
    public record Command(
        Guid PatientId,
        Guid DoctorId,
        DateTimeOffset Start,
        DateTimeOffset End,
        string? Notes) : IRequest<ErrorOr<Result>>;

    public record Result(Guid Id, DateTime StartUtc, DateTime EndUtc);

    internal static class Endpoint
    {
        public static async Task<IResult> Handle(
            Command command,
            ISender mediator)
        {
            var result = await mediator.Send(command);
            return result.Match(
                success => Results.Created($"/api/appointments/{success.Id}", success),
                errors => MinimalApiProblemHelper.Problem(errors));
        }
    }

    internal sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(v => v.PatientId).NotEmpty();
            RuleFor(v => v.DoctorId).NotEmpty();
            RuleFor(v => v.Start).LessThan(v => v.End)
                .WithMessage("Start time must be before end time");
        }
    }

    internal sealed class Handler(ApplicationDbContext context)
        : IRequestHandler<Command, ErrorOr<Result>>
    {
        public async Task<ErrorOr<Result>> Handle(
            Command request, CancellationToken ct)
        {
            // Check for conflicts, create appointment, save...
            var appointment = Appointment.Schedule(
                request.PatientId, request.DoctorId,
                request.Start.UtcDateTime, request.End.UtcDateTime,
                request.Notes);

            context.Appointments.Add(appointment);
            await context.SaveChangesAsync(ct);

            return new Result(appointment.Id,
                appointment.StartUtc, appointment.EndUtc);
        }
    }
}

Pros and Cons

Pros:

• Everything in one place—no jumping between files to understand a feature
• Deleting a feature means deleting one file
• Reduces ceremony for simple features
• The file name (BookAppointment.cs) is self-documenting
• Easier to move or refactor entire features

Cons:

• Files can grow large for complex features (300+ lines isn't unusual)
• Some developers dislike nested classes and find them harder to read
• IDE navigation within the file requires folding/unfolding
• Code generation tools may need customization

When to Use This Approach

This is my preferred approach for small to medium teams building CRUD-heavy applications. When feature cohesion matters more than file size, this structure keeps you moving fast. Putting all related code close together eliminates the "scatter" problem.

The cognitive load argument is strong: when you open BookAppointment.cs, you see everything. No context switching. No wondering where the validator lives.

Want to try this approach? Check out the Vertical Slice Architecture template or follow the Quick Start Guide to set it up.

Approach 3: Hybrid Clean + VSA

This approach keeps some horizontal layers (like a shared Domain) while organizing the Application layer by feature.

Structure Overview

src/
├── Api/
│   └── Program.cs
│
├── Domain/                    # Shared domain entities
│   ├── Appointment.cs
│   ├── Patient.cs
│   └── Doctor.cs
│
├── Application/               # Feature slices
│   ├── Scheduling/
│   │   ├── BookAppointment.cs
│   │   └── CancelAppointment.cs
│   └── Prescriptions/
│       └── CreatePrescription.cs
│
└── Infrastructure/            # Shared infrastructure
    └── Persistence/
        └── ApplicationDbContext.cs

The Domain and Infrastructure remain as shared horizontal layers. The Application layer uses vertical slices. This is essentially Clean Architecture with the Application layer reorganized by feature.

Why Teams Choose This

It's familiar. Teams coming from Clean Architecture don't have to unlearn everything. The domain model stays protected in its own layer. You get a gradual migration path—change the Application layer now, deal with the rest later.

The Catch

You still jump between layers (Domain → Application → Infrastructure). There's a real risk of drifting back toward pure Clean Architecture over time. That "protected domain" layer? It often becomes a shared dumping ground. And you won't get full isolation—features still reach across layers.

When It Makes Sense

Teams migrating from Clean Architecture who want feature organization without abandoning familiar patterns. Also appropriate when you have a genuinely complex domain model that benefits from isolation—if your Appointment entity has complex business rules enforced through invariants, keeping it in a dedicated Domain layer is reasonable.

The risk: teams often adopt this as a stepping stone to "real" VSA but never complete the journey. If the hybrid becomes permanent, make that decision intentionally.

Approach 4: Domain-Organized Slices

This approach organizes top-level folders by bounded context or business domain, with each domain containing its own features, entities, and infrastructure.

Structure Overview

src/
├── Api/
│   └── Program.cs
│
├── Scheduling/                # Bounded context
│   ├── Features/
│   │   ├── BookAppointment.cs
│   │   ├── CancelAppointment.cs
│   │   └── GetAppointments.cs
│   ├── Domain/
│   │   └── Appointment.cs
│   └── Infrastructure/
│       └── SchedulingDbContext.cs
│
├── Prescriptions/             # Bounded context
│   ├── Features/
│   │   └── CreatePrescription.cs
│   ├── Domain/
│   │   └── Prescription.cs
│   └── Infrastructure/
│       └── PrescriptionsDbContext.cs
│
└── Shared/                    # Cross-cutting kernel
    └── Common/
        └── AuditableEntity.cs

Each bounded context is self-contained. It has its own features, domain entities, and infrastructure. The only shared code lives in a Shared or Kernel folder for truly cross-cutting concerns.

Pros and Cons

Pros:

• Natural path to a modular monolith
• Clear bounded context boundaries from day one
• Each domain can evolve independently (different patterns, different complexity)
• Easy to extract into microservices later if needed

Cons:

• May duplicate common infrastructure (separate DbContexts, separate validators)
• Requires upfront domain knowledge to draw the right boundaries
• More complex project structure for small applications
• Risk of creating artificial boundaries that don't match the business

When to Use This Approach

This is the right choice when you're building a system that you expect to split into modules or microservices. If multiple teams will own different business domains, this structure sets clear ownership boundaries from the start.

It's also appropriate when bounded contexts are well-defined—because you've already done the collaborative discovery work. Techniques like Event Storming or Domain Storytelling help teams build shared understanding of the business domain before writing code. If you've been through workshops like these and can articulate the key use cases, processes, and where one domain ends and another begins ("Scheduling is separate from Prescriptions because..."), domain-organized slices are the obvious choice.

If you haven't done this discovery work yet, start with a simpler approach and refactor when the domain boundaries become clear through experience.

My Recommended Structure

I combine Approach 4 (domain-organized slices) at the top level with Approach 2 (single file) inside each feature. Here's what it looks like in my Vertical Slice Architecture template:

src/
├── Api/                          # ASP.NET Core entry point
│   └── Program.cs
│
└── Application/                  # All features and domain logic
    ├── Scheduling/               # Feature slice folder
    │   ├── BookAppointment.cs    # Command + Validator + Handler + Endpoint
    │   ├── CancelAppointment.cs
    │   ├── CompleteAppointment.cs
    │   ├── GetAppointments.cs
    │   ├── GetAppointmentById.cs
    │   └── AppointmentDto.cs     # Shared DTO for the feature area
    │
    ├── Domain/                   # Domain entities and events
    │   ├── Appointment.cs
    │   ├── Patient.cs
    │   └── Doctor.cs
    │
    ├── Common/                   # Shared infrastructure
    │   ├── Behaviours/
    │   └── Models/
    │
    └── Infrastructure/           # Data access
        └── Persistence/
            └── ApplicationDbContext.cs

Why this combination?

The domain-organized top level (Scheduling/, Domain/, Common/) gives me clear navigation and screaming architecture. I can see the business capabilities at a glance. The single-file features inside each area minimize ceremony and keep related code together.

The Common/ and Infrastructure/ folders hold genuinely shared code—MediatR behaviors, validation filters, the DbContext. These are things every feature needs, so centralizing them makes sense. But feature-specific logic stays in feature files.

This structure works for most projects I encounter: complex enough to need organization, but not so large that separate bounded context projects are justified. Start here, evolve when needed.

Common Mistakes to Avoid

Creating a "Shared" folder that becomes a dumping ground. Every team does this. You create Shared/ or Common/ for genuinely cross-cutting code, and within months it contains business logic that belongs in specific features. Be ruthless: if code relates to a specific feature, it lives with that feature. Only true infrastructure belongs in shared folders.

Mixing approaches inconsistently. Pick one approach and stick with it across the codebase. I've seen projects where half the features use single files and half use separate folders. The cognitive overhead of switching mental models as you navigate the code is significant. Consistency matters more than picking the "perfect" approach.

Over-engineering folder structure before you have features. Don't create elaborate hierarchies for a system that has three endpoints. Start flat, and add structure when you feel the pain. Premature organization is just as problematic as premature optimization.

Ignoring the "screaming architecture" test. Periodically ask: can a new developer look at this folder structure and understand what the system does? If they see Controllers/, Services/, Repositories/ instead of Scheduling/, Prescriptions/, Billing/, your structure is screaming about technology instead of business capabilities.

Picking the Right Approach

There's no universally correct answer. The best structure is the one your team can maintain consistently.

Start with the single-file approach (Approach 2) if you're unsure. It delivers most of the VSA benefits with minimal overhead. You can always refactor toward feature folders or domain organization as your application grows.

For a deeper dive into Vertical Slice Architecture itself—including CQRS patterns, MediatR setup, and testing strategies—see Vertical Slice Architecture in .NET 10: The Ultimate Guide or explore how VSA compares to Clean Architecture.

Stop debating folder structure in code reviews. Clone the Vertical Slice Architecture template and start building. It uses the single-file approach with domain organization - the combination I recommend for most .NET projects.

This guide walks you through cloning the template, running it, understanding its structure, and adding your first feature.

What's Included in the Template

The Vertical Slice Architecture template models a medical clinic appointment scheduling system. Patients book appointments with doctors, and the system enforces real-world constraints: no double-booking, appointments scheduled in advance, and controlled state transitions.

Features implemented:

Tech stack:

• .NET 10 Minimal APIs
• MediatR for request/response pattern
• FluentValidation for declarative validation
• ErrorOr for result pattern error handling
• Entity Framework Core 10 (in-memory or SQL Server)
• xUnit + FluentAssertions for testing

The template has over 540 stars on GitHub. It's not production-ready as-is. Think of it as a learning tool that shows patterns you can adapt for your own projects.

Prerequisites

.NET 10 SDK

Download from dot.net. Verify your installation:

dotnet --version
# Should output 10.0.x

IDE Options

Pick what works for you:

• Visual Studio 2022 (17.8+) — Full IDE experience, best debugging
• JetBrains Rider — Cross-platform, strong refactoring tools
• VS Code — Lightweight, free

Optional: Docker for SQL Server

The template runs with an in-memory database by default—no setup required. If you want persistent data with SQL Server, you'll need Docker:

docker pull mcr.microsoft.com/azure-sql-edge:latest

Azure SQL Edge works on all platforms including Apple Silicon.

Installation and Setup

Clone the Repository

git clone https://github.com/nadirbad/VerticalSliceArchitecture.git
cd VerticalSliceArchitecture

Database Configuration

Option 1: In-Memory (Default)

Nothing to configure. The template uses an in-memory database by default. Sample data gets seeded automatically in development mode.

Option 2: SQL Server

Start a SQL Server container:

docker run --cap-add SYS_PTRACE -e 'ACCEPT_EULA=1' -e 'MSSQL_SA_PASSWORD=yourStrong(!)Password' -p 1433:1433 --name azuresqledge -d mcr.microsoft.com/azure-sql-edge

Update src/Api/appsettings.json:

{
  "UseInMemoryDatabase": false,
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=VerticalSliceDb;User Id=sa;Password=yourStrong(!)Password;TrustServerCertificate=True"
  }
}

Apply migrations:

dotnet ef database update --project src/Application --startup-project src/Api

Running the API

dotnet run --project src/Api/Api.csproj

Open https://localhost:7098 in your browser. Swagger UI loads at the root with sample patient and doctor IDs ready to use.

Try booking an appointment:

curl -X POST https://localhost:7098/api/appointments \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "11111111-1111-1111-1111-111111111111",
    "doctorId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "start": "2027-01-20T09:00:00Z",
    "end": "2027-01-20T09:30:00Z",
    "notes": "Annual checkup"
  }'

Exploring the Codebase

Solution Structure

src/
├── Api/                          # ASP.NET Core entry point
│   └── Program.cs                # Minimal hosting, Swagger config
│
└── Application/                  # All features and domain logic
    ├── Scheduling/               # Feature slices
    │   ├── BookAppointment.cs
    │   ├── CancelAppointment.cs
    │   ├── CompleteAppointment.cs
    │   ├── GetAppointments.cs
    │   └── GetAppointmentById.cs
    │
    ├── Domain/                   # Entities and domain events
    │   ├── Appointment.cs
    │   ├── Patient.cs
    │   └── Doctor.cs
    │
    ├── Common/                   # Shared infrastructure
    │   └── Behaviours/           # MediatR pipeline behaviors
    │
    └── Infrastructure/
        └── Persistence/          # EF Core DbContext

Notice the Scheduling/ folder. Each file is a complete feature—command, validator, handler, and endpoint in one place. No jumping between Controllers, Services, and Repositories folders. For a deeper dive into folder organization options, see VSA Folder Structure: 4 Approaches Compared.

Feature Anatomy

Open BookAppointment.cs. A single file contains four components:

public static class BookAppointment
{
    // 1. Command - What the caller sends
    public record Command(
        Guid PatientId,
        Guid DoctorId,
        DateTimeOffset Start,
        DateTimeOffset End,
        string? Notes) : IRequest<ErrorOr<Result>>;

    // 2. Result - What the caller gets back
    public record Result(Guid Id, DateTime StartUtc, DateTime EndUtc);

    // 3. Endpoint - HTTP binding
    internal static class Endpoint
    {
        public static async Task<IResult> Handle(
            Command command,
            ISender mediator)
        {
            var result = await mediator.Send(command);
            return result.Match(
                success => Results.Created($"/api/appointments/{success.Id}", success),
                errors => MinimalApiProblemHelper.Problem(errors));
        }
    }

    // 4. Validator - Input validation
    internal sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(v => v.PatientId).NotEmpty();
            RuleFor(v => v.DoctorId).NotEmpty();
            RuleFor(v => v.Start).LessThan(v => v.End);
            // ... more rules
        }
    }

    // 5. Handler - Business logic
    internal sealed class Handler : IRequestHandler<Command, ErrorOr<Result>>
    {
        public async Task<ErrorOr<Result>> Handle(
            Command request,
            CancellationToken cancellationToken)
        {
            // Check conflicts, create appointment, save
        }
    }
}

Everything for booking an appointment lives in one file. When requirements change, you modify one file. When you review a PR, you see the complete context.

Testing Setup

Tests mirror the feature structure:

dotnet test

# Unit tests - validators and domain logic
dotnet test tests/Application.UnitTests

# Integration tests - API endpoints
dotnet test tests/Application.IntegrationTests

Unit tests use FluentValidation's TestValidate helper:

public class BookAppointmentValidatorTests
{
    private readonly BookAppointment.Validator _validator = new();

    [Fact]
    public void Should_Have_Error_When_PatientId_Is_Empty()
    {
        var command = new BookAppointment.Command(
            Guid.Empty, Guid.NewGuid(),
            DateTimeOffset.UtcNow.AddHours(1),
            DateTimeOffset.UtcNow.AddHours(2),
            null);

        var result = _validator.TestValidate(command);
        result.ShouldHaveValidationErrorFor(x => x.PatientId);
    }
}

Creating Your First Feature

Let's add a RescheduleAppointment feature that moves an existing appointment to a new time slot.

Step 1: Create the Feature File

Create src/Application/Scheduling/RescheduleAppointment.cs:

using ErrorOr;
using FluentValidation;
using MediatR;
using Microsoft.AspNetCore.Http;
using Microsoft.EntityFrameworkCore;
using VerticalSliceArchitecture.Application.Common;
using VerticalSliceArchitecture.Application.Domain;
using VerticalSliceArchitecture.Application.Infrastructure.Persistence;

namespace VerticalSliceArchitecture.Application.Scheduling;

public static class RescheduleAppointment
{
    public record Command(
        Guid AppointmentId,
        DateTimeOffset NewStart,
        DateTimeOffset NewEnd) : IRequest<ErrorOr<Result>>;

    public record Result(Guid Id, DateTime StartUtc, DateTime EndUtc);

    internal static class Endpoint
    {
        public static async Task<IResult> Handle(
            Guid appointmentId,
            Command command,
            ISender mediator)
        {
            if (appointmentId != command.AppointmentId)
            {
                return Results.BadRequest(new { error = "Route ID does not match command" });
            }

            var result = await mediator.Send(command);
            return result.Match(
                success => Results.Ok(success),
                errors => MinimalApiProblemHelper.Problem(errors));
        }
    }

    internal sealed class Validator : AbstractValidator<Command>
    {
        public Validator()
        {
            RuleFor(v => v.AppointmentId).NotEmpty();
            RuleFor(v => v.NewStart).LessThan(v => v.NewEnd)
                .WithMessage("Start time must be before end time");
            RuleFor(v => v.NewStart)
                .Must(start => start > DateTimeOffset.UtcNow.AddMinutes(15))
                .WithMessage("Must reschedule at least 15 minutes in advance");
        }
    }

    internal sealed class Handler(ApplicationDbContext context)
        : IRequestHandler<Command, ErrorOr<Result>>
    {
        public async Task<ErrorOr<Result>> Handle(
            Command request,
            CancellationToken cancellationToken)
        {
            var appointment = await context.Appointments
                .FirstOrDefaultAsync(a => a.Id == request.AppointmentId, cancellationToken);

            if (appointment is null)
            {
                return Error.NotFound("Appointment.NotFound",
                    $"Appointment {request.AppointmentId} not found");
            }

            if (appointment.Status != AppointmentStatus.Scheduled)
            {
                return Error.Validation("Appointment.CannotReschedule",
                    "Only scheduled appointments can be rescheduled");
            }

            // Check for conflicts at new time
            var hasConflict = await context.Appointments
                .AnyAsync(a =>
                    a.Id != request.AppointmentId &&
                    a.DoctorId == appointment.DoctorId &&
                    a.Status == AppointmentStatus.Scheduled &&
                    a.StartUtc < request.NewEnd.UtcDateTime &&
                    a.EndUtc > request.NewStart.UtcDateTime,
                    cancellationToken);

            if (hasConflict)
            {
                return Error.Conflict("Appointment.Conflict",
                    "Doctor has a conflicting appointment at the new time");
            }

            // Update times (you'd add a Reschedule method to the domain entity)
            // For now, this shows the pattern
            await context.SaveChangesAsync(cancellationToken);

            return new Result(appointment.Id, appointment.StartUtc, appointment.EndUtc);
        }
    }
}

Step 2: Register the Endpoint

Open src/Application/Scheduling/AppointmentEndpoints.cs and add:

group.MapPost("/{appointmentId:guid}/reschedule", RescheduleAppointment.Endpoint.Handle)
    .WithName("RescheduleAppointment")
    .WithSummary("Reschedule an existing appointment")
    .Produces<RescheduleAppointment.Result>()
    .ProducesProblem(StatusCodes.Status404NotFound)
    .ProducesProblem(StatusCodes.Status409Conflict);

Step 3: Add a Test

Create tests/Application.UnitTests/Scheduling/RescheduleAppointmentValidatorTests.cs:

using FluentValidation.TestHelper;
using VerticalSliceArchitecture.Application.Scheduling;

namespace VerticalSliceArchitecture.Application.UnitTests.Scheduling;

public class RescheduleAppointmentValidatorTests
{
    private readonly RescheduleAppointment.Validator _validator = new();

    [Fact]
    public void Should_Have_Error_When_Start_After_End()
    {
        var command = new RescheduleAppointment.Command(
            Guid.NewGuid(),
            DateTimeOffset.UtcNow.AddHours(2),
            DateTimeOffset.UtcNow.AddHours(1));

        var result = _validator.TestValidate(command);
        result.ShouldHaveValidationErrorFor(x => x.NewStart);
    }

    [Fact]
    public void Should_Not_Have_Error_When_Valid()
    {
        var start = DateTimeOffset.UtcNow.AddHours(1);
        var command = new RescheduleAppointment.Command(
            Guid.NewGuid(), start, start.AddHours(1));

        var result = _validator.TestValidate(command);
        result.ShouldNotHaveAnyValidationErrors();
    }
}

Run tests to verify:

dotnet test

Customization Options

Switching Databases

The ConfigureServices.cs file controls database selection:

public static IServiceCollection AddInfrastructure(
    this IServiceCollection services,
    IConfiguration configuration)
{
    if (configuration.GetValue<bool>("UseInMemoryDatabase"))
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseInMemoryDatabase("VerticalSliceDb"));
    }
    else
    {
        services.AddDbContext<ApplicationDbContext>(options =>
            options.UseSqlServer(
                configuration.GetConnectionString("DefaultConnection")));
    }
    // ...
}

For PostgreSQL, swap UseSqlServer for UseNpgsql and add the Npgsql.EntityFrameworkCore.PostgreSQL package.

Adding New Domains

The template focuses on scheduling, but you can add parallel domains:

1. Create a new folder under Application/ (e.g., Billing/)
2. Add feature files following the same pattern
3. Create a domain entity in Domain/
4. Register endpoints in a new BillingEndpoints.cs
5. Map endpoints in Program.cs: app.MapBillingEndpoints()

Keep domains isolated. Features within a domain can share its entities, but don't couple domains to each other.

Modifying Pipeline Behaviors

MediatR pipeline behaviors run for every request. The template includes:

• ValidationBehaviour — Runs FluentValidation before the handler
• PerformanceBehaviour — Logs slow requests

Add your own in Common/Behaviours/:

public class LoggingBehaviour<TRequest, TResponse>
    : IPipelineBehavior<TRequest, TResponse>
    where TRequest : IRequest<TResponse>
{
    public async Task<TResponse> Handle(
        TRequest request,
        RequestHandlerDelegate<TResponse> next,
        CancellationToken cancellationToken)
    {
        // Log before
        var response = await next();
        // Log after
        return response;
    }
}

Register in ConfigureServices.cs:

options.AddOpenBehavior(typeof(LoggingBehaviour<,>));

Next Steps

From here:

• Understand the theory: Read Vertical Slice Architecture in .NET: The Ultimate Guide for the architectural reasoning behind this approach
• Compare alternatives: See Vertical Slice vs. Clean Architecture if you're deciding between patterns
• Explore folder options: Check out VSA Folder Structure: 4 Approaches Compared to see different organization strategies
• Contribute: The template repo welcomes issues and PRs

The template is a starting point, not a framework. Take what works for your domain. Skip what doesn't.

Found this useful? Star the GitHub repo to help others discover it.

This comparison applies equally to Onion and Hexagonal architectures, which share Clean Architecture's layered philosophy. The feature-based vs layered architecture debate comes down to where you want your coupling.

So which one fits your project? Let's break it down.

This article is part of my Complete Guide to Vertical Slice Architecture in .NET, which includes a production-ready template with 530+ GitHub stars-featured in NDepend's architecture comparison.

Real-world comparison: This article compares two production-ready templates—Vertical Slice Architecture template for .NET 9 (530+ stars, healthcare domain) and Jason Taylor's Clean Architecture template (17k+ stars, ToDo). All code examples are from these actual codebases.

Clean Architecture: The Layered Approach

Clean Architecture (CA), popularized by Robert C. Martin, organizes code through concentric layers. The key rule: all dependencies point inward toward the core.

• Domain (Core): Business rules and entities live here. This layer depends on nothing else, so database or UI changes can't touch it.

• Application (Use Cases): Application-specific business logic.

• Infrastructure/UI (Outer Rings): The messy stuff: databases, web frameworks, external APIs.

The goal? Keep business logic independent from frameworks and tools. In theory, you could swap your database with minimal pain.

Vertical Slice Architecture: The Feature-First Approach

Vertical Slice Architecture (VSA), coined by Jimmy Bogard, flips the script. Instead of organizing by technical layer, you organize by feature.

A "slice" cuts through the entire stack - from API endpoint to database for one specific use case. The guiding principle: minimize coupling between slices, maximize cohesion within a slice.

When you add a feature in VSA, you're not scattering changes across layers. You're working in one folder that owns everything for that request.

How They Compare

Code Organization

Clean Architecture organizes by type. You get a folder for controllers, another for services, a project for repositories. Classic technical layering.

VSA organizes by capability. Got an "Order Cancellation" feature? There's an OrderCancellation folder with the endpoint, request model, handler, and data access all together. Some call this "Screaming Architecture" because your folder structure tells you what the system does.

The Cohesion Problem

Clean Architecture keeps technical layers loosely coupled. But here's the trade-off: code that changes together (a feature's UI and its database schema) ends up scattered across multiple projects.

VSA takes the opposite bet, following what's sometimes called the code locality principle: artifacts that change together should be grouped together. The API, logic, and database for a feature are naturally coupled—they change together. So keep them together. Less jumping between files to understand what's happening.

Real Example: Adding a Field

Let's trace what happens when you need to add a field to a feature in both architectures. I'll use real examples from production templates.

In Clean Architecture (Jason Taylor's template):

To add a "Tags" field to the TodoItem feature, you touch 8-10 files across 4 projects:

1. Domain/Entities/TodoItem.cs — Add property to entity
2. Application/TodoItems/Commands/CreateTodoItem/CreateTodoItem.cs — Add to command
3. Application/TodoItems/Commands/CreateTodoItem/CreateTodoItemCommandValidator.cs — Add validation rule
4. Application/TodoItems/Commands/UpdateTodoItemDetail/UpdateTodoItemDetail.cs — Add to update command
5. Application/TodoItems/Queries/GetTodoItemsWithPagination/TodoItemBriefDto.cs — Add to list DTO
6. Application/TodoLists/Queries/GetTodos/TodoItemDto.cs — Add to detail DTO
7. Infrastructure/Data/Configurations/TodoItemConfiguration.cs — Add EF Core mapping
8. Web/Endpoints/TodoItems.cs — Update endpoint mappings (if needed)
9. Plus corresponding test files in tests/Application.FunctionalTests/TodoItems/

You also need to rebuild 4 separate projects (Domain, Application, Infrastructure, Web) for the change to compile.

In VSA (my template):

To add a "CancellationCategory" enum field to the CancelAppointment feature, you touch 2-3 files:

1. Application/Domain/Appointment.cs — Add property and update domain method
2. Application/Scheduling/CancelAppointment.cs — Update command, validator, handler
3. Infrastructure/Persistence/Configurations/AppointmentConfiguration.cs — Add EF mapping (if needed)

// In Appointment.cs - Add property
public CancellationCategory? Category { get; private set; }

// Update Cancel method signature
public void Cancel(string reason, CancellationCategory category, DateTime? cancelledAtUtc = null)
{
    // ... existing validation ...
    Category = category;
}

// In CancelAppointment.cs - Update command
public record Command(Guid AppointmentId, string Reason, CancellationCategory Category);

// Add validation
RuleFor(v => v.Category).IsInEnum();

// Use in handler
appointment.Cancel(request.Reason, request.Category);

// In AppointmentConfiguration.cs (optional - only if custom mapping needed)
builder.Property(a => a.Category).HasConversion<int>();

The entire request/response flow lives in one cohesive area. Domain model, slice logic, and persistence config all sit in the Application project.

Change impact: CA scatters changes across layers; VSA contains them in one folder.

Testing

Clean Architecture is mock-heavy. Every layer hides behind interfaces, so your unit tests often end up testing mocks of the layer below. You're testing the wiring, not the behavior.

VSA leans toward integration testing. A slice is a self-contained request/response, so the most useful test exercises the full slice from API to database. Save unit tests for the shared domain model, not the handlers.

Why the difference? In Clean Architecture, the layering makes it natural to test each layer in isolation. In VSA, the handler is so thin (mostly orchestration) that integration tests give you more bang for your buck. You save unit tests for the parts with complex logic domain and validators.

When to Pick Each

VSA Works Well When

• You need to ship fast. Features live in isolation, so you can move quickly without stepping on other code.

• Requirements keep changing. Throwing away a self-contained slice is easier than untangling logic spread across layers.

• Your team is experienced. VSA has fewer guardrails. You need developers who'll recognize when to extract shared domain logic instead of copy-pasting.

• You're building APIs. Request-response systems map naturally to slices.

Clean Architecture Works Well When

• You have complex business rules. The protected domain core gives you a place for rich logic that won't get polluted by infrastructure concerns.

• You actually might swap infrastructure. If there's a real chance you'll change databases or frameworks, CA's abstraction boundaries pay off.

• Your team is newer. The rigid "Controller calls Service calls Repository" structure acts as training wheels. It's harder to make a mess.

The Hybrid: Best of Both?

Here's what I've seen work in practice: organize your top-level structure by features (VSA), but inside complex slices, apply CA principles.

1. Feature folders at the macro level. Each slice owns its endpoint, handler, and simple data access.

2. Domain separation at the micro level. When a slice gets complex, extract domain logic into a separate class.

3. Shared domain model. Multiple slices can reference common entities and value objects that stay persistence-ignorant.

You don't have to pick one religion. Use the structure that fits the complexity at hand.

For detailed folder organization patterns, see VSA Folder Structure: 4 Approaches Compared.

Migrating From Clean Architecture to VSA

If your CA project has turned into "lasagna architecture" with too many layers, you can simplify through defactoring:

1. Inline the abstractions. Move repository and service logic back into the handler for a single feature.

2. Group by feature. Put the endpoint, command, handler, and validator in one folder.

3. Delete the interfaces. If an interface only exists to satisfy the layering, remove it.

This feels wrong at first. You've been taught that more abstraction is better. But if an abstraction doesn't have multiple implementations and doesn't enable testing, it's just noise.

Cross-Cutting Concerns

"But what about logging? Validation? Transactions?"

Use a mediator pipeline (MediatR, Wolverine). Each slice stays simple while behaviors handle the cross-cutting stuff in one place. You get consistency without polluting every handler.

For implementation details, see Vertical Slice Architecture template for .NET 9.

Choosing Based on Your Team

Junior-heavy teams: Lean toward Clean Architecture. The prescriptive rules ("Controller calls Service") keep code organized while people learn. The structure does some of the thinking for them.

Experienced teams: VSA gives you speed. Senior developers have the judgment to refactor procedural code into a rich domain model and abstractions when it makes sense, and to leave simple CRUD operations simple.

Project Complexity Checklist

The Bottom Line

There's no universal winner. Clean Architecture protects complexity but adds ceremony. VSA reduces ceremony but requires discipline.

Start simple. If you're building a straightforward APIs, VSA will get you moving faster. If you're modeling a complex domain with lots of business rules, Clean Architecture's protected core is worth the overhead.

And don't be afraid to mix them. The best architectures I've seen treat this as a spectrum, not a binary choice.

Next Steps

New to the template? Start with the Quick Start Guide to get the healthcare API running in minutes.

Deciding on folder organization? See VSA Folder Structure: 4 Approaches Compared for practical patterns.

Ready to try VSA? Clone the Vertical Slice Architecture template (540+ stars) — a production-ready starting point with healthcare domain examples.

Want the full picture? Read the Complete Guide to Vertical Slice Architecture for implementation details, MediatR patterns, and testing strategies.

My recent exploration of NDepend, thanks to an invitation from Patrick at NDepend, sparked my interest in its potential to enhance my codebase. As a Software Architect, I often use static code analysis tools to enhance code quality, and NDepend didn't disappoint.

Getting Started on Mac

Step 1: Download NDepend

Visit the official NDepend website and download the macOS version. Your download will be a ZIP file containing everything you need.

Step 2: Extract and Set Up

Unzip the downloaded file to a location of your choice. Let's say we've extracted it to ~/NDepend for this guide. All further CLI commands will work as if you extracted NDepend to this path.

Step 3: Install .NET SDK (If You Haven't Already)

NDepend requires the .NET SDK to run. If you don't have it installed, you can download it from the .NET website. Follow the installation instructions specific to macOS.

Step 4: Register Evaluation or a license

This can be done using the dotnet command with the path to your NDepend file.

dotnet ~/Ndepend/net8.0/NDepend.Console.MultiOS.dll --RegEval

After you should see a message like this:

Evaluation registered on this machine

Evaluation 14 days left

Creating a NDepend Project

Recently, I decided to try NDepend on my VerticalSliceArchitecture project. I was pleasantly surprised by the detailed HTML report I received within seconds. The steps I followed were pretty straightforward.

With NDepend and the .NET SDK installed, you're ready to create your first NDepend project. Here's how to do it:

Step 1: Open Terminal

Fire up your Terminal app. We'll be using the command line to run NDepend.

Step 2: Create a NDepend project file

NDepend uses project files (.ndproj) to know what assemblies to analyze. NDepend.Console.MultiOS.dll can be used to create an NDepend project file (.ndproj extension). I created a project by pointing at my solution file e.g.:

dotnet ~/NDepend/net8.0/NDepend.Console.MultiOS.dll --CreateProject ./VerticalSliceArchitecture.ndproj ~/code/VerticalSliceArchitecture/VerticalSliceArchitecture.sln

If successful, you’ll get a confirmation message and the default NDepend project file will be created for analysis of your solution or project.

Running the Analysis

Follow these steps to run your analysis and review the results.

Step 1: Run NDepend Analysis

From the project directory, I run the following command:

dotnet ~/NDepend/net8.0/NDepend.Console.MultiOS.dll VerticalSliceArchitecture.ndproj

Replace VerticalSliceArchitecture.ndproj with the path to your NDepend project file.

Step 2: Review the Results

Once the analysis completes, NDepend will generate a nice HTML report in the NDependOut folder. Open the generated /NDependOut/NDependReport.html report in your browser to explore various metrics, code rules, and potential issues found in your codebase. Since my VerticalSliceArchitecture project code broke some rules, the command line exited non-zero. This is great for build integration where I want to fail if rules get violated.

Here’s a quick glimpse of the detailed insights and analysis you can expect from NDepend:

For a deeper look, explore sample reports from other projects to see the breadth of data and actionable recommendations NDepend provides.

Potential Enhancement

I believe there's always room for improvement. Here are a few suggestions that could refine the user experience further.

Standardize Installation

Incorporating an installation method that aligns with usage of package managers, like Homebrew, or maybe if it is available as dotnet tool would be great. For example executing dotnet tool install ndepend-tool -g sounds quite handy.

Simplifying Command Line Usage

Running the cross-platform executable currently requires a somewhat lengthy command:

dotnet ~/path/to/net8.0/NDepend.Console.MultiOS.dll

The command line executable is used for various actions like creating projects, registering licenses, and running analyses. It could be more intuitive if commands followed a hierarchical command structure e.g. <tool> <command> [subcommand] [options].

These suggestions aim to enhance the efficiency and user experience of NDepend, and that usage is intuitive and self-explanatory.

Missing Exploring Code Architecture Diagrams on macOS

If you are working on Windows and using Visual Studio you will benefit of having graphs and code architecture diagrams like this dependency graph. These graphs are really helpful, and they helped me to improve code architecture of VerticalSliceArchitecture and resolve coupling issues, as noted here on NDepend blog on comparing Clean Architecture and Vertical Slice approach. Here is the example of dependency graph of VerticalSliceArchitecture project:

Luckily, NDepend have plans to add SVG graphs to HTML reports like these:

https://www.ndepend.com/Res/v2020.1/AspNetCore3.1.html

https://www.ndepend.com/Res/v2020.1/DependencyGraph.html

Conclusion

And there you have it! You've successfully set up NDepend on your Mac, analyzed your .NET codebase.

NDepend is a powerful tool in maintaining high-quality code. By regularly analyzing your code, you can catch issues early, adhere to best practices. The tool's analysis capabilities and detailed reports ensure your code remains clean, efficient, well-structured.

While there are opportunities for enhancing the tool's user experience, such as streamlining installation and command structures, availability of graphs in HTML reports, NDepend remains a robust tool in the pursuit of code excellence.

Bonus: Explore NDepend in Action with VerticalSliceArchitecture

If you're looking for a practical example of setting up and running NDepend, check out my VerticalSliceArchitecture GitHub repository.

I've included:

• A complete step-by-step instruction guide for integrating NDepend.

• A helper shell run-ndepend.sh script to streamline the process.

This example demonstrates how NDepend can be used effectively to analyze and enhance a real-world project.