Lesson 6 of 15 · Architectural Styles
Vertical Slice Architecture
The eight-folder change
You add a feature: "guests can cancel a reservation". To implement it, you touch:
app/Http/Controllers/CancelReservationController.phpapp/Http/Requests/CancelReservationRequest.phpapp/Services/CancellationService.phpapp/Models/Reservation.phpapp/Repositories/ReservationRepository.phpapp/Events/ReservationCancelled.phpapp/Listeners/SendCancellationConfirmation.phpapp/Jobs/IssueRefundJob.php
Eight folders. One feature. Each folder also contains files for guests, rooms, rate plans, payments, and a dozen other things. The pull request scrolls forever. The reader of the PR has to context-switch between eight different parts of the codebase to understand a single conceptual change.
This is what horizontal layering looks like in practice. Each layer is a folder. Every feature spreads its files across all the layers. The folders are organized by what kind of code lives here (controllers, services, models, listeners), not by what feature this code serves.
Vertical Slice Architecture is the other organizing principle. Instead of folders by type, folders by feature. Each feature owns its entire stack: controller, request, command, handler, models, events. One folder per feature, top to bottom.
What Vertical Slice Architecture is
Vertical Slice Architecture, described by Jimmy Bogard in a 2018 blog post, is more an organizing principle than a strict architectural style. Bogard's rule is "Minimize coupling between slices, and maximize coupling in a slice." This course applies it with these rules:
The codebase is organized into modules, and each module is organized into slices.
A slice owns one feature or use case.
A slice contains everything the feature needs: input handling, business logic, persistence, output, side effects.
Slices can share things they genuinely share (domain entities, repositories within a module), but they don't share for the sake of it.
There is no formal layer rule, no input/output boundary requirement, no presenter pattern.
The freedom is the strength. You can use Hexagonal-flavored discipline inside a slice (commands, handlers, ports, adapters). You can use Clean-flavored discipline inside a slice (entities, use cases, presenters). You can use plain Laravel inside a slice for simple slices. The slice tells you where the code lives; the patterns inside it are your choice.
The key insight
High cohesion (things that change for the same reason living together) is one of the strongest properties a codebase can have.
A slice is a unit of cohesion. Every file in Hearth/Booking/CancelReservation/ exists for the "cancel reservation" use case. When the cancellation rules change, the changes land in this folder. Almost nothing else is touched. The blast radius of the change matches the boundary of the slice.
A worked slice
A typical vertical slice in this codebase's style:
Hearth/Booking/
├── CancelReservation/
│ ├── CancelReservationController.php # HTTP entry point
│ ├── CancelReservationRequest.php # validation
│ ├── CancelReservationCommand.php # input DTO
│ ├── CancelReservationCommandHandler.php # runs the use case
│ ├── ReservationCancelled.php # domain event
│ └── CancelReservationResource.php # response shape
└── Tests/
├── CancelReservationCommandHandlerTest.php
└── CancelReservationFeatureTest.phpSix files, tightly related, living in one folder, and their two tests in the module's Tests/ folder. The PR for "cancel reservation" is one folder's worth of changes, easy to review.
The email that tells the guest about the cancellation is not in this folder. The Notifications module owns it and listens for ReservationCancelled.
Other slices in Hearth/Booking/:
Hearth/Booking/
├── CancelReservation/ # the slice above
├── RequestReservation/
├── ConfirmReservation/
├── CheckInGuest/
├── Reservation/
│ ├── Reservation.php # shared by the slices
│ └── Reservations.php # shared repository interface
├── Infrastructure/
│ └── EloquentReservations.php # shared persistence
├── Tests/ # the module's tests and fakes
└── BookingServiceProvider.phpEach use case is its own slice. The shared concepts (the Reservation class, the Reservations repository) live at the module level, where everything in the module can reach them, but other modules can't.
The Hearth codebase uses this layout. Every module follows this shape: vertical slices nested inside module folders, with shared concepts living at the module level.
How layers and slices relate
A common confusion: are layers and slices alternatives, or can they coexist?
They coexist. Layers (Hexagonal, Clean) describe dependency direction: which kinds of code can depend on which. Slices describe organization: which folder a file lives in.
Inside a slice, you can have layered structure:
Hearth/Booking/CancelReservation/
├── CancelReservationController.php # presentation
├── CancelReservationCommand.php # application: input
├── CancelReservationCommandHandler.php # application: use case
└── ReservationCancelled.php # domain: eventThe controller depends on the command, and the bus hands it to the handler. The handler depends on the domain. Dependencies still point inward, just inside one slice.
What slices buy you
A few specific benefits:
Easier code review. A PR for one feature is one folder.
Easier deletion. When a feature is removed, the deletion is one folder, plus its route and its
Bus::mapline. (Compare: deleting a feature in a horizontally-layered codebase requires hunting across every layer for the bits that belonged to the removed feature.)Onboarding clarity. "Where does this kind of work live?" has one answer per use case.
Better fit for modern dispatch patterns. Commands and handlers live naturally in slices. The handler-per-use-case pattern aligns with one slice per use case.
The trade-offs
Cross-slice concerns are harder. Authentication, audit logging, metrics, rate limiting, transaction management. These cut across many slices. In a horizontal layout, they have a natural home (a middleware folder, a service folder). In a slice layout, you have to consciously choose where they live (often in module-level shared infrastructure or in framework-level middleware).
Code that's genuinely shared has to be promoted. When two slices want the same domain rule, the rule moves up to the module level. When two modules want it, it moves higher. This requires real judgment: "is this shared by accident, or shared by design?".
Some duplication. Two slices that look similar but aren't really the same feature might have similar code. The duplication is intentional (it's two different concepts that happen to look alike), but it can feel wrong to developers used to extracting shared code.
Less obvious global consistency. With horizontal layers, it's clear how every controller looks. With slices, each slice's controller is in its own folder, and global consistency requires team discipline (and tools like PHPArkitect or Deptrac for enforcement).
When Vertical Slice Architecture earns its place
It earns its place when:
The application has many use cases that don't share much. Distinct features with their own logic.
The team values cohesion over consistency by file kind. "Find everything related to this feature in one place" is more useful than "find every controller in one place".
Code review and feature deletion happen often. Both benefit from the slice structure.
The team is using commands/handlers (or similar) per use case. The slice and the use case map cleanly.
It doesn't earn its place when:
The application is genuinely a single feature with many variations. A single CRUD API with twenty endpoints all behaving similarly might be cleaner with horizontal layering.
Modules vs slices
A slice is one use case.
RequestReservation/,CancelReservation/. Small.A module is a group of related slices, plus their shared concepts.
Booking/,Pricing/,Housekeeping/,GuestProfile/,Payments/. Bigger.
Slices live inside modules. Modules don't depend on each other directly; they communicate through events, or through a contract the calling module defines. The module boundary is the architectural boundary; the slice is the organizational unit within.
A later lesson in this course gets into module boundaries inside a monolith.
Pitfalls
One slice per HTTP endpoint, mechanically. Reading "one slice per use case" as "one slice per route" ends in hundreds of tiny slices, each with one file. The slice is for meaningful use cases. A "list reservations" slice with a single read-only query is a slice; a "get reservation by id" wrapper that's just a parameterized version of "list reservations" is probably not its own slice.
Slice size creep. A slice that grows to twenty files is a slice that probably contains two or three use cases pretending to be one. Split it. The folder boundary should match a real conceptual unit.
Promoting shared code prematurely. Two slices have similar code. Someone extracts it to the module level. The third slice doesn't quite fit, and now the shared code grows flags and conditionals. Premature abstraction at the slice level. Wait for the third occurrence.
Slices that import each other. A slice in Booking/ that calls into a slice in Payments/ directly is a coupling that bypasses the module boundary. Use events, or a contract the calling module defines and the other module implements.
Forgetting cross-cutting concerns. Logging, metrics, transactions, authorization. These cross slices. Don't try to fit them into one slice; let them live in module-level or framework-level code.
The one thing to remember
If you organize the codebase by feature instead of by kind, every change has a smaller blast radius and every PR is easier to review. The slice is the unit of cohesion; the module is the unit of architectural boundary; everything else (commands, handlers, ports, adapters) lives inside that structure.
Related Links
- Vertical Slice Architecture, not Layers!Derek Comartin's CodeOpinion video on organizing code by feature instead of by layer.
- Vertical Slice ArchitectureBogard's 2018 post on why his team moved from onion architecture to slices.
- Organizing Code by Feature using Vertical SlicesDerek Comartin's independent take on the same organizing principle.