flutter_simple_architecture 1.1.0

A robust Flutter bootstrapping tool and project template emphasizing a clean, layer-first architecture with strict state management.

FSA (Flutter Simple Architecture)

A robust Flutter bootstrapping tool and project template emphasizing a clean, layer-first architecture with strict state management and a centralized design system.

FSA CLI

The project includes a CLI tool (fsa) to automate project creation and component scaffolding.

Installation

Install from GitLab (Recommended)

To install fsa globally directly from the repository:

fvm dart pub global activate --source git https://gitlab.com/godoytristanh/fsa.git

Install from Local Source

If you have cloned the repository locally:

fvm dart pub global activate --source path .

Note: Make sure your Dart SDK's bin directory is in your system's PATH (usually ~/.pub-cache/bin).

Local Usage

If you prefer not to install it globally, you can run it directly from the root:

fvm dart bin/fsa.dart <command>

Commands

• Create a new project:

  fsa create <project_name> <org_name>
  

  Bootstraps a new Flutter project with the FSA architecture.

  • Clean Template: Removes default counter app boilerplate.
  • Automated Config: Pre-configures hooks_riverpod, freezed, and l10n.
  • Environment Ready: Includes .fvmrc and analysis_options.yaml.
  • Analysis Passing: Generates code that passes flutter analyze immediately.

• Generate a Page:

  fsa generate page <name>
  

  Creates a routeable page with a Scaffold in lib/presentation/<name>/. Includes view.dart, ui_state.dart, and ui_state_notifier.dart.

• Generate a Smart Component:

  fsa generate smart <path/to/name>
  

  Creates a complex component with its own independent state management. Useful for logic-heavy widgets nested within pages.

• Generate a Dumb Component:

  fsa generate dumb <path/to/name>
  

  Creates a single-file StatelessWidget in the widgets/ subfolder of the specified path.

---

Architectural Principles

1. Smart vs. Dumb Components

• Pages/Smart Components: Extend ViewBuilder. They automate state and notifier access and handle side-effects (dialogs, notifications).
• Dumb Components: Simple StatelessWidgets that receive data via constructors. They are purely visual and reside in local widgets/ folders.

2. State Management

• Manual Riverpod Providers: We strictly use NotifierProvider and Provider without code generation for better stability and transparency.
• UI Union States: Every smart component uses a freezed union class (Initial, Loading, Success, Error) to represent its UI state.

3. Error Handling & Side Effects

• Functional Programming: Powered by fpdart. Repositories return Either<Failure, T>.
• The Guard Wrapper: Asynchronous operations are wrapped in a guard() function.
• SideEffect Notifier: Non-interactive events (dialogs, alerts) are managed via a global sideEffectProvider. Notifiers emit SideEffect objects (Success, Failure, Info, Warning), and the ViewBuilder automatically listens and displays the appropriate AppDialog.

---

SideEffect Pattern

To trigger a dialog without passing a BuildContext or using callbacks:

// In your Notifier
void someAction() {
  ref.read(sideEffectProvider.notifier).notify(
    SideEffect.success(title: 'Done', message: 'Action completed!')
  );
}

The ViewBuilder handles this via the onSideEffect hook. By default, it shows an AppDialog, but you can override it in your Page to use SnackBars or other UI:

@override
void onSideEffect(BuildContext context, SideEffect effect) {
  // Custom implementation: use a SnackBar instead of a Dialog
  ScaffoldMessenger.of(context).showSnackBar(
    SnackBar(content: Text(effect.message)),
  );
}

4. Design System

• Sealed Widgets: Base components (AppButton, AppText, AppDialog) use sealed classes and factory constructors to enforce semantic consistency.
• Centralized Theme: All styling is managed in lib/core/theme/ using ThemeExtension.

---

Project Structure

• bin/: CLI entry point.
• lib/core/: Global logic, services (Logger, ErrorHandler), and Design System (Sealed Widgets).
• lib/domain/: Pure business logic, entities, and repository definitions.
• lib/presentation/: UI layers, divided into Pages and nested Smart Components.

---

Getting Started

1. Ensure FVM is installed.
2. Run fvm flutter pub get.
3. Generate boilerplate: fvm flutter pub run build_runner build --delete-conflicting-outputs.
4. Run the app: fvm flutter run.