OSMEA ®️

Open Source Mobile E-commerce App Builder Tool

"OSMEA is not just a framework — it's an ecosystem."

🚀 Live Demo • 📚 Documentation • 🔍 API Explorer • 🎮 Component Showcase

📋 Table of Contents

• 📊 Project Statistics
• 🌟 What is OSMEA?
  • 🎯 Our Mission
  • ⚡ Why Choose OSMEA?
• 🏗️ OSMEA Ecosystem Architecture
  • 📦 Core Packages
  • 🚀 Ready-to-Use Applications
  • 🛠️ Development Tools
• 🛠️ Technology Stack
  • Frontend & Mobile
  • Backend & APIs
  • E-commerce Platforms
  • Development & DevOps
• ✨ Key Features & Benefits
  • 🚀 Developer Experience
  • 🛒 E-commerce Features
  • 📱 Cross-Platform Excellence
• 🚀 Getting Started
  • 📋 Prerequisites
  • ⚡ Quick Start
  • 🎯 Choose Your Application
• 📚 Architecture & Documentation
  • 🏗️ Project Structure
  • 📖 Documentation Hub
  • 🧠 Architecture Principles
• 📦 Package Details
  • 🎨 OSMEA Components
  • 🔧 OSMEA Core
  • 🌐 OSMEA APIs
• 🚀 Application Showcase
• 🤝 Contributing & Community
  • 👥 How to Contribute
  • 🎯 Current Opportunities
  • 🌟 Community Guidelines
• 📄 License & Legal
  • 📎 Legal Information
  • ⚖️ Usage Guidelines
• 🌟 Community & Support

📊 Project Statistics

🌟 What is OSMEA?

OSMEA (Open Source Mobile E-commerce Architecture) is a comprehensive Flutter ecosystem for building enterprise-level e-commerce mobile applications. MasterFabric represents the architecture of e-commerce mobile apps with professional, production-ready solutions.

🎯 Our Mission

"To provide the ultimate toolkit for Flutter developers to build world-class e-commerce applications faster than ever before."

⚡ Why Choose OSMEA?

• 🏗️ Enterprise Architecture - Production-ready, scalable structure
• 🔧 3 Core Packages - APIs, Components, Core utilities
• 🚀 6 Ready Apps - Complete applications for different use cases
• 📱 Cross-Platform - iOS, Android, Web, Desktop support
• 🛒 E-commerce Focused - Built specifically for commerce apps
• ⚙️ Automated Setup - One-command project initialization with setup.sh
• 🔌 Multi-Platform Integration - Shopify, WooCommerce, Supabase support
• 🎨 50+ UI Components - Material Design 3 components ready to use
• 🧪 Testing Framework - Comprehensive testing tools included
• 📚 Rich Documentation - Detailed guides, checklists, and examples

🏗️ OSMEA Ecosystem Architecture

📦 Core Packages (3)

🌐 APIs

Backend integration | ✅ Production Ready
REST/GraphQL • Shopify • WooCommerce • Auth • Error handling

🎨 Components

UI component library | ✅ Production Ready
50+ components • Material Design 3 • Responsive layouts

🔧 Core

Foundation utilities | ✅ Production Ready
DI • Storage • Analytics • Theming • i18n support

🚀 Ready-to-Use Applications (6)

🛠️ Development Tools

• ⚙️ Automated Setup - One-command initialization script
• 📚 Comprehensive Docs - Guides, checklists, examples
• 🧪 Testing Framework - Unit, widget, integration tests
• 📋 Development Rules - Coding standards and guidelines
• 🔌 Plugin Documentation - Extension guides

• 📊 Version Logs - Release notes and history

🛠️ Technology Stack

Frontend & Mobile

• Flutter 3.19+ - Cross-platform framework with native performance
• Dart - Primary language (99.4% of codebase)
• Material Design 3 - Modern design system with adaptive theming
• BLoC Pattern - Predictable state management for scalable apps

Backend & APIs

• REST APIs - RESTful service integration with robust error handling
• GraphQL - Modern API query language for efficient data fetching
• Firebase - Backend services, analytics, and real-time features
• Authentication - OAuth 2.0, JWT, and API key support

E-commerce Platforms

• Shopify - Full REST and GraphQL API integration
• WooCommerce - WordPress e-commerce platform support
• Supabase - Open source Firebase alternative
• Custom APIs - Flexible integration layer for any backend

Development & DevOps

• GitHub Actions - CI/CD pipelines for automated deployment
• TypeScript (0.4%) - Tooling and configuration scripts
• Shell Scripts (0.1%) - Automation with setup.sh
• Ruby (0.1%) - Fastlane deployment automation
• Flutter Test - Comprehensive testing suite
• Flutter Lints - Code quality enforcement

✨ Key Features & Benefits

🚀 Developer Experience

• ⚡ Rapid Development - Build 70% faster with pre-built components and templates
• 🔧 Modular Architecture - Use only what you need, plug-and-play design
• ⚙️ One-Command Setup - Automated project initialization with setup.sh
• 📚 Rich Documentation - Comprehensive guides, checklists, and API references
• 🧪 Built-in Testing - Unit, widget, and integration test frameworks included
• 🎯 Type Safety - Full type safety with Dart for robust applications
• 🔄 Hot Reload - Instant feedback during development
• 📋 Development Rules - Coding standards and best practices included

🛒 E-commerce Features

• 🏪 Multi-Platform Support - Shopify, WooCommerce, Supabase integrations
• 🎨 50+ UI Components - Production-ready e-commerce UI components
• 🔐 Authentication System - Secure user management and session handling
• 📊 Analytics Integration - Firebase Analytics built-in for insights
• 💳 Payment Processing - Multiple gateway support (Stripe, PayPal, etc.)
• 🛍️ Product Management - Catalog, search, filtering, and cart functionality
• 📦 Order Processing - Complete order management and tracking
• ⭐ Wishlist Support - Save and manage favorite items

📱 Cross-Platform Excellence

• 📱 Native Performance - iOS and Android optimization for smooth experience
• 🌐 Web Support - Progressive Web App (PWA) with responsive design
• 🖥️ Desktop Ready - Windows, macOS, Linux support from single codebase
• 🎨 Adaptive UI - Automatic platform-specific styling and behaviors
• 🌍 Internationalization - Multi-language support with slang integration
• 📐 Responsive Layouts - Works beautifully on all screen sizes
• 🎯 Material Design 3 - Modern design system with dynamic theming
• 🔄 Offline Support - Core functionality available without internet

📚 Architecture & Documentation

🏗️ Project Structure

osmea/
├── 📦 packages/                    # 3 Core Packages
│   ├── apis/                       # API integration layer
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── shopify/       # Shopify API integration
│   │   │   │   ├── woocommerce/   # WooCommerce API integration
│   │   │   │   └── core/          # Shared API utilities
│   │   │   └── apis.dart
│   │   ├── analysis_options.yaml
│   │   ├── build.yaml
│   │   ├── codegen.yaml
│   │   └── pubspec.yaml
│   │
│   ├── components/                 # UI component library
│   │   ├── lib/
│   │   │   ├── src/
│   │   │   │   ├── buttons/       # Button components
│   │   │   │   ├── cards/         # Card components
│   │   │   │   ├── forms/         # Form components
│   │   │   │   ├── layouts/       # Layout components
│   │   │   │   └── navigation/    # Navigation components
│   │   │   └── components.dart
│   │   ├── assets/                # Component assets
│   │   └── pubspec.yaml
│   │
│   └── core/                       # Foundation utilities
│       ├── lib/
│       │   ├── src/
│       │   │   ├── analytics/     # Firebase Analytics
│       │   │   ├── auth/          # Authentication
│       │   │   ├── di/            # Dependency Injection
│       │   │   ├── i18n/          # Internationalization
│       │   │   ├── storage/       # Local storage
│       │   │   └── theme/         # Theme system
│       │   └── core.dart
│       ├── assets/                # Core assets
│       ├── slang.yaml            # i18n configuration
│       └── pubspec.yaml
│
├── 🚀 projects/                    # 6 Ready-to-Use Applications
│   ├── admin_dashboard/            # 📊 Management interface (Web)
│   │   ├── lib/
│   │   ├── assets/
│   │   └── pubspec.yaml
│   │
│   ├── api_explorer/               # 🔍 API testing tool (Web)
│   │   ├── lib/
│   │   ├── assets/
│   │   └── pubspec.yaml
│   │
│   ├── components_app/             # 🎮 Component showcase (All platforms)
│   │   ├── lib/
│   │   ├── assets/
│   │   ├── android/
│   │   ├── ios/
│   │   └── pubspec.yaml
│   │
│   ├── storefront_supabase/        # 🛍️ Supabase e-commerce (Mobile)
│   │   ├── lib/
│   │   ├── assets/
│   │   ├── android/
│   │   ├── ios/
│   │   └── pubspec.yaml
│   │
│   ├── storefront_woo/             # 🛒 WooCommerce app (Mobile)
│   │   ├── lib/
│   │   ├── assets/
│   │   ├── android/
│   │   ├── ios/
│   │   └── pubspec.yaml
│   │
│   └── storybook/                  # 📖 Documentation hub (Web)
│       ├── lib/
│       ├── assets/
│       └── pubspec.yaml
│
├── 📚 docs/                        # Documentation & Resources
│   ├── assets/                     # Images, logos, banners
│   ├── checklists/                 # Development checklists
│   │   ├── core_components_checklist.md
│   │   ├── layout_utilities_checklist.md
│   │   ├── shopify_rest_api_checklist.md
│   │   ├── woocommerce_api_postman_checklist.md
│   │   └── woocommerce_rest_api_checklist.md
│   ├── guidance/                   # Setup & configuration guides
│   │   ├── permission_handler_guidance.md
│   │   ├── woocommerce_setup_guide_macos.md
│   │   ├── woocommerce_setup_guide_windows.md
│   │   └── woocommerce_wishlist_plugin_guide.md
│   ├── plugins/                    # Plugin documentation
│   │   ├── masterfabric-wishlist/
│   │   └── osmea-app-config-manager/
│   └── versions/                   # Version logs & release notes
│       └── version-logs.md
│
├── 🌐 website/                     # Project website (Next.js)
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   └── styles/
│   ├── public/
│   ├── package.json
│   ├── next.config.ts
│   └── tsconfig.json
│
├── 📋 rules/                       # Development rules & guidelines
│   ├── osmea_components_usage.cursorrules
│   ├── osmea-apis-network.cursorrules
│   ├── osmea-color-system.cursorrules
│   ├── osmea-components-ui.cursorrules
│   ├── osmea-core-foundation.cursorrules
│   ├── osmea-packages-general.cursorrules
│   ├── osmea-sizer-extensions.cursorrules
│   ├── osmea-text-extensions.cursorrules
│   ├── osmea-text-system.cursorrules
│   └── osmea-website-nextjs.cursorrules
│
├── ⚙️ setup.sh                     # Automated setup script
├── 📄 README.md                    # This file
├── 📋 CONTRIBUTING.md              # Contribution guidelines
├── 📜 CODE_OF_CONDUCT.md           # Community standards
├── 🔒 SECURITY.md                  # Security policy
├── ⚖️ LICENSE                      # AGPL v3.0 license
├── 📝 commits.md                   # Commit message guidelines
└── 📋 pull_request_template.md     # PR template

📖 Documentation Hub

OSMEA provides comprehensive documentation organized into several categories:

📋 Checklists - docs/checklists/

Step-by-step guides for implementation and verification:

• Core Components - UI component implementation checklist
• Layout Utilities - Responsive layout system guide
• Shopify REST API - Shopify integration checklist
• WooCommerce API - WooCommerce setup and testing
• Postman Collections - API testing with Postman

🎯 Guidance - docs/guidance/

Detailed setup and configuration tutorials:

• Permission Handler - Mobile permissions setup
• WooCommerce Setup - macOS and Windows guides
• Wishlist Plugin - WordPress plugin integration

🔌 Plugins - docs/plugins/

Custom plugin documentation:

• MasterFabric Wishlist - WordPress wishlist plugin
• OSMEA App Config Manager - App configuration plugin

📊 Versions - docs/versions/

Release notes and version history:

• Version logs with detailed changelogs
• Migration guides between versions

🧠 Architecture Principles

OSMEA follows industry best practices and design principles:

🚀 Getting Started

📋 Prerequisites

• Flutter SDK 3.19.0 or higher (Install Flutter)
• Dart SDK 2.17.0 or higher (comes with Flutter)
• Git for version control
• Android Studio or VS Code with Flutter extensions
• Xcode (for iOS development on macOS)
• Node.js (for website development)

⚡ Quick Start (Recommended)

Option 1: Automated Setup (Fastest)

# Clone the repository
git clone https://github.com/masterfabric-mobile/osmea.git
cd osmea

# Run automated setup script
chmod +x setup.sh
./setup.sh

# Start developing! 🚀

The setup.sh script will:

• ✅ Install all package dependencies
• ✅ Generate required code files
• ✅ Set up project configurations
• ✅ Verify Flutter installation
• ✅ Run initial health checks

Option 2: Manual Setup

# Install core package dependencies
cd packages/core && flutter pub get && cd ../..
cd packages/apis && flutter pub get && cd ../..
cd packages/components && flutter pub get && cd ../..

# Generate code with build_runner
cd packages/apis && flutter pub run build_runner build --delete-conflicting-outputs && cd ../..
cd packages/core && flutter pub run build_runner build --delete-conflicting-outputs && cd ../..

# Install application dependencies
cd projects/components_app && flutter pub get && cd ../..
cd projects/storefront_woo && flutter pub get && cd ../..

Option 3: Try Live Demos

Experience OSMEA without installation:

• 🎮 Components Showcase - Interactive component playground
• 🔍 API Explorer - API testing interface
• 📚 Storybook - Component documentation

🎯 Choose Your Application

# For interactive component showcase
cd projects/components_app
flutter run

# For API testing and exploration
cd projects/api_explorer
flutter run --platform web

# For WooCommerce storefront
cd projects/storefront_woo
flutter run --flavor dev  # Development environment
flutter run --flavor prod # Production environment

# For Supabase storefront
cd projects/storefront_supabase
flutter run

# For component documentation
cd projects/storybook
flutter run --platform web

# For admin dashboard
cd projects/admin_dashboard
flutter run --platform web

🛠️ Development Commands

# Run tests
flutter test

# Generate code (after model changes)
flutter pub run build_runner build --delete-conflicting-outputs

# Build for production
flutter build apk --release      # Android
flutter build ios --release      # iOS
flutter build web --release      # Web
flutter build macos --release    # macOS
flutter build windows --release  # Windows
flutter build linux --release    # Linux

# Format code
flutter format .

# Analyze code
flutter analyze

📦 Package Details

🎨 OSMEA Components

50+ production-ready UI components for building beautiful Flutter applications.

Key Features:

• 🎨 Rich Component Library: Buttons, cards, forms, layouts, navigation
• 📱 Responsive Design: Mobile-first with adaptive layouts
• 🎯 Type Safe: Full type safety with Dart
• 🔧 Highly Customizable: Extensive theming and styling options
• ♿ Accessible: WCAG compliance and screen reader support
• 🎨 Material Design 3: Latest design system implementation

Component Categories:

• Buttons: Primary, secondary, text, icon, floating action buttons
• Cards: Product cards, content cards, media cards
• Forms: Text fields, dropdowns, checkboxes, radio buttons
• Layouts: Grids, lists, responsive containers
• Navigation: Bottom bars, app bars, drawers, tabs
• Feedback: Snackbars, dialogs, loading indicators
• E-commerce: Product cards, cart items, checkout forms

Usage:

dependencies:
  osmea_components:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/components

🔧 OSMEA Core

Essential utilities, base classes, and shared logic for OSMEA applications.

Key Features:

• 🏗️ Clean Architecture: Structured foundation for scalable apps
• 🌐 Internationalization: Multi-language support with slang
• 💾 Storage Solutions: Local storage, preferences, secure storage
• 🔐 Authentication: User management and session handling
• 📊 Analytics: Firebase Analytics integration
• 🎨 Dynamic Theming: Runtime theme switching and customization
• 🔧 Dependency Injection: Injectable-based DI setup

Core Modules:

• Analytics: Firebase Analytics tracking and events
• Auth: Authentication providers and user management
• DI: Dependency injection configuration
• i18n: Internationalization with slang
• Storage: Local data persistence
• Theme: Dynamic theme system with Material Design 3
• Utils: Helper functions and extensions

Usage:

dependencies:
  core:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/core

🌐 OSMEA APIs

Comprehensive API network layer for e-commerce applications.

Key Features:

• 🛒 Multi-Platform: Shopify, WooCommerce, Supabase integrations
• 🔄 Dual Protocol: REST and GraphQL support
• 🔐 Security First: OAuth 2.0, JWT, API key authentication
• 📝 Request Logging: Network debugging and monitoring
• 🔧 DI Architecture: Injectable-based service layer
• 🛡️ Error Handling: Comprehensive error management
• ⚡ Performance: Request caching and rate limiting

Supported Platforms:

• Shopify: Full REST and GraphQL API integration
• WooCommerce: Complete WordPress e-commerce API
• Supabase: Open source backend integration
• Custom APIs: Flexible adapter pattern for any backend

API Features:

• Products: CRUD operations, search, filtering
• Orders: Order management, status tracking
• Customers: User authentication and profiles
• Cart: Shopping cart operations
• Payments: Payment gateway integration
• Webhooks: Event-driven updates

Usage:

dependencies:
  apis:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/apis

🚀 Application Showcase

🤝 Contributing & Community

👥 How to Contribute

We welcome contributions from the community! Here's how you can help:

1. 🍴 Fork the Repository

   git clone https://github.com/masterfabric-mobile/osmea.git
   cd osmea

2. 🌿 Create a Feature Branch

   git checkout -b feature/amazing-feature

3. 💻 Make Your Changes

   • Follow our coding standards
   • Write tests for new features
   • Update documentation
   • Follow the commit guidelines

4. 🧪 Test Your Changes

   flutter test
   flutter analyze

5. 📝 Update Documentation

   • Add/update relevant documentation
   • Include code examples
   • Update CHANGELOG if applicable

6. 🚀 Submit a Pull Request

   • Use the PR template
   • Provide clear description
   • Link related issues
   • Request reviews

🎯 Current Opportunities

Check out our Issues for:

• 🐛 Bug Fixes - Help improve stability and reliability
• ✨ New Features - Add exciting functionality
• 📚 Documentation - Improve guides and examples
• 🎨 UI Components - Create new components
• 🧪 Testing - Increase test coverage
• 🌍 Translations - Add language support
• 🔧 Performance - Optimize existing code
• ♿ Accessibility - Improve accessibility features

🌟 Community Guidelines

• 📋 Contributing Guide - Detailed contribution instructions
• 📜 Code of Conduct - Community standards and expectations
• 🔒 Security Policy - Security reporting guidelines
• 📝 Commit Guidelines - How to write good commit messages

💡 Development Guidelines

• Code Style: Follow Effective Dart guidelines
• Testing: Write unit tests for business logic, widget tests for UI
• Documentation: Document public APIs with clear examples
• Commit Messages: Use Conventional Commits
• Pull Requests: Keep PRs focused and reasonably sized

🏆 Recognition

Contributors are recognized in:

• GitHub contributors page
• Project documentation
• Release notes
• Community showcases

📄 License & Legal

🔐 License: GNU Affero General Public License v3.0
📜 This project is open source under AGPL v3.0 license.
If you use this project in production, you must open source your modifications.

📎 Legal Information

• 📋 Full License: LICENSE file
• 🏢 Copyright: © 2025 MasterFabric Mobile
• 🌐 Official Website: https://osmea.masterfabric.co
• 📧 Contact: [email protected]

🌟 Community & Support

📚 Resources

• 📖 Documentation - Complete guides and API references

  • 📋 Checklists - Implementation and verification guides
  • 🎯 Guidance - Setup and configuration tutorials
  • 🔌 Plugins - Extension documentation
  • 📊 Versions - Release notes and history

• 🎮 Live Demo - Interactive component showcase

• 📖 Component Storybook - Component documentation and testing

• 🔍 API Explorer - API testing and exploration tool

💬 Get Help

• 🐛 Report Issues - Bug reports and feature requests
• 💬 Discussions - Community discussions and Q&A
• 📧 Contact - Direct support and inquiries
• 🔒 Security - Security vulnerability reports

🤝 Contributing

• 📋 Contributing Guide - How to contribute to OSMEA
• 📜 Code of Conduct - Community guidelines and expectations
• 🔒 Security Policy - Security reporting procedures
• 📝 Commit Guidelines - Commit message conventions
• 📋 Pull Request Template - PR submission guide

🎯 Built For

OSMEA is designed to serve a wide range of developers and use cases:

• ✅ Startups - Build MVPs faster with pre-built components
• ✅ Agencies - Manage multiple client storefronts efficiently
• ✅ Enterprises - Scale with modular architecture
• ✅ Freelancers - Deliver projects quickly with ready solutions
• ✅ Open Source Contributors - Join and shape the ecosystem
• ✅ Students & Learners - Learn e-commerce app development

🌍 Use Cases

🛒 E-commerce Applications

• Mobile storefronts for Shopify and WooCommerce
• Custom marketplace applications
• B2B and B2C commerce platforms

📱 Mobile Apps

• Cross-platform iOS and Android applications
• Progressive Web Apps (PWA)
• Hybrid mobile solutions

🌐 Web Applications

• Admin dashboards and management interfaces
• API exploration and testing tools
• Component documentation portals

🖥️ Desktop Applications

• Store management tools
• Internal business applications
• Analytics and reporting dashboards