flutter_arch_lens

A powerful yet lightweight architecture analysis CLI tool for Flutter and Dart projects.

flutter_arch_lens analyzes your project structure, builds an import dependency graph, detects circular dependencies, enforces layered architecture rules, and produces CI-friendly reports to prevent architectural decay over time.

Supported Project Types

  • Flutter applications
  • Dart packages
  • Monorepos
  • CI/CD pipelines

Features

  • Circular dependency detection across all Dart files in lib/
  • Layered architecture enforcement via YAML configuration
  • Dependency graph generation for internal imports
  • Multiple output formats (text, JSON)
  • Explain mode to understand your current project structure
  • Recommend mode for actionable architecture guidance
  • CI-friendly with meaningful exit codes
  • Zero-config operation by default

Installation

dart pub add --dev flutter_arch_lens

Run the tool:

dart run flutter_arch_lens

Option 2: Global installation

dart pub global activate flutter_arch_lens

Run from anywhere:

flutter_arch_lens --help

Quick Start

From your project root:

dart run flutter_arch_lens

What it does by default:

  • Scans all files in lib/
  • Builds a dependency graph
  • Detects circular dependencies
  • Prints an architecture health report

Example output:

flutter_arch_lens report

Root: /my_project
Files scanned: 124
Score: 92/100
Cycles: 0
Violations: 1

Detected structure: Feature-first (lib/features/**)

✓ No circular dependencies detected.
✗ 1 layer rule violation detected.

Explain Mode

Understand how your project is currently structured.

dart run flutter_arch_lens --explain

Example output:

Layer distribution:
  - presentation: 24 file(s)
  - domain: 18 file(s)
  - data: 21 file(s)

File → layer mapping:
  lib/features/login/presentation/login_page.dart → presentation
  lib/features/login/domain/login_usecase.dart → domain

Use cases:

  • Code reviews
  • Developer onboarding
  • Refactoring planning

Recommend Mode

Get architecture improvement suggestions.

dart run flutter_arch_lens --recommend

Example recommendations:

For Flutter apps:

lib/
  core/
  features/
    <feature>/
      presentation/
      domain/
      data/

For Dart packages:

lib/
  my_package.dart     # public API
  src/                # internal code
bin/                  # CLI executables

Configuration

Create .arch_lens.yaml in your project root to enforce architecture rules.

Example: Clean Architecture

layers:
  - name: presentation
    include:
      - lib/features/**/presentation/**

  - name: domain
    include:
      - lib/features/**/domain/**

  - name: data
    include:
      - lib/features/**/data/**

  - name: core
    include:
      - lib/core/**

rules:
  allowedDependencies:
    presentation: [domain, data, core]
    domain: [core]
    data: [domain, core]
    core: []

thresholds:
  maxCycles: 0
  minScore: 85

Output Formats

JSON output

dart run flutter_arch_lens --format json

Save report to file

dart run flutter_arch_lens --format json --out build/arch_lens/report.json

CI/CD Integration

GitHub Actions Example

- name: Architecture check
  run: dart run flutter_arch_lens

The command fails automatically if violations are detected.

Exit Codes

Code Meaning
0 No issues detected
2 Architecture violations found
64 Configuration or usage error

What This Tool Does NOT Do

  • Does not modify your files
  • Does not move code automatically
  • Does not force a specific architecture

It analyzes and reports only.

License

MIT

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

Support

For issues, questions, or feature requests, please visit the GitHub repository.

Author

Manio Khan

If you find this package helpful, please consider giving it a star on GitHub and a like on pub.dev. Your support helps maintain and improve this tool for the Flutter and Dart community.

Acknowledgments

Built with care for developers who value clean architecture and maintainable code. Thank you for using flutter_arch_lens!

Libraries

flutter_arch_lens
flutter_arch_lens