SG CLI

Flutter Architecture Generator by SolGuruz

Scaffold production-ready Flutter apps in seconds — BLoC, type-safe navigation, state handlers, and 48+ widgets, all wired up from a single command.

✨ What You Get

One sg init sets up the entire Max Architecture — the same foundation used in SolGuruz production apps:

	Feature	Details
🧱	BLoC State Management	Typed base classes, events, 5 ready-to-use state handlers
🧭	Type-Safe Navigation	`Go` class, route configs, typed arguments — zero magic strings
⚡	ViewState Widgets	Auto-handles loading / error / empty / data — no boilerplate
🎨	Design System	AppColors (light + dark), AppTextStyles, 48+ production widgets
⚙️	Code Generators	Screens, bottom sheets, dialogs, events — routes wired automatically
🚀	Flavor & Deep Link Setup	Dev / stage / prod in one command

📦 Installation

dart pub global activate sg_cli

Add the pub cache bin to your PATH (one-time setup):

export PATH="$PATH":"$HOME/.pub-cache/bin"

Verify:

sg help

⚡ Quick Start

# 1. Go to your Flutter project root
cd my_flutter_app

# 2. Scaffold the entire Max architecture
sg init

# 3. Generate screens, bottom sheets, dialogs
sg create screen login
sg create screen home
sg create bs select_language
sg create dialog confirm_action

# 4. Add BLoC events
sg create event submit_login in login

Routes, BLoC files, state classes, and widget folders — all generated and wired automatically.

🛠 Commands

Project Setup

Command	What it does
`sg init`	Scaffold the complete Max architecture into your Flutter project
`sg setup_flavors`	Add dev / stage / prod flavors for Android & iOS
`sg setup_deeplink`	Configure per-flavor deep links (Android manifests + iOS entitlements)
`sg setup_firebase`	Automated Firebase setup via FlutterFire CLI
`sg setup_firebase_manual`	Generate Firebase placeholder configs

Code Generation

Command	What it does
`sg create screen <name>`	Screen + BLoC (event, state) + route auto-registered
`sg create sub_screen <name> in <parent>`	Sub-screen nested under a parent route
`sg create bs <name>`	Bottom sheet + BLoC + route auto-registered
`sg create dialog <name>`	Dialog + BLoC + route auto-registered
`sg create event <name> in <page>`	Add a BLoC event + handler to an existing screen / bs / dialog

All names must be snake_case. All generated code follows Max Architecture conventions.

📁 What Gets Generated

`sg create screen profile`

lib/presentation/screens/profile/
├── logic/
│   ├── profile_bloc.dart      ← BaseBloc with eventListeners()
│   ├── profile_event.dart     ← Abstract event extends BaseEvent
│   └── profile_state.dart     ← Immutable state with copyWith
└── view/
    ├── profile_screen.dart    ← StatefulWidget, BLoC via context extension
    └── widgets/               ← Screen-specific widget files

Auto-updated:

app/app_routes/screen_routes.dart
app/app_routes/_route_names.dart

`sg create event load_profile in profile`

class LoadProfile extends ProfileEvent {
  const LoadProfile();

  @override
  Map<String, dynamic> getAnalyticParameters() => {};

  @override
  List<Object?> get props => [];
}

Handler stub registered in profile_bloc.dart automatically.

🏗 Architecture Highlights

// Navigate with typed arguments
Go.to(ProfileRoute(
  arguments: ProfileArguments(userId: '42', userName: 'John'),
));

// Open a bottom sheet and await its result
final result = await Go.openBottomSheet<bool, SelectLanguageArguments>(
  const SelectLanguageRoute(),
  showDragHandle: true,
);

// Clear stack and go to login
Go.replaceAllTo(const LoginRoute());

⚡ State Handlers + ViewState Widgets

Five handlers cover every data-loading pattern. Pair with the matching widget — loading, error, empty, and data are handled automatically:

// BLoC — one handler replaces all manual emit() calls
late final scriptsHandler = PaginatedListHandler<ScriptModel>(
  bloc: this,
  getViewState: () => state.scripts,
  updateViewState: (s) => emit(state.copyWith(scripts: s)),
  loadMoreEvent: () => const ScriptsLoadMore(),
  repositoryCall: () => ScriptRepository.getScripts(
    page: state.scripts.paginationData?.nextPage,
    search: state.scripts.searchController?.text,
  ),
);

// Screen — auto loading / empty / error / paginate
SliverListStateWidget<ScriptsBloc, ScriptsState, ScriptModel>(
  listStateSelector: (s) => s.scripts,
  onLoadMore: (_) => bloc.add(const ScriptsLoadMore()),
  padding: const EdgeInsets.symmetric(horizontal: kHorizontalPadding),
  itemBuilder: (context, script, index) => ScriptCard(script: script),
)

🧱 BLoC Pattern

class LoginBloc extends BaseBloc<LoginEvent, LoginState> {
  LoginBloc() : super(LoginState.initial());

  final emailCtrl = TextFieldController();
  final submitCtrl = AppButtonController();

  @override
  void eventListeners() {
    on<SubmitLogin>(_onSubmitLogin);
  }

  Future<void> _onSubmitLogin(SubmitLogin event, Emitter<LoginState> emit) async {
    submitCtrl.startLoading();
    final response = await AuthRepository.loginWithEmail(email: emailCtrl.text);
    submitCtrl.stopLoading();
    if (response.isSuccess) Go.replaceAllTo(const HomeRoute());
  }

  @override
  Future<void> close() {
    emailCtrl.dispose();
    submitCtrl.dispose();
    return super.close();
  }
}

🏷 Architecture Versions

Version	Best For	Includes
Max ⭐	Full production apps	All commands — `init`, `create`, `setup_*`
Bronze	Apps with custom routing	`create screen / bs / dialog / event`
Amber	Role-based basic structure	`create page / bs / event`

Version is configured in sg_cli.yaml at your project root after sg init.

📋 Requirements

	Minimum
Dart SDK	`^3.11.0`
Flutter SDK	`^3.41.1`
Firebase CLI	Only needed for `setup_firebase`
FlutterFire CLI	Only needed for `setup_firebase`

📖 Documentation

Full architecture docs, tutorials, and API reference at sgcli.solguruz.com

Topic	What's covered
Architecture Overview	Folder structure, 3-layer design, data flow
State Handlers	All 5 handlers — BasicData, PaginatedList, FullList, and more
Navigation	Type-safe routing, route arguments, nested navigation
Widget Library	48+ widgets — AppButton, OTP, TextFields, ImagePicker, tabs
Theming	AppColors (light/dark), AppTextStyles, design system
Forms & Validation	Controllers, validators, input formatters
Networking	ApiClient, repositories, response pipeline
Reactor	Cross-BLoC reactive sync without boilerplate
Local Storage	PrefManager, type-safe persistence
Environments	Dev / stage / prod config, flavors, deep links

🔧 Troubleshooting

sg command not found

export PATH="$PATH":"$HOME/.pub-cache/bin"
# Persist: add the above line to ~/.zshrc or ~/.bashrc

Template errors after sg init

The boilerplate is bundled inside the package. Re-activating fixes most path issues:

dart pub global activate sg_cli

setup_firebase fails

npm install -g firebase-tools
dart pub global activate flutterfire_cli
firebase login

🏢 About SolGuruz

Engineering quality mobile and web solutions — with passion.

📄 License

Made with ❤️ by SolGuruz · sgcli.solguruz.com