Hexagonal Architecture (Ports & Adapters)

When to use

• The user wants domain logic that does not import framework, ORM, or HTTP classes so it can be tested and reused in isolation.
• The user needs to swap a database, message queue, or third-party client without changing business logic.
• The user wants to unit-test use cases by substituting in-memory fakes for databases and external services.

When NOT to use

• Do not force a hexagonal core when the team deliberately builds framework-native (active-record, controllers-with-logic) and accepts the coupling.
• Do not impose ports and adapters on a thin CRUD script that has no business rules and will never swap infrastructure.

Core guidance