Architecture health check for Flutter apps.
Flutter ScaleGuard is a deterministic CLI tool that detects architectural risks in Flutter projects before they become expensive to fix.
Instead of focusing on style or formatting, ScaleGuard analyzes structural architecture patterns such as:
- cross-feature coupling
- layer boundary violations
- service locator abuse
- module hotspots
- configuration risks
It helps teams detect architecture erosion early, before it slows development.
Install the CLI:
dart pub global activate scale_guardRun a scan in your Flutter project:
scale_guard scan .Flutter ScaleGuard v0.4.1
Project: ./my_flutter_app
Architecture Score: 69/100
Risk Level: Medium
Summary:
This codebase shows early-stage coupling patterns that may reduce feature isolation as the team scales.
Dominant Risk Category: Coupling Risk (69% of total penalty)
Most Expensive Risk: Feature Module Imports Another Feature (reduces isolation and scaling flexibility) (-15.0)
Hotspot (source): lib/features/user_profile
Hotspot (target): lib/features/dashboard
ScaleGuard can be used to prevent architectural regressions in CI pipelines.
Example:
scale_guard scan . --fail-under 70If the architecture score drops below the threshold, the command exits with a failure code.
This allows teams to enforce architecture quality gates automatically.
Global install via Dart:
dart pub global activate scale_guardOr run directly from the repository:
dart run bin/scale_guard.dart scan .Basic scan:
scale_guard scan .JSON output:
scale_guard scan . --jsonFail if architecture score is too low:
scale_guard scan . --fail-under 70ScaleGuard produces a structured report containing:
Numeric score from 0–100.
Higher score means lower architectural risk.
Risk classification based on score:
| Score | Risk Level |
|---|---|
| 80–100 | Low |
| 55–79 | Medium |
| 0–54 | High |
Identifies the architecture problem contributing most to the score penalty.
The single rule responsible for the largest score reduction.
Files or modules where architectural violations concentrate.
This helps teams focus refactoring effort where it matters most.
| Code | Meaning |
|---|---|
| 0 | Scan completed successfully |
| 1 | Score below --fail-under threshold |
| 64 | Invalid command usage |
ScaleGuard can be configured via a risk_scanner.yaml file in the project root.
Example configuration options:
| Key | Description | Default |
|---|---|---|
| feature_roots | Paths where feature modules are located | lib/features |
| layer_mappings | Mapping of folders to architecture layers | presentation / domain / data |
| ignored_patterns | File patterns to exclude from analysis | generated files |
| god_file_medium_loc | LOC threshold for medium file size risk | 500 |
| god_file_high_loc | LOC threshold for high file size risk | 900 |
ScaleGuard currently detects the following architecture risks:
Feature modules importing other feature modules.
Invalid dependencies between architecture layers.
Example:
presentation → data
Files exceeding defined size thresholds.
Configuration values embedded directly in code.
Global dependency access patterns.
Shared modules importing feature modules.
Direct route usage instead of centralized navigation.
ScaleGuard is intentionally designed to be:
Deterministic
Same code always produces the same result.
Fast
Scans large Flutter projects in seconds.
Opinionated
Focused specifically on architectural scale risks.
CLI-first
Simple tooling that integrates easily into CI pipelines.
ScaleGuard is useful when:
- preparing a Flutter app for scale
- auditing an existing codebase
- reviewing architecture health during development
- preventing architecture decay in CI
- identifying refactoring hotspots
Pavel Koifman
Mobile Strategy & Architecture for Founders
Creator of ScaleGuard – Flutter architecture health check.
- GitHub: https://github.com/PavelK2254
- LinkedIn: https://www.linkedin.com/in/pavel-koifman/
Apache License 2.0.
See the LICENSE file for details.