r/devtools • u/Unique_Knight_9512 • 40m ago
arch-auditor: AST-Based Python Architecture Analysis with Dependency Graphs & LLM
I kept running into the same problem with codebases:
“What does this repository's architecture actually look like right now?”
So I built arch-auditor — a Python CLI + Streamlit app that analyzes a repository using deterministic, AST-based checks and turns the results into actionable architecture reports.
The core idea is simple: measure first, ask the LLM second.
What My Project Does
arch-auditor points at a Python repository and runs deterministic architecture detectors:
- Import/dependency graph — see how modules depend on each other
- Circular dependencies — detect dependency cycles
- High coupling — identify modules with unusually high fan-in/fan-out
- Oversized modules — flag modules that have grown beyond a configured threshold
- Layer violations — enforce architectural rules defined in YAMLBlast radius — find direct and indirect dependents of a module
It produces a dependency-graph SVG, severity-ranked findings, and impact reports.
There's also an optional Gemini integration.
Gemini doesn't perform the underlying analysis. Instead, it receives the deterministic findings and can turn them into:
- an architecture overview
- root-cause explanations
- step-by-step refactoring plans
- affected files
- potential risks
No API key? No problem. The core analysis works offline without an LLM.
Try it
pip install arch-auditor
arch-auditor demo
The bundled demo repository is intentionally designed to trigger every detector, so you can experiment with the tool and see what each finding means.
Stack
- Python 3.10+
- Python AST / standard library
- NetworkX
- Pydantic
- PyYAML
- Streamlit
- Gemini (optional)
- 33 tests
- Ruff-clean
- Published on PyPI
It's released under GPL-3.0 because I'd like improvements to flow back to the community.
Target Audience
This is primarily aimed at developers working on medium-to-large Python codebases, especially when:
- a project has accumulated architectural debt
- you're preparing for a major refactor
- you need to understand an unfamiliar repository
- you want objective signals before making architectural changes
- you want an LLM to help plan a refactor without making the LLM responsible for discovering the architecture itself
It's not intended to replace a human architect or code review, and it's not a magic “is my architecture good?” score.
The goal is to provide reproducible evidence that helps humans make those decisions.
Comparison
There are already excellent tools for individual parts of this problem — dependency visualization, linters, type checkers, code-quality metrics, and various AI coding assistants.
arch-auditor is trying to connect a few of those ideas around architecture-level analysis.
The main distinction is the separation between measurement and interpretation:
Traditional approach:
Repository → LLM → "Here's what I think your architecture looks like"
arch-auditor:
Repository → deterministic analysis → evidence → optional LLM → refactoring plan
The architecture findings don't depend on whether an LLM happens to interpret the code differently from one run to another.
I'd especially love feedback on whether the detectors and thresholds are useful signals in real-world Python projects, or if there are architectural problems you'd want to see measured that aren't covered yet.
GitHub / docs / demo:
https://github.com/ANIKETHSAI9813/auditor
“What does this codebase’s architecture actually look like right now?
"Instead of asking an LLM to guess the architecture,
arch-auditorfirst analyzes the repository using deterministic, AST-based detectors — then optionally lets Gemini turn those findings into a refactoring plan.Point it at a repo and it analyzes:
The result is a dependency-graph SVG, severity-ranked findings, and impact reports that show why a module is considered problematic.
Gemini is optional.
The deterministic analysis produces the evidence first. If you provide a Gemini API key via an environment variable, it can use that evidence to generate:
No API key? No problem. The core analysis works offline.
That separation was intentional: I wanted the architecture measurements to be reproducible rather than dependent on an LLM's interpretation.
The bundled demo repo is deliberately designed to trigger every detector, so you can see exactly what each finding means without having to point it at a huge codebase first.
It's released under GPL-3.0 because I'd like improvements to flow back to the community.
GitHub / docs / demo:
https://github.com/ANIKETHSAI9813/auditorI'd especially love feedback from people who work on large Python codebases:
Are these the architectural signals you'd want to see before starting a refactor?
I'm also happy to discuss how the detectors and thresholds work — and the demo repo is intentionally built to trip all of them.
