Two feature modules, `orders` and `inventory`, are each internally well-layered — inside each, controllers depend on services depend on domain, all pointing inward. But `orders`' domain package imports a class from `inventory`'s domain package to check stock, and separately `inventory`'s domain package imports a class from `orders`' domain package to look up order history. What problem does this create, and how would you fix it while keeping both modules internally clean?

## The rule one level up Dependency direction is usually taught at the layer level — controller → service → domain — but the same rule applies one level up, at the boundary between modules or features, and it's easy to satisfy it inside each module while violating it between modules. In the scenario, `orders` and `inventory` are each **internally clean**: - within `orders`, the controller depends on the service depends on the domain, and nothing in that chain points backward - the same is true inside `inventory` But `orders`' domain package importing an `inventory` domain class, while `inventory`'s domain package separately imports an `orders` domain class, creates a **cycle** that lives entirely outside either module's internal layering — and internal cleanliness gives you no protection against it, because the two properties are checked at different levels of the package graph. ## What the cycle costs The problem this creates is concrete and shows up well before runtime. 1. **First**, you can no longer compile, test, or reason about either module without the other — `orders` isn't really an independent unit anymore, it's one half of a two-piece module that happens to live in two folders and pretend otherwise. 2. **Second**, if either module later needs to become an independently deployable service — a common reason teams organize code into modules in the first place — a cycle between their domains makes that literally impossible without first breaking the cycle: you cannot deploy `orders` and `inventory` as separate services if each one's core logic calls directly into the other's in-process classes. 3. **Third**, cycles make change-impact analysis much harder for the team: a change to `inventory`'s domain can now, via the cycle, ripple back into `orders`' domain and from there back out again, and reasoning about 'what could this change affect' no longer terminates cleanly at a module boundary. ## Picking a direction The fix mirrors what you'd do at the layer level, just applied to modules. The first move is to ask which module should be the stable, upstream one — not always obvious, but usually one direction of the coupling represents the 'true' dependency (checking whether stock exists is naturally something `orders` needs from `inventory`, while 'look up an order's history' from within `inventory` is usually a sign that the wrong module owns that logic, or that it shouldn't be a direct call at all). Once you pick a direction, you apply the same DIP move: `orders` defines an `InventoryPort` interface expressing only what it needs (`isInStock(sku): Boolean`), and `inventory` implements it — **never both directions**. ## Or decouple through events If both modules genuinely need something from each other, a cleaner answer is often to decouple them entirely from direct calls and let them communicate through domain events: `inventory` publishes a `StockReserved` or `StockDepleted` event; `orders` reacts to it through its own application layer without either module's domain package importing the other's. This trades a synchronous, tightly coupled cycle for an asynchronous, one-directional (or fully decoupled) relationship, at the cost of eventual consistency and more moving parts that the team now has to manage. ## Catching it automatically In practice, teams enforce this the same way they enforce layer direction: **with an automated check on the module graph** rather than trusting reviewers to notice. Spring Modulith, for instance, lets you declare allowed dependencies per module and run a verification step as part of the test suite; a genuine cycle like the one described here fails that verification with a clear error naming both offending imports, the same way a broken unit test fails the build. Without such a check, the cycle can persist for a long time precisely because nothing local looks wrong — each individual pull request that added one of the two imports passed code review and looked like a small, reasonable convenience, and only the aggregate, module-graph view reveals the mutual coupling.