flutter_arch_lens 1.0.2

Architecture analyzer for Flutter/Dart projects (CLI). Generates dependency graphs, detects cycles, and enforces layering rules.

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

Option 1: Add as a dev dependency (recommended)

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!