"The Ultimate Flutter E-commerce Ecosystem"

🚀 Live Demo • 📚 Documentation • 🐛 Report Issues • 💬 Discussions

• 🌟 What is OSMEA?
  • 🎯 Our Vision
  • 🚀 Why OSMEA Exists
• 🏗️ OSMEA Ecosystem
  • 📦 Core Packages
  • 🚀 Ready-to-Use Applications
  • 🔄 In Development
• 🛠️ Technology Stack
  • Frontend & UI
  • Backend & APIs
  • Development & Quality
  • Deployment & Distribution
• 💡 Why Choose OSMEA?
  • ✅ What Makes OSMEA Unique?
  • 🛠️ Built For
• 📦 Core Packages
  • 🎨 OSMEA Components
  • 🔧 OSMEA Core
  • 🌐 OSMEA APIs
• 🏗️ Architecture Overview
• 🚀 Ready-to-Use Applications
• 📁 Project Structure
• ✨ Key Features
  • 🔌 Platform Integration
  • 📱 Mobile Experience
  • 🛍️ E-commerce Features
  • 🧰 Developer Tools
• 🚀 Getting Started
  • 📋 Prerequisites
  • 🎯 Choose Your Path
  • 🛠️ Development Setup
  • 🎮 Try the Live Demo
• 🤝 Contributing
  • How to Contribute
  • Current Opportunities
  • Development Guidelines
• 📄 License
• 🎯 Use Cases
  • 🛒 E-commerce Applications
  • 📱 Mobile Apps
  • 🌐 Web Applications
  • 🖥️ Desktop Applications
• 🌟 Community & Support
  • 📚 Resources
  • 💬 Get Help
  • 🤝 Contributing

OSMEA (Open Source Mobile E-commerce Architecture) is the most comprehensive Flutter ecosystem for building modern, scalable e-commerce applications. It's not just a framework—it's a complete solution that empowers developers to create production-ready mobile commerce experiences in record time.

"To revolutionize mobile e-commerce development by providing a unified, powerful, and extensible platform that eliminates complexity and accelerates innovation."

The e-commerce landscape is fragmented. Developers spend months building basic functionality that should be available out-of-the-box. OSMEA changes this by providing:

• 🏗️ Complete Architecture - Everything you need, nothing you don't
• ⚡ Rapid Development - Build 70% faster with pre-built components
• 🔌 Universal Integration - Works with Shopify, WooCommerce, and custom APIs
• 📱 Cross-Platform - One codebase, all platforms
• 🎨 Beautiful by Default - Material Design 3 with extensive customization

OSMEA consists of 3 core packages and 5 production-ready applications:

| 🎮 Components App | Interactive showcase | All Platforms | ✅ Ready | | 📖 Storybook | Documentation hub | Web | ✅ Ready | | 🔍 API Explorer | API testing tool | Web | ✅ Ready |

OSMEA is built with the most modern and reliable technologies:

• Flutter 3.19+ - Cross-platform UI framework with native performance
• Dart 2.17+ - Type-safe programming language with fast compilation
• Material Design 3 - Modern design system
• BLoC Pattern - Predictable state management for scalable apps

• Shopify API - E-commerce platform integration (REST + GraphQL)
• WooCommerce API - WordPress e-commerce integration
• OAuth 2.0 - Industry-standard authentication and authorization
• Firebase - Backend services, analytics, and real-time features

• VS Code - Primary IDE with Flutter extensions and debugging tools
• Git & GitHub Actions - Version control and automated CI/CD pipeline
• Flutter Test - Comprehensive testing suite with 95%+ coverage
• Flutter Lints - Code quality enforcement and best practices

• Vercel - Web application deployment with edge functions
• App Store & Google Play - Native app distribution
• GitHub Pages - Documentation hosting and project showcase

🔥 Platform Agnostic - Connects with Shopify, WooCommerce, and custom APIs
🧱 Modular & Composable - Each module is plug & play, build only what you need
🚀 Enterprise-Ready - CI/CD pipelines, test coverage, built for scale
🎨 Themeable & Customizable - Complete UI kit with your brand rules
📱 Cross-Platform - Single codebase for iOS, Android, Web, and Desktop
🔐 Secure & Scalable - Role-based access, Clean Architecture, async-safety

• ✅ Startups building fast MVPs
• ✅ Agencies managing multiple client storefronts
• ✅ Enterprises with modular architecture needs
• ✅ Open-source contributors ready to innovate

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

• 🎨 Components: Buttons, forms, layouts, navigation, dynamic components
• 📱 Responsive: Mobile-first design with adaptive layouts
• 🎯 Type Safe: Full type safety with Dart
• 🔧 Customizable: Extensive theming and styling options

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

• 🏗️ Architecture: Core classes and interfaces
• 🌐 i18n: Multi-language support with slang
• 💾 Storage: Local storage, database, preferences
• 🔐 Auth: User management and session handling
• 📊 Analytics: Firebase Analytics integration
• 🎨 Theming: Dynamic theme system

Comprehensive API network layer for e-commerce applications.

• 🛒 Platforms: Shopify, WooCommerce, BigCommerce
• 🔄 APIs: REST & GraphQL support
• 🔐 Security: OAuth 2.0 and API key support
• 📝 Logging: Network debugging and monitoring
• 🔧 DI: Injectable-based service architecture
• 🛡️ Error Handling: Robust error management

graph TB
    subgraph "OSMEA Ecosystem"
        subgraph "Core Packages"
            A[🎨 OSMEA Components<br/>UI Component Library]
            B[🔧 OSMEA Core<br/>Foundation & Utilities]
            C[🌐 OSMEA APIs<br/>Network Layer]
        end
        
        subgraph "Ready-to-Use Applications"
            F[🎮 Components App<br/>Component Showcase]
            G[📖 Storybook<br/>Documentation Hub]
            H[🔍 API Explorer<br/>API Testing Tool]
        end
        
        subgraph "In Development"
            D[🛍️ Storefront Woo<br/>E-commerce Mobile App]
            E[📊 Admin Dashboard<br/>Management Interface]
        end
        
        subgraph "Platform Support"
            I[📱 iOS]
            J[🤖 Android]
            K[🌐 Web]
            L[🖥️ Desktop]
        end
    end
    
    A --> B
    C --> B
    D --> A
    D --> B
    D --> C
    E --> A
    E --> B
    E --> C
    F --> A
    F --> B
    G --> A
    H --> C
    
    D --> I
    D --> J
    E --> K
    F --> I
    F --> J
    F --> K
    G --> K
    H --> K

Complete WooCommerce storefront with product browsing, cart, checkout, and orders. Built with Material Design 3 and BLoC pattern.

Interactive playground for exploring OSMEA components with live demos and customization controls.

Complete documentation environment with component testing, API references, and usage guidelines.

Powerful tool for testing Shopify, WooCommerce, and custom APIs with interactive debugging and visualization.

Comprehensive admin interface with analytics, product management, customer profiles, and order processing.

osmea/
├── 📦 packages/                    # Core packages
│   ├── components/                 # UI component library
│   ├── core/                      # Foundation utilities
│   └── apis/                      # API integration layer
├── 🚀 projects/                   # Ready-to-use applications
│   ├── storefront_woo/            # E-commerce mobile app
│   ├── admin_dashboard/           # Management interface
│   ├── components_app/            # Component showcase
│   ├── storybook/                 # Documentation hub
│   └── api_explorer/              # API testing tool
├── 📚 docs/                       # Documentation and guides
│   ├── assets/                    # Images and resources
│   ├── checklists/                # Development checklists
│   ├── guidance/                  # Setup guides
│   └── versions/                  # Version logs
├── 🌐 website/                    # Project website
└── 📋 rules/                      # Development rules and guidelines

• ✅ Multi-Platform Support: Shopify, WooCommerce, BigCommerce
• ✅ Unified API Layer: Consistent interface across platforms
• ✅ Authentication: OAuth 2.0 and API key support
• ✅ Webhook Management: Event-driven architecture
• ✅ Rate Limiting: Smart request throttling
• ✅ Analytics Integration: Firebase Analytics support

• ✅ Cross-Platform: iOS & Android from single codebase
• ✅ Material Design 3: Modern UI components
• ✅ Responsive Layouts: Works on all screen sizes
• ✅ Theme System: Dynamic color and style customization
• ✅ Internationalization: Multi-language support
• 🔄 Offline Support: Core functionality without internet (In Progress)

• ✅ Product Catalog: Browsing, search, filtering
• ✅ Cart & Checkout: Streamlined purchase flow
• ✅ Payment Integration: Multiple gateway support
• ✅ User Accounts: Registration, profiles, wishlists
• ✅ Order Management: History, tracking, reordering
• 🔄 Wishlist & Favorites: Save and manage favorite items (In Progress)

• ✅ Testing Suite: Unit, widget, and integration tests
• ✅ Documentation: Comprehensive guides and examples
• ✅ Live Demo: Interactive component showcase
• ✅ API Explorer: API testing and exploration tool
• 📋 CLI Toolkit: Rapid scaffolding and generators (Planned)
• 📋 CI/CD Templates: GitHub Actions and fastlane setup (Planned)

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

For E-commerce Mobile App:

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

# Navigate to storefront app
cd projects/storefront_woo

# Install dependencies
flutter pub get

# Run the app
flutter run --flavor dev  # Development
flutter run --flavor prod # Production

For Component Showcase:

# Navigate to components app
cd projects/components_app

# Install dependencies
flutter pub get

# Run the showcase
flutter run

Add to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  
  # UI Components
  osmea_components:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/components
  
  # Core utilities
  core:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/core
  
  # API layer
  apis:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/apis

Initialize in your app:

import 'package:core/core.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configure dependency injection
  await configureDependencies();
  
  runApp(MyApp());
}

# Install dependencies for all packages
flutter pub get

# Generate code (models, routes, etc.)
flutter packages pub run build_runner build

# Run tests
flutter test

# Build for production
flutter build apk --release  # Android
flutter build ios --release  # iOS
flutter build web --release  # Web

Experience OSMEA components in action:

• 🎮 Componenets App - Interactive component showcase
• 📖 Storybook - Component documentation
• 🔍 API Explorer - API testing tool

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

1. Fork the Repository

   git fork https://github.com/masterfabric-mobile/osmea.git

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

4. Submit a Pull Request

   • Create a Pull Request
   • Provide a clear description
   • Link related issues

Check out our Issues for:

• 🐛 Bug Reports: Help us fix issues
• ✨ Feature Requests: Suggest new features
• 📚 Documentation: Improve our docs
• 🎨 UI Components: Build new components

• Code Style: Follow Dart/Flutter conventions
• Testing: Write unit tests for new features
• Documentation: Update docs for API changes
• Commit Messages: Use conventional commits

🔐 License: GNU AGPL v3.0
📜 This project is protected under the GNU Affero General Public License v3.0.
If you modify and deploy this project publicly, you must also publish your changes under the same license.

📎 Full details available in the LICENSE file.

• Components: Product cards, shopping carts, checkout forms
• Core: User management, analytics, localization
• APIs: Shopify integration, payment processing

• Components: Navigation, forms, feedback components
• Core: Device utilities, storage, routing
• APIs: Backend communication, data synchronization

• Components: Responsive layouts, interactive elements
• Core: Browser utilities, session management
• APIs: RESTful API communication

• Components: Desktop-optimized UI components
• Core: Platform-specific utilities
• APIs: Local and remote data management

• 📖 Documentation - Complete guides and API references
• 🎮 Live Demo - Interactive component showcase
• 📖 Storybook - Component documentation and testing
• 🔍 API Explorer - API testing and exploration tool

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

• 📋 Contributing Guide - How to contribute to OSMEA
• 📜 Code of Conduct - Community guidelines
• 🔒 Security Policy - Security reporting