Skip to content

Lesson 5 of 15 · Architectural Styles

Clean Architecture: When the Layers Pay and When They Don't

Advanced•
lesson•
November 16, 2026•
~8 min read

The diagram everyone has seen

If you've read about software architecture in the last decade, you've seen the diagram: four concentric circles, with the outer ring labeled "Frameworks & Drivers", the next "Interface Adapters", the next "Application Business Rules" (use cases), and the innermost "Enterprise Business Rules" (entities). Martin's post names the rule that governs the rings "The Dependency Rule".

Four concentric rings. Entities (Reservation, Guest) sit in the centre, then use cases (ConfirmReservation, RefundPayment), then interface adapters (controllers, presenters, gateways), then frameworks and drivers (Laravel, database driver, mailer SDK) on the outside. An arrow labeled "dependencies point inward" points at the centre.

That's Clean Architecture, popularized by Robert Martin in a 2012 blog post and the 2017 book Clean Architecture. It's hexagonal with more circles.

What Clean Architecture says

The textbook structure: four concentric layers, with a strict rule about how dependencies can flow.

The rings, inside-out:

  • Domain Entities. Business rules that exist independent of any application. The "rules of the world" your software models. Money, Reservation, CancellationPolicy. Pure PHP, no framework, no use case awareness.

  • Application Use Cases. Operations the application performs. "Request a reservation", "confirm a reservation", "refund a payment". Each use case orchestrates entities to do one thing the system can do.

  • Interface Adapters. Translators between the use cases and the outside world. Controllers (HTTP → use case input), presenters (use case output → HTTP), gateways (use case → external systems).

  • Frameworks & Drivers. Laravel itself. The database. The HTTP server. The queue. The mail provider. The third-party SDKs.

The single rule: outer layers depend on inner ones, never the reverse. An entity doesn't know what a use case is. A use case doesn't know what a controller is. A controller doesn't know what a database is. The framework doesn't know what your business is.

Same idea as Hexagonal, with more shape

If you read the Hexagonal Architecture lesson carefully, this all sounds familiar. Clean Architecture and Hexagonal Architecture are the same idea expressed slightly differently:

  • Both insist on dependency inversion (dependencies point inward; the D in SOLID).

  • Both put business logic in the middle.

  • Both put the framework on the outside.

  • Both rely on interfaces (ports / boundaries) to allow inner layers to be testable in isolation.

The differences are in the emphasis:

  • Clean Architecture explicitly separates entities (domain) from use cases (application). Hexagonal lumps them as "the application core" and lets you organize the inside however you like.

  • Clean Architecture has formal input boundaries and output boundaries for each use case (the Use Case Interactor pattern). Hexagonal's ports are usually less formal.

  • Clean Architecture talks about the screaming architecture principle: the top-level folder structure should make the application's purpose obvious, before you know what framework it's built on.

  • Clean Architecture has more layered terminology: presenters, controllers, gateways, interactors, request/response models. Hexagonal often gets by with "controller", "use case", and "repository".

The use case interactor pattern

The most distinctive Clean idea is the Interactor: a class that owns one use case, with explicit input and output boundaries.

The use case is five files in Hearth\Booking\RequestReservation, shown one block each. The input boundary is the interface a controller calls:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; interface RequestReservationInputBoundary { public function execute(RequestReservationRequestModel $request): void; }

The request model is the data crossing into the use case:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Hearth\Booking\DateRange; use Hearth\Booking\GuestCount; use Hearth\Booking\GuestId; use Hearth\Booking\RoomId; final readonly class RequestReservationRequestModel { public function __construct( public GuestId $guestId, public RoomId $roomId, public DateRange $stayDates, public GuestCount $guestCount, ) {} }

The output boundary is the presenter interface. Each outcome the use case can report is a method:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; interface RequestReservationOutputBoundary { public function presentSuccess(RequestReservationResponseModel $response): void; public function presentRoomNotAvailable(string $roomId): void; }

The response model is the data leaving the use case:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; final readonly class RequestReservationResponseModel { public function __construct( public string $reservationId, public int $priceCents, public string $currency, ) {} }

The interactor ties them together:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\RequestReservation; use Hearth\Booking\Clock; use Hearth\Booking\Dispatcher; use Hearth\Booking\Reservation\CancellationPolicy; use Hearth\Booking\Reservation\Reservation; use Hearth\Booking\Reservation\Reservations; use Hearth\Booking\ReservationPriceFactory; use Hearth\Booking\Rooms; final readonly class RequestReservationInteractor implements RequestReservationInputBoundary { public function __construct( private Reservations $reservations, private Rooms $rooms, private ReservationPriceFactory $priceFactory, private CancellationPolicy $cancellationPolicy, private Clock $clock, private Dispatcher $events, private RequestReservationOutputBoundary $presenter, ) {} public function execute(RequestReservationRequestModel $request): void { $room = $this->rooms->withId($request->roomId); if ($this->reservations->overlapping($request->roomId, $request->stayDates) !== []) { $this->presenter->presentRoomNotAvailable($request->roomId->toString()); return; } $price = $this->priceFactory->build($room, $request->stayDates, $request->guestCount); $reservation = Reservation::request( $request->guestId, $request->roomId, $request->stayDates, $request->guestCount, $price, $this->cancellationPolicy, $this->clock->now(), ); $this->reservations->save($reservation); foreach ($reservation->releaseEvents() as $event) { $this->events->dispatch($event); } $this->presenter->presentSuccess(new RequestReservationResponseModel( $reservation->id->toString(), $price->amountInCents, $price->currency->isoCode, )); } }

The interactor doesn't return a value. It calls methods on the output boundary (the presenter), which is responsible for shaping the response for the outside world.

The argument for this shape:

  • The use case is testable with a fake presenter.

  • The use case has no idea what the response format is (HTTP, CLI, JSON, gRPC). Different presenters for different drivers.

  • Failure modes are explicit methods on the boundary, instead of exceptions.

The argument against:

  • It's a lot of files for one operation. Five interfaces and classes for a single use case.

  • The "no return value, call the presenter" pattern is unfamiliar to PHP developers used to handlers that return.

  • The benefit (presenter swap) is rare in practice.

In the codebases I've seen that follow Clean ideas, few use the full Interactor pattern with input/output boundaries. They use a command + handler shape (like the handler in the Hexagonal Architecture lesson), with the handler returning a result.

Screaming architecture

The other useful idea Clean popularized is "screaming architecture":

Your architectures should tell readers about the system, not about the frameworks you used in your system.

That is Martin's wording in his 2011 post "Screaming Architecture".

A typical Laravel project has folders like app/Http/Controllers, app/Models, app/Services. You can tell from the layout that it's Laravel. You can't tell what the application does.

A screaming architecture has folders like Booking/, Pricing/, Housekeeping/, GuestProfile/, Payments/. You can tell from the layout that it's a hotel reservation system with pricing, housekeeping, guest profiles, and payment concerns. The framework is invisible at the top level, demoted to subfolders.

This is one of Clean's most applicable ideas in PHP, regardless of whether you adopt the rest of the architecture. The vertical-slice approach is essentially screaming architecture taken seriously.

How Clean shows up in modern Laravel

The next tree illustrates a pragmatic Clean-flavored layout: layers as folders, no boundaries or presenters. The course's own Hearth code uses the vertical slice layout instead.

TEXT
Hearth/Booking/ ├── Domain/ # Entities ├── Application/ # Use Cases ├── Infrastructure/ # Interface Adapters, Frameworks └── Http/ # Interface Adapters

Domain/ holds entities and value objects, Application/ the command and query handlers, Infrastructure/ the Eloquent repository implementations, and Http/ the controllers, requests and resources.

The strict-Clean version would also include input/output boundaries, presenters, request/response models, and interactor interfaces for every use case. The pragmatic version uses commands, handlers that return values, and direct controller-to-handler wiring.

If you read Clean strictly and apply it strictly, you'll write a lot of files for each operation. If you read it as a set of principles (dependency inversion, screaming structure, entities-vs-use-cases distinction), you'll write a codebase that's easier to live with.

What you actually get

The honest list of benefits Clean adds over plain Hexagonal:

  • Explicit entity-vs-use-case distinction. Helps with team conversations: "is this rule on the entity or in the use case?". For domain-heavy products this clarity matters.

  • Screaming architecture as a default. The structure makes the product's purpose obvious. New developers find the right folder fast.

  • Formal use case boundaries. When the team takes them seriously, every use case has its own clear contract for what it accepts and what it produces.

What it doesn't add:

  • Faster development. The extra structure costs upfront time. The payoff is in maintenance, not in time-to-first-version.

  • A guarantee against framework lock-in. Discipline still has to live within the architecture; the structure alone doesn't prevent leaks.

When Clean earns its place over Hexagonal

The two are close enough that the choice is more about emphasis than about substance:

  • Pick Clean when: the team values formal structure, has a domain rich enough to need explicit entity-vs-use-case separation, has people willing to maintain input/output boundaries, and is large enough that the screaming-architecture clarity helps onboarding.

  • Pick Hexagonal when: the team values flexibility in the inner organization, the domain is real but not formally complex, and the lighter ceremony is preferred.

  • Pick neither (or pick Vertical Slice Architecture) when: the team isn't ready for either, the product isn't long-lived, or the framework's defaults will do.

Pitfalls

Treating it as religion. "We're doing Clean Architecture" as a culture identity makes the team defensive about the patterns even when they're hurting. Clean is a tool. If a specific layer or boundary is costing more than it's earning, drop it.

Layer obsession. A team that worries more about "is this in the right layer?" than about "does this work and is it readable?" has lost the plot. The layers are means; the working software is the end.

Boundary explosion. Every use case getting input boundaries, output boundaries, request models, response models, presenters, controllers, and an interactor produces a codebase where one HTTP endpoint corresponds to seven files.

Ignoring the framework. Clean Architecture suggests treating the framework as a "detail" you can swap. I have not seen a team swap its framework. Trying to maintain pristine framework-independence at the cost of friction with the framework is paying for flexibility you'll never use.

The one thing to remember

Clean Architecture is Hexagonal with more rings, more terms, and stronger opinions about where things go. The principles (dependency inversion, business rules in the middle, framework on the outside, structure that screams what the app does) are real and useful. The full ceremony (interactors with input/output boundaries, presenters that don't return values) earns its place in specific contexts and should be skipped in others.

Course Content