🏗️ Flutter Architecture Generator

A powerful, production-ready CLI tool to instantly scaffold professional Flutter applications with your choice of architecture — Clean Architecture, MVVM, BLoC, GetX, or Provider.

Stop wasting hours on boilerplate. Generate a complete, scalable project architecture in seconds — with dependency injection, networking, routing, state management, theming, and tests all wired up and ready to go.

✨ Why This Tool?

📋 Table of Contents

• Supported Features
• Package Versions
• Installation
• Quick Start
• Commands Reference
• Generated Structure
• Generated Code Examples
• How Auto-Wiring Works
• Configuration Persistence
• Post-Generation Steps
• FAQ
• Contributing
• License

🎯 Supported Features

Architectures

State Management

Routing

Networking & Data

Additional Features

📦 Package Versions (Latest)

All generated dependencies use the latest stable versions from pub.dev:

🚀 Installation

Global Activation (Recommended)

dart pub global activate flutter_architecture_generator

This adds the flutter_arch_gen command to your PATH.

Verify Installation

flutter_arch_gen --help

⚡ Quick Start

1. Create a Flutter project

flutter create my_awesome_app
cd my_awesome_app

2. Initialize the architecture

flutter_arch_gen init

You'll be prompted to choose:

? Select architecture: (Use arrow keys)
❯ Clean Architecture (Feature-First)
  MVVM
  BLoC Architecture
  GetX Architecture
  Provider / Simple Architecture

? Select state management: (Use arrow keys)
❯ bloc
  riverpod
  provider
  getx

? Select routing:
❯ goRouter
  autoRoute
  navigator

? Enable localization? (Y/n)
? Enable Firebase? (y/N)
? Enable tests? (Y/n)

3. Install dependencies & generate code

flutter pub get
dart run build_runner build --delete-conflicting-outputs

4. Run your app

flutter run

That's it! You now have a complete Clean Architecture project with DI, routing, theming, networking, and an example auth feature — all production-ready.

📖 Commands Reference

flutter_arch_gen init

Initializes the complete project architecture with interactive prompts.

flutter_arch_gen init

What it generates:

• Directory structure (core/, features/, routes/, di/)
• main.dart with initialization pipeline
• app.dart with MaterialApp.router configuration
• injection_container.dart with GetIt setup
• api_client.dart with Dio configuration
• app_theme.dart with Material 3 light/dark themes
• app_router.dart with routing configuration
• failures.dart with error hierarchy
• .env.dev / .env.prod environment files
• .gitignore with security exclusions
• Example auth feature with Login & Register pages
• Localization files (if enabled)
• Test scaffolding (if enabled)

flutter_arch_gen feature <name>

Generates a complete Clean Architecture feature module.

# Basic usage
flutter_arch_gen feature products

# With positional arg
flutter_arch_gen feature user_profile

# PascalCase input is auto-normalized
flutter_arch_gen feature UserProfile  # → features/user_profile/

What it generates:

features/user_profile/
├── data/
│   ├── datasources/user_profile_remote_datasource.dart
│   ├── models/user_profile_model.dart
│   └── repositories/user_profile_repository_impl.dart
├── domain/
│   ├── entities/user_profile_entity.dart
│   ├── repositories/user_profile_repository.dart
│   └── usecases/get_user_profile_usecase.dart
└── presentation/
    ├── bloc/             # (or riverpod/ or provider/ or getx/)
    │   ├── user_profile_bloc.dart
    │   ├── user_profile_event.dart
    │   └── user_profile_state.dart
    ├── pages/user_profile_page.dart
    └── widgets/

Auto-wiring:

• ✅ Registers DataSource, Repository, UseCase, and Bloc in injection_container.dart
• ✅ Adds route + import to app_router.dart (GoRouter or AutoRoute)
• ✅ Generates repository test in test/features/user_profile/

features/user_profile/
├── models/user_profile_model.dart
├── services/user_profile_service.dart
├── view_models/user_profile_view_model.dart
└── views/
    ├── pages/user_profile_page.dart
    └── widgets/

features/user_profile/
├── bloc/
│   ├── user_profile_bloc.dart
│   ├── user_profile_event.dart
│   └── user_profile_state.dart
├── models/user_profile_model.dart
├── repositories/user_profile_repository.dart
├── pages/user_profile_page.dart
└── widgets/

features/user_profile/
├── bindings/user_profile_binding.dart
├── controllers/user_profile_controller.dart
├── models/user_profile_model.dart
└── views/
    ├── pages/user_profile_page.dart
    └── widgets/

features/user_profile/
├── models/user_profile_model.dart
├── providers/user_profile_provider.dart
├── pages/user_profile_page.dart
└── widgets/

flutter_arch_gen model <name> [-f feature]

Generates a Freezed model with JSON serialization.

# Inside a feature
flutter_arch_gen model Product -f shop

# Standalone (in lib/core/models/)
flutter_arch_gen model AppUser

Generated code:

import 'package:freezed_annotation/freezed_annotation.dart';

part 'product.freezed.dart';
part 'product.g.dart';

@freezed
class Product with _$Product {
  const factory Product({
    required int id,
  }) = _Product;

  factory Product.fromJson(Map<String, dynamic> json) => _$ProductFromJson(json);
}

flutter_arch_gen page <name> [-f feature]

Generates a new page with optional router auto-registration.

# Inside a feature
flutter_arch_gen page Settings -f settings

# Standalone page
flutter_arch_gen page About

Auto-wiring:

• ✅ GoRouter: Adds GoRoute with path and import to app_router.dart
• ✅ AutoRoute: Adds @RoutePage() annotation and AutoRoute(page: ...) entry

📂 Generated Structure

lib/
├── main.dart                          # App entry point with initialization
├── app.dart                           # MaterialApp with theme & routing
├── core/
│   ├── constants/
│   │   └── app_constants.dart         # Global constants
│   ├── errors/
│   │   └── failures.dart              # Failure hierarchy (Server, Cache, General)
│   ├── network/
│   │   └── api_client.dart            # Dio HTTP client with interceptors
│   ├── services/                      # Shared services
│   ├── theme/
│   │   └── app_theme.dart             # Material 3 light + dark themes
│   └── utils/                         # Shared utilities
├── di/
│   └── injection_container.dart       # GetIt DI setup (auto-updated)
├── features/
│   └── auth/                          # Example auth feature
│       ├── data/
│       │   ├── datasources/
│       │   ├── models/
│       │   └── repositories/
│       ├── domain/
│       │   ├── entities/
│       │   ├── repositories/
│       │   └── usecases/
│       └── presentation/
│           ├── bloc/                  # State management (BLoC/Riverpod/etc.)
│           ├── pages/                 # Login & Register pages
│           └── widgets/
├── routes/
│   └── app_router.dart                # GoRouter or AutoRoute config
├── .env.dev                           # Dev environment variables
├── .env.prod                          # Prod environment variables
├── .gitignore                         # Security exclusions
└── .flutter_arch_gen.json             # Persisted project config

test/
├── features/
│   └── auth/
│       └── auth_repository_test.dart  # Auto-generated repository test
├── unit/
│   └── sample_test.dart
├── widget/
└── integration/

💡 Generated Code Examples

main.dart

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_dotenv/flutter_dotenv.dart';
import 'package:my_app/app.dart';
import 'package:my_app/di/injection_container.dart' as di;

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await SystemChrome.setPreferredOrientations([
    DeviceOrientation.portraitUp,
    DeviceOrientation.portraitDown,
  ]);

  await dotenv.load(fileName: ".env.dev");
  await di.init();
  
  runApp(const MyApp());
}

injection_container.dart (after generating features)

import 'package:get_it/get_it.dart';
import 'package:dio/dio.dart';
import 'package:my_app/core/network/api_client.dart';

final sl = GetIt.instance;

Future<void> init() async {
  // External
  sl.registerLazySingleton(() => Dio());

  // Core
  sl.registerLazySingleton(() => ApiClient(sl()));

  // Features
  // Auth Feature
  sl.registerLazySingleton<IAuthRemoteDataSource>(() => AuthRemoteDataSourceImpl(sl()));
  sl.registerLazySingleton<IAuthRepository>(() => AuthRepositoryImpl(sl()));
  sl.registerLazySingleton(() => GetAuthUseCase(sl()));
  sl.registerFactory(() => AuthBloc(getAuthUseCase: sl()));
}

BLoC (auto-generated)

import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:equatable/equatable.dart';
import 'package:my_app/features/auth/domain/usecases/get_auth_usecase.dart';

part 'auth_event.dart';
part 'auth_state.dart';

class AuthBloc extends Bloc<AuthEvent, AuthState> {
  final GetAuthUseCase getAuthUseCase;

  AuthBloc({required this.getAuthUseCase}) : super(AuthInitial()) {
    on<GetAuthDataEvent>((event, emit) async {
      emit(AuthLoading());
      try {
        final data = await getAuthUseCase();
        emit(AuthLoaded(data: data.id.toString()));
      } catch (e) {
        emit(AuthError(message: e.toString()));
      }
    });
  }
}

🔗 How Auto-Wiring Works

When you run flutter_arch_gen feature <name>, three things happen automatically:

1. DI Registration

New imports and registrations are injected into injection_container.dart:

// Imports added at top
import 'package:my_app/features/products/data/datasources/products_remote_datasource.dart';
import 'package:my_app/features/products/data/repositories/products_repository_impl.dart';
// ...

// Registrations added under "// Features"
sl.registerLazySingleton<IProductsRemoteDataSource>(() => ProductsRemoteDataSourceImpl(sl()));
sl.registerLazySingleton<IProductsRepository>(() => ProductsRepositoryImpl(sl()));
sl.registerLazySingleton(() => GetProductsUseCase(sl()));
sl.registerFactory(() => ProductsBloc(getProductsUseCase: sl()));

2. Router Registration

GoRouter:

// Import added
import 'package:my_app/features/products/presentation/pages/products_page.dart';

// Route added
GoRoute(
  path: '/products',
  builder: (context, state) => const ProductsPage(),
),

AutoRoute:

// Import added
import 'package:my_app/features/products/presentation/pages/products_page.dart';

// Route added
AutoRoute(page: ProductsRoute.page),

3. Test Generation

A repository test is created at test/features/products/products_repository_test.dart with a mock data source.

💾 Configuration Persistence

After running init, your choices are saved in .flutter_arch_gen.json:

{
  "architecture": "clean",
  "stateManagement": "bloc",
  "routing": "goRouter",
  "localization": true,
  "firebase": false,
  "tests": true
}

All subsequent commands (feature, model, page) automatically read this config — no need to pass flags for state management or routing every time.

🔧 Post-Generation Steps

After running flutter_arch_gen init:

# 1. Install all dependencies
flutter pub get

# 2. Generate Freezed models and AutoRoute (if applicable)
dart run build_runner build --delete-conflicting-outputs

# 3. Configure your API base URL
# Edit .env.dev and .env.prod with your actual endpoints

# 4. Run your app
flutter run

❓ FAQ

Q: Can I use this on an existing project?

A: Yes! Run flutter_arch_gen init in your existing Flutter project root. It will add files alongside your existing code. Existing files with the same names will be overwritten, so commit first.

Q: Does it modify my existing pubspec.yaml?

A: Yes, it adds the required dependencies under dependencies and dev_dependencies. Existing dependencies are not overwritten — only new ones are added.

Q: Can I generate features with different state management?

A: The tool uses the state management from your saved config (.flutter_arch_gen.json). To change it, re-run flutter_arch_gen init or manually edit the config file.

Q: Does it support Cubit?

A: Currently, BLoC with Bloc (event-driven) is generated. You can easily convert the generated Bloc to a Cubit since both come from flutter_bloc.

Q: What naming convention is used?

A: All file names and directory names use snake_case. Class names use PascalCase. Variable names use camelCase. Input like UserProfile or user_profile both work correctly.

Q: Does it work on Windows?

A: Yes! All path handling uses cross-platform normalization to ensure correct imports on Windows, macOS, and Linux.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

Made with ❤️ for the Flutter community