Field notes. Short version first: layered architecture and hexagonal (also called ports and adapters, or clean) architecture are not rival religions. They are two answers to one question. Which module is allowed to know about which? Get that arrow direction right and the names matter very little.
Classic layers
Most Spring, .NET and Django projects start here. Presentation (controllers) calls the business layer (services), which calls the data layer (repositories, the database). Each layer talks only to the one below. It is easy to explain and easy for a fresher to navigate, and for a CRUD application with little real logic it is perfectly good. I would not argue anyone out of it.
The weakness is the dependency direction. The business layer sits on top of the data layer, so it imports persistence types. In practice that means service classes end up holding ORM entities, calling database-specific features, and being impossible to test without a database. Business rules become coupled to the thing most likely to change: the storage technology, or the vendor of a payment API.
Another common failure: “layers” turn into pass-through. A controller calls a service method that calls a repository method that runs one query. Three files, no logic, lots of ceremony. If your service layer is a set of one-line delegators, the layer is decoration.
Hexagonal: invert one arrow
Alistair Cockburn’s hexagonal architecture puts the business logic in the centre and says the centre depends on nothing technical. Instead of calling a database class, the core defines a port: an interface written in the core’s own language, such as “save this order” or “charge this amount”. The outside world supplies adapters that implement those ports: one adapter talks to PostgreSQL, another to Razorpay, another is a fake used in tests. Incoming adapters work the same way: a REST controller, a message consumer and a command-line job all translate their input into calls on the core.
So the source-code dependency points inward. The database adapter knows about the core’s interface; the core knows nothing about the database adapter. Robert Martin’s Clean Architecture and Jeffrey Palermo’s onion architecture are variations on the same inward-pointing rule, with different diagrams and more named rings.
What you actually gain
- Fast tests. You can run the core’s rules with in-memory fakes in milliseconds, with no database, no network, no Spring context.
- Swappable edges. Moving from one payment provider to another means writing one new adapter, not hunting through services.
- Several entry points. The same logic serves the web API, a nightly batch and a queue consumer without copying rules.
What it costs
More files. More mapping, because the core has its own domain objects and each adapter converts to and from its own representation (database rows, JSON, vendor responses). Small teams sometimes drown in mappers. A new joiner meets interfaces with exactly one implementation and wonders why. If your app really is forms over a database, you are paying for flexibility you will never use.
My opinion, stated plainly: the claim that you will “swap the database someday” is the weakest reason to adopt it, because it almost never happens, and when it does, the work is dominated by data migration and query behaviour, not by class structure. The strong reasons are testability and keeping business rules readable and free of framework noise.
A rule of thumb for choosing
Ask how much of the system is rules and how much is plumbing. A loan-eligibility engine, a pricing module or an insurance premium calculator has dense, changing rules; protect them with an inward-pointing core. An internal admin screen that lists, edits and deletes records has almost none; use plain layers and move on.
You do not need to choose for the whole codebase either. Many good systems use simple layers for the boring parts and a hexagonal core for the one module that carries the business. Start layered. When you notice business code being hard to test, or a vendor API’s types leaking into your rules, introduce a port at that single seam. Refactoring toward it one boundary at a time is cheaper than building every boundary in advance.
Smells that say you got it wrong
Core classes that import framework annotations or HTTP types: the arrow is pointing outwards again. Ports shaped like the database (“findByIdWithJoins”) instead of the business need (“find open orders for customer”): the adapter’s concerns are leaking inward. An interface for every class “just in case”, including ones that will never have a second implementation. And a domain model that is only getters and setters while all the rules live in services, which gets you the cost of the pattern with none of the benefit.
Judge a design by one practical test: can I change how data is stored, or how requests arrive, without opening the files where the business rules live? If yes, whatever you call it, the dependencies point the right way.
Leave a Reply