DEV Community

Nilofer 🚀
Nilofer 🚀

Posted on

ArchGuard: Detect Architecture Drift Before It Becomes Technical Debt

#python #llm #machinelearning #opensource

Architecture degrades gradually. A circular dependency here, a god class there, a controller reaching directly into the database layer. Each violation is small on its own. Over time they compound into a codebase that is expensive to change and expensive to understand.

Most teams discover this in retrospect when a refactor takes three times as long as expected, or when a seemingly isolated change breaks something unrelated. By then the drift is already embedded.

ArchGuard is a production-ready Python static analysis tool that detects architecture degradation patterns in codebases over time. It runs six built-in detectors, compares architecture health between branches, tracks drift over the last 10 commits, and integrates into CI/CD through a GitHub Action or git hooks - all without any AI model dependency, using deterministic local static analysis.

Features

6 Built-in Detectors - circular dependencies, god classes, service layer bypasses, magic values, cyclomatic complexity, and layer violations.
Per-PR Analysis - compare architecture health between branches to catch regressions before they merge.
Trend Analysis - track architecture health over the last 10 commits to see drift over time.
Multiple Output Formats - table, JSON, YAML, Markdown, and HTML.
CLI and Git Hooks - command-line tool with pre-commit and pre-push hooks.
GitHub Action - CI/CD integration for automated architecture checks.
YAML Configuration - flexible, project-specific configuration via .archguard.yml.

Architecture

The CLI and YAML config feed the core engine - an AST parser, dependency graph, and base analyzer which fans out to six detectors. Findings are graded by severity, rendered as Table, JSON, YAML, Markdown, or HTML, and delivered through the CLI, git hooks, or the GitHub Action.

Installation

From PyPI

pip install archguard
Enter fullscreen mode Exit fullscreen mode

From Source

git clone https://github.com/dakshjain-1616/Arch-Guard
cd archguard
pip install -e ".[dev]"
Enter fullscreen mode Exit fullscreen mode

Requires Python 3.10+.

Quick Start

Initialize a configuration file in the project root:

archguard init
Enter fullscreen mode Exit fullscreen mode

Scan the current tree or point it at a specific path:

archguard scan
archguard scan ./src
Enter fullscreen mode Exit fullscreen mode

For machine-readable results:

archguard scan --format json --output report.json
Enter fullscreen mode Exit fullscreen mode

Review architecture drift over the last 10 commits:

archguard trend
Enter fullscreen mode Exit fullscreen mode

CLI Commands

scan - Analyze Codebase

archguard scan [PATH] [OPTIONS]
Enter fullscreen mode Exit fullscreen mode

Key flags: --format, --output, --detectors, --severity, --fail-on-violations. Global flags: --config, --verbose.

trend - Analyze Trends

archguard trend [OPTIONS]
Enter fullscreen mode Exit fullscreen mode

Flags: --commits, --format, --output.

init - Create Configuration

archguard init [OPTIONS]
Enter fullscreen mode Exit fullscreen mode

--path selects the config file location.

config - Manage Configuration

archguard config                          # Show active configuration
archguard config output_format            # Read a value
archguard config output_format json       # Update a value
Enter fullscreen mode Exit fullscreen mode

The Six Detectors

Circular Dependency
Detects circular import dependencies between modules.
min_cycle_length - minimum cycle length to report, default 2
max_cycles - maximum cycles to report, default 100

God Class
Detects classes with too many methods, attributes, or lines.
max_methods - maximum methods per class, default 20
max_attributes - maximum attributes per class, default 15
max_lines - maximum lines per class, default 500

Service Layer Bypass
Detects when controller or presentation layers bypass service layers to access repositories directly.
controller_patterns - regex patterns for controller files
service_patterns - regex patterns for service files
repository_patterns - regex patterns for repository files

Magic Value
Detects hardcoded literals that should be named constants.
min_string_length - minimum string length to flag, default 3
max_string_length - maximum string length to check, default 100

Cyclomatic Complexity
Detects functions and methods with high cyclomatic complexity.
thresholds - complexity thresholds for each severity level

Layer Violation
Detects violations of layered architecture, such as the presentation layer importing from the repository layer.
layers - layer definitions with patterns and allowed calls

Configuration

Create a .archguard.yml file in your project root. The config supports project metadata, include and exclude patterns, and per-detector options such as cycle length, maximum class size, and complexity thresholds. Output behavior, Git integration, and trend analysis are all controlled through the same file.

Git Hooks

Installation

python hooks/install.py                        # Install pre-commit hook
python hooks/install.py --pre-commit --pre-push  # Install both hooks
python hooks/install.py --force                # Overwrite existing hooks
python hooks/install.py --uninstall            # Remove hooks
Enter fullscreen mode Exit fullscreen mode

Pre-commit hook - runs ArchGuard on staged Python files before committing.
Pre-push hook - runs trend analysis before pushing to remote.

GitHub Action

The GitHub Action integrates ArchGuard into CI/CD pipelines. Basic usage runs on push or pull request workflows, checks out the repository with full history, and passes path, format, severity, and fail-on-violations settings as action inputs. Advanced configuration enables trend mode, selects Markdown output, sets the commit window, and uploads the generated report as an artifact.

Acknowledgments

Built with Click for CLI, Python's built-in ast module for AST parsing, NetworkX for dependency graph analysis, Rich for terminal output, and GitPython for Git integration.

Development

Setup

git clone https://github.com/dakshjain-1616/Arch-Guard
cd archguard
pip install -e ".[dev]"
pre-commit install
Enter fullscreen mode Exit fullscreen mode

Running Tests

pytest                                                        # Full suite
pytest --cov=src/archguard --cov-report=html                 # With coverage
pytest tests/unit/test_detectors.py                          # Targeted detector check
pytest tests/integration/                                    # Integration coverage
Enter fullscreen mode Exit fullscreen mode

Code Quality

ruff check src/ tests/               # Linting
ruff check --fix src/ tests/         # Auto-fix
pyright src/                         # Type checking
ruff check src/ tests/ && pyright src/  # Combined gate
Enter fullscreen mode Exit fullscreen mode

Contributing

Fork the repository. Create a feature branch:

git checkout -b feature/amazing-feature
Enter fullscreen mode Exit fullscreen mode

Make your changes, run tests with pytest, run linting with ruff check src/ tests/, commit, push to the branch, and open a Pull Request.

How I Built This Using NEO

This project was built using NEO. NEO is a fully autonomous AI engineering agent that can write code and build solutions for AI/ML tasks including AI model evals, prompt optimization and end to end AI pipeline development.

The requirement was a production-ready static analysis tool that detects architecture drift in Python codebases over time - with six built-in detectors, trend analysis over git history, multiple output formats, git hook integration, and a GitHub Action for CI/CD. NEO built the full implementation: the core engine with AST parser, dependency graph via NetworkX, and base analyzer; all six detector modules; the formatter layer covering table, JSON, YAML, Markdown, and HTML output; the git integration via GitPython; the CLI built on Click; the YAML configuration layer; the git hook installer and pre-commit and pre-push hooks; the GitHub Action; and the full test suite covering unit and integration tests.

How You Can Use and Extend This With NEO

Use it as a quality gate in every pull request.
Add the GitHub Action to your workflow with --fail-on-violations and the severity threshold you care about. Every PR gets checked for new circular dependencies, god classes, layer violations, and complexity regressions before it merges automatically, without any manual review step.

Use trend analysis to measure the health of an inherited codebase.
Run archguard trend on a codebase you have just taken over. The last 10 commits give you a picture of whether the architecture is improving or degrading, and which detectors are firing most frequently - useful context before making any changes.

Use git hooks to enforce standards locally before code reaches CI.
Install the pre-commit hook with python hooks/install.py. Staged files are checked on every commit. The pre-push hook runs trend analysis before anything reaches the remote. Issues are caught at the developer's machine, not in CI.

Extend it with additional detectors.
The six detectors share a common base analyzer interface. A new detector for a project-specific architecture rule follows the same pattern - implement the detection logic, add per-detector configuration to .archguard.yml, and register it. It appears automatically in scan output, trend analysis, and all output formats.

Final Notes

Architecture drift is invisible until it is expensive. ArchGuard makes it visible at every commit, every PR, and every push - with deterministic static analysis that requires no API keys, no model downloads, and no network calls. Six detectors, trend tracking over git history, and CI/CD integration in one tool.

The code is at https://github.com/dakshjain-1616/Arch-Guard
You can also build with NEO in your IDE using the VS Code extension or Cursor.
You can use NEO MCP with Claude Code: https://heyneo.com/claude-code

Top comments (0)