Three architectures walk into your codebase. Only one makes tomorrow’s changes cheaper.
Press enter or click to view image in full size
You start with a “simple CRUD app.” Nothing fancy just a few endpoints, a database, and maybe a login screen if you’re feeling responsible. Six months later, that same app looks like an Elden Ring skill tree. Controllers talk to services that talk to databases that somehow talk back, and your unit tests collapse if you so much as rename a column.
Sound familiar?
Developers rant about this stuff every day:
- “My tests break every time I change the database.”
- “Why does my business logic live in five different places?”
- “I just wanted to add a feature, not refactor the entire universe.”
This is where architecture comes in. Not the skyscraper kind the “how do we stop spaghetti from turning into lasagna” kind. The big question is: which style actually helps us ship clean, testable, maintainable code without making our lives harder?
In this piece, we’ll break down three heavy-hitters:
- Hexagonal architecture (aka Ports & Adapters)
- Clean architecture (Uncle Bob’s layered rings)
- Onion architecture (the domain-core classic)
We’ll compare them, show where each shines (and fails), and give you a practical decision guide for 2026 codebases. No PhD required, no 40-slide diagrams, just what you need to survive tomorrow’s changes.
TLDR: If your app feels like spaghetti now, this article will show you whether Hex, Clean, or Onion is the sauce you actually need and when you should just keep it simple.
Why we even need architectures
Let’s be real: most of us don’t start a project thinking,
“I’m going to design a beautiful, future-proof architecture today.”
Nope. We think:
“Let’s get this feature working before lunch.”
And that’s fine… until it isn’t.
Without some structure, your codebase slowly mutates into a spaghetti monster. Controllers balloon into “God services.” Database queries leak everywhere like water through a cracked dam. Changing one thing means breaking three others, and onboarding a new dev takes longer than teaching your parents how to use Git.
Developers complain about this constantly on Reddit and Stack Overflow:
- “Unit tests feel useless because they break whenever we swap infra.”
- “It takes a week for a junior to add their first endpoint.”
- “We picked Mongo, and now we’re basically stuck with it forever.”
These aren’t just minor annoyances. They’re productivity black holes. Every hour spent fixing brittle tests or reverse-engineering someone’s “service utils helper manager” class is an hour not spent shipping features.
The point of an architecture isn’t to impress interviewers or flex buzzwords. It’s to put guardrails in place so future-you doesn’t rage-quit at 2 a.m. when a “simple change” turns into a full refactor.
At its best, an architecture untangles dependencies, keeps your business rules clean, and makes testing less painful. At its worst, it adds needless ceremony and boilerplate. The trick is knowing which one helps your app and which one just makes your life harder.
And that’s why we’re here. Let’s start with the one that’s been getting the most buzz: Hexagonal architecture.
Press enter or click to view image in full size
Hexagonal architecture 101
Ever swapped a database and watched half your app catch fire? That’s the kind of chaos Hexagonal Architecture (aka Ports and Adapters) was designed to prevent.
The idea is simple: keep your business logic in the center, and push everything else databases, APIs, UIs to the edges.
Think of your domain as the socket on the wall. The outside world connects through adapters: a SQL adapter, a NoSQL adapter, a REST API adapter, even a CLI adapter. The socket doesn’t care what’s plugged in, as long as it fits the port.
Quick example
Core: Orderservice
Port: PaymentPort
Adapters: StripeAdapter,PayPalAdapter
Switch Stripe for PayPal? No domain code changes just swap the adapter.
Why it matters
- Decoupling: swap infra without breaking business rules
- Testability: mock a port, keep tests clean
- Flexibility: add multiple entry points without spaghetti
Hex isn’t about looking clever in diagrams. It’s survival. Frameworks and DBs churn every few years Hex gives your core logic a fighting chance to outlive them.
Clean vs Onion vs Hexagonal
Once you dive into architecture discussions, you’ll quickly notice that Clean, Onion, and Hexagonal often get lumped together. They all share the same DNA: keep business rules at the center, shove frameworks and databases to the edges. But their vibes and how painful they feel to implement are different.
Clean architecture
Uncle Bob’s classic. Picture concentric circles where dependencies always point inward. The innermost ring is your use cases and entities. As you move outward, you hit interfaces, then frameworks and drivers. The rules are strict: nothing in the core should know about anything on the outside. It’s powerful, but it can feel like playing a coding version of Dark Souls lots of rules, lots of ceremony.
Onion architecture
Onion is like Clean’s less preachy cousin. Still has rings, still emphasizes the domain model in the center, but it focuses more on layering your domain and application logic around that core. It’s structured, but usually has less “thou shalt not” energy. If Clean feels academic, Onion feels more practical.
Hexagonal architecture
Then comes Hex, which says, “Forget the rings let’s think in terms of ports and adapters.” Instead of visualizing layers, you think of your domain as the socket and the outer world as swappable plugs. Same goal (protect the core), but Hex usually feels less intimidating to beginners.
Here’s the side-by-side:
Press enter or click to view image in full size
So which one should you pick? If your team is battling regulatory checklists and compliance audits, Clean might be worth the ceremony. If you’re building a rich domain model (say, a banking system), Onion shines. But for most apps that need to survive framework churn and play nice with multiple integrations, Hex is the pragmatic sweet spot.
You don’t need a PhD to choose just ask yourself:
Do I need strict rules, structured layers, or flexible plugs?
Developer pain points in 2025–26
Architectures are supposed to make life easier. But in practice? Developers keep tripping over the same issues just wrapped in fancier patterns.
Overengineering small apps
A two-person startup building a to-do list app doesn’t need Clean architecture with five layers of indirection. Yet you still see juniors posting on Reddit: “Should my MVP use Hex with DDD?” Bro, no. If your app has fewer endpoints than a microwaved API tutorial, adding ports and adapters is just cosplay.
Underengineering big apps
On the flip side, plenty of teams ship a “temporary monolith” that accidentally becomes permanent. Fast forward a year: half the team is burnt out, and every change feels like diffusing a bomb. The problem wasn’t picking Hex or Onion it was pretending they didn’t need structure at all.
AI-generated boilerplate
2025 brought another twist: AI-generated code. Tools like Copilot, Cursor, and Amazon’s AI IDE can spit out services and adapters faster than you can sip your coffee. Sounds great, until your repo is full of layers you don’t actually understand. Developers on Hacker News have started joking: “AI gave me Clean architecture, but I don’t even know where my business logic lives anymore.”
The vibe on forums
A recurring thread across Reddit, HN, and Discord:
- “Hex looks neat, but do I really need all these interfaces?”
- “We used Clean, now our onboarding doc is a novel.”
- “Our AI assistant built an Onion app… we still don’t get it.”
The pain isn’t the architecture itself it’s mismatching the tool to the job. Use too much, you drown in ceremony. Use too little, you drown in chaos.
Next, let’s get practical: when does Hexagonal actually make sense, and when should you avoid it?
Press enter or click to view image in full size
When (and when not) to use Hexagonal
So when should you actually go full Hex? Short answer: when you care about testability, churn survival, or juggling multiple entry points. Long answer: let’s break it down.
When Hex makes sense
- You need testability. Writing clean unit tests without dragging in a real DB or API becomes way easier. Mocking a port is cleaner than mocking half your framework.
- You expect churn. Switching from SQL to NoSQL, from REST to gRPC, or from one framework to another? Ports and adapters are basically insurance.
- You’re scaling. If your system has multiple ways in (APIs, queues, CLI tools), Hex keeps your domain logic from becoming a traffic jam of spaghetti.
When to skip it
- Tiny MVPs. If you’ve got fewer than five endpoints, Hex is overkill. Use KISS (Keep It Simple, Stupid) and just ship.
- Solo side projects. Unless you’re secretly planning for unicorn status, you’ll move faster without layers of ports and adapters.
- Short-lived apps. Hackathon project? Startup experiment? Don’t waste cycles future-proofing something that might not see next month.
Quick decision guide
- <5 endpoints: go simple.
- Multiple integrations / scaling: Hex is your friend.
- Enterprise / multi-team: Clean or Onion will give you stronger guardrails.
Think of it like armor: Hex is a good leather jacket. Clean is full medieval plate mail. Sometimes you just need a hoodie.
Step-by-step example
Let’s put this into code. Imagine we’re building an OrderService that needs to process payments. Instead of wiring Stripe or PayPal directly into our business logic, we define a port an interface that says what “payment” means for our domain. Then we build adapters for each provider.
Step 1: Define the port (contract)
# domain/ports/payment_port.py
class PaymentPort:
def charge(self, amount: float, currency: str) -> bool:
raise NotImplementedError
This is our plug socket. The core app only knows this interface exists.
Step 2: Write the core service
# domain/order_service.py
from domain.ports.payment_port import PaymentPort
class OrderService:
def init(self, payment: PaymentPort):
self.payment = payment
def place_order(self, amount: float, currency: str):
if self.payment.charge(amount, currency):
return "Order confirmed!"
return "Payment failed."
Notice: OrderService has zero clue whether Stripe or PayPal is behind the curtain.
Step 3: Build adapters
# adapters/stripe_adapter.py
from domain.ports.payment_port import PaymentPort
class StripeAdapter(PaymentPort):
def charge(self, amount: float, currency: str) -> bool:
print(f"[Stripe] Charging {amount} {currency}")
return True
# adapters/paypal_adapter.py
class PayPalAdapter(PaymentPort):
def charge(self, amount: float, currency: str) -> bool:
print(f"[PayPal] Charging {amount} {currency}")
return True
Step 4: Wire it up
# main.py
from domain.order_service import OrderService
from adapters.stripe_adapter import StripeAdapter
order_service = OrderService(payment=StripeAdapter())
print(order_service.place_order(49.99, "USD"))
Want PayPal instead? Just swap StripeAdapter for PayPalAdapter. Domain untouched.
TLDR: Ports = contracts, adapters = implementations, domain = rules. Swap the outside, keep the inside safe.
Press enter or click to view image in full size
The future-proof angle (2026 and beyond)
The tech stack you’re using today probably won’t look the same in two years. Frameworks burn out faster than JavaScript memes, and AI-assisted infra keeps reshaping how we build apps. In 2026, we’re already seeing codebases where 30% of the boilerplate was written by AI and half of it tied directly to a single framework.
That’s a problem. Because when the framework dies (and it will), your business logic goes down with it. Ask anyone who tried to migrate off Meteor, Backbone, or the “hot” ORM of 2018.
Hexagonal architecture is basically an insurance policy against that churn. By isolating frameworks, databases, and APIs at the edges, your core logic survives. You can rewrite the adapters as the landscape shifts AI queue system this year, some quantum-backed DB next year without nuking the rules that actually matter.
In other words: Hex makes your app refactor-friendly. When your infra or tools inevitably evolve, you won’t be staring at a rewrite from scratch. You’ll just be swapping plugs.
And in an industry where “change” is the only constant, that’s as close to future-proof as you’re going to get.
Conclusion
Codebases don’t blow up all at once they rot slowly, one “quick fix” at a time. Clean and Onion architectures work, but often feel like heavy armor when you just need something lighter.
Hexagonal usually hits the sweet spot: simple enough for small-to-mid apps, strong enough to survive tomorrow’s churn. The real point of architecture isn’t buzzwords it’s making change cheaper.
So audit your app: is your business logic free to evolve, or welded to a framework that might be dead next year? The survivors in 2026 won’t be the prettiest apps just the ones designed for change.
Helpful resources
- Alistair Cockburn on Hexagonal Architecture
- Uncle Bob’s Clean Architecture overview
- Onion Architecture explained
- Martin Fowler’s take on architecture
- Hexagonal Architecture example repo
Top comments (0)