Combating Architecture Drift: Strategies for Code-Design Alignment

Architecture Drift Detection: Keep Your Code Aligned with Design

Vincent Composieux identifies architecture drift as the silent divergence between a system’s documentation and its actual implementation. This phenomenon occurs universally across engineering teams, manifesting as structural, behavioral, dependency, and decision drift.

Why This Matters

The gap between technical reality and ideal architectural models leads to critical failures during incident response and slow onboarding for new engineers. When architects make decisions based on stale documentation—such as assuming low traffic for a service that has actually scaled 10x—the resulting technical errors can compromise system stability and lead to compliance failures in regulated industries (SOC 2, ISO 27001, HIPAA).

Key Insights

• Architecture Fitness Functions are automated tests that validate architectural properties, such as ensuring no direct database imports exist in handler packages.
• Static Analysis Tools like ArchUnit (Java), Deptrac (PHP), and go-arch-lint (Go) enforce layered architecture by restricting component dependencies.
• Automated Drift Scoring validates the full model against the codebase by checking if documented systems match repositories and containers match directories.
• Architecture Erosion differs from drift; while drift is a documentation accuracy problem, erosion is the actual degradation of code quality and violation of architectural principles.

Working Examples

A fitness function implemented in Go to prevent database leak into the handler layer.

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
	packages := analyzeImports("./internal/handler/...")
	for _, pkg := range packages {
		for _, imp := range pkg.Imports {
			assert.NotContains(t, imp, "database/sql", "Handler %s imports database/sql directly", pkg.Name)
			assert.NotContains(t, imp, "gorm.io", "Handler %s imports GORM directly", pkg.Name)
		}
	}
}

go-arch-lint configuration defining strict layered dependency rules.

components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/
rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

GitHub Action workflow to fail builds when the architecture drift score falls below 70%.

on:
  push:
    branches: [main]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

Practical Applications

References:

https://dev.to/eko/architecture-drift-detection-keep-your-code-aligned-with-design-kae” ]): {  }