architecture-patterns

Organize code into domain (entities, value objects, interfaces), use_cases, adapters, and infrastructure layers. Every import in domain and use_cases must point only toward domain; concrete implementations like PostgresUserRepository live in adapters and are wired via a DI container.

Both enforce inward-pointing dependencies. Hexagonal Architecture frames the domain core around ports (abstract interfaces) and adapters (concrete implementations), while Clean Architecture uses four rings: entities, use cases, interface adapters, and frameworks. Onion Architecture is a close variant with explicit domain services.

Inject an in-memory repository implementing the same abstract port interface, such as InMemoryUserRepository backed by a dictionary. The use case constructor must accept the abstract port, not the concrete class, so tests need no Docker, database, or network.

Circular imports happen when a use case imports a concrete adapter class instead of the abstract port. Define the interface in domain/interfaces, have adapters implement it, and wire implementations in the infrastructure layer's DI container.

Use an ACL when one bounded context must consume another's model, such as Ordering fetching Catalog product data. The downstream context defines its own value object (e.g., ProductSnapshot) and a port interface, with an adapter translating the upstream response into the local model.

Put objects that must be consistent together in the same aggregate; use domain events for eventually consistent relationships. Reference other aggregates by ID only, keep aggregates small enough to avoid loading thousands of objects, and make the controlling entity the aggregate root.