Architecture on Brian Faust

Retire the Browser, Keep the Test Runner

Thu, 15 Oct 2026 00:00:00 +0000

The Go port deliberately dropped the browser UI. The API tester was the awkward exception: not its pages, but the program behind them. It could create a test configuration, publish it, make real API calls, extract identifiers, wait for a result and clean up afterward. Deleting its screen was straightforward. Deleting all of that would have thrown away a useful part of the migration.

Replacing it with a CLI also exposed distinctions the screen could make easy to overlook. An HTTP 200 response could mean a failed test step. A failed run could still be a successfully produced command result. A saved step record didn’t mean its API call would never execute again. Those weren’t reasons to redesign the tester during the port; they were behavior to understand before moving its entry point.

When the Framework Sets the Latency Floor

Sat, 01 Aug 2026 00:00:00 +0000

By the time I considered moving the pricing backend to Go, the PHP version already had table-driven pricing, prepared runtime projections, candidate indexes, and substantial cache work. Those changes mattered. They didn’t remove the request cost I was still seeing before business processing: roughly 50–100 milliseconds on the conventional PHP/Laravel path, reduced to roughly 30–40 milliseconds with Octane in the setup I tested.

I didn’t want to spend the rest of the project squeezing a little more out of that same path. Go was a better fit for the request and computation work, particularly as the pricing datasets grew. Performance, resource consumption, and stability drove the choice. The interesting engineering question became how to replace the runtime without quietly replacing the application too.

The Order of Charges Changes the Price

Wed, 15 Apr 2026 00:00:00 +0000

Two row orders can produce the same €35 quote while disagreeing about the fuel charge. In one, fuel is €2.70; in the other, it’s €2.40. A minimum-charge top-up hides the difference in the total. Assert only that total and the test passes either way.

The difference comes from when the fuel row sees a handling charge. The percentage reads the components already built, not a final basket reconstructed after every row has run. Scope also limits which of those components it can use. A shipment percentage doesn’t automatically include parcel charges just because they contribute to the same quote.

How a Shipping Quote Gets Its Price

Thu, 01 Jan 2026 00:00:00 +0000

A parcel weighs two kilograms. The tariff has a price for two kilograms. Returning that price sounds reasonable. It can also be wrong before the lookup finishes: the tariff may charge for volume, the account may have a negotiated transport rate, and handling may apply to each parcel rather than once to the shipment.

I built a private logistics rating engine around those interactions. It stayed private rather than becoming a commercial product. What made it interesting was that most of the difficulty came from pricing itself. I could work on the model without first accommodating years of unrelated business exceptions. There was still plenty to get wrong.

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 through changing commercial priorities, agencies, freelancers, and eventually an internal development team. Plenty of individual decisions made sense when they were made. Their combined cost still landed on the next person trying to change anything.

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.

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, which is an odd thing to spend an interface on.

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. That can look like simplification because the constructor now says nothing. The object graph did not become simpler. Part of it moved into method code and configuration, where Laravel cannot reject it until a quote reaches that line.

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 is architecture by folder name, and it buys almost nothing.

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.

A Design Principle Is a Compressed Failure History

Fri, 01 Jan 2021 00:00:00 +0000

“This violates the single-responsibility principle” is not an explanation. It may be the conclusion of one, but the useful part starts earlier:

Lookup policy, selection policy, and construction policy change for different
reasons. One class owns all three. A lookup change therefore makes selection
tests and construction code part of the review surface.

Once that reasoning exists, “single responsibility” gives it a short name that another engineer can retrieve. Without the reasoning, it is just a respectable label which can justify almost any refactor.

Design Becomes Valuable When the Next Change Arrives

Tue, 01 Dec 2020 00:00:00 +0000

One migration removed four vendor packages. Two payment drivers, their client interfaces, and their factory interfaces did not change; the concrete clients changed substantially.

Two application controllers were less fortunate. They had constructed a vendor connection directly to manage webhooks, so the replacement had to add a small webhook-management role and move the remote protocol behind it.

The same migration produced both results: some earlier seams absorbed the change, while other paths showed exactly where the vendor had leaked through. That tells us more than declaring the design “clean.” A design makes a prediction about future change, and the next real change tells us which parts of that prediction were right.

A Directory Map Is Not a Redesign Plan

Tue, 01 Jan 2019 00:00:00 +0000

A reorganization plan found dozens of domain directories and several older modules. It assigned them to a set of proposed bounded contexts, selected an apparently isolated location-and-address context as a safe starting point, and described where its files should move.

The map was detailed and tidy. It was also missing the part which determined whether the boundary was real.

In the running system, the legacy application kept service-point policy while calling separate location and postal applications. Location lookup called postal lookup. Each application owned different state. Booking, validation, labels, returns, settings, administration, and health checks all consumed some part of the flow.

A Capability Interface Is Smaller Than a Vendor Client

Sat, 01 Dec 2018 00:00:00 +0000

A controller needs to register an order webhook. Instead, it constructs a vendor SDK connection, accesses a dynamic resource property, calls its creation method, names the remote event, chooses response fields, and catches the SDK’s base exception. That is a lot of vendor vocabulary for one product decision.

The test is no better. It has to intercept construction of that concrete connection and mock a dynamic property chain. Two useful behavior tests ended up skipped with the same explanation: the code needed an interface and dependency injection.