BlackMesa Labs

Our domain layer contains nothing but exceptions. On purpose.

2026-10-04T00:00:00+00:00

Articles about hexagonal architecture almost always show the same diagram: a circle in the middle, ports around it, adapters outside, and an arrow pointing inward. None of them ever shows what the Domain/ folder actually holds six months later.

Here is ours. Nine contexts, and twelve domain files in total: nine exceptions, two enums, one role. Zero interfaces. Zero aggregates. Zero value objects. Calling that a business layer would be a lie, and that is precisely what this piece is about.

What we kept: the C in CQRS, not the Q

The bus configuration declares three channels with explicit semantics:

default_bus: command.bus
buses:
    command.bus:            # a command mutates state, exactly one handler
        default_middleware: { enabled: true, allow_no_handlers: false }
    query.bus:              # a query returns a value, a single handler
        default_middleware: { enabled: true, allow_no_handlers: false }
    event.bus:              # a domain event: 0..n subscribers
        default_middleware: { enabled: true, allow_no_handlers: true }

The actual count today: twenty-nine command handlers, one query handler. The query bus exists, it is configured, and it is very nearly empty.

That is not migration debt, it is a conclusion. A command earns its ceremony because it brings three things we did not have: a name for an intent (ChangeCompanySubscriptionPlan is not setSubscriptionPlan), a guarantee that exactly one place executes it — allow_no_handlers: false fails at boot, not in production — and an obvious transaction boundary, the handler’s.

A read brings none of that. Its shape is dictated by the screen that displays it: this page needs these seven columns, joined this way, sorted like that. Putting that on a bus adds no rule, adds a layer, and moves the SQL from one file to another. So we read through Doctrine repositories, directly, without apologising for it.

One detail matters more than it looks: default_bus: command.bus. A bare dispatch() is a command. The default is the channel that mutates state — the one thing you never want travelling down the wrong channel by accident.

What we turned down: dependency inversion

This is the heart of the hexagon in the literature: the domain declares interfaces, infrastructure implements them, the dependency arrow points inward. We did not do it. Here is a full handler, uncut:

#[AsMessageHandler(bus: 'command.bus')]
final readonly class ChangeCompanySubscriptionPlanHandler
{
    public function __construct(
        private EntityManagerInterface $entityManager,
        private LoggerInterface $logger,
    ) {}

    public function __invoke(ChangeCompanySubscriptionPlanCommand $command): void
    {
        $company = $this->entityManager->find(Company::class, Ulid::fromString($command->companyId));
        if (!$company instanceof Company) {
            throw CompanyNotFoundException::withId($command->companyId);
        }
        // …
    }
}

EntityManagerInterface as a direct dependency. Out of thirty-eight handlers, twenty-four depend on it. The Company entity comes from App\Entity, shared by every context. There is no abstract repository, no port, no domain model distinct from the table.

Two remarks on that example, because they say more than the diagram does.

First, the command carries string $companyId, not a CompanyId value object. That is not laziness: the message has to be serialisable for asynchronous transport. The bus boundary dictates the shape of the message — infrastructure setting the signature of what we call the domain, from the very first line.

Second, Ulid::fromString(...). The domain identifier exists in two forms depending on whether you are carrying it or querying with it, and that conversion is a storage constraint, not a business one.

What the boundary buys anyway

One thing, exactly one, and it is worth its price: coupling between contexts became visible in the import list.

The handler above lives in App\Billing. It imports App\Company\Domain\Exception\CompanyNotFoundException. That single import says billing depends on the Company context, and it says so at the top of the file, in one line, with no diagram to keep up to date. The cross-context dependency graph is a grep over use statements.

That is modest. Compared with a codebase where everything lives in App\Service, it is the difference between “we assume it’s coupled” and “here is exactly where”. That benefit is what we bought, and nothing else.

The five places infrastructure crosses

Here is what no diagram shows: the places where Doctrine decides the shape of a business operation. These are real leaks, all of them in the code today.

1. The business rule written in two dialects. Our policy for keeping internal companies out of commercial figures is one predicate. It exists in two versions, because some read paths are native SQL for performance and others are DQL:

public static function sql(string $alias = 'c'): string  // native queries
{ return ($alias !== '' ? $alias.'.' : '').'excluded_from_stats = false'; }

public static function dql(string $alias = 'c'): string  // ORM queries
{ return $alias.'.excludedFromStats = false'; }

One rule, two spellings, because of the query language. The divergence is a single character — excluded_from_stats against excludedFromStats — so it is invisible to a quick read, and no test would fail if one of the two drifted.

2. The ambient filter. Doctrine’s soft-delete filter is mutable global state. A query looking for a unique identifier finds nothing while the unique index still holds it. The way out is to disable the filter and put it back:

$filters = $this->em->getFilters();
$wasEnabled = $filters->isEnabled('softdeleteable');
if ($wasEnabled) { $filters->disable('softdeleteable'); }
$existing = $repo->findOneBy(['slug' => $slug]);
if ($wasEnabled) { $filters->enable('softdeleteable'); }

A “business query” whose result depends on ambient state is not a function. This is not a Doctrine defect — the filter does exactly what we asked of it — but it forbids reasoning about application code without knowing which mode it runs in.

3. Write ordering inside the unit of work. Replacing a piece of content’s translations looks like one operation: drop the old ones, add the new ones, save. Within a single flush(), Doctrine runs INSERTs before orphan DELETEs, and the unique constraint on (feedback_id, locale) breaks. The operation has to be split into two successive saves.

Put differently: the shape of the application-level operation is not set by the business but by the ORM’s internal scheduling. No port would have protected us, because the constraint lives neither in the domain nor in the adapter — it lives in the execution order that connects them.

4. The join alias that truncates in silence. Filtering on an association already joined with fetch also restricts the hydrated collection: you think you are filtering rows, you are amputating the returned object. Filtering needs its own second join:

$qb->innerJoin('f.industries', 'i_filter')      // alias distinct from the fetch one
   ->andWhere('i_filter.id IN (:industries)');

The bug is invisible: the query returns the right entities, with incomplete collections. That is infrastructure semantics, right in the middle of what reads like a search rule.

5. The identifier’s type. Identifiers travel as ULIDs, compare as RFC 4122 in queries, and forgetting the conversion yields an empty result rather than an error. A port would have moved the conversion; it would not have removed it.

The migration rule

Which leaves the question that kills rewrites: what do we do with the existing code, written as classic Symfony services?

Nothing, as long as nobody touches it. The policy is written down: CQRS for new writes and new reads; existing code migrates on demand only. Never a wholesale rewrite in the name of consistency.

Because consistency is not a business outcome. Rewriting a service that works so it resembles its neighbours produces risk without producing value — and it is exactly the kind of work that justifies itself indefinitely, because its stopping criterion is aesthetic.

This is not purist DDD, it is time to market

The real reason has to be named, because everything above reads differently once it is on the table.

We have already written here that the cheapest feature is the one you don’t build. A port is a feature. So is an aggregate, so is a value object, so is an anti-corruption layer. Each one costs writing, costs reading for whoever arrives next, and costs upkeep for as long as the code lives. An abstraction is not free because it is immaterial.

So the useful question is not “is this correct DDD”. It is: what does this abstraction buy today, and what is it merely postponing? A repository behind an interface buys the ability to change storage — we are not leaving PostgreSQL. It also buys tests without a database, and that one is a real benefit: it is the single argument that may yet make us pay the bill.

What we did instead fits in one sentence: ship, and keep only the boundaries that pay for themselves. The command bus costs three files and helps the same day. Ports cost a whole layer and may help, later, a team that does not exist yet.

The risk in that position is well known, and writing it down is part of the price: it is indistinguishable from laziness at a glance. The difference comes down to one detail — we can name what we did not build, and why.

And we own it. These are our choices, not accidents we would discover on a re-read. We correct them when we can and when we have the time: the day a friction becomes real and measurable, not the day an architecture article explains that they are incorrect. A debt that is written down, dated and argued is not a denied debt — it is the only kind you are able to repay at the right moment.

What it produced

Nine named contexts, whose mutual coupling is read in the imports rather than in an out-of-date diagram.
Twenty-nine commands, each with an intent name, a single handler guaranteed at boot, and an obvious transaction boundary.
One query handler, deliberately: reads go through repositories.
Twelve domain files — nine exceptions, two enums, one role — which is to say no business rule genuinely isolated from Doctrine.
Zero rewrites of the existing classic code, which keeps working alongside.

Good practices

Treat every abstraction as a feature: it has to say what it buys today, not what it would allow one day.
Adopt the pieces separately. A command bus delivers something without the rest; ports, aggregates and value objects are distinct purchases, each with its own bill.
Pick the strictest default: the default bus is the one that mutates state, and a missing handler fails the boot rather than production.
Use namespaces as a coupling detector rather than a barrier: they protect nothing, they make things visible.
Write the migration rule down, with its stopping criterion. Without one, “harmonising the architecture” is infinite work.
Look at what Domain/ actually contains before claiming you do DDD. The count is instructive.

Watch-outs

The folder is not the boundary. Creating Domain/, Application/, Infrastructure/ gives a comforting sense of measurable progress — and measuring an architecture by its folder count is the surest way to get none of the guarantees they suggest.
Twenty-four of thirty-eight handlers depend on the EntityManager: none can be tested with an in-memory repository. The test suite needs a real database. That is a cost, it is accepted, it is not free.
Shared Doctrine entities are the real coupling, and it is invisible in the folder tree. The day two contexts want the same table to diverge, that is the wall we will hit — not the absence of ports.
A business rule duplicated across two query dialects will eventually drift, and today nothing would catch it. That is the most concrete debt in everything above.

We were our own best customer. That was a bug.

2026-09-30T00:00:00+00:00

Everyone tells you to use your own product. Nobody warns you about the side effect: the moment your company has an account, it enters your figures. Not in a footnote — in the revenue, in the conversion rate, in the list of customers to chase.

Our case: BlackMesa publishes real case studies on Show me the REX. The account is real, the plan is real, the articles get read. What is not real is the revenue — we do not invoice ourselves. So a zero-euro customer sat inside our MRR, inflated the plan breakdown, and filled a slot in the conversion funnel without ever having converted anything.

The obvious fix — “exclude our own company” — is wrong. It assumes the problem is the company. The problem is somewhere else.

It isn’t “who to exclude”, it’s “what does this number answer”

The reflex is to look for a list of entities to leave out. The right question is asked metric by metric: which question is this number the answer to?

A view counter answers “how many people read this text”. The answer is the same whether the reader came from our offices or from anywhere else: the page was served, it was read, the content exists. Excluding our views would make that number wrong.

Monthly revenue answers “how much do our customers pay us”. Our own company is not a customer. Its presence makes that number wrong.

Both metrics look at the same database, sometimes at the same row, and need opposite rules. That is not an exception to handle, it is the rule: the unit of exclusion is not the data, it is the question being asked.

The case that settles it: a view that counts and does not count

The clearest example is also the most uncomfortable, because it rules out every implementation shortcut.

On the platform, a case-study view feeds two distinct things. On one side, audience: the counter shown on the article, the dashboard total, the traffic curve. On the other, a commercial signal: “which companies have read your case studies”, used to identify contacts worth following up.

Same event, same record. In the first group, a read from our own offices counts — somebody really did read it. In the second, it must not count at all: we are not a prospect to call back, and an internal reader sitting in a lead list is a sales action triggered for nothing.

So there is no global filter to install once at the door. Every query has to know which family it belongs to.

A flag in the database, not a constant in the code

First version, the quickest one: a hardcoded list of company names. It lasted an hour. A constant forces a deployment to reclassify a company, and more importantly it lies about the nature of the information: “this company is not a customer” is business data — it changes, it gets decided, and it has to be visible to whoever administers the accounts.

So it became a checkbox on the company form, with its help text spelled out, because an option whose scope nobody understands ends up ticked at random:

Our own companies publish and stay visible on the public site, but count in no commercial or marketing figure: MRR, plans, funnel, upsell/churn, leads, digests. Views and visits, however, still count.

The list of names did not disappear: it bootstraps a freshly installed environment so it never starts with polluted metrics. But it no longer decides anything.

The predicate itself lives in one small class, in two flavours — one for ORM queries, one for raw SQL. That sounds trivial; it is what makes the rule auditable. Finding every place that applies it became a text search, and checking it against the list of commercial figures takes a minute by eye.

Verify rather than re-read

Re-reading your own exclusion code proves nothing: you read back what you believe you wrote. The only verification worth the name is to toggle the checkbox and compare the dashboards before and after, figure by figure.

About thirty values moved. Seven stayed strictly identical — and that was the expected result: they are the audience counters and the published-content volumes. A number that moves when it shouldn’t is a bug; a number that stays put when it should have moved is an omission. Without that pass, we would have caught neither.

The final shape: one flag, one policy class, thirty-four predicates across eight files — MRR, plans, funnel, upsell, churn risk, follow-ups, lead intelligence, monthly digests, coupon expiry, nurturing.

That last one deserves a mention. Without the exclusion, our own company sat in the automated re-engagement sequence. We would have been sending ourselves our own win-back e-mails.

What it produced

An MRR with no zero-euro customer in it, and a conversion rate that no longer counts our own sign-up in its denominator.
About thirty corrected values across the commercial dashboards, seven deliberately unchanged.
Zero change on the public site: the case studies stay published, visible, filterable, and their views still count.
One rule written in one place, with its reason, rather than an AND copied from query to query.
A checkbox that reclassifies a company without a deployment.

Good practices

Classify each metric before coding the filter: audience measurement, or commercial signal. The answer sets the rule, and it is not the same for two numbers drawn from the same table.
Put membership in the database, not in a constant: it is business data, it changes and it gets decided.
Keep the predicate in a single class even if it fits on one line: the point is not reuse, it is being able to find every call site.
Verify by toggling: comparing figures before and after is the only way to tell an omission from a decision.
Write the scope into the admin interface, right where the box gets ticked.

Watch-outs

Nothing stops the next query from forgetting the predicate. The rule is held by code review, not by a test, and that is the main weakness of the setup today.
An exclusion that is too broad is as wrong as no exclusion at all: pulling our views out of the audience counter would have produced a lie in the other direction.
The day an internal company becomes a real paying customer, the box has to be unticked — and nobody will remind you. That decision is human, and it needs a scheduled moment where it gets revisited.
Saying publicly that your statistics exclude your own data costs nothing, and beats having someone else discover it for you.

The cheapest feature is the one you don't build

2026-09-27T00:00:00+00:00

Digital sobriety is almost always framed as an optimisation problem: lighter images, better caching, a cleaner region. All true, and all marginal. The real waste sits elsewhere, and nobody measures it: code written for nothing. A migration to redo, a tool bought then dropped, a feature shipped that nobody opens. Which leaves the question we had never put into words: how do you decide not to build something?

The report gives the three signals we settled on, and what each one saved over one ordinary working day: a broken feature nobody complained about — information about the feature, not about the bug; 1,400 translations we did not write because no reader could reach them; and a monitoring gap that turned out to be a rehearsal gap, not a tooling gap.

It also says what those signals do not mean. “Nobody needs it” is the perfect excuse for doing nothing, and a rule that can only say no has stopped being a rule. Two guardrails keep it honest — including this one: an unused feature is sometimes badly exposed rather than useless.

Upgrading the OS under Docker: what is still coupled, and what nothing validates

2026-09-27T00:00:00+00:00

Show me the REX runs on a single host: one Postgres, one Redis, one front proxy, and the application deployed blue-green — two identical instances, “blue” and “green”, of which only one serves traffic at a time. A new version is started on the idle one, and once it answers correctly the proxy is switched over. At the time of writing, that host serves 52 published case studies and a little over 16,000 cumulative views.

This arrangement protects a release: if the new version misbehaves, switching back takes a second and nobody notices. It protects nothing at all against the machine itself, since both instances sit on that same host — stop it and you stop them both.

The single host is a deliberate choice, not an oversight: no redundancy until traffic justifies it, and the threshold for revisiting it is written down — a thousand visits a day. Below that, a second machine costs far more in complexity (replication, failover, consistency) than it returns in availability, and complexity nobody needs yet is the most expensive thing you can build.

Owning that choice creates an obligation, though. If you accept that a reboot takes the service down, you owe yourself an exact figure for what it costs. That is the part we got wrong that night, and we come back to it at the end.

We moved that host from one Ubuntu release to the next. The operation went through — and that is not the interesting part. The interesting part is that containerisation has narrowed what such an upgrade can still break down to a very short list, and that we found exactly the item on it that nothing in our chain was watching.

What containerisation actually decoupled

The application is immune to a distribution upgrade, and it is worth being precise about why: it does not use anything from the host. Its PHP, its extensions, its system libraries, its CA bundle all ship inside the image. The host’s ca-certificates can be replaced wholesale — our outbound calls to VIES, the payment provider and object storage are unaffected, because they never read that store.

This is why teams have come to treat an OS upgrade on a container host as routine. It is very nearly true, and it is the “very nearly” that costs.

The four coupling points that remain

Once you have moved everything you can into images, what still belongs to the host is a short list — and it is the same list on every containerised server:

The kernel. Containers share it. A major jump changes the ground under a database far more than under a web process.
The Docker daemon. It is not in your image; it is a host package, installed from a third-party repository.
The apt sources for that daemon. The thing that decides whether the previous point ever gets a security patch again.
The restart contract. Which containers come back on their own after a boot, and which deliberately do not — the idle instance, for one, must stay down, or two versions of the application would fight over the same database.

Nothing else really matters. That list is short enough to be checked by hand, before and after — which is precisely what makes not checking it inexcusable.

The only lasting damage landed on point three

A release upgrade disables or removes third-party apt sources. This is not a bug: those sources are built for the release you are leaving, and keeping them enabled across the jump is how you break a system. The tool is right to do it, and it says so.

What it does not do is tell you afterwards. Our Docker source was gone. Nothing broke — the daemon kept running, the containers with it, the site served. But the installed package had been built for the previous distribution, and there was no longer any repository able to replace it. The failure mode is not a service that stops; it is a package manager that becomes authoritative and empty at the same time. It reports that everything is up to date, and it is telling the truth about a universe it can no longer see.

Restoring the source is four lines and no restart. It immediately revealed seven minor versions of drift accumulated in silence. Nothing would ever have raised a hand: not the daemon, which works; not the monitoring we do not have; not apt, which had nothing left to compare against.

The blind spot: the compose files

Then the structural finding, which is the one worth taking away.

Our database service had no restart policy. After a reboot, every other container would have come back and Postgres would not. The bug is trivial — one missing line. Its lifespan is not: it had been there for months, and it could only manifest on a host reboot, which had not happened in that whole time.

The real question is not how it got written. It is why nothing caught it. And the answer generalises well beyond our setup: the compose files are the only production configuration that nothing owns. They are not baked into the image, so the build never sees them. No test exercises them, because tests run against the application, not against the host’s topology. And our deploy job does not even copy them — it opens an SSH session and runs a script. They are edited in the repository, applied by hand, and validated by nothing.

In a chain that is otherwise fully automated — tests, static analysis, image build, zero-downtime deploy — that is where a defect can sleep indefinitely. Not in the code the pipeline reads twenty times a day, but in the handful of YAML lines it never opens.

What the kernel could have broken, and what we did not verify

A major kernel jump under a containerised Postgres deserves more than “it came back up”. Three questions are worth asking, and we can only answer the first two:

The data directory. It lives in a named volume, on the same filesystem, with the same storage driver. Nothing moved — and that is the reason the upgrade was survivable at all, not luck.
The daemon’s confinement profiles. Seccomp and AppArmor defaults ship with the Docker package, not with the distribution, which is why the containers found the same environment on the other side.
Durability semantics. Whether a new kernel changes anything for Postgres under our mount options is a question we did not answer. It held, which proves nothing. We are writing it down rather than claiming a verification we never ran.

The measurement already existed

Which leaves the obligation set out at the start: knowing the real cost of the outage we chose to accept. We stated a figure by reading container logs — the gap between a process’s last error and the next one’s start. That number describes the host, not the visitors. It leaves out the shutdown before it and the warm-up after, and it can be off by a factor of three.

Meanwhile all our traffic goes through a CDN, which had already recorded, request by request, exactly what people got during that window. The measurement we thought we lacked had been taken for us, by an appliance we had been paying for and never queried.

The reflex to fix is not “add instrumentation”. It is to inventory what already measures before adding anything: the CDN, the reverse proxy’s own logs, the provider’s console. Our procedural slips that night — a guessed container name, shell variables that do not survive an SSH reconnection, a grep loose enough to report 41 lines for 2 errors — all belong to the same family, and they are worth exactly one sentence: a runbook must resolve what it needs, never freeze it. Which instance is live is the textbook case: it changes at every deploy.

Why we publish all of this — and the one thing we hold back

A report is only useful if it is specific, so this one carries the commands, the failure modes and the gaps. Which raises a fair question: is publishing all that not handing an attacker a map?

Our rule fits in one sentence. The problem is never naming a version. It is naming a version you are still vulnerable on.

“We were on version X, it cost us this, it is patched” is ordinary post-mortem practice. The same text published before the fix is a weakness that is still true with the target attached — a case study is signed, it names a company and a domain. So: fix first, tell afterwards, and generalise whatever teaches nothing. The gap — seven versions of silent drift — is the lesson; our host’s exact version string is not. What never gets published is the other category, the part that cannot be learned from but can be copied: host names, paths, the chain of keys that decrypts a backup. The line is not “sensitive versus harmless” — it is does this teach, or does this open?

What it gave us

Four coupling points isolated between a containerised application and its host: kernel, daemon, the daemon’s apt sources, restart contract. Short enough to check by hand, before and after.
A frozen update path restored: the daemon had drifted seven minor versions behind, with nothing able to report it.
A structural blind spot named: the compose files, the only production configuration that no build, no test and no deploy job ever reads.
A measurement recovered rather than built: the CDN had already recorded what visitors saw, for free.

Good practices

Write down your coupling points once. On a container host there are four of them, they are always the same, and checking them takes ten minutes.
After a release upgrade, re-check the third-party sources first: a package manager with nothing left to compare against reports that everything is up to date, and it is not lying.
Look for what your automation does not own. In a fully automated chain, the defect that survives is in the file the pipeline never opens.
Inventory what already measures — CDN, proxy, provider console — before adding instrumentation. The figure you are missing has often already been recorded.
A runbook resolves, it never freezes: which instance is live, its container name, the service id — all of it is asked for at call time.

Watch-outs

The dangerous failure is not the service that stops, it is the one that keeps working while losing its ability to be updated. It emits nothing.
“It came back up” proves nothing about durability. Write down the questions you did not answer rather than claiming a verification you never ran.
A defect that can only manifest on a host reboot has the lifespan of the interval between two reboots. On a well-behaved server, that is months.
An internal log says when a process died, never when visitors stopped being served. Only a measurement taken in front of the stack says that.
Fix before you tell: a report describing a weakness that is still open, signed with your own name, is not transparency — it is an instruction manual.

Building a complete, production-ready SaaS with a coding agent

2026-09-26T00:00:00+00:00

How we designed, secured and shipped an entire platform — blue-green switching with no downtime, real direct debits, passkey sign-in, a trilingual site, encrypted backups — while working alongside a coding agent.

The report goes through the architecture we settled on, what the agent genuinely accelerated, and above all the places where we had to take the wheel back.

Guaranteeing legitimate case studies without a moderation team

2026-09-25T00:00:00+00:00

A case-study platform is worth exactly as much as the trust placed in what gets published on it. One fake report and the credibility of the whole corpus wobbles. The question we faced: how do you guarantee the legitimacy of every publication, at scale, without standing up a moderation team — and without handing the triage to an AI, which judges the form of a text rather than the legitimacy of whoever publishes it?

Our answer replaces content moderation with sender verification: no company, no publication; a minimum of substance required; an intra-community VAT number checked against the EU registry; full traceability.

The report also tells the story of the two traps we hit along the way, both from the same family: a third-party service answering 200 OK without having been able to check anything, then an “unknown” state that actually covered two opposite situations — “I could not check right now” and “I will never be able to check this value”. The second one let any string of characters through for months.