arch-auditor

Evidence-backed repository architecture analysis. Deterministic static analysis first (AST-level facts, import graphs, cycle detection, coupling, blast radius), with Gemini as an optional explain-and-plan assistant. Ships a Streamlit web app and a CLI from the same engine.

• Python 3.10+
• Detectors: circular dependencies, high coupling, large modules, layer violations; plus a blast-radius impact report per module.
• Ruleset-driven layer validation (config/architecture.yaml).
• Architecture model, findings, severity, impact: arch_auditor/models/.
• Detector engine: arch_auditor/analyzer/.
• Gemini integration (overview, per-finding insights, refactoring plans): arch_auditor/ai/.
• Streamlit single-page app: app.py (7 sections per the UI spec).

Install

pip install -e .

or, once published, pip install arch-auditor.

CLI

# Analyze a repository
arch-auditor analyze path/to/repo

# Analyze the bundled demo repository
arch-auditor demo

# Ask Gemini for a refactoring plan for one finding (needs GEMINI_API_KEY)
arch-auditor plan CIRCULAR_DEPENDENCY_1 path/to/repo

# Version
arch-auditor --version

The CLI returns exit code 1 when findings exist, 0 when the repository is clean, and 2 for usage errors. The Gemini key is read from the environment only and is never logged.

Web app

streamlit run app.py

Open the generated localhost URL. Enter a repository path (default: the bundled demo_repo) and press ANALYZE.

For Streamlit Community Cloud: connect the repo and set the main script path to arch-auditor/app.py. Dependencies come from arch-auditor/requirements.txt.

Reference architecture ruleset

Layer validation is opt-in: drop config/architecture.yaml (see arch_auditor/config/architecture.yaml) into the repository being analyzed. Without a ruleset, layer validation is skipped and the remaining detectors run on structure alone.

Gemini key

Optional. Set GEMINI_API_KEY in the environment (CLI) or paste a key into the app's sidebar (session only).

Demo repository

demo_repo/ is an intentionally problematic repository that exercises every detector:

• cycle orders -> payments -> users -> orders
• payment_service.py: > 30 functions (LARGE_MODULE), fan-in 5 + fan-out 1 (HIGH_COUPLING, HIGH impact)
• database.py -> api.py inverts the layer rules (LAYER_VIOLATION)

Development

pip install -e ".[dev]"
ruff check .
pytest -q
python -m build

CI (.github/workflows/ci.yml) runs ruff, pytest, pip-audit (dependency CVE scan), and builds + verifies the distribution on every push and PR. CodeQL and weekly Dependabot updates keep the supply chain current.

License

GPL-3.0-only. See LICENSE in the repository root and arch-auditor/LICENSE (shipped inside the wheel).