I got tired of AI code assistants breaking our project architecture, so I built ArchSentry

Hey everyone,

Lately my team has been using Cursor and Copilot a lot. While it writes code super fast, I kept noticing that it quietly breaks architectural boundaries in our PRs. For example, it would start writing raw database queries straight inside API route handlers instead of using our repository layer, or importing internal modules across domain boundaries.

ESLint and standard linters didn't really catch this without writing tedious custom AST plugins, and paying for AI review bots just to check simple rules got expensive and slow on CI.

So over the past few weeks, I built ArchSentry.

It’s an open-source CLI and CI gate where you define your team's architectural invariants in a simple YAML contract (archsentry.yml). For example: "files inside /controllers can never contain db.query or SQL strings".

---

How it Works:

           ┌──────────────────────────────┐
           │    Pull Request Git Diff     │
           └──────────────┬───────────────┘
                          │
                (Deterministic Gate)
                          ▼
           ┌──────────────────────────────┐
           │ ArchSentry Engine Registry   │
           │  - Sub-ms Pattern Matcher    │
           │  - AST Semgrep Interpreter   │
           └──────────────┬───────────────┘
                          │
                [0 Violations: Exit 0]
                [Violations Found: Exit 1]
                          │
                          ▼
           ┌──────────────────────────────┐
           │   Contextual Remediation     │
           │  (OpenRouter Free / Ollama)  │
           └──────────────┬───────────────┘
                          │
                          ▼
           ┌──────────────────────────────┐
           │ PR Comment / Terminal Output │
           └──────────────────────────────┘

1. Deterministic Scan ($0 Cost, <100ms): Matches code and PR diffs against your rules using regex and AST/Semgrep patterns. Zero LLM tokens spent finding violations.
2. Contextual Remediation (Optional): When a violation is flagged, you can optionally pass --explain to let an LLM (or local Ollama / OpenRouter free models) generate a concise 2-sentence fix hint on how to maintain the proper abstraction layer.
3. Diff-Aware Line Filtering: Instead of failing on legacy technical debt, you can pipe a git diff to scan only the lines changed in that specific PR.

30-Second Quickstart (Zero Install via npx)
You can run it in any repo without installing anything:

Scan a directory against your contract

npx archsentry scan --config archsentry.yml --path .

Or pipe git diff directly

git diff main...HEAD | npx archsentry scan --config archsentry.yml --diff -

GitHub Actions Integration
Add .github/workflows/archsentry.yml:
name: Architectural Gate

on:
pull_request:
branches: [main]

jobs:
archsentry-scan:
name: Architectural Integrity Gate
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npx --yes archsentry scan --config archsentry.yml --path .

Open Source & Repo
I just published archsentry@0.3.0 under the MIT license:

comerade2134 / ArchSentry

Enforce your team's architecture rules on every PR. Deterministic, config-first, free to scan.

🛡️ ArchSentry

Enforce your team's architectural contracts on every pull request — deterministically, at zero scan token cost, with instant AI remediation.

---

⚡ Terminal Demo

$ npx archsentry scan --config archsentry.yml --path src --explain

❌ ArchSentry found 1 violation(s) (1 error, 0 warnings):

  • [error] no-direct-sql  src/controllers/user.controller.ts:7
    All database writes must go through the repository layer.
    > await db.query("INSERT INTO users (email, name) VALUES ($1, $2)", [payload.email, payload.name]);
    💡 Remediation: All database writes must go through the repository layer. Move this call
       behind the appropriate service or repository layer so the access path is centralized
       and reviewable, rather than issued directly from `src/controllers/user.controller.ts`.

$ echo $?
1

---

💡 Why ArchSentry?

AI coding assistants (Cursor, Copilot, Claude Code) generate thousands of lines of code per day. While standard linters catch syntax errors and SAST tools detect known CVE vulnerabilities, neither…

View on GitHub

I'd really love feedback from fellow engineers on the rule schema, or what kind of architectural guardrails you find yourself having to manually police in PRs!

Comments

[Light]

I built this because Cursor and Copilot kept sneaking raw database queries into our routes. How are you all keeping AI code assistants from violating your architectural boundaries? Would love to hear your thoughts on the rule schema!