Checking Module Boundaries with Commands, Not Reviews

A rule nobody checks stops being a rule

A modular monolith works while its modules stay separate. The rule is easy to state: modules talk through contracts, never through each other's internals. It is just as easy to break, one convenient import at a time, and each break looks harmless in a review.

Three places drift shows up

• Module boundaries: a module reaches into another module's folders instead of its public contract.
• Code: classes in one domain depend directly on classes in another.
• Database: a foreign key or a join couples two modules' tables, which makes the modules impossible to separate later.

Make each check a command

A check that has to be remembered will be skipped. A command can run in a hook and in CI. Each of the three drifts above deserves its own scan, plus one command that applies the architecture policy and reports a score, and one that snapshots the whole picture so changes between releases are visible.

Report first, then block

Run on an existing codebase, a new scan finds violations that already exist. Blocking on all of them on day one stops the team. Record the current state as the baseline, fail only on new violations, and bring the baseline down over time.

Run them before the merge

The cheapest moment to fix a boundary violation is before it lands. A pre-commit hook gives the developer the answer while the change is still in their head, and the same commands in CI catch anything that skipped the hook.

In our own products

RumuzePMO ships these as artisan commands: an architecture check, scans for module boundaries, code dependencies and database dependencies, and a cross-module snapshot. It also ships a pre-commit hook for the architecture checks, installed with one script, so the rule is enforced by tooling instead of by memory.