architecture-patterns

Organize code into domain (entities, value objects, interfaces), use_cases (application rules), adapters (repositories, controllers), and infrastructure (config, DI). Every import in domain and use_cases must point only toward domain, never toward adapters or infrastructure.

Both enforce inward-pointing dependencies. Hexagonal Architecture emphasizes ports (abstract interfaces) and adapters (concrete implementations) around a domain core, while Clean Architecture defines four rings: entities, use cases, interface adapters, and frameworks.

Inject an in-memory implementation of the repository port into the use case constructor. The use case must depend on the abstract interface, not a concrete class like PostgresUserRepository, so tests need no Docker 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 them together in the infrastructure DI container.

Use an ACL 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 foreign domain concepts from leaking in.

Put objects that must be consistent together in the same aggregate; use domain events for eventually consistent relationships. The root controls access, and if you load thousands of objects to change one, the aggregate is too large and should be split.