Architecture on Brian Faust

Boundaries Follow Work Without Becoming Destiny

Tue, 01 Oct 2024 00:00:00 +0000

We had a small team, so every service was officially owned by everyone. In practice, a developer could finish five hours of work in a specialist application and then spend three weeks integrating and testing it against the legacy API.

The delay was not a queue in front of another team. There was no other team. It came from a system which had evolved across years, changing commercial priorities, agencies, freelancers, and eventually an internal development team. Each period left decisions which made sense under its own pressure. Their combined cost appeared in the next change.

Enforce Architecture at the Cheapest Reliable Layer

Sun, 01 Sep 2024 00:00:00 +0000

The rule says Domain must not depend on Infrastructure.

Code review misses this reference:

final class Order extends \Illuminate\Database\Eloquent\Model
{
}

A quick substring scan catches it. The same scan also rejects a harmless docblock which names EloquentOrderRepository while explaining what Domain must not do.

The first check is unreliable because a person must notice every occurrence. The second is unreliable because text is not a PHP dependency. A token-aware source check catches the executable reference and ignores the prose.

Name the Independent Thing

Thu, 01 Aug 2024 00:00:00 +0000

Both diagrams say microservices.

The first has four HTTP endpoints and four repositories. They share one database, move on one release train, page one on-call rotation, and require a coordinated deployment when the shared schema changes.

The second can release Payments without Ordering, lose the Payments process without losing unrelated Ordering work, rotate payment credentials inside one data zone, and send repair to a staffed Payments owner.

The label is identical. The operating contract is not.

A Module Is Cheaper Than a Network Boundary

Mon, 01 Jul 2024 00:00:00 +0000

The payment was captured. Ordering does not know that.

Its request reached Payments, the capture became durable, and the response disappeared on the way back. Ordering now has a pending order and a timeout. Retrying without a stable identity may charge twice. Treating the timeout as a decline may abandon a real capture.

Inside one process and transaction, that particular ambiguity does not exist. The payment and order commit together or roll back together. Moving Payments across a network has bought a separate release and failure boundary. It has also replaced a return value with a protocol for identity, uncertainty, and repair.

Decompose by Change, Not by Layer

Sat, 01 Jun 2024 00:00:00 +0000

A cancellation rule changes: refuse cancellation after warehouse handoff.

In a conventional layered application, the work touches a controller, an application service, a domain policy, a repository, a migration, and tests. If the organization mirrors those directories, one business decision becomes a project for API, backend, and database teams.

The next change adds a covering index for order lookup. It touches only the persistence layer and changes no business decision.

A Version Column Is Not Concurrency Control

Sun, 01 Jan 2023 00:00:00 +0000

A capacity pool has ten units available. Two workers load it before either one writes:

worker A loads: version 0, reserved 0
worker B loads: version 0, reserved 0

worker A allocates 6 to allocation-a
worker B allocates 6 to allocation-b

Both decisions pass the aggregate’s rule. Each worker sees ten remaining units. They cannot both belong to one ordered history: after either allocation, only four remain.

Loading State Is Not Creating It Again

Thu, 01 Dec 2022 00:00:00 +0000

An order placed in 2024 is still in the database:

number=LEGACY-42
status=placed
fulfil_by=2024-12-20T10:00:00Z
version=7

Today, new web orders need a number beginning with WEB- and a fulfilment deadline in the future. Pass that stored row through today’s creation factory and one of two bad things happens. The factory rejects valid history, or the load pretends that placement happened again and records a new OrderPlaced fact.

Loading is not a second attempt at creation. Creation decides whether a new transition is allowed now. Reconstitution restores state which was accepted before, without claiming that the transition just occurred.

A Mapper Connects Two Honest Models

Tue, 01 Nov 2022 00:00:00 +0000

An order in the domain has an OrderNumber, a Money total, typed lines, and an operation named place(). The same order in a relational database has an orders row, several order_lines rows, integer minor units, a nullable deadline, check constraints, a foreign key, and an index used by fulfilment.

Forcing those shapes to match exactly damages one side or the other.

Make the domain object mirror the tables and it acquires column names, nullable intermediate state, relationship-loading concerns, and methods shaped around persistence. Store the object as one opaque document and the database loses straightforward constraints and access paths required by the selected query.

A Repository Is a Domain Collection, Not an ORM Wrapper

Sat, 01 Oct 2022 00:00:00 +0000

This interface appears in many Laravel codebases:

interface Repository
{
 public function all(): Collection;
 public function find(int $id): ?Model;
 public function create(array $attributes): Model;
 public function update(int $id, array $attributes): Model;
 public function delete(int $id): bool;
}

It hides the word Eloquent and preserves everything else about Eloquent’s world: models, attribute arrays, record IDs, and CRUD operations. Callers still need to know which fields are writable, which relationships are loaded, and which operations preserve domain rules.

That is not a useful persistence boundary. It is a smaller, less capable ORM.

A Composition Root Makes Choices Visible

Thu, 01 Sep 2022 00:00:00 +0000

Remove the ProductPrices binding from a Laravel service provider, then ask the container for QuoteProduct. Laravel refuses to construct it:

Target [App\Application\ProductPrices] is not instantiable while building
[App\Application\QuoteProduct].

Move the same lookup into QuoteProduct::execute() and construction succeeds. The missing dependency does not become visible until a quote request reaches that line. The application object looks simpler because its constructor says nothing. Its object graph is not simpler; part of the graph has moved into method code and configuration.

A Hexagon Is Not a Directory Layout

Mon, 01 Aug 2022 00:00:00 +0000

A Laravel controller calls a catalogue API, reads price_cents, and returns a quote. Moving that HTTP code into Application/QuoteProduct.php makes the controller thinner. It also leaves the application service coupled to Laravel’s HTTP client, the provider URL, and the provider’s JSON.

The tree looks more architectural. The source dependencies have not moved.

That difference becomes visible when the catalogue replaces price_cents with price.amount_minor. A folder name cannot decide where the resulting change lands. A useful hexagonal boundary can: application policy defines the conversation it needs, while an outside adapter owns the provider mechanism.