ddd

Refactor incrementally: extract domain models free of framework imports, define outbound port interfaces for repositories, create in-memory adapters for testability, move orchestration into application services, and wire everything in a composition root. Add architecture tests to prevent re-coupling.

Entities have a distinct identity that persists through attribute changes and are compared by ID. Value objects are defined entirely by their attributes, are immutable, self-validating at construction, and compared by value, such as Money, Email, or DateRange.

Hexagonal architecture makes the domain the center with dependencies pointing only inward through port interfaces. Adapters for databases, APIs, and UIs implement those ports, so infrastructure can be swapped without touching domain code, unlike traditional top-down layers.

Avoid it for simple CRUD applications, short-lived prototypes, thin database wrappers, or small teams with straightforward domains. The indirection overhead outweighs benefits when business logic is minimal; start simple and refactor toward DDD as complexity grows.

Keep the domain layer free of infrastructure imports so unit tests run pure business rules directly. Replace outbound ports with in-memory fake repositories in service tests, and reserve real database tests for adapter integration tests with test containers.