🏗️ Arch-CLI - Flutter Enterprise Architecture Generator

A powerful Node.js CLI tool that scaffolds Flutter project structures for different architectural patterns and state management solutions.

✨ Features

• 🎯 3 Architecture Patterns: MVVM, Clean Architecture, MVC
• 🔄 4 State Management Solutions: Bloc, GetX, Provider, Riverpod
• ⚡ One Command Setup: Generate complete feature scaffolds in seconds
• 📁 Intelligent Folder Structure: Proper separation of concerns for enterprise apps
• 🧪 Comprehensive Test Suite: Validate all 12 combinations with automated testing

🚀 Quick Start

Installation

npm install

Setup Your Architecture

node bin/index.js setup

This will prompt you to choose:

1. Architecture Pattern: MVVM, Clean Architecture, or MVC
2. State Management: Bloc, GetX, Provider, or Riverpod

Generate a Feature

node bin/index.js create my_feature

Creates a complete feature scaffold based on your configuration.

View Configuration

node bin/index.js info

Shows your current architecture and state management setup.

📊 Supported Combinations

| Architecture | Bloc | GetX | Provider | Riverpod | |---|---|---|---|---| | MVVM | ✅ | ✅ | ✅ | ✅ | | Clean Architecture | ✅ | ✅ | ✅ | ✅ | | MVC | ✅ | ✅ | ✅ | ✅ |

🧪 Testing

Run Comprehensive Test Suite

node test-runner.js

This runs 12 automated tests covering all architecture + state management combinations:

• ✅ Creates feature scaffolds
• ✅ Verifies folder structures
• ✅ Validates file generation
• ✅ Provides pass/fail summary

Expected output:

✅ PASSED: 12/12
❌ FAILED: 0/12

🎉 All tests passed! Your arch-cli is bug-free!

See TEST_RUNNER_README.md for detailed test documentation.

📁 Generated Folder Structures

MVVM Example (with Bloc)

lib/features/my_feature/
├── models/
│   └── my_feature_model.dart
├── repositories/
│   └── my_feature_repository.dart
├── bloc/
│   ├── my_feature_bloc.dart
│   ├── my_feature_event.dart
│   └── my_feature_state.dart
└── views/
    └── my_feature_page.dart

Clean Architecture Example (with Provider)

lib/features/my_feature/
├── data/
│   ├── models/
│   ├── datasources/
│   └── repositories/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── usecases/
└── presentation/
    ├── providers/
    └── pages/

MVC Example (with GetX)

lib/features/my_feature/
├── models/
│   └── my_feature_model.dart
├── views/
│   ├── widgets/
│   └── my_feature_page.dart
└── controllers/
    └── my_feature_controller.dart

📝 Usage Examples

Create MVVM Feature with Bloc

# Setup
node bin/index.js setup
# Choose: MVVM + Bloc

# Create feature
node bin/index.js create auth

# View config
node bin/index.js info

Create Clean Architecture Feature with Provider

# Update config directly (or use setup)
echo '{"architecture":"clean","stateManagement":"provider"}' > .arch_config.json

# Create feature
node bin/index.js create user_profile

🔗 Commands

setup

Initialize architecture configuration interactively.

node bin/index.js setup

create <feature_name>

Generate a new feature scaffold.

node bin/index.js create dashboard

The feature name is automatically converted:

• Input: my-feature, my_feature, myFeature
• Folder: lib/features/my_feature/
• Class: MyFeature

info

Display current project configuration.

node bin/index.js info

📦 Dependencies

{
  "chalk": "^5.6.2",          // Colored terminal output
  "commander": "^14.0.3",     // CLI command parsing
  "fs-extra": "^11.3.3",      // File operations
  "inquirer": "^13.3.0"       // Interactive prompts
}

🏗️ Project Structure

arch-cli/
├── bin/
│   └── index.js              # Main CLI entry point
├── templates/
│   └── flutter/
│       ├── clean.js          # Clean Architecture templates
│       ├── mvvm.js           # MVVM templates
│       └── mvc.js            # MVC templates
├── test-runner.js            # Comprehensive test suite
├── package.json
└── .arch_config.json         # User configuration (generated)

🎯 Architecture Details

MVVM (Model-View-ViewModel)

Best for: Medium to large apps with clear UI logic separation.

• Models: Data structures
• Repositories: Data access layer
• ViewModels: Business logic (GetX/Provider/Riverpod) or Bloc (for Bloc state management)
• Views: UI pages and widgets

Clean Architecture

Best for: Large enterprise apps with strict separation of concerns.

• Data Layer: Models, datasources, repository implementations
• Domain Layer: Entities, repository contracts, usecases
• Presentation Layer: UI components, state management, controllers/blocs

MVC (Model-View-Controller)

Best for: Simple to medium apps with traditional separation.

• Models: Data structures
• Views: UI pages and widgets
• Controllers: Business logic

🔄 State Management Descriptions

• Bloc: Powerful, event-driven, great for complex state
• GetX: Lightweight, reactive, easy to use
• Provider: Simple, flutter-first approach
• Riverpod: Modern, composable, type-safe

📋 Configuration

The tool stores configuration in .arch_config.json:

{
  "architecture": "mvvm",
  "stateManagement": "bloc"
}

Valid values:

• architecture: "mvvm", "clean", "mvc"
• stateManagement: "bloc", "getx", "provider", "riverpod"

✅ Verification

Verify Installation

node bin/index.js --version

Verify Command Works

node bin/index.js setup

Run Full Test Suite

node test-runner.js

🐛 Troubleshooting

Issue: "No configuration found! Run 'arch setup' first."

Solution: Run node bin/index.js setup to create configuration.

Issue: "Feature already exists!"

Solution: Delete the existing feature folder or use a different feature name.

Issue: Permission errors on macOS

Solution: Use sudo if needed, or check folder permissions.

🤝 Contributing

To extend the tool:

1. Add new architecture: Update templates/flutter/new_arch.js and bin/index.js
2. Add new state manager: Update template files to handle new state management approach
3. Improve templates: Modify files in templates/flutter/
4. Fix bugs: Run node test-runner.js to verify changes

📜 License

ISC

📞 Support

For issues or questions, refer to:

• TEST_RUNNER_README.md - Detailed testing guide
• Check generated .arch_config.json for configuration
• Verify template files in templates/flutter/

Made with ❤️ for Flutter developers

All 12 combinations tested and verified ✅