KOEN
Read Original
#Backend

Scaling ArchUnit with Nebula ArchRules

Scaling ArchUnit with Nebula ArchRules
01

Summary

How Netflix Governs Architecture Across 10,000+ Repositories

Scaling ArchUnit with Nebula to detect 1 million issues and manage technical debt at scale

This article explores Netflix's strategy for enforcing architectural rules and managing technical debt in a massive polyrepo environment. It details the architecture of Nebula ArchRules, which allows rules to be distributed and executed as library dependencies.

  • 01Overcomes the single-repo limitation of ArchUnit to enforce rules enterprise-wide
  • 02Uses ASM-based bytecode analysis for cross-language JVM support and higher precision
  • 03Leverages Gradle Module Metadata to dynamically link rules with their corresponding libraries
  • 04Integrates with internal developer portals to visualize nearly 1 million detected issues
  • 05Discusses a roadmap for auto-remediation using OpenRewrite and LLMs

RECOMMENDATION

Highly recommended for platform engineers managing large-scale microservices or library authors who need to monitor downstream API consumption.

The Problem

Netflix operates tens of thousands of Java repositories in a polyrepo strategy, making it difficult to share build logic and manage library lifecycles across the entire fleet. Library authors lacked visibility into how their APIs were being used downstream, complicating breaking change management.

The Solution

They developed the Nebula ArchRules plugin suite to scale ArchUnit. It enables packaging and publishing architectural rules as JAR variants using Gradle Module Metadata, and introduced a runner plugin that automatically discovers and executes relevant rules in downstream projects.

The Result

The system now runs 358 rules across over 5,000 repositories, detecting nearly 1 million issues. It provides library authors with a clear view of experimental or deprecated API usage across the organization.

Trade-off

The solution is deeply integrated with the Gradle ecosystem and Nebula plugins, limiting portability to other build systems. It may also introduce slight build-time overhead due to bytecode analysis in large projects.

03

Key Concepts

Concept · 01

ArchUnit

An open-source library used to enforce architectural code rules as part of a JVM testing suite.

  • Netflix scaled this to a general-purpose static analysis tool for their entire fleet.
Concept · 02

Nebula ArchRules

A suite of Gradle plugins by Netflix designed to share and apply ArchUnit rules across any number of repositories.

  • It includes a Library Plugin for authoring and a Runner Plugin for automated execution.
Concept · 03

ASM (Bytecode Analysis)

A framework for analyzing compiled Java bytecode instead of parsing the Abstract Syntax Tree (AST) of the source code.

  • This allows ArchUnit to support multiple JVM languages like Kotlin and Scala without rewriting rules.