flutter_archkit 0.2.2

An automated Flutter architecture generator (Clean, MVVM, MVC with Bloc, Cubit, Riverpod, Provider, GetX), feature module generator, and multi-flavor CLI configuration tool.

Flutter ArchKit

The Ultimate Flutter Architecture Generator, Feature Scaffolder, Code Generator & Multi-Flavor CLI Toolkit

---

📖 Overview

flutter_archkit is an enterprise-grade command-line interface (CLI) toolkit and code generator designed to eliminate architectural boilerplate and streamline Flutter app development.

Whether starting a greenfield project or scaling an existing production codebase, flutter_archkit automates:

• 🏗️ Project Scaffolding: Interactive wizard for Clean Architecture, MVVM, or MVC.
• ⚡ Feature Modules: One-command feature generator matching your project's architecture and state management.
• 🧠 @Archkit Code Generation: Automatically writes cascading UseCases, Repositories, DataSources, and API calls from annotated presentation handlers.
• 🛣️ Router Infrastructure: Scaffolds Navigator 1.0/2.0, Go Router (with Bottom Navigation Shells), Auto Route, or GetX Routing.
• 🌐 Network Layer: Scaffolds production Dio HTTP client with generic ApiResponse<T>, custom ApiException, interceptors, and typed contracts.
• 🎯 Multi-Flavor Environments: Configures Android Flavors, iOS Schemes & .xcconfig, Dart ServerConfig, VS Code launch.json, and Android Studio run configurations.

---

📚 Documentation Guides & Topics

Explore dedicated, in-depth documentation guides for each architecture pattern and feature:

Topic / Guide	Description
🏗️ Clean Architecture Guide	Deep dive into Data, Domain, Presentation, & DI layers with BLoC, Cubit, Riverpod, Provider, & GetX.
🎨 MVVM Architecture Guide	Deep dive into Models, Services, ViewModels, Views, and reactive state management integration.
🏛️ MVC Architecture Guide	Deep dive into Models, Controllers, Views, and lightweight action dispatching.
🧠 @Archkit Code Generator Guide	Complete guide on annotating presentation handlers and cascading methods across domain/data layers.
🛣️ Route Systems Guide	Comprehensive setup for Go Router (with Bottom Nav Shell), Auto Route, GetX Routing, Navigator 1.0/2.0.
🌐 Production Network Layer Guide	Detailed guide for Dio HTTP client, ApiResponse<T>, ApiException, and interceptors.
🎯 Multi-Flavor Setup Guide	Complete guide for archkit flavor, flavor.yaml, Android Gradle, iOS Xcode schemes, & IDE run targets.

---

📑 Table of Contents

• Documentation Guides & Topics
• Features & Architecture Matrix
• CLI Command Cheat Sheet
• Installation
• Usage Guide
  • 1. Creating a Project (archkit create)
  • 2. Scaffolding Feature Modules (archkit feature)
  • 3. Setting Up Route Systems (archkit route)
  • 4. Generating Network Layer (archkit network)
  • 5. @Archkit Code Generation (archkit generate)
  • 6. Multi-Flavor Configuration (archkit flavor)
  • 7. App & Package Renamer (archkit rename)
• Directory Structures
• Example Application
• Contributing & Issues
• License

---

🧩 Features & Architecture Matrix

Capability	Supported Technologies & Options
Architectures	Clean Architecture (Data / Domain / Presentation / DI), MVVM (Models / Services / ViewModels / Views), MVC (Models / Controllers / Views)
State Management	BLoC, Cubit, Riverpod, Provider, GetX
Routing Systems	Navigator 1.0, Navigator 2.0, Go Router (with StatefulShellRoute bottom navigation support), Auto Route, GetX Routing
Networking	Dio 5.x, Generic ApiResponse<T>, ApiException, Logging Interceptor, Auth Interceptors, ApiInterface contract
Code Generation	@Archkit annotation parser: Cascading generation of UseCases, Repositories, Remote DataSources, and Service interfaces
Multi-Flavor	Android (flavor.gradle.kts), iOS (XCConfig, Schemes, project.pbxproj), Dart (ServerConfig), IDE Run Configs (VS Code & Android Studio)
App & Package Renamer	All 6 Platforms: Android, iOS, Web, macOS, Windows, Linux + automated conversion to flavor.yaml
Configuration	Smart .metadata tracking: Auto-detects project architecture without passing repetitive flags

---

⚡ CLI Command Cheat Sheet

Command	Aliases	Description	Example
archkit create <app_name>	-c, --create	Creates a new Flutter app with chosen architecture & state management	archkit create my_app -a Clean -s Bloc
archkit feature <name>	-f, --feature	Scaffolds a new feature module matching project architecture	archkit feature auth or archkit -f profile
archkit route	-r, --route	Scaffolds routing system & installs router dependencies	archkit route -t "Go Router" --shell
archkit network	-n, --network	Scaffolds production Dio HTTP network layer	archkit network --override
archkit generate	g, gen, -g	Generates domain & data layer methods for @Archkit annotations	archkit g -p lib/features/auth
archkit flavor	-fl, --flavor	Configures multi-flavor environments (Android, iOS, Dart, IDEs)	archkit flavor --init or archkit -fl
archkit rename	-rn, --rename	Renames app name and package/bundle ID across all 6 platforms	archkit rename --init or archkit rename

---

📦 Installation

Global Activation (Recommended)

Activate flutter_archkit globally to use the archkit CLI from anywhere in your terminal:

dart pub global activate flutter_archkit

Note: Ensure your global pub cache bin path is added to your system's PATH environment variable.

As a Project Dependency

Add flutter_archkit to your Flutter project's pubspec.yaml under dev_dependencies to utilize the @Archkit annotation and flavor generators:

dev_dependencies:
  flutter_archkit: ^0.2.1

Then run:

flutter pub get

---

🚀 Usage Guide

1. Creating a Project (archkit create)

Scaffold a complete, production-ready Flutter application with interactive terminal prompts:

archkit create my_app

? Select Architecture:
  ❯ Clean Architecture (Data, Domain, Presentation, DI)
    MVVM Architecture (Models, Services, ViewModels, Views)
    MVC Architecture (Models, Controllers, Views)

? Select State Management:
  ❯ Bloc
    Cubit
    Riverpod
    Provider
    GetX

? Organization Identifier: com.example
? Target Platforms: android, ios, web

Non-Interactive CLI Mode

Automate CI/CD or scripted project generation using command-line flags:

archkit create my_app \
  --org com.example \
  --architecture Clean \
  --state-management Bloc \
  --platforms android,ios,web

---

2. Scaffolding Feature Modules (archkit feature)

Generate modular, architecture-compliant feature packages in seconds. archkit automatically detects your project's architecture and state management from .metadata!

# Full command
archkit feature auth

# Or quick shortcut
archkit -f user_profile

Clean Architecture Feature Output (lib/features/auth/):

• domain/entities/auth_entity.dart
• domain/repositories/auth_repository.dart
• domain/usecases/auth_usecase.dart
• data/models/auth_model.dart
• data/data_sources/auth_remote_datasource.dart & _impl.dart
• data/repositories/auth_repository_impl.dart
• presentation/bloc/auth_bloc.dart, auth_event.dart, auth_state.dart
• presentation/page/auth_page.dart
• di/auth_di.dart

---

3. Setting Up Route Systems (archkit route)

Set up a robust navigation infrastructure tailored to your preferred routing engine:

archkit route
# Or alias
archkit r

Supported Route Engines:

1. Navigator 1.0: Traditional named routes with RouteGenerator and MaterialPageRoute.
2. Navigator 2.0: Declarative routing with custom RouterDelegate and RouteInformationParser.
3. Go Router: URL-driven routing supporting deep links, route redirection, and optional StatefulShellRoute bottom navigation.
4. Auto Route: Type-safe code-generated navigation.
5. GetX Routing: Lightweight GetPage navigation.

---

4. Generating Network Layer (archkit network)

Scaffold a battle-tested Dio network client architecture in lib/core/network/ and lib/core/util/:

archkit network
# Or alias
archkit n

---

5. Smart @Archkit Code Generation (archkit generate)

Speed up development exponentially by designing your UI/Presentation layer first and generating all corresponding domain and data layer classes with a single command.

Step 1: Annotate your Presentation Method

Import package:flutter_archkit/flutter_archkit.dart and annotate event handlers or functions in your BLoC, Cubit, Riverpod Notifier, ViewModel, or Controller:

import 'package:flutter_archkit/flutter_archkit.dart';
import '../models/weather_model.dart';

class WeatherBloc extends Bloc<WeatherEvent, WeatherState> {
  WeatherBloc() : super(WeatherInitial()) {
    on<FetchWeatherEvent>(_onFetchWeather);
  }

  @Archkit(
    endpoint: '/weather',
    method: 'GET',
    returnType: WeatherModel,
  )
  Future<void> _onFetchWeather(
    FetchWeatherEvent event,
    Emitter<WeatherState> emit, {
    required String city,
    String? units,
  }) async {
    // Business logic...
  }
}

Step 2: Run Code Generator

# Run code generation on target feature
archkit generate --path lib/features/weather

# Or use shortcuts
archkit g -p lib/features/weather

# Preview changes without modifying files
archkit g -p lib/features/weather --dry-run

---

6. Multi-Flavor Configuration (archkit flavor)

Easily configure enterprise-grade multi-environment setups (e.g. dev, staging, prod) for both Android and iOS in seconds.

# Initialize flavor.yaml template
archkit flavor --init

# Validate syntax
archkit flavor --validate

# Generate Android, iOS, Dart, and IDE flavor files
archkit flavor

---

7. App & Package Renamer (archkit rename)

Quickly change the application display name and package / bundle identifier across all Flutter platforms (Android, iOS, Web, macOS, Windows, Linux), or convert your rename settings into a multi-flavor flavor.yaml setup.

Step 1: Initialize rename.yaml

# Global CLI command
archkit rename --init

# Or shortcut
archkit -rn --init

# Or via Dart run
dart run flutter_archkit:rename --init

This creates a sample rename.yaml at your project root:

# flutter_archkit App & Package Rename Configuration
app_name: "My Awesome App"
package_name: "com.example.my_awesome_app"

# Optional: Platform-specific overrides
# android:
#   app_name: "My Awesome App Android"
#   package_name: "com.example.my_awesome_app"
# ios:
#   app_name: "My Awesome App iOS"
#   bundle_id: "com.example.my_awesome_app"
# web:
#   app_name: "My Awesome App Web"
#   description: "My Awesome App Web Application"
# macos:
#   app_name: "My Awesome App macOS"
#   bundle_id: "com.example.my_awesome_app"
# windows:
#   app_name: "My Awesome App Windows"
# linux:
#   app_name: "My Awesome App Linux"
#   package_name: "com.example.my_awesome_app"

Step 2: Apply the Rename Across All Platforms

archkit rename

# Or via Dart run
dart run flutter_archkit:rename

This automatically modifies:

• Android: android/app/build.gradle.kts / build.gradle (applicationId & namespace), AndroidManifest.xml (package & android:label), strings.xml, MainActivity.kt / MainActivity.java package declaration, and moves the file to the new directory structure.
• iOS: ios/Runner/Info.plist (CFBundleDisplayName, CFBundleName) and ios/Runner.xcodeproj/project.pbxproj (PRODUCT_BUNDLE_IDENTIFIER).
• Web: web/index.html (<title> & <meta name="apple-mobile-web-app-title">) and web/manifest.json.
• macOS: macos/Runner/Configs/AppInfo.xcconfig (PRODUCT_NAME & PRODUCT_BUNDLE_IDENTIFIER), Info.plist, and project.pbxproj.
• Windows: windows/runner/Runner.rc (FileDescription, InternalName, ProductName) and windows/runner/main.cpp.
• Linux: linux/my_application.cc (gtk_header_bar_set_title, gtk_window_set_title) and linux/CMakeLists.txt (APPLICATION_ID).

Step 3: Transition to Multi-Flavor Environments (archkit flavor --init)

If you decide to enable multi-flavor environments later, simply run:

archkit flavor --init
# Or via Dart run
dart run flutter_archkit:setup_flavor --init

flutter_archkit will automatically detect your existing rename.yaml (or rename.yml), generate a flavor.yaml pre-configured with dev and prod environments matching your desired app and package names, and automatically remove rename.yaml.

From then on, flavor.yaml is your single source of truth for all app names, bundle IDs, and multi-environment configurations!

---

📁 Directory Structures

• 🏗️ Clean Architecture Details: doc/clean_architecture.md
• 🎨 MVVM Architecture Details: doc/mvvm_architecture.md
• 🏛️ MVC Architecture Details: doc/mvc_architecture.md

---

🌟 Example Application

A full reference application demonstrating Clean Architecture, MVVM, MVC, Network Layer, Routing, and Flavor configurations is available in the example/ directory.

To run the example app:

cd example
flutter pub get
flutter run

---

🤝 Contributing & Issues

Contributions, feature suggestions, and bug reports are welcome!

• 🐛 Report Issues: GitHub Issue Tracker
• 💡 Source Code: GitHub Repository

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.