architecture-patterns

Clean Architecture in Python organizes code into four layers: domain entities, use cases, adapters, and infrastructure. Dependencies point inward, so use cases depend only on abstract repository interfaces, while concrete implementations like PostgresUserRepository live in the adapters layer.

Clean Architecture organizes code into concentric layers with dependencies pointing inward, while Hexagonal Architecture centers the domain and connects external concerns through ports and adapters. Both keep business logic independent of frameworks and make cores testable with mock adapters.

Define repository and gateway interfaces as abstract ports, then inject mock adapters during testing. For example, a MockPaymentAdapter returns successful results without calling Stripe, letting you test use cases and domain services without external dependencies.

Avoid these patterns for simple CRUD applications or small localized refactors, where the layering overhead exceeds the benefit. They fit complex domains with rich business rules, not systems that are primarily frontend or need only minor implementation changes.

Common pitfalls include anemic domain models with data but no behavior, business logic leaking into controllers, exposing ORM objects through repositories, and concrete dependencies in the domain core. Keep behavior in entities and enforce invariants through aggregate roots.