The Problem
Every codebase I've worked on in 19 years had the same story: the architecture starts clean, then slowly rots. Someone imports from the wrong layer. A utility class grows into a God Class. Circular dependencies creep in. By the time you notice in code review, refactoring is expensive.
I wanted automated architecture checks — like ESLint for structure, not syntax.
What Architect Genesis Does
Architect Genesis is a CLI tool that analyzes your codebase architecture using Tree-Sitter AST parsing. It works with TypeScript, Python, Go, Java, Rust, Ruby, and PHP.
Install and Run
bashnpm install -g @girardelli/architect
architect analyze ./src
That's it. No config needed to start. It infers your stack, framework, and domain automatically.
What You Get
Architecture Score (0-100) across four weighted dimensions:
Dimension Weight What it measures
Modularity 40% How well-separated are your modules
Coupling 25% Cross-boundary dependency count
Cohesion 20% How related are elements within a module
Layering. 15% Clean layer separation (View/Core/Data/Infra)
Anti-pattern detection: God Classes, Circular Dependencies, Leaky Abstractions, Spaghetti Modules. All derived from AST structure, not heuristics.
Layer detection: Automatically classifies your code into View, Core, Data, and Infrastructure layers based on dependency patterns.
Architecture as Code
The real power is declaring rules in .architect.rules.yml:
yamlquality_gates:
min_overall_score: 60
max_critical_anti_patterns: 0
max_high_anti_patterns: 3
boundaries:
allow_circular_dependencies: false
banned_imports:
- from: "presentation/*"
to: "infrastructure/*"
- from: "domain/*"
to: "framework/*"
Then plug into CI:
basharchitect check ./src
# Exit code 0 = pass, 1 = fail
Architecture violations now break the build.
AI-Assisted Refactoring
When Architect finds problems, it generates a refactoring plan with 5 rule-based transformations:
- Hub Splitting — breaks up God Classes
- Barrel Optimization — cleans up index/init files
- Import Organization — restructures import paths
- Module Grouping — reorganizes related files
- Dead Code Detection — finds unreferenced exports
Run architect execute and it applies these using Claude, GPT, or Gemini — with human gating on every step. You approve, skip, retry with a different AI, or rollback. It creates a protective git branch and commits each step individually.
Predicting Architecture Decay
The architect forecast command reads your git history, computes velocity-adjusted scoring, and runs ML-based regression to predict where your score will be in 3-6 months. You can see which modules are trending downward before it becomes a crisis.
Technical Architecture
It's a monorepo with three packages:
architect-core — Tree-Sitter AST parsing, scoring engine, rules engine
architect-agents — AI provider integration, stack/domain detection
architect CLI — reports (HTML/JSON/Markdown), GitHub Actions adapter
Plus a VS Code extension (Architect Intelligence) with CodeLens integration and inline scoring.
What I Learned Building This
Scoring weights are hard. I calibrated 40/25/20/15 against ~30 codebases, but I'm not confident they generalize. A React SPA has different architecture concerns than a Spring Boot microservice. Context-aware weights might be the next step.
AST beats regex. Early versions used pattern matching. Tree-Sitter was a game-changer — it gives you the real dependency graph, not approximations.
Human gating matters. I tried fully autonomous refactoring first. It was terrifying. The approve/skip/rollback model gives you AI speed with human judgment.
Where It's Heading
The roadmap is to evolve from analyzer to intent compiler — describe the architecture you want, and the system generates the code. But that's the future. Today, v8.2.0 does analysis, scoring, validation, and assisted refactoring. And it does them well.
Open source, MIT licensed.
Top comments (0)