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 is Max Architecture? #

Max Architecture is simply the name we gave to our most mature internal Flutter architecture after years of building production apps. It combines the patterns, tooling, and project structure that consistently worked well for us and covers the common requirements we need in almost every project, while keeping developers comfortable and productive.

Fun fact: we initially maintained multiple internal architecture variants with color-based names like Amber, Bronze, and Cyan, each evolving with different ideas and features. Over time, they all converged into a single approach that worked best across projects, so we called it Max — not because it's "finished", but because it represented the most complete version of everything we'd learned.

✨ What You Get #

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

📦 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 #

Code Generation #

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 #

🧭 Type-Safe Navigation #

// 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 is configured in sg_cli.yaml at your project root after sg init.

📋 Requirements #

📖 Documentation #

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

🔧 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 #

MIT © 2025 SolGuruz Private Limited — see LICENSE for full text.

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