arch_guard 1.10.0

A CLI tool and Dart library for static architecture analysis, Clean Architecture layer governance, circular dependency metrics, and graph visualization.

arch_guard

Keep your Dart and Flutter architecture the way you designed it. arch_guard fails the build when a file imports a layer it shouldn't, finds circular dependencies, and draws your dependency graph, in the terminal, in pre-commit hooks and in CI.

dart pub add --dev arch_guard
dart run arch_guard init     # detects your layout and writes arch_guard.yaml
dart run arch_guard          # checks the project

📖 Documentation: creatorpiyush.github.io/arch_guard

---

Features

• 🛡️ Layer rules. Say which layers may import which (domain must not import data); every violation shows the import line and the rule it breaks.
• 🚫 Forbidden packages. Keep flutter, dart:io or any package out of a layer (or the whole project), with globs like firebase_*.
• 🏢 Workspace rules. In a monorepo, say which packages may depend on which: apps/* may use packages/*, never the reverse.
• 📏 Metric limits and hotspots. max_fan_out / max_fan_in stop files from becoming hubs; reports list the most coupled files.
• ⚡ Presets and init. clean_architecture, riverpod, bloc and feature_first presets; arch_guard init detects which one fits your project.
• 🔁 Circular dependencies. Tarjan's algorithm finds every group of files that import each other, with fan-in/fan-out, instability and hub metrics.
• 📌 Baselines for existing code. Record today's problems once; CI then fails only on new ones.
• 🎯 --since origin/main. Report only problems touching files changed on the branch.
• 🩹 Cycle-breaking hints. Each cycle names the one import to remove to break it.
• 🧪 Architecture tests. await expectArchitecture(); in dart test / flutter test runs the same checks. See Testing.
• 💡 IDE warnings and quick fixes. The arch_guard_lint analyzer plugin underlines layer violations, forbidden imports and the import that closes each cycle as you type, with one-click fixes. See IDE.
• 🤖 CI-ready. A GitHub Action that comments on PRs, SARIF for GitHub Code Scanning, Markdown job summaries, pre-commit hooks, standalone binaries.
• 🎨 Graphs. Interactive HTML (works offline), Mermaid, Graphviz DOT and JSON.
• 🏢 Workspaces and monorepos. Dart workspaces and Melos-style packages//apps/ repos, including cycles across packages.
• 🔍 --explain <file>. Why is this file in a cycle? What does it import and what imports it?

Examples: a small, runnable project for each feature, with the command and its real output. See example/example.md.

Why arch_guard?

	arch_guard	DCM	import_lint	lakos
Price	Free, MIT	Free tier (1 seat, up to 50k LOC); paid plans	Free, MIT	Free, MIT
Import / layer rules	✅ layers with allowed_imports, plus package-level workspace_rules	✅ avoid-banned-imports rule	✅ target / from rules	–
Ready-made architecture presets + init	✅	–	–	–
Circular dependency detection	✅ with metrics	–	–	✅
Baseline for legacy code	✅	✅	–	–
Dependency graph output	HTML, Mermaid, DOT, JSON	DOT (analyze-structure)	–	DOT, JSON
PR comment / SARIF / GitHub Action	✅	CI integrations on paid plans	–	–
Warnings in the IDE	✅ (arch_guard_lint analyzer plugin)	✅	✅ (analyzer plugin)	–

DCM is a full linting suite with hundreds of rules; import_lint shows import rules right in your editor; lakos focuses on graph metrics. arch_guard is built for one job: making architecture rules easy to adopt, including on a large existing codebase, and enforced on every pull request. Comparison based on each tool's public documentation in October 2026; corrections welcome.

---

Installation

Requires Dart SDK 3.8 or later (Flutter 3.32 or later).

dart pub add --dev arch_guard          # as a dev dependency: dart run arch_guard
dart pub global activate arch_guard    # or globally: arch_guard

No Dart SDK? Prebuilt binaries for Linux (x64, arm64), macOS (Apple Silicon) and Windows (x64) are attached to every GitHub Release, with SHA-256 checksums.

Configuration

arch_guard init writes arch_guard.yaml for you. The simplest config is a preset:

# arch_guard.yaml
preset: clean_architecture

Preset	Layers	Main rules
clean_architecture	core, domain, data, presentation	domain imports only core; presentation may not import data.
riverpod	domain, data, application, presentation	domain imports nothing else; data never imports application or presentation.
bloc	models, business_logic, repository, data_provider, presentation	UI → bloc/cubit → repository → data provider; models everywhere.
feature_first	shared + one feature_<name> per folder in lib/features	A feature imports only itself and shared (lib/core, lib/shared, lib/common).

Adjust a preset by listing only what changes, or define every layer yourself:

preset: clean_architecture
ignore:
  - "**/*.mocks.dart"
max_scc_size: 5            # optional: fail when a cycle group grows beyond 5 files
layers:
  presentation:
    allowed_imports: [core, domain, presentation, data]   # allow UI -> data
  di:
    patterns: ["lib/di/**"]
    allowed_imports: [core, domain, data, presentation, di]

The presets guide has a recipe for each architecture, and the configuration reference covers every key and how workspaces are matched.

Reading the report

❌ Layer Violation: [presentation] lib/features/auth/presentation/page.dart:3 -> [data] lib/features/auth/data/repo.dart
   Rule: `presentation` may only import `core`, `domain`, `presentation`.

To fix a violation, invert the dependency (an interface in the importing layer, implemented by the imported one), move the code to a layer it may import, or, if the dependency is intended, add the layer to allowed_imports.

Strongly Connected Component #1 (2 files)
  Representative Cycle Path:
  lib/widgets/nav.dart
  -> lib/screens/home.dart
  -> lib/widgets/nav.dart
  Suggested fix: remove lib/screens/home.dart:1 -> lib/widgets/nav.dart (breaks the cycle)

Each cycle comes with a Suggested fix: line naming the one import whose removal breaks it, or, when no single import does, the one that shrinks it most.

Adopting on an existing codebase

arch_guard --update-baseline        # writes arch_guard_baseline.json
git add arch_guard_baseline.json

From then on only new cycles and layer violations fail the run. When known problems are fixed, arch_guard tells you, so you can update the baseline and keep them from coming back. More about baselines.

CI

# .github/workflows/architecture.yml
name: Architecture
on: [pull_request]

permissions:
  contents: read
  pull-requests: write     # PR comment

jobs:
  arch_guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: creatorpiyush/arch_guard@v1.10.0

The action downloads a checksum-verified binary, posts one PR comment it keeps up to date, and can upload SARIF to GitHub Code Scanning. GitLab CI, pre-commit, lefthook and plain git hooks are covered in the CI & hooks guide.

Command line

arch_guard [path] [options]
arch_guard . -f html -o build/reports                      # interactive graph
arch_guard . --explain lib/services/auth_service.dart      # one file's dependencies
arch_guard . -f sarif -f markdown -o build/reports         # for CI

Exit code	Meaning
0	No cycles, layer violations or forbidden imports (or none new, with a baseline).
1	Cycles, layer violations or forbidden package imports found.
2	Scan error: missing directory, unreadable project or invalid baseline.
64	Invalid flags or arguments.

All flags, output formats and the Dart API are in the CLI reference and API guide.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup and checks, and ARCHITECTURE.md for how the code is organised.

License

MIT License. See THIRD_PARTY_NOTICES.md for third-party software attributions.