architecture-patterns

Organize code into four layers: domain (entities and abstract interfaces), use_cases (application logic), adapters (concrete repositories and controllers), and infrastructure (framework wiring). Enforce the rule that domain and use_cases only import from domain, never from adapters or infrastructure.

Both enforce inward-pointing dependencies. Hexagonal Architecture frames the core as interacting with the outside through ports (abstract interfaces) and adapters (implementations), while Clean Architecture names four rings: entities, use cases, interface adapters, and frameworks.

Inject an in-memory repository implementing the same abstract port interface instead of the PostgreSQL adapter. The use case constructor accepts the abstract port, so tests run as plain unit tests with no Docker, database, or network required.

Circular imports happen when a use case imports a concrete adapter class instead of the abstract port. Fix it by defining the interface in domain/interfaces, having the use case import only that port, and wiring implementations in the infrastructure layer.

Use an Anti-Corruption Layer when one bounded context must consume another context's model, such as Ordering fetching Catalog product data. The ACL translates the upstream model into the downstream context's own value objects, preventing model coupling.

Place objects that must be consistent together in the same aggregate, and use domain events for eventually consistent relationships. Keep aggregates small by referencing other aggregates by ID rather than embedding full object graphs.