Skip to content
BranchesTags

Repository files navigation

ArchGuard

CI Release License: MIT

Architecture gate for AI-assisted React PRs.

ArchGuard enforces layer import boundaries in React + TypeScript projects — with five-minute setup, monorepo support, baseline mode for legacy code, and CI output designed for coding agents.

npm install: npm install -D @lifesavertech/archguard-cli@2.2.0 (requires Node.js 20+). The legacy scope @archguard/cli on npm is an unrelated package — do not use it.

Why ArchGuard

AI coding assistants merge architectural violations faster than humans can review. ESLint and TypeScript do not enforce folder-layer rules. dependency-cruiser is powerful but heavy to configure and does not offer PR diff mode or agent-oriented output.

ArchGuard fills the gap:

You need… ArchGuard provides…
Simple setup One architecture.yaml, archguard init in minutes
Layer enforcement Deterministic import boundaries between domain, features, ui, etc.
Monorepo support --root, workspace packages, tsconfig project references
Legacy code Baseline mode — fail only on new violations
AI workflows Agent JSON, AGENTS.md sync, Cursor/Copilot rules, MCP server
Fast PR checks --diff mode (v2.1)

See docs/COMPARISON.md for an honest comparison with dependency-cruiser, eslint-plugin-boundaries, and Steiger.

Feature status

Feature Status
Layer import boundaries ✅ Shipped
Circular dependency detection ✅ Shipped
Baseline / incremental adoption ✅ Shipped
Monorepo --root + workspace resolution ✅ Shipped
JSON / SARIF / GitHub Action ✅ Shipped
React UI heuristics (loops, fetch in components) ✅ Shipped (optional)
npm install (@lifesavertech/archguard-cli) ✅ Shipped (v2.2.0)
Custom layer paths mapping ✅ Shipped (v2.0.4)
patterns: schema + smart init ✅ Shipped (v2.0.5)
--config, --json, --format github ✅ Shipped (v2.0.6)
Agent output (--format agent, fix hints) ✅ Shipped (v2.0.6)
archguard sync + sync --check ✅ Shipped (v2.0.7)
Action SARIF upload + sync-check ✅ Shipped (v2.0.7)
PR diff mode (--diff) ✅ Shipped (v2.1.0)
Multi-agent outputs (Cursor, Copilot) ✅ Shipped (v2.1.0)
MCP server (git / local install) ✅ Shipped (v2.2.0)
Barrel bypass detection ✅ Shipped (v2.2.0)
Mermaid diagrams 🔜 v2.3
VS Code extension 🔜 v2.4

Full roadmap: ROADMAP.md · Adoption guide: docs/ADOPTION.md

Quick start

Install

npm install -D @lifesavertech/archguard-cli@2.2.0
npx archguard --version
npx archguard check --json          # machine-readable CI output
npx archguard check --format github # GitHub Actions annotations

Requires Node.js 20 or newer (engines.node in package.json). On Node 18 the CLI exits with a clear error instead of installing broken dependencies.

Custom folder layouts

Default presets match folder names (domain/, features/, ui/). For components/, db/, pages/, etc., map folders with patterns (recommended) or layers.*.paths:

patterns:
  root: src
  ignore: ["**/*.test.{ts,tsx}", "**/__tests__/**"]
  layers:
    ui:
      include: [components/**, pages/**]
    db:
      include: [db/**]
      exclude: [db/migrations/**]

layers:
  ui:
    allowedImports: [features, db]
  db:
    allowedImports: []

Shorthand (still supported):

layers:
  ui:
    paths: [src/components, src/pages]
    allowedImports: [features, db]
  db:
    paths: [src/db]
    allowedImports: []

If boundary rules are enabled but no files match any layer, check errors instead of reporting a false pass.

GitHub Action (CI):

- uses: lindseystead/ArchGuard@v2   # or @v1 for legacy

From source (before npm publish):

git clone https://github.com/lindseystead/ArchGuard.git
cd ArchGuard
npm install && npm run build && npm link

Initialize

archguard init                              # smart-detect folders + boundaries-only rules
archguard init --no-detect                  # static preset only (skip repo scan)
archguard init --preset react-layered       # detected layout + UI heuristics rules
archguard init --preset feature-sliced-react

Writes architecture.yaml, AGENTS.md, and .archguard/ARCHITECTURE_RULES.md.

Check

archguard check

Example output:

✗ Found 3 violation(s):

src/ui/UserProfile.tsx:2:1 - Layer 'ui' cannot import from 'domain'. Import from allowed layers only: features, shared. Move the imported code to an allowed layer or restructure dependencies. (layer-import-boundary)

Monorepo

archguard check --root apps/web --verbose

Incremental adoption

archguard check --update-baseline    # capture existing violations
archguard check --baseline           # fail only on new ones

Configuration

architecture.yaml is the source of truth:

layers:
  domain:
    allowedImports: []
  features:
    allowedImports: [domain, shared]
  ui:
    allowedImports: [features, shared]
  shared:
    allowedImports: []

uiLayers: [ui]   # optional: scope React UI rules

rules:
  enforceLayerBoundaries: true
  noCircularLayerDeps: true
  # Optional UI heuristics (off by default in v2 init; use react-layered preset to enable)
  noBusinessLogicInComponents: false
  noDataFetchingInUI: false

Full reference: docs/architecture.example.yaml

enforceFeatureBoundaries remains a deprecated alias for enforceLayerBoundaries.

Command reference

Command Description
archguard init Scaffold config (boundaries-only default)
archguard init --preset <name> boundaries-only, react-layered, feature-sliced-react
archguard check --diff PR-scoped scan (changed files + import neighbors)
archguard check --diff-base <ref> Git ref for diff (default origin/main)
archguard sync Regenerate guidance from config
archguard sync --check Fail if guidance is stale (CI)
archguard sync --targets cursor,copilot Write Cursor/Copilot rule files only
archguard sync --force Overwrite existing agent rule files
archguard check Full-repository scan
archguard check --root <path> Scan monorepo app package
archguard check --config <path> Use a custom architecture.yaml
archguard check --baseline Suppress known violations
archguard check --update-baseline Write baseline file
archguard check --json JSON output (alias)
archguard check --format json|sarif|github|agent Structured output
archguard check --verbose Resolution diagnostics

Also available: archguard diagram (v2.3 planned) — see ROADMAP.md.

GitHub Actions

- uses: actions/checkout@v4
  with:
    fetch-depth: 0
- uses: lindseystead/ArchGuard@v2
  with:
    diff-only: true
    diff-base: origin/main
    baseline: .archguard-baseline.json
    format: agent

Monorepo, SARIF upload, sync-check, and baseline workflows: docs/github-action.md

MCP server (Cursor / Claude)

MCP ships with the repo — build once, point Cursor at the local binary. No npm install required.

git clone https://github.com/lindseystead/ArchGuard.git
cd ArchGuard && npm ci && npm run build -w @lifesavertech/archguard-mcp
{
  "mcpServers": {
    "archguard": {
      "command": "node",
      "args": ["/absolute/path/to/ArchGuard/packages/mcp/dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Copy examples/mcp.cursor.json and replace the path. Full guide: packages/mcp/README.md.

See packages/mcp/README.md and examples/mcp.cursor.json.

Tools: archguard_check, archguard_explain, archguard_init (write-gated via ARCHGUARD_MCP_ALLOW_WRITE=true).

Project structure

ArchGuard/
├── packages/
│   ├── core/           # Config, parsing, resolution, workspace discovery
│   ├── cli/            # archguard command + presets/
│   │   └── src/presets/   # init preset definitions
│   ├── rules-react/    # Boundary, cycle, and optional UI rules
│   ├── guidance/       # AGENTS.md generation
│   └── mcp/            # MCP server for AI agents
├── tests/fixture-*/    # CI fixtures
├── examples/react-layered-app/
├── docs/               # Adoption, comparison, engineering plan
├── action.yml          # Composite GitHub Action
└── architecture.schema.ts

Documentation

Document Description
docs/ADOPTION.md Step-by-step team adoption
docs/COMPARISON.md vs dependency-cruiser, ESLint, Steiger
docs/PRODUCT.md Positioning and personas
docs/ENGINEERING_PLAN.md v2 refactor plan (maintainers)
docs/architecture.example.yaml Config reference
docs/github-action.md Action inputs and workflows
docs/migration/v1-to-v2.md Upgrade guide
ROADMAP.md Shipped vs planned features
CONTRIBUTING.md Development setup
PUBLISHING.md Release process

Example project

examples/react-layered-app — passing reference with domain / features / ui layout.

How it works

  1. Parse .ts / .tsx with the TypeScript compiler API
  2. Map files to layers via exact path segments (src/ui, not substrings)
  3. Resolve imports: relative paths, tsconfig aliases, workspace packages, project references
  4. Evaluate boundary rules from architecture.yaml
  5. Emit violations as text, JSON, or SARIF

AGENTS.md is reference material for contributors and agents. Enforcement happens through the CLI and architecture.yaml. Run archguard sync after editing config to keep guidance aligned.

Known limitations

  • UI behavior rules are heuristic and opt-in (off by default in v2 init)
  • Layer detection uses exact path segments
  • Barrel/re-export bypass is detected via no-barrel-boundary-bypass (on by default when layer boundaries are enforced)
  • Full-repo scan remains the default; schedule periodic full scans in CI alongside PR diff checks
  • npm package: @lifesavertech/archguard-cli@2.2.0
  • No IDE extension yet (v2.4) — CI and CLI only today

Testing

npm test

37 tests across core, CLI (including presets), rules, and guidance. CI smoke-tests the Action, passing example, failing fixture, and monorepo --root.

Contributing

See CONTRIBUTING.md. Read docs/ENGINEERING_PLAN.md before starting v2 work.

License

MIT — see LICENSE.

About

Local-first architecture enforcement for React + TypeScript — layer boundaries, UI rules, monorepo support, and a composite GitHub Action.

Topics

ai-toolsarchitectureclean-architecturecode-qualitycursordeveloper-toolsgithub-actionsgithub-copilotlintingmonoreporeactstatic-analysistypescript

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages