architecture-patterns

Organize code into four layers: domain entities, use cases, adapters, and infrastructure, with dependencies pointing inward. Define repository interfaces in the domain layer, implement them in adapters such as PostgresUserRepository, and keep controllers thin by delegating to use case classes.

Clean Architecture organizes code into concentric layers with an inward dependency rule, while Hexagonal Architecture centers the domain and connects external concerns through ports and adapters. Both keep business logic independent of frameworks and make implementations swappable for testing.

Define a PaymentGatewayPort abstract interface with methods like charge, then implement adapters such as StripePaymentAdapter for production and MockPaymentAdapter for tests. The domain service depends only on the port, so implementations can be swapped without changing business logic.

Avoid full Clean Architecture for simple CRUD applications or small localized refactors, where the layering adds overhead without benefit. The pattern fits complex domains with meaningful business rules, multiple external integrations, or long-lived codebases requiring testability.

Aggregates are consistency boundaries with a root entity that controls access to related objects and enforces invariants, such as a Customer limiting addresses to five. Repositories persist and reconstitute entire aggregates, and domain events are published after saving.