moose_core #

A comprehensive, production-ready core architecture package for building modular Flutter e-commerce applications.

Features #

• Plugin-Based Architecture: Modular feature plugins with clean boundaries
• Repository Pattern: Abstract data layer with swappable backend adapters
• BLoC State Management: Built-in support for predictable state management
• FeatureSection Pattern: Configurable, reusable UI sections
• Registry Systems: Widget, Adapter, Action, Hook, and Addon registries
• Cache Management: Multi-layer caching with TTL support
• Configuration System: JSON-based external configuration
• Modular Imports: Import entire package or specific modules for optimized builds
• Type-Safe APIs: Generic methods with compile-time type checking
• AI-Ready Documentation: Comprehensive documentation for AI-assisted development

Quick Start #

Installation #

Add to your pubspec.yaml:

dependencies:
  moose_core: ^1.0.0

Import Options #

// Option 1: Import everything (recommended for most cases)
import 'package:moose_core/moose_core.dart';

// Option 2: Import specific modules (for optimized builds)
import 'package:moose_core/app.dart';            // MooseAppContext, MooseScope, MooseBootstrapper
import 'package:moose_core/entities.dart';       // Domain entities
import 'package:moose_core/repositories.dart';   // Repository interfaces
import 'package:moose_core/plugin.dart';         // Plugin system
import 'package:moose_core/widgets.dart';        // UI components
import 'package:moose_core/adapters.dart';       // Adapter pattern
import 'package:moose_core/cache.dart';          // Caching system
import 'package:moose_core/services.dart';       // Utilities & helpers

Basic Usage #

import 'package:moose_core/moose_core.dart';

// 1. Bootstrap the app with MooseAppContext + MooseScope
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await CacheManager.initPersistentCache();
  final appContext = MooseAppContext();
  runApp(MooseScope(
    appContext: appContext,
    child: AppBootstrap(appContext: appContext),
  ));
}

class AppBootstrap extends StatefulWidget {
  final MooseAppContext appContext;
  const AppBootstrap({super.key, required this.appContext});
  @override State<AppBootstrap> createState() => _AppBootstrapState();
}

class _AppBootstrapState extends State<AppBootstrap> {
  bool _ready = false;

  @override
  void initState() {
    super.initState();
    MooseBootstrapper(appContext: widget.appContext).run(
      config: {'adapters': {'woocommerce': {'baseUrl': 'https://mystore.com'}}},
      adapters: [WooCommerceAdapter()],
      plugins: [() => ProductsPlugin()],
    ).then((_) { if (mounted) setState(() => _ready = true); });
  }

  @override
  Widget build(BuildContext context) => _ready
      ? const MyApp()
      : const Scaffold(body: Center(child: CircularProgressIndicator()));
}

// 2. Create a plugin — use inherited registry getters (hookRegistry, widgetRegistry, etc.)
class ProductsPlugin extends FeaturePlugin {
  @override String get name => 'products';
  @override String get version => '1.0.0';

  @override
  void onRegister() {
    // widgetRegistry, hookRegistry, addonRegistry, etc. delegate to injected appContext
    widgetRegistry.register(
      'products.featured',
      (context, {data, onEvent}) => FeaturedProductsSection(
        settings: data?['settings'] as Map<String, dynamic>?,
      ),
    );
  }

  @override Future<void> onInit() async {}

  @override
  Map<String, WidgetBuilder>? getRoutes() => {
    '/products': (_) => ProductsListScreen(),
  };
}

// 3. Create a FeatureSection — use adaptersOf(context) inside build()
class FeaturedProductsSection extends FeatureSection {
  const FeaturedProductsSection({super.key, super.settings});

  @override
  Map<String, dynamic> getDefaultSettings() => {
    'title': 'FEATURED PRODUCTS',
    'itemCount': 10,
  };

  @override
  Widget build(BuildContext context) {
    final repository = adaptersOf(context).getRepository<ProductsRepository>();
    return BlocProvider(
      create: (_) => FeaturedProductsBloc(repository)
        ..add(const LoadFeaturedProducts()),
      child: BlocBuilder<FeaturedProductsBloc, FeaturedProductsState>(
        builder: (context, state) {
          if (state is FeaturedProductsLoaded) return _buildProducts(state.products);
          if (state is FeaturedProductsError) return Text(state.message);
          return const CircularProgressIndicator();
        },
      ),
    );
  }
}

// 4. Create a backend adapter — hookRegistry and eventBus are set before initializeFromConfig
class WooCommerceAdapter extends BackendAdapter {
  @override String get name => 'woocommerce';
  @override String get version => '1.0.0';

  @override
  Future<void> initializeFromConfig({ConfigManager? configManager}) async {
    registerRepositoryFactory<ProductsRepository>(
      () => WooProductsRepository(apiClient, hookRegistry: hookRegistry, eventBus: eventBus),
    );
    registerRepositoryFactory<CartRepository>(
      () => WooCartRepository(apiClient, hookRegistry: hookRegistry, eventBus: eventBus),
    );
  }
}

Core Concepts #

Plugin System #

Every feature is a self-contained plugin:

class MyPlugin extends FeaturePlugin {
  @override
  String get name => 'my_plugin';

  @override
  void onRegister() {
    // widgetRegistry, hookRegistry, actionRegistry, etc. are available as
    // inherited getters backed by the injected MooseAppContext
    widgetRegistry.register('my.section', (ctx, {data, onEvent}) => MySection());
    hookRegistry.register('my:hook', (data) => processData(data));
    actionRegistry.register('my.action', (ctx, payload) async { /* ... */ });
  }

  @override
  Future<void> onInit() async {
    // Async initialization (called after all plugins are registered)
  }

  @override
  Map<String, WidgetBuilder>? getRoutes() => {
    '/my-route': (_) => MyScreen(),
  };
}

Repository Pattern #

Abstract interfaces with backend-specific implementations:

// Core repository interface (abstract, defined in moose_core)
abstract class ProductsRepository extends CoreRepository {
  Future<ProductListResult> getProducts({ProductFilters? filters});
  Future<Product> getProductById(String id);
}

// Backend implementation — forward hookRegistry and eventBus to super
class WooProductsRepository extends ProductsRepository {
  final ApiClient _apiClient;

  WooProductsRepository(this._apiClient, {
    required super.hookRegistry,
    required super.eventBus,
  });

  @override
  Future<ProductListResult> getProducts({ProductFilters? filters}) async {
    // WooCommerce-specific implementation
  }
}

FeatureSection Pattern #

Configurable UI sections:

class MySection extends FeatureSection {
  const MySection({super.key, super.settings});

  @override
  Map<String, dynamic> getDefaultSettings() {
    return {
      'title': 'Default Title',
      'itemCount': 5,
    };
  }

  @override
  Widget build(BuildContext context) {
    final title = getSetting<String>('title');
    final count = getSetting<int>('itemCount');
    // Build UI...
  }
}

Registry Systems #

WidgetRegistry

Dynamic widget composition. In plugins use the inherited getter; in widgets use context.moose:

// In a plugin's onRegister():
widgetRegistry.register('my.widget', (context, {data, onEvent}) => MyWidget());

// In any widget's build(context):
final widget = context.moose.widgetRegistry.build('my.widget', context);

AdapterRegistry

Backend adapter management. In FeatureSection.build() use adaptersOf(context):

// In a FeatureSection's build(context):
final repo = adaptersOf(context).getRepository<ProductsRepository>();

// In any other widget's build(context):
final repo = context.moose.adapterRegistry.getRepository<ProductsRepository>();

ActionRegistry

Custom action handling:

// In a plugin's onRegister():
actionRegistry.register('custom_action', (context, payload) async {
  // Handle action
});

// In any widget's build(context):
context.moose.actionRegistry.execute('custom_action', context, payload);

EventBus

Asynchronous event-driven communication between plugins:

// In a plugin — fire events using the inherited getter:
eventBus.fire(
  'cart.item.added',
  data: {'productId': 'prod-123', 'quantity': 2},
  metadata: {'cartTotal': 99.99},
);

// In a plugin — subscribe to events:
final subscription = eventBus.on('cart.item.added', (event) {
  final productId = event.data['productId'];
});

// Async event handlers:
eventBus.onAsync('order.placed', (event) async {
  await sendConfirmationEmail(event.data['orderId']);
});

// In a widget — use context.moose:
context.moose.eventBus.fire('my.event', data: {});

// Clean up
await subscription.cancel();

HookRegistry

Synchronous data transformation and service hooks:

// In a plugin's onRegister() — expose hooks using inherited getter:
hookRegistry.register('cart:get_cart_item_count', (data) {
  if (state is CartLoaded) return state.cart.itemCount;
  return 0;
});

hookRegistry.register('cart:item_count_stream', (data) {
  return cartBloc.stream.map((state) => state.totalItems).distinct();
});

// In a widget — consume hooks via context.moose:
final count = context.moose.hookRegistry.execute<int>('cart:get_cart_item_count', 0);
final stream = context.moose.hookRegistry.execute<Stream<int>>(
  'cart:item_count_stream',
  const Stream<int>.empty(),
);

Architecture #

┌─────────────────────────────────────────────┐
│         Presentation Layer                  │
│         (Screens, Sections)                 │
└──────────────────┬──────────────────────────┘
                   │ Events/States
┌──────────────────▼──────────────────────────┐
│         Business Logic (BLoC)               │
└──────────────────┬──────────────────────────┘
                   │ Repository Calls
┌──────────────────▼──────────────────────────┐
│         Repository Interfaces               │
└──────────────────┬──────────────────────────┘
                   │ Implementation
┌──────────────────▼──────────────────────────┐
│         Backend Adapters                    │
│         (WooCommerce, Shopify, etc.)        │
└─────────────────────────────────────────────┘

Package Modules #

The package is organized into focused modules for better maintainability and selective imports:

Documentation #

• Architecture Guide - Complete architectural patterns
• Plugin System - Creating and using plugins
• FeatureSection Guide - Building configurable sections
• Adapter Pattern - Backend adapter implementation
• Event System Guide - EventBus and HookRegistry usage
• Registries - Using registry systems
• Anti-Patterns - What to avoid
• API Reference - Complete API documentation
• Migration Guide - Modular structure migration

Example Projects #

See the example directory for complete working examples:

• Basic plugin implementation
• Custom adapter creation
• FeatureSection usage
• Full app integration

AI-Assisted Development #

This package is designed for AI-assisted development with comprehensive AI-ready documentation. See doc/ai-ready/README.md for:

• Architectural patterns for AI agents
• Code generation guidelines
• Anti-patterns to avoid
• Best practices

Requirements #

• Dart SDK: >=3.0.0 <4.0.0
• Flutter: >=3.0.0

Dependencies #

• flutter_bloc - State management
• equatable - Value equality
• dio - HTTP client
• shared_preferences - Local storage
• intl - Internationalization

Contributing #

Contributions are welcome! Please read our Contributing Guide for details.

License #

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

Support #

• Documentation
• Issue Tracker
• Discussions

Changelog #

See CHANGELOG.md for version history.