Rants on Software Design

“I can’t rely on LLMs because they’re not deterministic. How can I be sure what I’ll get?” — I bet you’ve thought that yourself. I did for sure.

It’s a fair point. LLMs can be unpredictable: the same input can produce different outputs. But here’s the thing: neither are you deterministic, nor am I. A cup of coffee can dramatically improve our “inference.” A bad night’s sleep can tank it. We’re so unpredictable that we have a term for when our variability wreaks havoc: human error.

And when human error happens, we’ve learned not to simply blame the person. Instead, we examine the environment. Why didn’t the system prevent this? We expect systems to withstand human errors, or better yet, prevent them from happening in the first place.

LLMs are made in our likeness. They’re trained on the code, books, and articles we’ve written. So why do we blame them for human errors? Sorry, I meant machine errors.

Vibe coding, or as some prefer to call it, “hands-off” software engineering, is having its moment. AI agents write code, implement features, and even spin up entire projects from a prompt. The results are impressive for demos. For production systems, not so much.

The knee-jerk reaction is to blame the models. That was my reaction too. But the problem isn’t the models. It’s what we’re not giving them.

Production-grade code is iterative. No one writes it right on the first attempt. Our profession is built around this fact: code reviews, refactoring, pair programming, testing. Domain-Driven Design makes iterative modeling a first-class concern, because getting the model right requires continuous learning and refinement. We iterate until the code is good enough. Yet when AI doesn’t nail it on the first try, we use it as proof that AI isn’t there yet.

I was in that camp. Then something changed my mind.

“Words should be weighed, not counted.” — A Yiddish Saying

Static code analysis tools count dependencies, calculate ratios, and assign neat scores. Yet in my experience, chasing those metrics never really made the design more modular. It’s so easy to game the scores without any improvement to the design itself. Let’s see why, and what you can do instead.

The Counting Approach

Most static analysis tools evaluate coupling by counting dependencies. Afferent coupling (Ca) counts how many components depend on yours. Efferent coupling (Ce) counts how many components yours depends on. A popular instability metric combines them into a neat formula:

I = Ce / (Ce + Ca)

The higher the ratio of outgoing to total dependencies, the more “unstable” a component is considered. Simple. Automatable. And deeply misleading.

Every other post on my feed celebrates how AI lets us write code faster: whole apps built in a matter of a few hours, 99% AI-generated codebases, hundred-fold productivity gains, and on and on. But does writing code faster actually make us more productive?

A Quick Detour Through a Factory

The Theory of Constraints says that every system’s throughput is limited by a single constraint: its bottleneck. What makes a system more effective? Improving the bottleneck. What makes a system less efficient? Improving anything else.

I know, that second part is counterintuitive. Here’s the thing: if you speed up a non-bottleneck, you don’t improve the system; you produce more work-in-progress that piles up in front of the bottleneck! More inventory. More cost. More waste. The system becomes more expensive to operate, not more productive.

This is a well-established principle in manufacturing, and software manufacturing is no exception.

Lately I’ve been spending more and more time researching AI models and their effects on software engineering and architecture, so it’s time to share my findings.

First, let me explain what I mean by “complicated.” I’m a huge fan of the Cynefin framework. If you are not familiar with it, here is the gist.

Cynefin

Say you need to decide on something. For example, let’s assume you need to change the behavior of a software application and are contemplating how to do it.

Cynefin is a tool for guiding the decision-making process in different kinds of situations. It says that first you need to understand what kind of situation you are in, and once you do, picking the optimal course of action is much easier. For that, the framework identifies four basic situations—domains:

This weekend, I have a rare opportunity to write about two things I care deeply about: Domain-Driven Design and Formula 1. If you’re not into Formula 1, don’t worry—I’ll give a brief heads-up into the domain and the ubiquitous language of the relevant bounded context.

The Crash

This race weekend in the beautiful Japan started with a scare. During a pre-race practice, Jack Doohan, a rookie driver from the Alpine team, suddenly spun out of control in the highest-speed section of the track and hit a wall (video). He was going over 320 kilometers per hour (200 miles per hour) at the time. Thanks to the marvels of modern race car engineering, Jack walked away unharmed—not even a concussion. But why did it happen in the first place?

One of the most common pieces of feedback I received about Balancing Coupling in Software Design was that readers wanted a resource they could easily share with colleagues—a quick way to introduce the balanced coupling model and make discussions about it more accessible.

To meet that need, I created coupling.dev, a website that distills the core concepts of balanced coupling and related models into concise, approachable posts. It also serves as a hub for other learning resources, including conference talks and podcast appearances, helping teams streamline adoption and deepen their understanding together.

My news feed these days:
“Take a look at the app I built with zero coding skills!”
“50% of our code is now written by AI!”
“Engineering hiring freeze: AI is the future!”

Alright then. Time for me to jump on the vibe coding bandwagon and share an opinion that some may categorize as a hot take.

The notion of modularity was introduced to software engineering way back in the late 1960s. Today — many decades later — we’re entering the golden age of modularity. To understand why, let’s first define what modularity actually is.

Modularity

There are many ways to define modularity — from designing software systems as interchangeable LEGO blocks to chasing the holy grail of reusable “building blocks” meant to be plugged into anything and everything. I prefer a more practical perspective. To me, a modular design satisfies two key criteria:

1. When you need to change the codebase—whether to adjust existing functionality or introduce a new one—it’s crystal clear what parts of the system need to be touched. Ideally, the number of affected components should be as small as possible. Preferably, just one.

2. When you introduce a change to a modular system, you know exactly what the effect of that change will be. You can predict the system’s behavior.

My previous post in this series discussed the reliability issues many messaging-based systems suffer from and how to address them by implementing the outbox pattern. This post switches the focus from publishing to processing messages published by other components of the system.

As before, I will start by defining the problem we have to tackle.

The Problem

Let’s revisit the outbox pattern once more. It addresses the common problem of publishing messages after the underlying business transaction has already been committed: the events might not get published at all. By implementing the pattern, you ensure that all the events will be published—at least once. Let me explain the last part.

Figure 1: The outbox pattern

In my previous post in the series, I discussed the basic building blocks for implementing event-driven architecture (EDA) using AWS managed services. This post is about the advanced basics. It’s advanced because, based on my consulting experience, very few companies apply the practices I want to discuss. However, I still consider this as basics because these practices are not optional but essential for implementing reliable messaging-based systems.

Although the examples in this post use AWS services, the material applies to any system, regardless of the infrastructure it runs on. The implementation might differ, but the underlying principles remain the same.

Since this post is about a pattern—and patterns, by definition, are repeatable solutions to commonly occurring problems—I want to begin by discussing a commonly overlooked problem in EDA-based systems.

The Problem

In the previous post, I suggested using AWS SNS for publishing messages in an event-driven system. Here’s a common example of how such publishing is carried out:

...

sns.publish(
    TopicArn=users_topic_arn,
    Message=json.dumps({
        'event_type': 'user_registered',
        'event_id': str(uuid.uuid4()),
        'user_id': 'USER12345',
        'name': 'John Doe',
        'email': 'john.doe@example.com',
        'source': 'mobile_app',
        'registration_date': '2024-10-11T20:01:00Z'
    })
)

...

In the above example, an event of type user_registered is published to an SNS topic. But did that event come from thin air? Is that all services do, just publish messages? Of course not. The event is part of a larger business process that typically involves updating some state in an operational database before notifying external components about it. A more accurate representation of this process would look like this: