Skip to content

Latest commit

 

History

History
580 lines (463 loc) · 19.3 KB

analysis.md

File metadata and controls

580 lines (463 loc) · 19.3 KB

OSMEA Core Package Analysis 📊

Comprehensive analysis of the OSMEA Core Flutter package from the masterfabric-mobile/osmea repository (dev branch)

📋 Table of Contents

  1. Overview
  2. Package Information
  3. Architecture Analysis
  4. Module Breakdown
  5. Dependencies Analysis
  6. File Structure
  7. Key Components
  8. Integration Points
  9. Recommendations

Overview

OSMEA Core is a comprehensive Flutter package that provides essential utilities, base classes, and shared logic for building scalable Flutter applications. It serves as the foundational layer for the OSMEA project ecosystem.

Key Highlights

Aspect Details
Package Name core
Version 0.0.1
SDK Constraint Dart ^3.6.1, Flutter >=1.17.0
License GNU AGPL v3.0
State Management BLoC / Cubit Pattern
DI Framework Injectable + GetIt

Package Information

pubspec.yaml Summary

name: core
description: "Core utilities, base classes, and shared logic for the OSMEA Flutter project."
version: 0.0.1

environment:
  sdk: ^3.6.1
  flutter: ">=1.17.0"

Technology Stack

  • Flutter 3.19+ - Cross-platform UI framework
  • Dart 3.6+ - Type-safe programming language
  • BLoC 9.1+ - State management pattern
  • Hydrated BLoC 10.1+ - Persisted state management
  • Injectable 2.7+ - Dependency injection
  • Firebase - Analytics, Remote Config, Core services
  • Slang 4.11+ - Localization and internationalization
  • Go Router 15.1+ - Navigation/Routing

Architecture Analysis

Design Patterns Used

  1. BLoC Pattern - Business Logic Component for state management
  2. Cubit Pattern - Simplified BLoC for simpler state scenarios
  3. Hydrated Cubit - State persistence across app restarts
  4. Repository Pattern - Data abstraction layer
  5. Dependency Injection - Injectable-based service registration
  6. Factory Pattern - For creating view models and services

Layered Architecture

┌─────────────────────────────────────────┐
│              Presentation               │
│    (Views, Widgets, Master Views)       │
├─────────────────────────────────────────┤
│           State Management              │
│   (BLoC, Cubit, Hydrated Cubit)         │
├─────────────────────────────────────────┤
│              Business Logic             │
│      (View Models, Helpers)             │
├─────────────────────────────────────────┤
│               Data Layer                │
│  (Models, Storage, Remote Config)       │
├─────────────────────────────────────────┤
│              Core/Foundation            │
│     (DI, Base Classes, Utilities)       │
└─────────────────────────────────────────┘

Module Breakdown

1. Base Module (lib/src/base/)

Core base classes for consistent view architecture.

File Purpose Size
base_view_bloc.dart Abstract BLoC-based view 10KB
base_view_cubit.dart Abstract Cubit-based view 4.3KB
base_view_hydrated_cubit.dart Persisted Cubit view 2KB
base_view_model.dart Base view model class 2.5KB
base_view_model_cubit.dart Cubit-based view model 3.5KB
base_view_model_hydrated_cubit.dart Persisted view model 1KB
base_view_state.dart Base state management 3.2KB

Sub-modules:

  • master_view/ - Master application view wrapper
  • master_view_cubit/ - Cubit-based master view
  • master_view_hydrated_cubit/ - Hydrated master view with persistence
  • widgets/ - Common reusable widgets (e.g., master_scaffold_widget.dart)

2. Helper Module (lib/src/helper/)

Comprehensive utility helpers for various functionalities.

Helper File Size Purpose
local_notification_helper.dart 56KB Local push notifications
file_download_helper.dart 39KB File downloads with progress
asset_config_helper.dart 31KB JSON config management
url_launcher_helper.dart 28KB External URL/app launching
web_viewer_helper.dart 28KB HTML/WebView rendering
datetime_helper.dart 27KB Date/time operations
price_info_currency_helper.dart 27KB Currency formatting
remote_config_helper.dart 17KB Firebase Remote Config
double_extension_helper.dart 12KB Number formatting
auth_storage_helper.dart 11KB Auth data persistence
device_info_helper.dart 4.8KB Device information
application_share_helper.dart 3.3KB Content sharing
onboarding_helper.dart 3.3KB Onboarding storage
spacer_helper.dart 1.1KB UI spacing utilities
first_letter_capitalize_helper.dart 0.5KB String capitalization
grid_helper.dart 0.4KB Grid layout helpers

Sub-modules:

  • local_storage/ - SharedPreferences wrapper
  • permission_handler_helper/ - Runtime permissions
    • permission_handler_helper.dart
    • models/permission_models.dart
    • abstract/permission_handler_base.dart
  • common_logger_helper/ - Logging utilities

3. Views Module (lib/src/views/)

Pre-built views with BLoC/Cubit state management.

View Description
splash/ Splash screen with loading logic
onboarding/ User onboarding flow
auth/ Authentication (Sign In + Sign Up with TabBar)
account/ User account management
permissions/ Permission request screens
error_handling/ Error display and recovery
loading/ Loading state views
empty_view/ Empty state views
info_bottom_sheet/ Information bottom sheets
image_detail/ Image detail viewer
search/ Search functionality

Each view includes:

  • *_view.dart - UI implementation
  • cubit/*_cubit.dart - State management
  • cubit/*_state.dart - State definitions
  • widgets/ - View-specific widgets (optional)

4. Models Module (lib/src/models/)

Data models for views and business logic.

Model File Size Purpose
loading_models.dart 15.6KB Loading state configurations
error_handling_models.dart 10.7KB Error handling data
onboarding_models.dart 8.9KB Onboarding page models
splash_models.dart 8.5KB Splash screen configs
empty_view_models.dart 7.8KB Empty state configs
info_models.dart 6.5KB Info sheet configurations

5. Layout Module (lib/src/layout/)

Layout utilities for consistent UI spacing.

File Size Purpose
grid.dart 3.2KB Grid layout system
spacer.dart 1.8KB Spacing utilities

6. DI Module (lib/src/di/)

Dependency injection configuration.

  • config/ - Injectable configuration files

7. Resources Module (lib/src/resources/)

Generated localization resources.

  • resources.g.dart - Generated translation file (Slang)

Dependencies Analysis

Production Dependencies

Package Version Category
flutter_bloc ^9.1.0 State Management
hydrated_bloc ^10.1.1 Persisted State
equatable ^2.0.7 Value Equality
go_router ^15.1.1 Navigation
injectable ^2.7.1 Dependency Injection
logger ^2.5.0 Logging
slang ^4.11.1 Localization
slang_flutter ^4.11.0 Flutter Localization
url_launcher ^6.3.1 URL Launching
intl ^0.20.0 Internationalization
sqflite ^2.4.2 SQLite Database
shared_preferences ^2.5.3 Key-Value Storage
firebase_analytics ^11.4.5 Analytics
firebase_core ^3.13.0 Firebase Core
firebase_remote_config ^5.3.4 Remote Config
device_info_plus ^11.4.0 Device Info
package_info_plus ^8.3.0 Package Info
dio ^5.7.0 HTTP Client
path_provider ^2.1.5 File Paths
permission_handler ^11.2.0 Permissions
share_plus ^10.1.4 Content Sharing
flutter_html ^3.0.0 HTML Rendering
flutter_inappwebview ^6.1.5 WebView
webview_flutter ^4.10.0 Native WebView
timezone ^0.10.1 Timezone Handling
flutter_local_notifications ^19.4.2 Local Notifications
osmea_components path: ../components UI Kit

Development Dependencies

Package Version Purpose
flutter_test SDK Testing
build_runner ^2.4.7 Code Generation
injectable_generator ^2.11.1 DI Code Gen
slang_build_runner ^4.8.0 Localization Gen

Dependency Overrides

dependency_overrides:
  build: ^4.0.0
  intl: ^0.20.0

File Structure

packages/core/
├── 📄 .gitignore
├── 📄 .metadata
├── 📁 .vscode/
├── 📄 CHANGELOG.md
├── 📄 CODE_OF_CONDUCT.md
├── 📄 LICENSE (GNU AGPL v3.0)
├── 📄 README.md (26KB - comprehensive documentation)
├── 📄 analysis_options.yaml
├── 📁 assets/
│   ├── app_config.json
│   └── i18n/
│       └── en.json
├── 📄 devtools_options.yaml
├── 📄 firebase.json
├── 📄 pubspec.yaml
├── 📄 slang.yaml
└── 📁 lib/
    ├── 📄 core.dart (Main export file - 8KB)
    ├── 📄 firebase_options.dart (2.7KB)
    ├── 📁 gen/ (Generated files)
    └── 📁 src/
        ├── 📄 core.dart (0.5KB)
        ├── 📁 base/
        │   ├── 📄 base_view_bloc.dart
        │   ├── 📄 base_view_cubit.dart
        │   ├── 📄 base_view_hydrated_cubit.dart
        │   ├── 📄 base_view_model.dart
        │   ├── 📄 base_view_model_cubit.dart
        │   ├── 📄 base_view_model_hydrated_cubit.dart
        │   ├── 📄 base_view_state.dart
        │   ├── 📁 master_view/
        │   │   ├── 📄 master_app.dart
        │   │   └── 📄 master_view.dart
        │   ├── 📁 master_view_cubit/
        │   │   └── 📄 master_view_cubit.dart
        │   ├── 📁 master_view_hydrated_cubit/
        │   │   ├── 📄 master_view_hydrated_cubit.dart
        │   │   └── 📁 hydrated/
        │   │       └── 📄 hydrated_bloc_init.dart
        │   └── 📁 widgets/
        │       └── 📄 master_scaffold_widget.dart
        ├── 📁 di/
        │   └── 📁 config/
        ├── 📁 helper/
        │   ├── 📄 application_share_helper.dart
        │   ├── 📄 asset_config_helper.dart
        │   ├── 📄 auth_storage_helper.dart
        │   ├── 📄 datetime_helper.dart
        │   ├── 📄 device_info_helper.dart
        │   ├── 📄 double_extension_helper.dart
        │   ├── 📄 file_download_helper.dart
        │   ├── 📄 first_letter_capitalize_helper.dart
        │   ├── 📄 grid_helper.dart
        │   ├── 📄 local_notification_helper.dart
        │   ├── 📄 onboarding_helper.dart
        │   ├── 📄 package_info_helper.dart
        │   ├── 📄 price_info_currency_helper.dart
        │   ├── 📄 remote_config_helper.dart
        │   ├── 📄 spacer_helper.dart
        │   ├── 📄 url_launcher_helper.dart
        │   ├── 📄 web_viewer_helper.dart
        │   ├── 📁 common_logger_helper/
        │   ├── 📁 local_storage/
        │   │   └── 📄 local_storage_helper.dart
        │   └── 📁 permission_handler_helper/
        │       ├── 📄 permission_handler_helper.dart
        │       ├── 📁 abstract/
        │       │   └── 📄 permission_handler_base.dart
        │       └── 📁 models/
        │           └── 📄 permission_models.dart
        ├── 📁 layout/
        │   ├── 📄 grid.dart
        │   └── 📄 spacer.dart
        ├── 📁 models/
        │   ├── 📄 empty_view_models.dart
        │   ├── 📄 error_handling_models.dart
        │   ├── 📄 info_models.dart
        │   ├── 📄 loading_models.dart
        │   ├── 📄 onboarding_models.dart
        │   └── 📄 splash_models.dart
        ├── 📁 resources/
        │   └── 📄 resources.g.dart
        └── 📁 views/
            ├── 📄 routes.dart
            ├── 📁 account/
            │   ├── 📄 account_view.dart
            │   ├── 📁 cubit/
            │   │   ├── 📄 account_cubit.dart
            │   │   └── 📄 account_state.dart
            │   └── 📁 widgets/
            │       ├── 📄 account_widget.dart
            │       └── 📄 orders_list_widget.dart
            ├── 📁 auth/
            │   ├── 📄 auth_view.dart
            │   └── 📁 cubit/
            │       ├── 📄 auth_cubit.dart
            │       └── 📄 auth_state.dart
            ├── 📁 empty_view/
            ├── 📁 error_handling/
            ├── 📁 image_detail/
            ├── 📁 info_bottom_sheet/
            ├── 📁 loading/
            ├── 📁 onboarding/
            ├── 📁 permissions/
            ├── 📁 search/
            └── 📁 splash/

Key Components

1. Master App & Master View

The entry point for OSMEA applications:

// MasterApp - Main application wrapper
export 'package:core/src/base/master_view/master_app.dart';

// MasterView - Unified view management
export 'package:core/src/base/master_view/master_view.dart';

// MasterViewCubit - Cubit-based master view
export 'package:core/src/base/master_view_cubit/master_view_cubit.dart';

2. Base View Classes

Three approaches for building views:

Class Use Case
BaseViewBloc Complex state with events and states
BaseViewCubit Simpler state management
BaseViewHydratedCubit State persistence across restarts

3. State Management Pattern

// Base State with common patterns
export 'package:core/src/base/base_view_state.dart';

// View Models for business logic
export 'package:core/src/base/base_view_model.dart';
export 'package:core/src/base/base_view_model_cubit.dart';

4. Pre-built Views

Ready-to-use screens with customization:

  • SplashView - App launch screen
  • OnboardingView - User introduction
  • AuthView - Sign In/Sign Up with TabBar
  • AccountView - User profile management
  • PermissionsView - Permission requests
  • ErrorHandlingView - Error display
  • LoadingView - Loading states
  • EmptyView - Empty states
  • InfoBottomSheetView - Information sheets
  • ImageDetailView - Image viewer
  • SearchView - Search interface

5. Helper Functions

Comprehensive utilities organized by functionality:

// Storage
export 'package:core/src/helper/local_storage/local_storage_helper.dart';
export 'package:core/src/helper/auth_storage_helper.dart';

// UI Helpers
export 'package:core/src/helper/spacer_helper.dart';
export 'package:core/src/helper/url_launcher_helper.dart';
export 'package:core/src/helper/web_viewer_helper.dart';

// Data Helpers
export 'package:core/src/helper/datetime_helper.dart';
export 'package:core/src/helper/double_extension_helper.dart';
export 'package:core/src/helper/price_info_currency_helper.dart';
export 'package:core/src/helper/first_letter_capitalize_helper.dart';

// System Helpers
export 'package:core/src/helper/device_info_helper.dart';
export 'package:core/src/helper/permission_handler_helper/permission_handler_helper.dart';
export 'package:core/src/helper/local_notification_helper.dart';
export 'package:core/src/helper/file_download_helper.dart';
export 'package:core/src/helper/application_share_helper.dart';

// Configuration
export 'package:core/src/helper/asset_config_helper.dart';
export 'package:core/src/helper/remote_config_helper.dart';

Integration Points

1. External Package Integration

The package integrates with osmea_components:

dependencies:
  osmea_components:
    path: ../components

This is exported for use:

export 'package:osmea_components/osmea_components.dart';

2. Firebase Integration

  • Firebase Core - Foundation for all Firebase services
  • Firebase Analytics - User behavior tracking
  • Firebase Remote Config - Dynamic configuration
// Firebase options configuration
export 'package:core/firebase_options.dart';

3. Localization (Slang)

Configuration in slang.yaml:

  • Translation files in assets/i18n/
  • Generated resources in resources.g.dart

4. Dependency Injection

Using Injectable with GetIt:

  • Configuration in lib/src/di/config/
  • Auto-registration of services
  • Environment-based configuration

Recommendations

Strengths ✅

  1. Well-structured architecture - Clear separation of concerns
  2. Comprehensive helpers - Rich utility functions
  3. State management options - BLoC, Cubit, and Hydrated variants
  4. Pre-built views - Common screens ready to use
  5. Type-safe localization - Slang integration
  6. Modern dependencies - Up-to-date package versions

Areas for Improvement 🔄

  1. Testing coverage - Add unit tests for helpers and cubits
  2. Documentation - Add inline documentation to exported APIs
  3. Example app - Include sample implementation
  4. Error handling - Standardize error types across helpers
  5. Logging - Implement consistent logging strategy

Migration Considerations

When integrating into masterfabric_core:

  1. Dependency Alignment - Ensure version compatibility
  2. Package Reference - Update osmea_components path or remove
  3. Firebase Setup - Configure firebase_options for your project
  4. Asset Configuration - Copy assets folder structure
  5. Code Generation - Run build_runner after setup

Quick Start Commands

# Install dependencies
flutter pub get

# Generate code (DI, localization)
dart run build_runner build --delete-conflicting-outputs

# Run tests
flutter test

# Analyze code
flutter analyze

Summary Statistics

Metric Count
Total Dart Files 60+
Helper Classes 21
Pre-built Views 12
Model Classes 6
Base Classes 7
Production Dependencies 25+
Dev Dependencies 4

Document Generated: December 22, 2025
Source: https://github.com/masterfabric-mobile/osmea/tree/dev/packages/core
Branch: dev
Commit SHA: 5a1a9dd0327b874b322b3fbe0c74739763ecd4d6

This analysis document is part of the masterfabric_core project documentation.