You added hexagonal architecture to your CRUD app. Now changing a field name requires touching 6 files. Congratulations you've optimized for the wrong problem.
Every pattern has a failure mode. Hexagonal architecture's is using it for everything.
This series taught the pattern in good faith: clean domain models, proper ports, testable adapters, and a composition root that wires it all together. Now let's do the honest part. When does this structure pay off? When is it expensive overhead that slows you down? And what are the traps that catch even experienced engineers?
The Real Costs
Hexagonal architecture is not free. Before weighing whether to use it, you need to know what you're actually paying.
The upfront complexity tax. You're writing a new feature. In a flat codebase, you add a field to a model, update the query, ship. In a hexagonal one, adding promo_code to Order means updating the domain model, the port interface, the SQLAlchemy adapter, the in-memory test adapter, and probably two or three test fixtures. Here's what that cascade looks like:
# 1. Domain model — domain/models.py
@dataclass
class Order:
customer_id: str
items: list[OrderItem]
discount: Discount
promo_code: str | None = None # new field
status: str = "draft"
id: str | None = None
# 2. Port — domain/ports.py (if the port has a find method with filtering)
class OrderRepository(Protocol):
def save(self, order: Order) -> Order: ...
def find_by_promo_code(self, code: str) -> list[Order]: ... # new method
# 3. SQLAlchemy adapter — adapters/sqlalchemy/repositories.py
class SQLAlchemyOrderRepository:
def save(self, order: Order) -> Order:
row = OrderRow(
customer_id=order.customer_id,
status=order.status,
total=order.total().amount,
promo_code=order.promo_code, # new column
)
...
def find_by_promo_code(self, code: str) -> list[Order]: # new method
rows = self.session.query(OrderRow).filter_by(promo_code=code).all()
return [self._to_domain(row) for row in rows]
# 4. In-memory adapter adapters/memory/repositories.py
class InMemoryOrderRepository:
def find_by_promo_code(self, code: str) -> list[Order]: # new method
return [o for o in self.saved if o.promo_code == code]
# 5. ORM table adapters/sqlalchemy/orm.py
orders_table = Table("orders", metadata,
Column("promo_code", String, nullable=True), # new column
...
)
Five files for one field. In a small FastAPI app with a Pydantic model and a SQLAlchemy model, that's two files. When you're moving fast or still discovering the domain, this multiplier is painful.
The indirection overhead. Junior engineers joining the codebase struggle to follow the execution path. A request comes in at api/orders.py, calls OrderService, which calls a CustomerRepository Protocol and where does that actually go? You have to know about dependencies.py and the composition root to understand what runs. Debugging a broken save operation means tracing through three layers before you find the SQLAlchemy stack trace that tells you what actually went wrong.
Port interface rigidity. Ports are stable by design that's the point. But early in a project, requirements change constantly. Every time a port changes, every adapter implementing it must change too. When your domain isn't stable yet, that multiplies the churn from exploratory work.
When It's Overkill
Here's the honest version: hexagonal architecture is the wrong choice for a lot of real projects.
Signal 1: No meaningful business logic. If your domain model is just dataclasses with no methods data in, data out, nothing in between there's no domain worth protecting.
@dataclass
class BlogPost:
title: str
body: str
author_id: str
published_at: datetime | None = None
id: str | None = None
No behavior. No rules. No invariants. You've drawn a clean fence around an empty lot. Most internal tooling, admin dashboards, and data pipelines live here. Hexagonal architecture would be ceremony without substance.
Signal 2: A single adapter you'll never swap. The flexibility of ports and adapters is: multiple adapters can fulfill the same port. But what if you have exactly one adapter per port, and no realistic plan to add a second?
# You have this:
class UserRepository(Protocol):
def find_by_id(self, user_id: str) -> User | None: ...
# Implemented only by:
class PostgreSQLUserRepository:
... # and this will never be replaced
You've paid the interface cost for flexibility you'll never use. You could write the SQLAlchemy call directly in the service, test it with a test database, and be done in half the time.
Signal 3: An early-stage project where the domain is still being discovered. Hexagonal architecture rewards stable domains. It punishes exploration. "Write it flat, refactor when the boundaries are clear" is not a cop-out. It's a legitimate strategy. The ports will emerge naturally when you feel the second adapter appearing or when testing becomes painful without them.
Signal 4: A performance-critical hot path. The port abstraction adds function calls and interface dispatch. In tight loops or data processing pipelines where Python-layer performance matters, direct calls are faster.
Common Pitfalls (Even When You're Doing It Right)
Over-porting. Creating a port for every external dependency, including things that will never have a second implementation. A Logger port backed only ever by StructlogLogger. The test for "should this be a port?" is: will there ever be a second adapter? If the answer is no, you're creating ceremony, not flexibility.
Leaky ports. A port should speak the language of the domain, not the language of infrastructure:
# Bad: infrastructure leaking into the port
class OrderRepository(Protocol):
def find_orders(self, filters: dict, limit: int, offset: int) -> tuple[list[Order], int]: ...
def execute_raw(self, query: str, params: dict) -> list[dict]: ...
# Good: domain language only
class OrderRepository(Protocol):
def save(self, order: Order) -> Order: ...
def find_pending(self) -> list[Order]: ...
def find_by_customer(self, customer_id: str) -> list[Order]: ...
If you can read the method name and understand the business intent without knowing anything about databases, you're in the right place.
The anemic service trap. If your domain model is rich (as Post 3 built it), the service should be thin. The opposite failure is common: a service that does all the work, and domain objects that are still just data containers.
# Service doing too much domain logic leaked up
class OrderService:
def place_order(self, customer_id: str, items: list[OrderItem]) -> Order:
customer = self.customer_repo.find_by_id(customer_id)
raw_total = sum(item.price.amount * item.quantity for item in items)
if customer.loyalty_points > 500:
raw_total *= 0.9
order = Order(customer_id=customer_id, items=items, discount=Discount(0.0))
order.status = "pending"
return self.order_repo.save(order)
The discount calculation belongs on Customer.discount(). The status transition belongs on Order.place(). When you see arithmetic in the service, a rule has leaked out of the domain.
Testing the wrong things. Hexagonal architecture makes domain logic easy to test in isolation. But over-investing in unit tests and under-investing in integration tests produces a domain with 100% test coverage that silently breaks because the SQLAlchemy adapter isn't mapping a field correctly.
When Hexagonal Architecture Actually Pays Off
Long-lived systems with real business rules. Order management, billing, insurance, financial calculations. The longer a codebase lives, the more the clean boundary pays back. Years of changes stay organized because new infrastructure adapters don't touch the domain.
Systems with multiple infrastructure targets. When you actually need multiple adapters a PaymentGateway port backed by StripeAdapter, BraintreeAdapter, and InMemoryPaymentAdapter the pattern earns its keep. The service never changes when you add a new processor.
Teams doing Domain-Driven Design seriously. When the team has a shared ubiquitous language and domain objects reflect real business concepts, ports emerge naturally from the domain's needs.
Codebases with a 2+ year horizon. The upfront cost is amortized over time. A codebase maintained for years pays the setup cost once and benefits across every feature after that.
The Decision Framework
Use hexagonal architecture if:
✓ Your domain has real behavior — methods, rules, state transitions
✓ You need (or will need) multiple adapters for the same port
✓ The codebase will be actively maintained for 2+ years
✓ The team understands DDD and will maintain the vocabulary
✓ You need fast, isolated domain tests without infrastructure
Skip it (or defer it) if:
✗ You're building CRUD — data in, data out, minimal logic
✗ The domain is still being discovered (early startup, first few sprints)
✗ Every port has exactly one adapter and no second is planned
✗ You're wrapping a framework with strong data layer opinions (Django ORM)
✗ The team is small and junior — onboarding time matters more than purity
✗ This is a prototype or MVP with a likely rewrite horizon
The gradient approach is often the right one: start without hexagonal architecture. Build flat. Extract a port when you feel the second adapter appearing. Extract another when testing becomes painful. The full structure emerges when it's earned, not when it's assumed.
What to Do With Your Existing Codebase
Don't rewrite everything. Pick one service — the one with the most business logic, the hardest tests to write, the most infrastructure coupled into the domain. Extract that one first. If the result is cleaner and faster to test, you've found the right place to keep going. If it's not improving anything, that's the signal to stop, not to push harder.
The Series in One Paragraph
Post 1 named the problem: domain logic fused with infrastructure. Post 2 named the pattern: ports and adapters. Post 3 built a domain worth protecting. Post 4 wired it all together. This post gave you the honest accounting.
The meta-lesson: it's a tool for a specific problem. The engineers who get the most out of hexagonal architecture are the ones who understand its costs as clearly as its benefits.
Pick one place in your current codebase. Apply the framework. That's worth more than any number of rewrites.
SOCIAL SHARE CARD GENERATOR