Architecture fitness functions in CI/CD pipelines

An architecture fitness function is an automated test that evaluates whether the system's architecture satisfies a defined constraint — dependency rules, performance thresholds, security properties, or complexity limits. The term comes from evolutionary architecture theory. Fitness functions make implicit architectural rules explicit and machine-enforceable: instead of relying on code review to catch layering violations, a fitness function fails the CI build when the domain layer imports from the infrastructure layer, preventing architectural drift before it reaches the main branch.

ArchUnit is a Java/Kotlin library for writing architectural rules as unit tests. It works by analysing the compiled bytecode of your application and evaluating rules expressed in a fluent DSL: "no classes in the domain package should depend on classes in the infrastructure package." These rules run as JUnit tests in your standard test suite, integrating naturally with Maven/Gradle builds and CI/CD pipelines. ArchUnit supports rules for package dependencies, class naming conventions, annotation requirements, circular dependency detection, and layered architecture enforcement.

For TypeScript and JavaScript projects, Dependency Cruiser is the primary tool for module dependency rules and circular dependency detection. It analyses import graphs and applies rules defined in a configuration file, failing the build when rules are violated. ESLint's import rules (import/no-restricted-imports, import/no-cycle) provide lighter-weight enforcement directly in the linting pipeline. For bundle size budgets, size-limit or bundlesize enforce JavaScript bundle constraints. SonarCloud covers complexity metrics across multiple languages including TypeScript.

Clean architecture (and hexagonal architecture, onion architecture) define layering rules: domain logic in the center with no outward dependencies; application services depending on domain; infrastructure adapters depending on application interfaces but never the reverse. Fitness functions enforce these rules automatically. ArchUnit's noClasses().that().resideInAPackage("..domain..").should().dependOnClassesThat().resideInAPackage("..infrastructure..") directly encodes the clean architecture dependency rule as a failing test, preventing the rule from being quietly violated as the codebase grows.

Start with the highest-value, lowest-effort fitness functions: circular dependency detection (Dependency Cruiser or ArchUnit's beFreeOfCycles()) — circular dependencies are universally harmful and easy to detect automatically; layer dependency rules encoding your architectural boundaries; bundle size budgets if you have performance-sensitive frontend code; and critical security properties like "all API endpoints must require authentication." These provide immediate architectural safety net value and are straightforward to implement. Save complex performance SLO testing and consumer contract tests for later phases when the basic structure is protected.

Yes, fitness functions apply to both. For microservices, the most valuable fitness functions are: consumer-driven contract tests (Pact) that prevent API changes from breaking downstream services; API design rule enforcement (Spectral on OpenAPI specs) ensuring consistent naming, versioning, and error formats across services; dependency scanning for known vulnerabilities in service dependencies; and performance SLO tests that assert service response times meet requirements. For monorepos containing multiple services, Dependency Cruiser and ArchUnit can enforce that services don't import directly from each other's internals, maintaining service boundary integrity.

Consumer-driven contract testing is a pattern where API consumers define the contract they expect (the specific request and response format they rely on), and provider CI/CD pipelines verify they still satisfy those contracts before deployment. Pact is the most widely used framework for this pattern. Consumers write Pact tests that generate contract files; providers run Pact verification tests against those contracts. When a provider change would break a consumer contract, the provider's CI build fails before the breaking change is deployed. This gives service teams confidence to evolve their APIs without inadvertently breaking downstream consumers.

Legitimate exceptions require a formal process to prevent the exception mechanism from becoming a workaround for the rule. For ArchUnit, use .ignoreDependency() to document specific known exceptions with an explanation comment. For Dependency Cruiser, use the allowedSeverity configuration or path-specific rule exceptions. For ESLint, use targeted // eslint-disable-next-line with a comment explaining the exception. The key principle is that every exception must be explicit and documented — not a blanket rule disable. Track exceptions as technical debt items for future resolution, and review them in quarterly architecture reviews.