How do you declare which modules a given module is allowed to depend on, and how does verify() catch a violation?

## The default rule Out of the box, Spring Modulith is permissive about *which* modules you depend on: any module may depend on the **exposed** types of any other module. What's always forbidden is reaching into another module's **internal** packages, and forming **cycles**. Allowed-dependencies let you tighten the first part into an explicit allow-list. ## Declaring an allow-list with `@ApplicationModule` You configure a module through a **`package-info.java`** file in the module's **base package** (the root package of that module). Annotate the package with `@org.springframework.modulith.ApplicationModule`: ```java @org.springframework.modulith.ApplicationModule( allowedDependencies = { "inventory", "shared" } ) package com.example.shop.order; ``` Semantics: - The `order` module may now depend **only** on the `inventory` and `shared` modules. - Any reference from `order` to a module **not** in that list is a violation — even one that was legal before you added the annotation. Declaring `allowedDependencies` flips the module from 'open to all' to 'closed to all but these'. - Depending on nothing? `allowedDependencies = {}` forbids all outgoing module dependencies. ## Named-interface granularity A module can expose one or more **named interfaces** (curated subsets of its public types, declared via `@NamedInterface`). You can allow only a specific one using the double-colon syntax: ```java @ApplicationModule(allowedDependencies = { "inventory :: stock-api" }) package com.example.shop.order; ``` Now `order` may use only the `stock-api` named interface of `inventory`, not its whole public surface. ## How `verify()` catches a violation 1. Modulith reads each module's `@ApplicationModule` metadata and builds the allowed-dependency graph. 2. It generates **ArchUnit** rules encoding: 'classes in module X may only access classes belonging to allowed modules / named interfaces, and never internal packages of others.' 3. During `verify()`, ArchUnit walks the actual class-to-class references (field types, method params/returns, calls, inheritance). Any edge that violates the derived rule is collected. 4. The result is a `Violations` exception whose message enumerates each violation with the source type, the illegal dependency, and the target — e.g. `Module 'order' depends on module 'billing' via ...` — making it easy to locate. ## Edge cases & gotchas - **Transitive isn't automatic**: if `order` is allowed `inventory`, and `inventory` uses `shared`, that does *not* grant `order` access to `shared`. Each module's list is about *its own* direct references. - **Renaming a module** (its base-package simple name, or a `displayName`) means every allow-list referencing the old name breaks — the string must match the module's name. - **Adding the annotation is a breaking tightening**: introducing `allowedDependencies` to a previously-open module often surfaces a burst of pre-existing violations. That's expected and desirable. - The check is **compile-time/static** — dependencies expressed only via reflection or Spring bean lookups by type string won't be seen. ## When to use Use explicit `allowedDependencies` on modules where you want to hard-enforce an intended layering (e.g. a `web` module may talk to `order` but never `persistence` internals). Leave others open until you need the constraint.