Skip to content

Lesson 12 of 15 · Living With an Architecture

Choosing a Style Per Module

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

Three extra files to flip one column

A team picked Hexagonal Architecture for their hotel booking codebase and applied it everywhere, on principle, without exception. Every module got a command, a handler, a repository port, an Eloquent adapter behind that port, and a domain object with its own event list. That was the right call for Booking, where a reservation has real invariants to protect: dates that can't overlap, capacity that can't be exceeded, a status that can't skip states.

Then Housekeeping needed the same treatment, because the rule said every module gets the same treatment. Housekeeping's entire job, in this hotel, is tracking whether a room is dirty, clean, or inspected. To let a housekeeper mark a room clean, the team wrote a Rooms port, an EloquentRooms adapter behind it and a second Room domain class with a markClean() method and its own pending-events list, on top of the command, handler and event the operation needed anyway. Those three files exist only to change one column from DIRTY to CLEAN.

Nobody on that team did anything wrong by the rule they were given. The rule itself was wrong for that module. Housekeeping has no invariant worth protecting in a domain object: the hotel doesn't enforce an order between dirty, clean and inspected in software, so the status follows whatever order a housekeeper actually walks the floor. There's no overlap to prevent and no capacity to check. It's a status field with an audit trail.

Isolation is what makes this a local decision

The modular monolith lesson drew a hard line: modules import almost nothing from each other and talk through events or a narrow interface. That boundary is the whole reason a module's internals can be a local decision instead of an application-wide one.

Once Booking can't reach into Housekeeping's classes and Housekeeping can't reach into Booking's, nothing outside a module depends on how that module is built inside. Booking's aggregate, its port, its adapter, none of that is visible past its event classes. Housekeeping's Eloquent model, its controller, none of that is visible past Hearth\Housekeeping\MarkRoomClean\RoomCleaned and its sibling events. The only contract between them is the event, and an event doesn't care whether the module that emitted it has a domain layer at all.

Applying one answer to every module, hexagonal for Booking and hexagonal for Housekeeping alike, is how a team pays hexagonal prices for a CRUD screen.

Five questions, no scoring rubric

These five questions are worth asking about a module before deciding how much structure it gets.

  • How many rules does this module actually enforce? Count the invariants, not the fields. Booking has several: date ranges can't overlap, guest count can't exceed room capacity, a cancelled reservation can't be checked in. Housekeeping has close to none: a status field with three valid values and no ordering constraint.

  • How many ways is it entered? Booking is reached from the web, from a nightly no-show job, and eventually from a channel manager's webhook (the service that sends in bookings from Booking.com and Expedia). Housekeeping is reached from one screen a housekeeper uses on a tablet.

  • How often does it change? A module the team keeps changing earns structure that pays for itself. A module nobody opens doesn't.

  • Does it talk to anything outside the process? Payments calls Stripe over the network, which can time out, retry, or come back with a webhook hours later. A port there absorbs exactly that seam.

  • Would a bug here cost money or an apology? A miscalculated total or a double-booked room costs the business money and the guest trust. A room marked clean a few minutes late costs an apology, if that.

A module that answers most of these toward "yes, this matters" earns the full treatment. A module that answers "no" or "barely" across the board is over-served by it. In my experience most modules land somewhere in between.

The five modules, five verdicts

Four of these are Hearth modules from the modular monolith lesson. Reporting is a fifth, a read-only module added here because it sits at the thin end of the range.

Module

Verdict

Why

Booking

Full hexagonal-flavored treatment: command, handler, port, adapter, aggregate

Several real invariants, several entry points (web, no-show job, eventual channel-manager webhook), the module the team touches most, and a bug here costs a double-booked room.

Pricing

A domain layer, fewer ports

Rate calculation has real rules worth keeping framework-free. It reads rate plans and returns a price, and talks to nothing outside the process, so it needs a port for rate plans and not much else.

Payments

Ports, thinner domain

Few rules of its own, but it talks to Stripe over the network, and that seam is exactly what a port exists to absorb.

Housekeeping

Active Record: an Eloquent model with domain methods, no port

Almost no invariants, one entry point, changes rarely, touches nothing outside the process, and a late cleanup costs an apology at worst.

Reporting

No domain layer at all

Pure read side: listeners update denormalized tables, a controller queries them with SQL. There's no write path to protect.

Booking and Reporting are the two ends of the range on purpose. Everything else sits between them, closer to whichever end its own answers point at.

Same shape, two modules

Two operations, checking a guest in for Booking and marking a room clean for Housekeeping, are the same shape: a status flip triggered by one person doing one thing. Written for the style each module earned, they look nothing alike.

The files both operations touch, with each module's style:

TEXT
Hearth/ ├── Booking/ # ports and adapters │ ├── CheckInGuest/ │ │ ├── CheckInGuestCommand.php │ │ ├── CheckInGuestCommandHandler.php │ │ └── GuestCheckedIn.php # event │ ├── Reservation/ │ │ ├── Reservation.php # plain PHP aggregate │ │ └── Reservations.php # port │ ├── Infrastructure/ │ │ └── EloquentReservations.php # adapter │ ├── Clock.php # port │ └── Dispatcher.php # port └── Housekeeping/ # Active Record ├── MarkRoomClean/ │ ├── MarkRoomCleanCommand.php │ ├── MarkRoomCleanCommandHandler.php │ ├── MarkRoomCleanController.php │ ├── MarkRoomCleanRequest.php │ └── RoomCleaned.php # event ├── Room/ │ ├── Room.php # Eloquent model │ └── CleaningStatus.php └── HousekeepingServiceProvider.php

The same files colored by layer, without the controllers, Form Requests and providers:

Two folder trees side by side on a dark card, colored by layer. Booking, ports and adapters: CheckInGuest/ holds CheckInGuestCommand and CheckInGuestCommandHandler (use case) and the GuestCheckedIn event (domain); Reservation/ holds Reservation and the Reservations port (domain); Infrastructure/ holds the EloquentReservations adapter (infrastructure); the Clock and Dispatcher ports sit at the module root (domain). Housekeeping, Active Record: MarkRoomClean/ holds MarkRoomCleanCommand and MarkRoomCleanCommandHandler (use case) and the RoomCleaned event (domain); Room/ holds Room, drawn as a domain box inside a dashed infrastructure ring and labelled domain + persistence in one class, and CleaningStatus (domain). Controllers, Form Requests and providers are not shown.

Booking's CheckInGuest slice, in the file Hearth/Booking/CheckInGuest/CheckInGuestCommand.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\CheckInGuest; use Hearth\Booking\Reservation\ReservationId; final readonly class CheckInGuestCommand { public function __construct( public ReservationId $reservationId, ) {} }

And its handler, in Hearth/Booking/CheckInGuest/CheckInGuestCommandHandler.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Booking\CheckInGuest; use Hearth\Booking\Clock; use Hearth\Booking\Dispatcher; use Hearth\Booking\Reservation\Reservations; final readonly class CheckInGuestCommandHandler { public function __construct( private Reservations $reservations, private Clock $clock, private Dispatcher $dispatcher, ) {} public function handle(CheckInGuestCommand $command): void { $reservation = $this->reservations->withId($command->reservationId); $reservation->checkIn($this->clock->now()); $this->reservations->save($reservation); foreach ($reservation->releaseEvents() as $event) { $this->dispatcher->dispatch($event); } } }

That slice cost three new files and a checkIn() method on Reservation, because it stands on infrastructure the module already paid for: the Reservations port and its EloquentReservations adapter, built by earlier operations in the same module. Booking has several use cases sharing that infrastructure, so the fixed cost of the port and the adapter is paid once and amortized across every one of them.

Housekeeping has three use cases: mark dirty, mark clean, mark inspected. Building a Rooms port, an EloquentRooms adapter and a plain-PHP Room next to the Eloquent one to serve three thin operations would cost more than it saves. Housekeeping still gets a slice, with a command, a handler, a Form Request and a controller. The difference is that Room is the Eloquent model and carries its own markClean() method, the Active Record style. The slice's command, in Hearth/Housekeeping/MarkRoomClean/MarkRoomCleanCommand.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\MarkRoomClean; final readonly class MarkRoomCleanCommand { public function __construct( public string $roomId, public string $cleanedBy, ) {} }

Its handler, in Hearth/Housekeeping/MarkRoomClean/MarkRoomCleanCommandHandler.php. Housekeeping has no ports, so it takes Laravel's own event dispatcher contract directly:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\MarkRoomClean; use Carbon\CarbonImmutable; use Hearth\Housekeeping\Room\Room; use Illuminate\Contracts\Events\Dispatcher; final readonly class MarkRoomCleanCommandHandler { public function __construct( private Dispatcher $events, ) {} public function handle(MarkRoomCleanCommand $command): void { $now = CarbonImmutable::now(); $room = Room::query()->findOrFail($command->roomId); $room->markClean($command->cleanedBy, $now); $room->save(); $this->events->dispatch(new RoomCleaned($room->id, $command->cleanedBy, $now)); } }

The module's provider pairs the command with its handler, in Hearth/Housekeeping/HousekeepingServiceProvider.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping; use Hearth\Housekeeping\MarkRoomClean\MarkRoomCleanCommand; use Hearth\Housekeeping\MarkRoomClean\MarkRoomCleanCommandHandler; use Illuminate\Support\Facades\Bus; use Illuminate\Support\ServiceProvider; final class HousekeepingServiceProvider extends ServiceProvider { public function boot(): void { Bus::map([ MarkRoomCleanCommand::class => MarkRoomCleanCommandHandler::class, ]); } }

The controller, in Hearth/Housekeeping/MarkRoomClean/MarkRoomCleanController.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\MarkRoomClean; use Illuminate\Contracts\Bus\Dispatcher; use Illuminate\Http\RedirectResponse; use Illuminate\Routing\Redirector; final readonly class MarkRoomCleanController { public function __construct( private Dispatcher $bus, private Redirector $redirector, ) {} public function __invoke(MarkRoomCleanRequest $request, string $roomId): RedirectResponse { $this->bus->dispatchSync(new MarkRoomCleanCommand($roomId, $request->string('cleaned_by')->toString())); return $this->redirector ->route('housekeeping.rooms.index') ->with('status', 'Room marked clean.'); } }

The Form Request, in Hearth/Housekeeping/MarkRoomClean/MarkRoomCleanRequest.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\MarkRoomClean; use Illuminate\Foundation\Http\FormRequest; final class MarkRoomCleanRequest extends FormRequest { public function authorize(): bool { return true; } /** * @return array<string, list<string>> */ public function rules(): array { return [ 'cleaned_by' => ['required', 'string', 'max:255'], ]; } }

The event it dispatches, in Hearth/Housekeeping/MarkRoomClean/RoomCleaned.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\MarkRoomClean; use Carbon\CarbonImmutable; final readonly class RoomCleaned { public function __construct( public string $roomId, public string $cleanedBy, public CarbonImmutable $cleanedAt, ) {} }

Room is an Eloquent model, in Hearth/Housekeeping/Room/Room.php, with the status column cast to a CleaningStatus enum and the state change as a method on the model. It maps to Housekeeping's own housekeeping_rooms table, keyed by the room id, because the rooms table belongs to Booking:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\Room; use Carbon\CarbonImmutable; use Illuminate\Database\Eloquent\Model; final class Room extends Model { protected $table = 'housekeeping_rooms'; public $incrementing = false; protected $keyType = 'string'; public function markClean(string $cleanedBy, CarbonImmutable $cleanedAt): void { $this->status = CleaningStatus::CLEAN; $this->last_cleaned_at = $cleanedAt; $this->last_cleaned_by = $cleanedBy; } protected function casts(): array { return [ 'status' => CleaningStatus::class, 'last_cleaned_at' => 'immutable_datetime', ]; } }

And the enum, in Hearth/Housekeeping/Room/CleaningStatus.php:

PHP
<?php declare(strict_types=1); namespace Hearth\Housekeeping\Room; enum CleaningStatus: string { case DIRTY = 'DIRTY'; case CLEAN = 'CLEAN'; case INSPECTED = 'INSPECTED'; }

The event carries the room id as a string and a CarbonImmutable timestamp, the same kind of values Booking's events carry. The moment a value leaves the module, it is part of what other modules read, so the event holds ids and scalars and never a Housekeeping class. There's no port because there's no second implementation ever coming: this module isn't going to swap its persistence layer, and if it ever does, changing three find and save calls by hand costs less than the port would have cost to build and maintain.

What still has to match everywhere

Letting the inside of a module vary doesn't mean the module system itself gets to vary. A few things stay fixed across every module regardless of which style it uses inside:

  • The module boundary. The import rules from the modular monolith lesson apply the same way whether a module is built on ports or on Eloquent directly.

  • How modules talk to each other. A module with a thin internal style still emits RoomCleaned through the same event mechanism Booking uses for ReservationConfirmed.

  • The naming of the public surface. Hearth\<Module>\<Slice>\<PastTenseName> for every event a module emits, living in the slice that produces it, whether the module behind it has a handler or a controller.

  • The enforcement tooling. PHPArkitect or Deptrac rules that check for cross-module imports don't care whether the module on either side of the boundary has an aggregate.

Those four hold the codebase together. Without them, a mix of styles across modules turns into a codebase nobody can navigate, because finding out how a given module works becomes a per-module investigation instead of a read of the folder layout.

When a module's style should change

Housekeeping's Active Record Room is the right call today. It stops being the right call once a real rule shows up that markClean() can't express cleanly: a room can't be marked clean out of a maintenance hold, a cleaning has to be logged against a specific shift, a double-clean within the same hour has to be rejected instead of silently overwriting the timestamp.

Watch for two concrete tells. markClean() starts growing if statements that check business state before doing the update, or the same logic gets copy-pasted into a second method for a related action. Either one is the module asking for an aggregate: a Room domain object that owns its own transitions and refuses the ones that violate a rule, behind a Rooms port the same way Booking's Reservation already works.

That upgrade adds to the module. The Room Eloquent model becomes the persistence detail behind an EloquentRooms adapter instead of the thing the handler talks to directly; the if checks move into the new domain class's markClean(), where they belong. Nothing about the module boundary changes.

Pitfalls

Picking the style once, for the whole application, at the kickoff meeting. The team that wrote the port-and-adapter Housekeeping example above did this. The style decision belongs in the module, made when the module is scoped, not in a document written before any module existed.

Treating "Active Record" as a synonym for "no discipline." Housekeeping's Form Request still validates input, still uses an enum instead of a magic string, still dispatches a typed event other modules can subscribe to. Less architecture means the same care spent on fewer layers.

Forgetting to revisit the verdict. A module's verdict is a snapshot of what it does today. A quiet module that starts accumulating rules needs someone to notice and re-run the five questions.

Skipping structure in a module that is earning it. Booking's invariants are real; a controller updating reservation rows directly would enforce them on the web path only, and the no-show job would skip them.

The one thing to remember

The architecture question is answered per module. Ask the five questions module by module, and let modules like Housekeeping stay thin while modules like Booking carry the full structure they've earned.

Course Content