Hexagonal Architecture Should Be Your Default

I think hexagonal architecture should be the default for almost any project bigger than a script. Not because it's trendy or because some book said so, but because the math is wildly in your favor: the cost is tiny and the payoff is large.

Let me make that case.

What you actually pay

Hexagonal architecture asks you for two things:

1. A port — an interface describing what your domain needs from the outside world. "I need something that can save a User." "I need something that can send an email."
2. An adapter — a concrete implementation of that port. The Postgres class that saves the user. The SendGrid client that sends the email.

That's it. That's the whole tax.

In statically-typed languages, the port is a literal interface (or trait, or protocol). In interpreted languages, such as Python, Ruby, or JavaScript, you don't technically need to declare anything; duck typing handles it. I still recommend writing the contract down somewhere, even informally as a base class or a Protocol or just a comment block. The reason isn't the compiler. It's that when something goes wrong at 2 a.m. and you're staring at a stack trace, having an explicit named seam in the system makes "where did this go off the rails" a five-second question instead of a five-minute one.

Here's the part people undersell: the adapter is the code you were going to write anyway. You were going to call the database. You were going to hit Stripe. You were going to send the email. The only difference is that this code now sits behind one layer of indirection instead of being splattered through your business logic. You aren't writing extra code. You're writing the same code in a slightly more organized place.

So the real cost is: one interface (free in some languages), one small bit of wiring, and the discipline to call through it instead of around it.

What you get

A lot. Here's the short list.

Testability. This is the big one. Swap your real adapters for in-memory fakes and your domain logic becomes testable in milliseconds, with no database, no network, no Docker container. Tests that used to take a minute take a second. Tests that were flaky stop being flaky because the flake lived in the infrastructure, not the logic.

Swappability. You can replace Postgres with SQLite, SendGrid with Mailgun, REST with gRPC, and your domain doesn't notice. You probably won't do this often...but when you have to, it's a contained change instead of a rewrite. More importantly, you can do it gradually: run both adapters side by side, migrate slowly, roll back trivially.

Predictability. The seams are explicit. You can look at a domain class and know exactly what it depends on — it's right there in the constructor. You can look at the ports and know exactly what the outside world is allowed to do to your domain. Surprise interactions get rare because there are fewer places for them to hide.

Deferred decisions. You can build the domain before you've picked a database. You can model the business before you've picked a queue. Decisions that used to block work become decisions you can make later, with more information, when they actually matter.

Onboarding. New devs read the ports and immediately see what the system needs and what it talks to. The shape of the application is visible in one folder.

Forced clarity. Having to name a port (e.g., "what does my domain actually want from a payment processor?") makes you think about the domain on its own terms instead of in terms of whatever vendor you happen to be using this quarter. You end up with a PaymentGateway interface that says what you need, not a StripeClient reference that says what Stripe offers. Those are different things and the first one ages much better.

Add it up: for the price of an interface and a small bit of wiring, you get fast tests, replaceable infrastructure, clearer code, faster onboarding, and the option to defer decisions. That's an absurdly good trade.

It works for almost any project

People associate hexagonal with web backends, but the pattern is general. Anything that has logic that needs to talk to stuff benefits from separating the two.

• CLIs. The domain doesn't care whether it was triggered by argv, a config file, or a cron entry. Inbound adapter parses the inputs, calls the domain, formats the output.
• APIs and web services. Obvious fit. More on this below.
• Background workers. Same as a web app, just with a queue consumer as the inbound adapter instead of an HTTP controller.
• Desktop and mobile apps. Domain doesn't care if the UI is SwiftUI, Qt, or a terminal. The view is an adapter.
• Data pipelines. Sources and sinks are adapters. Transformations are domain.
• Even libraries. Lighter touch, but the principle of "separate the logic from the IO" still applies.

Where it isn't worth it: one-off scripts, throwaway prototypes, and pure CRUD apps where the "domain" is literally just shuffling rows in and out of a table. In those cases the indirection genuinely costs more than it saves. But that's a smaller share of real-world projects than people pretend.

How I use it for web apps

Concretely, here's the shape:

Domain in the middle. Entities, value objects, and use cases (some folks call them application services, services, interactors, whatever). The use cases are the public API of your application — they're verbs. RegisterUser. PlaceOrder. CancelSubscription. Each one orchestrates the domain to accomplish one meaningful thing.

Inbound adapters at the top. HTTP controllers, GraphQL resolvers, queue consumers, CLI commands. Their job is small and dumb: parse the input, call a use case, format the response. If a controller has business logic in it, that's a smell — push it down into a use case where it can be tested without spinning up a request.

Outbound adapters at the bottom. Repositories that wrap the database. Clients that wrap external APIs. Email senders, file storage, queue publishers, the clock. Each one implements a port the domain owns.

The framework is an adapter, not the architecture. This is the mental shift that matters most. Rails, Django, Express, Spring — these are inbound adapters. They live at the edge. They're not the center of your app; your app's domain is the center, and the framework is a thing that lets the outside world talk to it. Treating the framework this way means your domain isn't married to it, your tests don't need it, and version upgrades don't ripple through your business logic.

What you end up with, in practice:

• Controllers stay thin. A few lines each. If a controller is long, work is in the wrong place.
• Use cases are testable in isolation with fake adapters. Fast, deterministic, no infrastructure.
• Adapters have their own integration tests that hit the real things — actual database, actual HTTP — to confirm the wiring works. Sparse, focused, not where your bulk of test coverage lives.
• End-to-end tests stay rare and exist only for the few flows you really want to smoke-test through the whole stack.
• Adding a new entrypoint is cheap. Need a CLI version of something the API does? Write a new inbound adapter and call the same use case. Need a webhook? Same.

Wrap up

The price of hexagonal architecture is one interface and one class — and you were going to write the class anyway. In exchange you get fast tests, swappable infrastructure, clearer boundaries, deferred decisions, and a codebase that survives changes in vendors, frameworks, and team members.

I don't think it should be the default for everything. Scripts and trivial CRUD genuinely don't need it. But for almost anything that's going to live longer than a few months or be touched by more than one person, the indirection pays for itself within the first month.

Pay the small tax. Get the big benefits. Hard to think of an easier call.