How do requires, requires transitive, and the readability graph shape module API design and migration at scale?

## Readability: the foundation In JPMS, one module can use another's exported API only if it **reads** that module. **Readability** is the directed relationship 'A can see B's exported packages.' You create it with **`requires B;`** in A's descriptor. The complete set of these edges across all resolved modules is the **readability graph** (a directed graph: nodes = modules, edges = 'reads'). Resolution builds and validates this graph before the program runs — this is precisely the 'reliable configuration' guarantee applied to the dependency structure. Three pieces always combine for cross-module use: the producer **exports** a package, the producer is **read** by the consumer (`requires`), and the type is **public**. Readability is the 'requires' half. ## Plain `requires` vs `requires transitive` - **`requires B;`** — A reads B. This is **not** propagated: if C reads A, C does **not** automatically read B. A's dependency on B is A's private business. - **`requires transitive B;`** — A reads B **and** implied readability is granted to anyone who reads A. So if C `requires A`, C automatically reads B too, with no explicit `requires B` of its own. ### When transitive is required, not optional If A's **exported API exposes types from B** — e.g. a public method returns a `B.SomeType` or takes one as a parameter — then any consumer C that calls that method must be able to name `B.SomeType`. Without `requires transitive B`, C would have to add its own `requires B` just to use A's API, which is leaky and brittle. The rule of thumb: **if a dependency's types appear in your public/exported signatures, declare it `requires transitive`; otherwise use plain `requires`.** This makes the transitive keyword an explicit statement of 'this dependency is part of my API contract.' ## `requires static` (compile-time-only) — for completeness `requires static B;` declares an **optional** dependency needed at compile time but not necessarily at run time (e.g. annotations or an optional integration). It does not force B to be present at runtime. It is a third flavour worth knowing when shaping the graph, used for optional/compile-only edges. ## Aggregator (façade) modules Because `requires transitive` re-exports readability, you can build an **aggregator module** whose descriptor is *only* a list of `requires transitive` directives and contains no code. Consumers `requires` the single aggregator and transitively read the whole bundle. The JDK uses this pattern (e.g. an umbrella module pulling in several others). It is a deliberate API-surface-as-a-module technique. ## Qualified exports/opens for layering `exports pkg to specific.module;` (a **qualified export**) restricts who may use a package — ideal for SPI/plugin or internal-shared packages that should be visible to a sibling module but not the world. Combined with the readability graph, this lets architects encode **layering rules the compiler enforces**: a UI module that should never touch a persistence-internal package simply has no read edge / export to it, and the build fails if someone tries. ## Designing the graph at scale For a large, multi-team codebase the readability graph becomes an architectural artifact: - **Minimize transitive edges** to avoid over-coupling — each `requires transitive` is a promise that leaks a dependency to all your consumers and is hard to remove later (removing it can break downstream compiles). - **Use plain `requires` for implementation dependencies** so they stay swappable internal details. - **Use qualified exports** to expose SPI to known collaborators without going public. - **Treat the export surface as the public API** — changing or removing an export is a breaking change subject to the same versioning discipline as method signatures. - **Mandate `Automatic-Module-Name`** on libraries so consumers can pin a stable `requires` target even before full modularization. ## Migration implications Because named modules cannot read the **unnamed module** (classpath), modularizing one layer often forces its dependencies onto the modulepath too (as explicit or automatic modules). Planning the readability graph top-down lets you sequence this: introduce explicit modules at the leaves of your dependency tree first, let upstream dependencies ride as automatic modules, and tighten `requires`/exports as each layer modularizes. The graph also surfaces hidden cyclic or split-package problems early, since resolution rejects them. ## The payoff The readability graph turns dependency and visibility decisions into **compiler-checked architecture**. `requires` vs `requires transitive` is the lever that decides whether a dependency is private plumbing or part of your published contract — a small keyword with large, long-lived API and coupling consequences.