archguard (PR-first)

Minimal Architecture-as-Code tool focused on deterministic PR guardrails in GitHub Actions.

See ROADMAP.md for planned milestones and priorities. See docs/ROADMAP_GTM.md for user-facing rollout plan. See docs/ADOPTION_CHECKLIST.md for first 10 installs tracking. See docs/CI_BASELINE_ROLLOUT.md for Day 0 -> Day 1 rollout. See docs/CONFIG_REFERENCE.md for current config schema.

30-second quickstart

npx @nahuelorselli/archguard init --yes
npx @nahuelorselli/archguard doctor
npx @nahuelorselli/archguard check

Expected result:

• doctor reports 0 errors on a valid config
• check reports architecture violations only when rules are broken

What this MVP does

• Reads architecture model from .archguard.yaml
• Maps service paths in the repo
• Enforces rules: no_frontend_db_access, require_owner
• Posts a report in pull requests
• Fails CI when the rule is violated

Rule demo

If any file inside a frontend service imports one of these DB clients, CI fails:

• @prisma/client
• pg
• mysql2
• mongodb

require_owner fails when a service in .archguard.yaml has no owner.

Customize DB client detector packages in config:

detectors:
  db_client_packages_mode: extend
  db_client_packages:
    - drizzle-orm
    - knex
    - typeorm

Add custom path-boundary guardrails without changing Archguard code:

rule_templates:
  - id: no-web-imports-from-api
    type: no_path_imports
    from: apps/web/**
    deny_import: apps/api/**
    severity: error

Allow dependencies per service with a template:

rule_templates:
  - id: web-allowed-deps
    type: allowed_service_dependencies
    service: web
    allow:
      - apps/shared/**
      - apps/contracts/**
    severity: error

Fast onboarding

Create a starter .archguard.yaml from your repo layout:

npx @nahuelorselli/archguard init

By default it discovers folders under apps/* and services/*. archguard check auto-discovers config in this order: .archguard.yaml, .archguard.yml, .arch.yaml, .arch.yml.

Useful init flags:

npx @nahuelorselli/archguard init --yes
npx @nahuelorselli/archguard init --preset minimal --root src
npx @nahuelorselli/archguard init --config .archguard.yaml --force

Validate config and paths:

npx @nahuelorselli/archguard doctor

Share first-install feedback in:

• New issue -> Try Archguard (First install feedback)

Baseline mode (legacy-friendly rollout)

Create a baseline from current findings:

npx @nahuelorselli/archguard baseline create --out .archguard-baseline.json

Then fail only on newly introduced violations:

npx @nahuelorselli/archguard check --baseline .archguard-baseline.json

For a staged adoption plan, follow docs/CI_BASELINE_ROLLOUT.md.

Install and run

No global install required:

npx @nahuelorselli/archguard check
pnpm dlx @nahuelorselli/archguard check
bunx @nahuelorselli/archguard check

Local development

npm install
npm run archguard
npm run archguard:doctor

Changed files mode:

npm run archguard:changed

GitHub Actions run

Workflow file: .github/workflows/archguard.yml

On each PR, the workflow:

1. runs archguard on changed files
2. writes archguard-report.md
3. comments the report in the PR
4. fails the job if violations exist

Gradual rollout tip:

• Commit .archguard-baseline.json and the default workflow auto-applies --baseline when the file exists.

End-to-end demo scenario

PR that should fail

1. Edit apps/web/src/lib/http.ts
2. Add:

import { PrismaClient } from '@prisma/client'

3. Open PR
4. Expected: PR comment with violation + failed check

PR that should pass

1. Remove DB client import from frontend
2. Keep DB access in apps/api
3. Push update
4. Expected: passing check and clean report

Report output

Each violation includes:

• exact file (and line for code imports)
• why the change is risky
• how to fix it

Live demo PRs

• Expected fail (frontend DB access): https://github.com/NahuelOrselli/archguard/pull/6
• Expected pass (safe API-only change): https://github.com/NahuelOrselli/archguard/pull/5

Demo screenshots

Expected fail

Expected pass