🧩 BLoC Architecture Guide

Guide lengkap untuk implementasi BLoC (Business Logic Component) pattern di MStore Mobile dengan proper scope dan lifecycle management.

📌 Prinsip Dasar

Siapa yang Memiliki State?

BLoC bukan sekadar “controller” — dia pemilik state dan event lifecycle.Pertanyaannya bukan “di mana paling mudah”, tapi siapa yang bertanggung jawab mengelola durasi hidup state itu.

⚙️ Hierarki UI dan Scope yang Tepat

Tabel Scope BLoC

Level	Contoh	Cocok untuk BLoC?	Alasan
App (root)	`main.dart`	✅ Ya, tapi hanya global state	Auth, UserSession, Theme
Route / Feature	`/sales`, `/inventory`	✅ IDEAL	BLoC punya domain boundary jelas
Page / Scaffold	`SalesListPage`	⚠️ Bisa, jika state hanya untuk page itu	Hanya 1 page concern
Component / Widget	`SalesCardWidget`	❌ TIDAK	BLoC akan hidup-mati tiap rebuild

🧩 Best Practice BLoC Scope per Domain

Global / Persistent

Scope: Root (di MaterialApp)Contoh:

AuthBloc
SettingsBloc
ThemeBloc

Feature-based

Scope: RouteContoh:

SalesBloc
InventoryBloc
HRBloc

Ephemeral UI

Scope: Page / Widget StateContoh:

FilterCubit
TabIndexCubit
DialogCubit

Gunakan Cubit untuk state lokal kecil, bukan Bloc penuh.“Gunakan BLoC untuk domain state, Cubit untuk UI state.”

🧠 Struktur Ideal (Modular + Feature Scoped)

lib/
 ┣ features/
 ┃ ┣ sales/
 ┃ ┃ ┣ bloc/
 ┃ ┃ ┃ ┣ sales_bloc.dart
 ┃ ┃ ┃ ┣ sales_event.dart
 ┃ ┃ ┃ ┗ sales_state.dart
 ┃ ┃ ┣ pages/
 ┃ ┃ ┃ ┗ sales_page.dart
 ┃ ┃ ┣ widgets/
 ┃ ┃ ┃ ┗ sales_card.dart
 ┃ ┃ ┣ sales_repository.dart
 ┃ ┃ ┗ sales_service.dart
 ┃ ┣ inventory/
 ┃ ┃ ┣ bloc/
 ┃ ┃ ┣ pages/
 ┃ ┃ ┗ ...
 ┣ cmd/
 ┃ ┗ routes/
 ┃   ┣ core/
 ┃   ┃ ┗ auth_routes.dart  ← BlocProvider here
 ┃   ┣ ops/
 ┃   ┃ ┗ sales_routes.dart  ← BlocProvider here
 ┃   ┗ routes.dart
 ┣ app.dart
 ┗ main.dart

🔧 Implementation Pattern

✅ CORRECT: Route-Level BlocProvider

// cmd/routes/core/auth_routes.dart
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:go_router/go_router.dart';

final List<RouteBase> authRoutes = [
  GoRoute(
    path: '/auth/login',
    builder: (context, state) => BlocProvider(
      create: (_) => getIt<AuthBloc>(),  // ✅ Route-level
      child: const LoginPage(),
    ),
  ),
];

Benefits:

✅ AuthBloc hanya hidup selama route aktif
✅ Semua widget di bawah LoginPage bisa context.watch<AuthBloc>()
✅ Tidak membanjiri global scope
✅ Auto-disposed saat keluar route

❌ ANTIPATTERN: Page-Level BlocProvider

// ❌ JANGAN SEPERTI INI
class SalesPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => SalesBloc(),  // ❌ Recreate setiap rebuild
      child: Scaffold(...),
    );
  }
}

Problems:

❌ Setiap kali route direpush, SalesBloc direcreate
❌ Request API ulang
❌ State hilang saat navigasi antar tab
❌ Tidak bisa share state ke sub-page (/sales/detail/:id)

🧮 MultiBloc Pattern

Jika satu feature butuh beberapa state domain:

// cmd/routes/ops/sales_routes.dart
return MultiBlocProvider(
  providers: [
    BlocProvider(create: (_) => getIt<SalesBloc>()),
    BlocProvider(create: (_) => getIt<FilterCubit>()),
    BlocProvider(create: (_) => getIt<SortCubit>()),
  ],
  child: const SalesPage(),
);

Results:

✅ Semua anak widget bisa akses multi-state
✅ Masih terisolasi dalam feature route
✅ Lifecycle otomatis dihapus saat keluar route

🧱 Decision Matrix

Kapan taruh di Route
Kapan taruh di Page
Kapan taruh di Component

State domain / API calls
Perlu diakses antar sub-page
Misal: Sales, Inventory, HR
Lifecycle: Lives as long as route lives

✅ Implementation Checklist

Define BLoC Scope

Tentukan apakah state ini:

Global (auth, theme)
Feature-level (sales, inventory)
UI-only (filter, sort)

Create BLoC/Cubit

@injectable
class SalesBloc extends Bloc<SalesEvent, SalesState> {
  final SalesRepository _repository;
  
  SalesBloc(this._repository) : super(SalesInitial());
}

// di/injection.dart
@module
abstract class AppModule {
  @lazySingleton
  SalesBloc salesBloc(SalesRepository repo) => SalesBloc(repo);
}

Provide at Route Level

// cmd/routes/ops/sales_routes.dart
GoRoute(
  path: '/sales',
  builder: (context, state) => BlocProvider(
    create: (_) => getIt<SalesBloc>(),
    child: const SalesPage(),
  ),
);

Access in Widgets

// pages/sales_page.dart
class SalesPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocBuilder<SalesBloc, SalesState>(
      builder: (context, state) {
        // Use state here
      },
    );
  }
}

📊 Architecture Summary

Prinsip	Rekomendasi
Scope utama BLoC	Per feature route (domain boundary)
Scope global	Hanya untuk state universal (auth, theme)
Page/Component level	Gunakan Cubit, bukan BLoC
Lifecycle rule	”Bloc lives as long as the feature route lives.”
Konsekuensi baiknya	- Tidak recreate state - Modular domain boundary - Lebih mudah di test dan DI

💡 Key Takeaways

BLoC Domain

Di route-level (feature provider)Contoh: /sales, /inventory

Cubit Ringan

Di page/component levelContoh: Filter, Sort, Tab Index

Root BLoC

Hanya untuk global shared stateContoh: Auth, Theme, Locale

Never in Component

Jangan taruh BLoC di widget kecilAkan recreate setiap build

Mobile Architecture

Complete mobile architecture guide

State Management

State management patterns

Dependency Injection

DI setup dengan Injectable

Testing BLoC

Unit testing untuk BLoC

Best Practice: Selalu provide BLoC di route-level untuk proper lifecycle management dan avoid memory leaks.

Avoid: Jangan provide BLoC di component-level widget. Ini akan cause recreate setiap rebuild dan memory issues.

​🧩 BLoC Architecture Guide

​📌 Prinsip Dasar

Siapa yang Memiliki State?

​⚙️ Hierarki UI dan Scope yang Tepat

​Tabel Scope BLoC

​🧩 Best Practice BLoC Scope per Domain

Global / Persistent

Feature-based

Ephemeral UI

​🧠 Struktur Ideal (Modular + Feature Scoped)

​🔧 Implementation Pattern

​✅ CORRECT: Route-Level BlocProvider

​❌ ANTIPATTERN: Page-Level BlocProvider

​🧮 MultiBloc Pattern

​🧱 Decision Matrix

​✅ Implementation Checklist

​📊 Architecture Summary

​💡 Key Takeaways

BLoC Domain

Cubit Ringan

Root BLoC

Never in Component

​🔗 Related Documentation

Mobile Architecture

State Management

Dependency Injection

Testing BLoC

🧩 BLoC Architecture Guide

📌 Prinsip Dasar

⚙️ Hierarki UI dan Scope yang Tepat

Tabel Scope BLoC

🧩 Best Practice BLoC Scope per Domain

🧠 Struktur Ideal (Modular + Feature Scoped)

🔧 Implementation Pattern

✅ CORRECT: Route-Level BlocProvider

❌ ANTIPATTERN: Page-Level BlocProvider

🧮 MultiBloc Pattern

🧱 Decision Matrix

✅ Implementation Checklist

📊 Architecture Summary

💡 Key Takeaways

🔗 Related Documentation