Domain-Driven-Design on Brian Faust

Test Process State, Not Message Choreography

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

A strict mock test expects five calls in order:

load process
check message ID
dispatch ReserveInventory
save process
record inbox

Every expectation passes. Unfortunately, save process writes the old awaiting_payment state. The command says inventory should be reserved while the durable process still says it is waiting for payment.

Now fix the persistence and move record inbox before save process inside the same database transaction. The committed process, inbox, and outbox rows are identical. The strict test fails because two calls changed places.

A Process Manager Remembers What the Queue Cannot

Fri, 01 Sep 2023 00:00:00 +0000

An order is paid at 10:00. Inventory is reserved at 10:01. The warehouse does not respond until 14:30. Shipping fails the next morning, after two worker deployments and a payment-provider timeout.

No request, transaction, or queue worker owns that whole timeline. Chaining jobs can move execution from one step to the next, but the queue does not know whether the business process is waiting, complete, compensating, or stuck.

A Process Manager exists to remember that state and decide what should happen when a relevant message arrives. Its value begins where call-stack control ends.

An Outbox Moves the Failure Window

Tue, 01 Aug 2023 00:00:00 +0000

Place an order, commit it, then publish OrderPlaced. If the broker rejects the send, the order remains placed and nothing durable says publication is still required.

Reverse the sequence. Publish OrderPlaced, then commit the order. If the database rolls back, the broker now carries a fact which the source database never accepted.

A transactional outbox changes the sequence again. Insert the order and a pending message in one local transaction. Rollback removes both. Commit makes both durable. A separate relay can keep trying the message after the request which placed the order has ended.

Publishing Events Is Not Event Sourcing

Sat, 01 Jul 2023 00:00:00 +0000

Two wallet applications accept the same credits and publish the same FundsCredited event. Both end with a balance of 3,500 cents. Both can update a listener-owned read model.

Now delete the wallet row and ask each application to recover.

The first application cannot. Its wallets.balance_minor column was the authoritative value. The events were notifications sent after accepted changes, and their payloads do not contain enough information to reconstruct the balance.

A Domain Event Is a Fact, Not a Question

Thu, 01 Jun 2023 00:00:00 +0000

An order cannot be placed until a credit policy accepts it. The handler needs that answer before it can continue:

if (!$this->credit->allows($customerId, $amountCents)) {
 throw new CreditRefused();
}

$order->place($customerId, $amountCents, $placedOn);

Turn that call into a CheckCredit event and the question does not disappear. It becomes harder to see. The handler still needs an answer, but an event dispatcher normally gives it a list of listeners, not a typed decision. Now the code needs a mutable payload, stopped propagation, or some other private convention to recover the response.

CQRS Starts When Reads Need a Different Model

Mon, 01 May 2023 00:00:00 +0000

An order-details page needs customer name, payment status, shipment progress, line totals, tax labels, and the latest support case. The write model needs to protect payment, cancellation, and fulfilment invariants.

Trying to make one Eloquent graph serve both jobs creates a familiar mess: relationships exist for screen composition, write methods expose persistence concerns, and every request loads a different subset of a model that is never quite complete.

That tension can justify different read and write models. It does not automatically justify two databases, an event store, a command bus, or eventual consistency. CQRS is the model split; the infrastructure is a separate set of decisions.

A Queued Command Changes the Contract

Sat, 01 Apr 2023 00:00:00 +0000

Send the same payment-capture request through two Laravel routes.

The synchronous route returns 204 after the provider has created charge ch_001 and the order records that reference. When the provider returns 503, the HTTP request returns 500 and the order remains unpaid.

The queued route returns 202 while the order is still unpaid and the provider ledger is empty. Its response contains an operation URL. Cancel the order before a worker starts and that operation later becomes refused; the provider is never called.

A Command Bus Must Pay for Its Indirection

Wed, 01 Mar 2023 00:00:00 +0000

Four Laravel routes handle two commands in the reproducible fixture . Two routes inject typed handlers. Two inject Laravel’s dispatcher. All four return 204, and both call graphs leave the same SQLite rows behind.

Then one line disappears from the dispatcher’s handler map. The bus route still resolves its controller, constructs CancelOrder, and enters the pipeline. It returns 500 without selecting a handler. The direct controller has no equivalent registry entry to lose because its constructor already names DirectCancelOrderHandler.

A Valid Command Can Still Be Refused

Wed, 01 Feb 2023 00:00:00 +0000

Send this cancellation request to two orders:

{
 "reason": "customer_request"
}

The placed order returns 204 and becomes cancelled. The shipped order returns 409 and remains shipped. Both requests pass the same Laravel Form Request.

Change the reason to unknown and the result is different again: Laravel returns 422 before the controller constructs a command. Three requests crossed two different decision boundaries. Calling one result “valid” and the others “invalid” hides the part of the system which made each decision.

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.

An Open Host Service Is Not a Published Language

Fri, 01 Jul 2022 00:00:00 +0000

Inventory exposes one endpoint to Storefront, Fulfilment, and Replenishment:

GET /availability/{sku}?location={location}

The route, authentication, media type, and JSON shape remain unchanged. One release quietly redefines available_quantity. Yesterday it meant physical stock at the location. Today it means stock which may still be promised after reservations and holds.

Every request still returns 200. Schema validation still sees an integer. Storefront, Fulfilment, and Replenishment now act on a different fact.

An API Cannot Tell You Who Has Influence

Wed, 01 Jun 2022 00:00:00 +0000

Two Order Management features call the same Payments endpoint. They use the same schema, service credential, and provider-managed release process.

The first feature needs a reversal_reason. Orders raises the request, Payments accepts it into quarterly planning, and a Payments owner commits to a compatibility window.

The second feature asks for another Orders-specific field. Payments declines it as outside the product roadmap. Orders decides that the generic refund status is adequate for its support view and accepts the cost of adapting when the provider contract changes.

An Anti-Corruption Layer Must Own the Translation

Sun, 01 May 2022 00:00:00 +0000

Payments adds a refund state named reversed. Order Management already has a default branch for provider failures, so the new event keeps moving:

anything except completed ──▶ provider-refund-failed

Nothing crashes. That is the problem.

The provider has reported a fact, but Orders has invented its consequence. A reversed refund might reopen the order, create a debt, require manual recovery, or leave the order cancelled while Finance resolves the money. The provider enum cannot choose among those policies.

A Context Map Must Say What the Arrow Means

Fri, 01 Apr 2022 00:00:00 +0000

The cancellation workshop ends with three boxes: Orders, Payments, and Fulfilment. Someone connects them in event order. The diagram looks plausible.

It is also impossible to read.

Does the arrow mean an HTTP request, a domain event, a dependency, ownership, or influence over another model? Does it describe the system that exists or the one the team hopes to build? Who translates “refund declined” into an order state? The line answers none of these questions.

Shared Kernel or Published Language: Choose Where Coordination Lives

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

Billing and fulfilment both use the word “order.” Sharing an Order class looks like the obvious way to keep them consistent.

Then billing adds credit notes, tax evidence, and settlement state. Fulfilment adds picking waves, split shipments, and packing exceptions. The shared class either accumulates both models or becomes a negotiation every time one team changes it.

Integration always creates coordination. A Shared Kernel and a Published Language place that coordination in different locations. The first shares a small piece of model and requires teams to change it together. The second shares a versioned language at the boundary and lets each side translate it into its own model.

EventStorming Finds Disagreement Before It Finds Services

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

Ask sales, support, finance, and engineering when an order becomes cancelled and the answers may sound compatible until they share a wall.

Sales says cancellation happens when the customer asks. Support says it happens after a case is approved. Finance says a paid order remains active until the refund clears. Engineering points to a cancelled_at column written before the payment provider responds.

That disagreement is not workshop noise. It is the model.