Show HN: ArchSentry – Deterministic architectural enforcement for CI

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

$ 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

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 understands your system's architecture.

LLM review bots burn hundreds of dollars per repo summarizing diffs without guaranteeing architectural compliance.

ArchSentry solves this with a two-phase architecture:

Deterministic Phase (Zero Cost & Blazing Fast): Code is matched against your YAML contracts via sub-millisecond regex or AST/Semgrep patterns. No tokens are spent finding violations.Explanation Phase (Optional & Free-Tier Compatible): When a violation is flagged, an LLM generates a concise, contextual remediation hint directly on the offending code snippet.

No installation required. Run directly in any repository:

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

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

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

0

: Clean scan. All architectural invariants satisfied.1

: Architectural violations detected (severity:error

).2

: Runtime error (missing configuration file, malformed YAML, or invalid path).

Add .github/workflows/archsentry.yml

to your repository:

name: ArchSentry Architectural Gate

on:
  pull_request:
    branches: [main, master, develop]
  push:
    branches: [main, master]

jobs:
  archsentry-scan:
    name: Architectural Integrity Gate
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run ArchSentry Gate
        run: npx --yes archsentry scan --config archsentry.yml --path .
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

ArchSentry can also run as a dedicated Probot-powered GitHub App that automatically reviews PRs, posts inline architectural remediation comments, and cleans up stale comments upon push.

pnpm install

cp .env.example .env

pnpm start

Architectural contracts are declared in archsentry.yml

at the root of your project:

version: 1

rules:
  - id: no-direct-db-in-controllers
    type: pattern
    severity: error
    description: "Controllers must route data queries through the repository layer."
    match:
      patterns:
        - "db.query("
        - "connection.query("
        - "INSERT INTO"
        - "UPDATE "
        - "DELETE FROM"
      paths:
        - "src/controllers/**"
        - "apps/api/controllers/**"
      exclude:
        - "src/repositories/**"
        - "**/tests/**"

  - id: no-raw-eval
    type: semgrep
    severity: error
    description: "Do not call eval() or new Function() in application code."
    semgrep:
      languages: ["typescript", "javascript"]
      pattern-either:
        - pattern: eval(...)
        - pattern: new Function(...)
      paths:
        include:
          - "src/**"
        exclude:
          - "**/*.spec.ts"

  - id: avoid-console-log-in-production
    type: pattern
    severity: warn
    description: "Use structured logger (logger.info / logger.error) instead of console.log."
    match:
      patterns:
        - "console.log("
      paths:
        - "src/**"
      exclude:
        - "src/scripts/**"

When --explain

is enabled (or running via PR comment bot), ArchSentry derives remediation hints using whichever provider key is detected in the environment:

git clone https://github.com/comerade2134/archsentry.git
cd archsentry

pnpm install

pnpm test

pnpm typecheck
pnpm run build

MIT © comerade2134