Netflix's Nebula ArchRules: Architecture Governance Across Thousands of Repos
Problem + constraints
Netflix runs a polyrepo strategy with tens of thousands of independent Java repositories rather than one shared monorepo. ArchUnit — the standard library for asserting architecture rules in Java code ("controllers shouldn't call repositories directly," "package X shouldn't depend on package Y") — is designed to run as part of a single repository's own JUnit suite, owned and maintained by that repo's own team. That model works fine for one team enforcing its own local rules. It breaks down as an org-wide architecture-governance mechanism: if a platform team wants a rule enforced consistently across tens of thousands of independently-owned repos, hand-copying ArchUnit rule code into every one of them — and then keeping every copy in sync as the rule evolves — isn't a maintenance plan, it's a maintenance burden that scales linearly with repo count. The constraint isn't "can we write the rule," it's "can the rule stay enforced and current across an organization whose repos you don't have write access to."
Solution
Netflix's JVM Ecosystem team built Nebula ArchRules, a Gradle plugin layer on top of ArchUnit that turns an architecture rule into a shared, publishable artifact instead of duplicated test code. An ArchRules Library Plugin adds a dedicated archRules source set to a Gradle project; a rule author implements an ArchRulesService interface once inside that source set, and the resulting rule package can be published and pulled into any number of consuming repos, evaluated against each repo's own code without that repo needing to hand-maintain the rule logic itself. Updating a rule becomes "publish a new version of the shared library," not "file a PR against every affected repo." Netflix is also exploring wiring auto-remediation into ArchRules findings — deterministic fixes for mechanical violations via tools like OpenRewrite, and non-deterministic (LLM-based) fixes for messier cases — so a violation doesn't just get flagged, it comes with a proposed fix.
What to steal
- The moment an enforcement mechanism needs to apply identically across many independently-owned units — repos, services, cloud accounts — stop treating "the rule" and "the place it's enforced" as one artifact. Package the rule as a shared, versioned dependency instead of logic duplicated at every enforcement site.
- A shared interface (
ArchRulesService) is what makes rules pluggable and independently versionable — the framework only needs to know how to run whatever rule it's handed, not what that specific rule checks. - Pair detection with remediation, even partial or deterministic remediation first. A governance tool that surfaces thousands of violations across repos you don't own is close to useless without a low-friction path for the owning teams to actually fix them — the report itself isn't the deliverable, the fix path is.
Engineering Lens
This is squarely pillar-org-complexity territory — the same shape of problem shows up whenever you're accountable for a standard (a security control, a naming convention, a resilience pattern) that needs to hold across teams and repos you can't force through in one PR. The Principal-level move here isn't writing the rule itself; it's recognizing that the rule and its distribution mechanism are two separate design problems, and that adoption at scale depends far more on the second one — how cheaply a team can consume the rule and stay current with it — than on how clever the rule is. That's a directly transferable lens for any large org (BigTech or otherwise): governance that doesn't scale its distribution mechanism becomes a policy nobody actually follows.