Your Codebase's Architecture Guardian β AI-Powered Structural Health Analysis on Every Pull Request
"Is this PR degrading our architecture?" Just push β and ArchSentinel will tell you.
Stop merging code that silently erodes your architecture. ArchSentinel AI is an automated, AI-powered architecture impact analyzer that integrates seamlessly into your GitHub workflow. Every time a pull request is opened, updated, or pushed to, ArchSentinel performs a deep, multi-dimensional structural analysis of your entire codebase and posts a beautifully formatted, actionable health report β directly as a comment on your PR.
No dashboards to check. No CLI tools to run. No manual reviews to schedule. Just push, and your architecture speaks for itself.
- Why ArchSentinel?
- How It Works
- Core Analysis Capabilities
- Health Score Model
- AI-Powered Explanations & Suggestions
- PR Comment Reports
- Multi-User & Multi-Repo Support
- Architecture & Tech Stack
- Analysis Pipeline Deep Dive
- Quick Start
- Configuration Reference
- REST API Reference
- Security & Privacy
- Who Is This For?
- Requirements
- Comparison with Alternatives
- Roadmap
- Contributing
- License
Software architecture doesn't break overnight β it decays incrementally, one pull request at a time. A shortcut here, a direct dependency there, and before you know it, your clean layered architecture has become an untestable, undeployable monolith.
Traditional code review catches syntax errors and logic bugs. ArchSentinel catches the structural rot that code review misses.
| Without ArchSentinel | With ArchSentinel |
|---|---|
| Architecture violations slip through code review unnoticed | Every PR is automatically analyzed for structural impact |
| Circular dependencies grow silently until deployment breaks | Cycle chains are detected and reported instantly |
| Coupling hotspots accumulate until refactoring becomes a multi-sprint effort | Over-connected classes are flagged before they become entrenched |
| Performance anti-patterns (N+1 queries) reach production | Static detection at review time β before runtime |
| Layer violations erode separation of concerns gradually | Controller β Repository bypasses are caught immediately |
| "Architecture review" is an ad-hoc, inconsistent process | Every single PR gets a quantified, repeatable, AI-explained health check |
- π€ Fully Automated β no manual triggers, no CLI commands, no dashboards to poll
- π In-Context Feedback β reports appear exactly where your team works: on the PR itself
- π’ Quantified Results β a single 0β100 health score with weighted, configurable dimensions
- π§ AI-Explained β not just metrics, but LLM-powered explanations of what they mean and what to do about them
- π₯ Multi-User Native β any team member registers their own token; no centralized admin bottleneck
- π Secure by Design β HMAC webhook validation, scoped tokens, masked credentials in all responses
βββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββ
β Developer ββββββΆβ Opens a PR ββββββΆβ GitHub ββββββΆβ ArchSentinel β
β pushes code β β or pushes β β sends β β receives β
β β β to branch β β webhook β β webhook event β
βββββββββββββββ ββββββββββββββββ ββββββββββββββββ ββββββββββ¬ββββββββββ
β
βΌ
ββββββββββββββββββββββββββ
β 8-Step Analysis β
β Pipeline Executes β
β β
β 1. Clone base branch β
β 2. Clone head branch β
β 3. AST parse (both) β
β 4. Build dep graphs β
β 5. Compute 5 metrics β
β 6. Calculate scores β
β 7. Generate diff β
β 8. AI analysis β
ββββββββββββββ¬ββββββββββββ
β
βΌ
ββββββββββββββββββββββββββ
β π Posts detailed β
β architecture report β
β as a PR comment β
ββββββββββββββββββββββββββ
In plain English:
- A developer opens a pull request (or pushes new commits to an existing one).
- GitHub fires a webhook event to your ArchSentinel instance.
- ArchSentinel validates the webhook signature (HMAC-SHA256) for security.
- The analysis pipeline kicks off asynchronously β your PR is never blocked.
- Both the base branch and the PR head are cloned at their exact commits.
- Full static analysis runs on both snapshots independently.
- A before/after comparison generates a detailed Impact Report.
- An AI service generates human-readable explanations and actionable suggestions.
- A beautifully formatted architecture report is posted directly on the PR as a comment.
The entire process runs in the background. The developer simply opens a PR and waits for the report to appear β typically within seconds.
ArchSentinel runs five independent analysis engines on every pull request. Each engine examines a different dimension of architectural quality, and together they provide a 360-degree view of your codebase's structural health.
What it detects: Classes that are over-connected β the "God objects" that know too much about the rest of your system.
How it works:
ArchSentinel measures fan-in (how many other classes depend on this one) and fan-out (how many other classes this one depends on) for every class in your codebase. Classes that exceed configurable thresholds are flagged as coupling hotspots.
Why it matters:
High coupling is one of the strongest predictors of maintenance difficulty. When a single class is connected to dozens of others, modifying it creates a blast radius that can cascade across your entire system. Coupling hotspots are the classes most likely to:
- Cause merge conflicts across teams
- Require coordinated deployments
- Resist safe refactoring
- Generate unexpected side effects during changes
What the report shows:
- Per-class coupling scores (fan-in / fan-out)
- Identified coupling hotspots with their exact file locations
- Before/after coupling score comparison to show the PR's impact
What it detects: Circular (cyclic) dependency chains where Class A β Class B β Class C β Class A.
How it works:
ArchSentinel builds a full directed dependency graph from your codebase's import and usage relationships. It then runs a depth-first search (DFS) with three-color marking (white/gray/black) to detect back-edges β the hallmark of cycles in directed graphs. When a cycle is found, the full path is recorded.
Why it matters:
Circular dependencies are among the most insidious forms of architectural decay:
- They make individual modules impossible to test in isolation
- They create deployment order problems β you can't deploy A without B, but B depends on A
- They indicate that module boundaries are poorly defined
- They grow exponentially harder to fix the longer they exist
- They often indicate that responsibilities are leaking across architectural boundaries
What the report shows:
- Total count of circular dependency chains found
- Exact cycle paths (e.g.,
OrderService β PaymentService β NotificationService β OrderService) - Before/after comparison showing whether the PR introduced new cycles
What it detects: Methods with excessive branching logic β the functions that are hard to read, hard to test, and hard to maintain.
How it works:
Using JavaParser AST analysis, ArchSentinel calculates the cyclomatic complexity of every method in your codebase. Cyclomatic complexity counts the number of independent execution paths through a function β each if, else, switch case, for, while, catch, &&, and || adds a path. Methods exceeding safe thresholds are flagged.
Why it matters:
Complex methods are the primary source of:
- Bugs β more paths mean more chances for unexpected behavior
- Testing difficulty β each path requires its own test case; a method with complexity 20 needs at least 20 tests for full branch coverage
- Cognitive load β developers struggle to hold complex methods in their heads
- Review difficulty β reviewers are more likely to miss issues in complex code
What the report shows:
- List of methods exceeding complexity thresholds
- Per-method complexity scores with class name and file location
- Before/after complexity comparison showing the PR's impact on readability
What it detects: Components that bypass architectural boundaries β for example, a Controller calling a Repository directly, skipping the Service layer.
How it works:
ArchSentinel classifies every class into its architectural layer based on annotations, naming conventions, and package structure:
| Layer | Detection Criteria |
|---|---|
| Controller | @RestController, @Controller, classes ending in Controller |
| Service | @Service, classes ending in Service |
| Repository | @Repository, classes ending in Repository, Dao |
It then checks all dependency edges against a layer access matrix. Violations occur when a higher-level layer directly accesses a lower-level layer without going through the intermediate layer.
Why it matters:
Layer violations destroy separation of concerns β the foundational principle that makes large codebases manageable:
- Controllers that call repositories directly bypass business logic, validation, and transaction management
- Skipped layers create hidden coupling between presentation and persistence
- They make it impossible to swap implementations (e.g., changing database) without modifying UI code
- They indicate that the Service layer is either missing or inadequate
What the report shows:
- Total count of layer violations
- Specific violation descriptions (e.g., "Controller
UserControllerdirectly accesses RepositoryUserRepository") - Before/after comparison showing whether the PR introduced new violations
What it detects: Static patterns that are likely to cause performance issues at runtime β most notably N+1 query patterns.
How it works:
ArchSentinel analyzes the AST for patterns where repository/database calls occur inside loops, or where lazy-loaded collections are accessed in iteration contexts. These patterns are the most common cause of unexpected database load in production.
Why it matters:
N+1 queries are invisible in development (where you have 10 records) but devastating in production (where you have 10,000):
- A single N+1 pattern can turn a 1-query page load into a 10,001-query page load
- They are the #1 cause of unexpected database load
- They often hide behind ORM abstractions and are invisible in code review
- Fixing them after deployment requires emergency patches
What the report shows:
- Total count of performance risks identified
- Specific risk descriptions with file and method locations
- Before/after comparison showing whether the PR introduced new risks
Every analysis produces a single, quantified Health Score (0β100) that gives your team an instant, at-a-glance read on the structural quality of the codebase β and how the current PR is affecting it.
Health Score = 100 - (
Coupling Penalty Γ 0.25 +
Circular Dep Penalty Γ 0.25 +
Complexity Penalty Γ 0.20 +
Performance Penalty Γ 0.20 +
Layer Violation Penalty Γ 0.10
)
| Score Range | Risk Level | Indicator | Recommended Action |
|---|---|---|---|
| 80 β 100 | π’ HEALTHY | β All clear | Safe to merge β architecture is in good shape |
| 60 β 79 | π‘ MODERATE | Review flagged items β consider addressing before merge | |
| 40 β 59 | π AT RISK | πΆ Refactoring needed | Strongly recommend refactoring before merging |
| 0 β 39 | π΄ CRITICAL | π¨ Immediate action | Do not merge β severe structural problems detected |
Engineering teams are drowning in metrics. ArchSentinel deliberately distills five complex analysis dimensions into one number so that:
- Developers get instant feedback without reading a full report
- Tech leads can set health score thresholds for merge gates
- Managers can track architecture quality trends over time
- CI/CD pipelines can gate deployments on architecture quality (coming soon)
Every team has different priorities. ArchSentinel's scoring weights are fully configurable via environment variables or Spring Boot configuration:
archsentinel:
scoring:
coupling-weight: 0.25
circular-weight: 0.25
complexity-weight: 0.20
performance-weight: 0.20
layer-violation-weight: 0.10Want to prioritize performance? Increase performance-weight. Don't care about layer violations? Set it to 0.0. The scoring model adapts to your team's values.
Raw metrics tell you what is wrong. AI tells you why it matters and what to do about it.
After the metrics engine computes the Impact Report, ArchSentinel forwards the complete analysis payload β including dependency graphs, metric deltas, coupling hotspots, complex methods, and layer violations β to an integrated AI service powered by OpenRouter (supporting GPT-4o-mini and other LLMs).
The AI service returns:
| Output | Description |
|---|---|
| Explanation | A plain-English summary of the architecture impact β written for humans, not machines |
| Suggestions | A numbered list of specific, actionable refactoring steps with class and method references |
Explanation: This PR introduces a new
NotificationServicethat directly importsUserRepository, bypassing the existingUserService. This creates a layer violation and increases coupling βUserRepositorynow has 4 dependents instead of 2. Additionally, thesendBulkNotificationsmethod has a cyclomatic complexity of 14, largely due to nested conditionals handling different notification channels.Suggestions:
- Inject
UserServiceintoNotificationServiceinstead ofUserRepositorydirectly β this preserves the service layer boundary- Extract the channel-specific notification logic in
sendBulkNotificationsinto a Strategy pattern (EmailNotifier,SmsNotifier,PushNotifier)- Consider introducing a
NotificationChannelinterface to decouple the notification dispatch from channel implementations
When the LLM is unavailable (no API key configured, rate limits, network issues), ArchSentinel gracefully falls back to a built-in rule-based reasoning engine that still produces meaningful, context-aware recommendations based on the detected metrics. Your PR reports never fail silently.
ArchSentinel posts a comprehensive, beautifully formatted architecture report directly as a comment on your pull request. No context switching. No external dashboards. No separate tools.
| Section | Contents |
|---|---|
| π₯ Health Score | Before/after scores with delta (e.g., 82 β 76 (Ξ -6)) |
| π Coupling Analysis | Per-class fan-in/fan-out, identified hotspots |
| π Circular Dependencies | Cycle count, exact cycle paths |
| 𧩠Complexity | Flagged methods with complexity scores and file locations |
| ποΈ Layer Violations | Specific violations with class-to-class references |
| β‘ Performance Risks | Identified anti-patterns with method locations |
| πΈοΈ Dependency Graph | Visual Mermaid diagram of class relationships |
| π€ AI Explanation | LLM-generated plain-English analysis |
| π Suggestions | Numbered, actionable refactoring recommendations |
| π Class Details | Per-class breakdown (name, type, file, dependencies, method count) |
Research consistently shows that feedback delivered in context is exponentially more effective than feedback delivered elsewhere:
- Developers don't need to leave their PR to understand architectural impact
- Reviewers can reference the architecture report during code review
- Discussions about structural quality happen alongside the code that caused them
- Historical reports are preserved in the PR timeline for future reference
ArchSentinel is designed for real teams with real workflows β not just solo developers.
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Multi-User Token Flow β
β β
β User A registers token βββΊ Maps to User A's repos β
β User B registers token βββΊ Maps to User B's repos β
β User C registers token βββΊ Maps to User C's repos β
β β
β When a webhook arrives for repo "org/service-x": β
β InstallationTokenStore looks up: repo β user's token β
β Uses that token for clone + PR comment posting β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Step | Action | Details |
|---|---|---|
| 1 | Register Token | Open the web UI β paste your GitHub PAT β click "Connect All My Repos" |
| 2 | Auto-Discovery | ArchSentinel automatically discovers all repositories accessible with your token |
| 3 | Add Webhook | Go to your repo β Settings β Webhooks β Add https://your-server/webhook/github |
| 4 | Open a PR | That's it β the architecture report will appear as a PR comment |
- β No server restarts β tokens are registered at runtime via API/UI
- β Token isolation β each user's token is mapped only to their own repos
- β Token masking β API responses never expose full token values
- β Fallback token β optional global token for repos without a registered user
- β Auto-discovery β registering a token automatically enumerates all accessible repos
ArchSentinel is built as a three-tier microservice architecture, containerized with Docker Compose for one-command deployment.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Frontend (React + Vite) β
β β
β β’ Token registration dashboard β
β β’ Connected repositories overview β
β β’ System health monitoring β
β β’ Responsive, modern UI β
βββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββ
β HTTP
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Backend (Java 17 + Spring Boot :8080) β
β β
β βββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββ β
β β WebhookController β β InstallationTokenStore β β
β β (POST /webhook/ β β Maps repo β user's token β β
β β github) β ββββββββββββββββββββββββββββββββββββ β
β ββββββββββ¬βββββββββββββ β
β β β
β ββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Analysis Pipeline (Async) β β
β β β β
β β RepoCloner βββΊ StaticAnalyzer βββΊ GraphBuilder β β
β β β β β β β
β β β βΌ βΌ β β
β β β JavaParser DependencyGraph β β
β β β (AST Parse) (Directed Graph) β β
β β β β β β β
β β β βββββββββ¬ββββββββββββ β β
β β β βΌ β β
β β β MetricsEngine β β
β β β (5 Analysis Engines) β β
β β β β β β
β β β βΌ β β
β β β HealthScoreCalculator β β
β β β (Weighted 0-100) β β
β β β β β β
β β β βΌ β β
β β β DiffEngine β β
β β β (Before/After Compare) β β
β β β β β β
β β β βββββββββ΄ββββββββ β β
β β β βΌ βΌ β β
β β β AiServiceClient GitHubCommentService β β
β β β (LLM Analysis) (Post PR Comment) β β
β βββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββ
β HTTP
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AI Service (Python + FastAPI :8000) β
β β
β βββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββ β
β β /analyze endpoint β β reasoning_engine.py β β
β β (POST) β β (Rule-based fallback) β β
β ββββββββββ¬βββββββββββββ ββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββ β
β β OpenRouter API β β
β β (GPT-4o-mini / β β
β β configurable LLM) β β
β βββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Frontend | React + Vite | Latest | Token registration UI, repo management dashboard |
| Backend | Java + Spring Boot | 17 / 3.x | Core analysis engine, webhook processing, API |
| AI Service | Python + FastAPI | 3.x | LLM integration, rule-based reasoning fallback |
| Code Parsing | JavaParser | Latest | Abstract Syntax Tree generation and traversal |
| AI/LLM | OpenRouter API | β | GPT-4o-mini (configurable) for analysis explanations |
| Version Control | JGit | Latest | Programmatic repository cloning at specific commits |
| Containerization | Docker + Compose | Latest | One-command deployment of entire stack |
| Webhook Security | HMAC-SHA256 | β | Cryptographic validation of incoming webhooks |
When a webhook arrives, ArchSentinel executes a rigorous 8-step analysis pipeline asynchronously. Here's exactly what happens at each step:
| Step | Component | Action | Output |
|---|---|---|---|
| 1 | RepoCloner |
Clone repository at base branch commit via JGit | Local copy of base codebase |
| 2 | RepoCloner |
Clone repository at PR head commit via JGit | Local copy of PR codebase |
| 3 | StaticAnalyzer |
Parse all .java files in base into AST via JavaParser |
List<ClassInfo> for base |
| 4 | StaticAnalyzer |
Parse all .java files in PR head into AST via JavaParser |
List<ClassInfo> for PR |
| 5 | GraphBuilder |
Build directed dependency graphs from both class lists | DependencyGraph (base + PR) |
| 6 | MetricsEngine |
Compute all 5 metric categories for both snapshots | ArchitectureSnapshot Γ 2 |
| 7 | HealthScoreCalculator + DiffEngine |
Calculate weighted scores, compare before/after | ImpactReport with deltas |
| 8 | AiServiceClient + GitHubCommentService |
Get AI analysis, format and post PR comment | β Report on PR |
Push events follow the same pipeline but compare before-commit vs after-commit (instead of base vs head branch). For first pushes to a new branch, ArchSentinel intelligently detects the zero-commit state and analyzes the current snapshot only.
After every analysis β regardless of success or failure β ArchSentinel automatically cleans up all cloned directories to prevent disk space leaks. This is handled in a finally block to guarantee cleanup even during exceptions.
| Requirement | Required? | Purpose |
|---|---|---|
| Docker & Docker Compose | β Yes | Runs the entire stack |
| GitHub Personal Access Token | β Yes | Repository access + PR commenting (needs repo scope) |
| OpenRouter API Key | β¬ Optional | Enables AI-powered explanations (falls back to rule-based without it) |
git clone https://github.com/Prabal864/ArchSentinel.git
cd ArchSentinel# Required: Secret for validating incoming webhook signatures
export WEBHOOK_SECRET=your_random_secret_here
# Optional: Enables AI-powered analysis explanations
export OPENROUTER_API_KEY=your_openrouter_api_key
# Optional: Fallback token for repos without a registered user
export GITHUB_TOKEN=ghp_your_fallback_tokendocker-compose up --buildThis starts three containers:
- Backend on port
8080(Spring Boot) - AI Service on port
8000(FastAPI) - Frontend served via the backend
- Open
http://localhost:8080in your browser - Paste your GitHub Personal Access Token (needs
reposcope) - Click "Connect All My Repos" β ArchSentinel auto-discovers all accessible repositories
- Go to your repository β Settings β Webhooks β Add webhook
- Payload URL:
https://your-server.com/webhook/github - Content type:
application/json - Secret: Same value as your
WEBHOOK_SECRET - Events: Select Pull requests and Pushes
- Click Add webhook
Open a pull request on any connected repository. Within seconds, ArchSentinel will post a comprehensive architecture health report as a comment on your PR.
| Variable | Required | Description | Default |
|---|---|---|---|
WEBHOOK_SECRET |
β | HMAC-SHA256 secret for validating incoming GitHub webhook signatures | β |
OPENROUTER_API_KEY |
β¬ | API key for OpenRouter LLM service (enables AI-powered explanations) | β |
GITHUB_TOKEN |
β¬ | Fallback GitHub token used when no user token is registered for a repo | β |
LLM_MODEL |
β¬ | LLM model identifier to use via OpenRouter | openai/gpt-4o-mini |
AI_SERVICE_URL |
β¬ | Internal URL of the AI analysis microservice | http://ai-service:8000 |
CLONE_DIR |
β¬ | Directory path for temporary repository clones | /tmp/archsentinel-repos |
archsentinel:
scoring:
coupling-weight: 0.25 # Weight for coupling analysis (0.0 β 1.0)
circular-weight: 0.25 # Weight for circular dependency detection
complexity-weight: 0.20 # Weight for cyclomatic complexity
performance-weight: 0.20 # Weight for performance risk detection
layer-violation-weight: 0.10 # Weight for layer violation detectionNote: Weights should sum to 1.0 for a meaningful 0β100 score, but this is not enforced β you can over/under-weight as desired.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST |
/api/register |
Register a GitHub Personal Access Token. Auto-discovers all accessible repos. | None |
DELETE |
/api/register/{owner}/{repo} |
Remove the registered token for a specific repository. | None |
GET |
/api/repos |
List all registered repositories with masked token values. | None |
GET |
/api/health |
System health check β returns uptime, registered repo count, and system stats. | None |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST |
/webhook/github |
Receives GitHub webhook events. Validates HMAC signature. Processes pull_request and push events. |
HMAC-SHA256 |
GET |
/webhook/test |
Simple health check to verify the backend is running and accessible. | None |
| Method | Endpoint | Description | Auth |
|---|---|---|---|
POST |
/analyze |
Accepts an Impact Report payload and returns AI-generated explanation + suggestions. | None (internal) |
GET |
/health |
Health check for the AI microservice. | None |
ArchSentinel is designed with security as a first-class concern:
| Security Feature | Implementation |
|---|---|
| Webhook Signature Validation | Every incoming webhook is validated against WEBHOOK_SECRET using HMAC-SHA256. Invalid signatures are rejected with HTTP 401. |
| Token Isolation | Each user's GitHub PAT is mapped exclusively to their own repositories. No cross-user token access. |
| Token Masking | All API responses that include token information mask the token value. Full tokens are never exposed via the API. |
| Scoped Access | ArchSentinel requires only the repo scope β the minimum needed for cloning and PR commenting. |
| Automatic Cleanup | Cloned repository directories are deleted immediately after analysis, regardless of success or failure. |
| No Data Persistence | ArchSentinel does not persist your code, analysis results, or tokens to any database. Everything is in-mem D0B4 ory and ephemeral. |
| Internal AI Communication | The AI service is internal to the Docker network and not exposed externally by default. |
"We merge 50+ PRs per week across 12 services. We can't manually review every one for architecture compliance."
ArchSentinel gives your team automated, consistent architecture governance on every single PR β no exceptions, no human bottleneck.
"I need to enforce our architecture principles without becoming a review bottleneck."
ArchSentinel codifies your architecture rules into automated checks. Layer violations, coupling thresholds, and complexity limits are enforced programmatically β you only need to review the exceptions.
"I don't have a team to review my architecture decisions. I need a second pair of eyes."
ArchSentinel acts as your AI-powered architecture advisor β catching mistakes that are invisible when you're deep in implementation mode.
"Contributors submit PRs from all over the world. I need to ensure they don't degrade the codebase structure."
ArchSentinel automatically analyzes every contributor PR, giving maintainers a structural quality assessment before they even begin code review.
"I want to teach students what good architecture looks like β with real, measurable feedback."
ArchSentinel provides quantified, educational feedback on architectural quality β perfect for university courses, bootcamps, and self-study.
| Component | Minimum | Recommended |
|---|---|---|
| Docker | 20.10+ | Latest |
| Docker Compose | 2.0+ | Latest |
| Memory | 512 MB | 2 GB+ |
| Disk | 1 GB free | 5 GB+ (for cloning large repos) |
| GitHub Token | PAT with repo scope |
Fine-grained PAT with repository access |
| OpenRouter Key | β | Required for AI-powered explanations |
| Feature | ArchSentinel AI | SonarQube | CodeClimate | Codacy |
|---|---|---|---|---|
| PR-native comments | β | β¬ Partial | β | β |
| Architecture-specific analysis | β | β¬ Limited | β | β |
| Circular dependency detection | β | β | β | β |
| Layer violation detection | β | β | β | β |
| Dependency graph visualization | β | β | β | β |
| AI-powered explanations | β | β | β | β |
| Single health score (0β100) | β | β¬ Different model | β | β |
| Before/after PR comparison | β | β¬ Partial | β¬ Partial | β¬ Partial |
| Multi-user token registration | β | N/A | N/A | N/A |
| Self-hosted | β | β | β | β |
| Open source | β | β¬ Community Edition | β | β |
| Zero configuration | β | β | β¬ Partial | β¬ Partial |
| Docker one-command deploy | β | β¬ Complex | N/A | N/A |
| Status | Feature | Description |
|---|---|---|
| β | Core Analysis | Coupling, circular deps, complexity, layers, performance |
| β | AI Explanations | LLM-powered analysis via OpenRouter |
| β | Multi-User | Token registration with auto-discovery |
| β | Push Analysis | Before/after commit comparison on push events |
| β | Docker Compose | One-command deployment |
| π | GitHub App | Native GitHub App installation (no webhook setup needed) |
| π | Multi-Language | Support for Python, TypeScript, Go, Kotlin, and more |
| π | Historical Trends | Track health score over time with charts and dashboards |
| π | CI/CD Integration | Fail builds when health score drops below threshold |
| π | Custom Rules | Define your own architectural rules and patterns |
| π | Slack/Discord Notifications | Alert channels when critical PRs are detected |
| π | GitHub Checks API | Native status checks on PRs (pass/fail) |
| π | Team Dashboards | Organization-wide architecture health overview |
| π | Dependency Graph UI | Interactive visualization of your architecture |
| π | PR Merge Gates | Block PRs that don't meet architecture standards |
We welcome contributions from the community! Whether it's a bug fix, new analysis engine, language support, or documentation improvement β every contribution matters.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
# Backend
cd backend
mvn clean package
java -jar target/archsentinel-backend-*.jar
# AI Service
cd ai-service
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000cd backend
mvn testThis project is released under a custom license. See the LICENSE file for details.
ποΈ ArchSentinel AI Your architecture deserves a guardian. Every PR deserves a health check.
π Live Demo Β· π¦ Source Code Β· π Report Bug Β· π‘ Request Feature
If you found this useful, give it a β on GitHub!