architecture-patterns

Organize code into domain (entities, value objects, interfaces), use_cases (application rules), adapters (repositories, controllers, gateways), and infrastructure (config, wiring). All imports in domain and use_cases must point inward only, never toward adapters or infrastructure.

Both enforce dependency inversion so business logic stays framework-free. Clean Architecture uses concentric layers (entities, use cases, adapters, frameworks), while Hexagonal Architecture defines ports as abstract interfaces with swappable adapters like PostgreSQL or Stripe implementations.

Inject an in-memory repository implementing the same abstract port interface into the use case constructor. This lets every use case run in plain unit tests with no Docker, database, or network, which is the hallmark of correctly applied Clean Architecture.

Circular imports happen when a use case imports a concrete adapter class instead of the abstract port. Enforce the rule that use_cases imports only from domain entities and interfaces, never from adapters or infrastructure.

Use bounded contexts when a single shared model serves multiple subdomains and causes coupling. Isolate a coherent model per context, and add an Anti-Corruption Layer when one context must reference another, such as Order holding its own CustomerId value object.