Your Ports Are Lying About Your Business

A developer argues that hexagonal architecture ports are typically named after HTTP operations like createUser or updateUser rather than business concepts, undermining their purpose of isolating business logic from delivery mechanisms. The engineer contends this mismatch turns tests into database checks instead of business specifications and that AI coding agents will replicate the flawed convention at scale. The post also questions whether the port interface is worth keeping in the single-adapter case.

Your hexagonal architecture ports might still be speaking HTTP instead of business. In hexagonal architecture, ports exist to isolate your business logic from how it's delivered. In practice, most of them are still named after HTTP operations like createUser or updateUser — a habit inherited from years of REST-first development. That mismatch isn't cosmetic. It turns your tests into database checks instead of real business specifications. And it's exactly the convention AI coding agents will pick up from your existing code and repeat at scale, for as long as the repo lives. I wrote about why ports keep lying about your business, and what it takes to name them so a domain expert would recognize what they actually do. Read the full article on the SQUER blog → https://www.squer.io/blog/your-ports-are-lying-about-your-business The part people push back on most is the single-adapter case — if there's only ever going to be one adapter, is the port interface worth keeping? Curious whether you'd skip it.