Stop your Flutter architecture from drifting: layer rules and cycle checks in your IDE and CI with arch_guard

Description and use

arch_guard detects architecture violations in Flutter projects—wrong imports, forbidden packages, and circular dependencies—and integrates with IDE, tests, and CI.

Problem

Flutter projects often drift from their intended architecture, with widgets importing repository implementations directly and services importing each other, leading to broken architecture diagrams and hidden violations that the analyzer and tests do not catch.

Outcome

After adopting arch_guard, architecture violations are caught early in the IDE, tests, and CI. Baselines allow teams to focus on new violations, and the tool provides interactive graphs and quick fixes, reducing architecture drift.

Workflow

• Add arch_guard as a dev dependency: dart pub add --dev arch_guard
• Initialize configuration: dart run arch_guard init (detects layout and writes arch_guard.yaml)
• Run checks: dart run arch_guard (reports violations)
• Configure IDE plugin: add arch_guard_lint to analysis_options.yaml
• Add architecture test: import package:arch_guard/testing.dart and call expectArchitecture() in tests
• Set up CI workflow to run arch_guard on pull requests
• Use --update-baseline to record current violations and allow only new ones to fail CI

Evidence

Every Flutter project I've worked on started with a clean folder structure: domain, data, presentation, maybe a features/ folder. And on every one, six months later, a widget was importing a repository implementation directly, and two services imported each other.

Source

arch_guard runs Tarjan's algorithm over the import graph and reports every group of files that import each other, with fan-in/fan-out, instability and the "hub" files.

Source

If you'd rather keep architecture rules next to the code, they also run in dart test / flutter test: ... It fails exactly when the CLI would, with a readable list of problems.

Source