A team wants to guarantee that classes in a controller package never call classes in a repository package directly, skipping the service layer, and that this is caught automatically if someone violates it. Visibility modifiers alone can't express this since both packages are legitimately public within the same module. How would an ArchUnit rule enforce this, and why is a runnable test needed here instead of relying on code review?

## How ArchUnit works ArchUnit works by reading already-compiled `.class` files, via a bytecode-analysis library (ASM) under the hood, and constructing an in-memory graph of every class, its fields, methods, and every reference one class makes to another: - method calls - field accesses - type usage - inheritance On top of that graph it exposes a **fluent DSL** for asserting structural rules, run as ordinary JUnit tests: `noClasses().that().resideInAPackage("..controller..").should().dependOnClassesThat().resideInAPackage("..repository..")` walks every class ArchUnit found in a package matching `..controller..` and asserts that none of its outgoing dependencies land in a class from a package matching `..repository..`, where a violation produces a normal JUnit assertion failure naming the exact class and dependency that broke the rule. ArchUnit also ships **pre-built rule sets** for common shapes, notably `Architectures.layeredArchitecture()`, which lets you declare named layers and `mayOnlyBeAccessedByLayers(...)` relationships in one readable block instead of hand-writing each pairwise rule. ## Why a visibility modifier cannot express layering Layering is fundamentally a statement about the relationship between two packages, not a property any single class's visibility modifier can express. Both controller and repository are legitimately public, or internal, within the same module: - the repository has to be reachable by the service layer; - the controller has to be reachable by the framework's dispatcher. So no visibility level says "public to service, but not to controller." Only a rule that inspects the actual call graph across the whole codebase, rather than a per-class access check, can enforce that kind of cross-cutting architectural constraint, which is exactly the gap between what the compiler already gives you for free and what a dedicated architecture test is needed for. ## The cost — the rules are code too The cost is that these rules require ongoing authorship and maintenance — someone has to write the rule, decide package-matching patterns precisely enough to catch real violations without false-positiving on legitimate exceptions, such as a shared `dto` or `mapper` package legitimately reachable from both layers, and keep it updated as the codebase's package structure evolves. - Rules that are **too strict** block legitimate work and get bypassed or disabled under deadline pressure if the team doesn't trust them. - Rules that are **too loose** give false confidence — the test suite is green, but the architecture has actually drifted. Adopting these tests against a pre-existing, already-violating codebase also has a bootstrapping cost, typically solved with a freeze/baseline mechanism, such as ArchUnit's `FreezingArchRule`, that records existing violations and only fails on new ones, letting the team pay down debt incrementally. ## Why code review alone misses this Code review alone misses layering violations for structural reasons. 1. **Reviewers see one diff at a time** and rarely have the whole call graph in their head, so an indirect violation — controller calls a shared `OrderHelper` utility that itself calls the repository — is easy to miss since the diff never mentions "repository" by name. 2. **The rule isn't written down anywhere machine-checkable**, so new team members have no artifact to consult besides tribal knowledge. 3. **The constraint silently erodes** as the team grows, turns over, or forgets under deadline pressure — nothing fails loudly, the violating code just merges and sits there, usually discovered only when someone later tries to refactor the repository layer and finds unexpected callers reaching straight past the service layer. A test, in contrast, runs on every single CI build, fails at the exact commit that introduced the violation when it's cheap to fix, rather than months later when it might require untangling dozens of call sites, and simultaneously serves as living, runnable documentation of the intended architecture that never goes stale the way a wiki page does. ## Where it shows up — a Spring Modulith backend A Spring Modulith Kotlin backend typically layers this exact rule two ways: a plain ArchUnit `layeredArchitecture()` rule enforcing controller-to-service-to-repository call direction within a module, plus Spring Modulith's own `ApplicationModules.of(...).verify()` enforcing the coarser, module-to-module allowed-dependency graph. Both run as fast JUnit tests, with no server, database, or network involved, so they execute in every CI run and in a local fast quality gate, catching an accidental layering or module-boundary violation within seconds of it being written rather than after it ships and someone tries to unwind months of accumulated shortcuts.