osmea

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #llm #golang #machine-learning #nodejs #windows #cli #kubernetes #pytorch #ios #open-source

(★ 118)

MasterFabric represents the architecture of e-commerce mobile apps.Enterprise-level Flutter development.

osmea Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OSMEA ®️
### Open Source Mobile E-commerce App Builder Tool

[![Version](https://img.shields.io/badge/version-1.0.0-2D3748?style=for-the-badge&logo=flutter&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea)
[![Platform](https://img.shields.io/badge/platform-Flutter-2D3748?style=for-the-badge&logo=flutter&logoColor=white&labelColor=1A202C)](https://flutter.dev)
[![Firebase](https://img.shields.io/badge/firebase-2D3748?style=for-the-badge&logo=firebase&logoColor=white&labelColor=1A202C)](https://firebase.google.com)
[![Shopify](https://img.shields.io/badge/shopify-2D3748?style=for-the-badge&logo=shopify&logoColor=white&labelColor=1A202C)](https://shopify.dev)
[![WooCommerce](https://img.shields.io/badge/woocommerce-2D3748?style=for-the-badge&logo=woocommerce&logoColor=white&labelColor=1A202C)](https://woocommerce.com)
[![Supabase](https://img.shields.io/badge/supabase-2D3748?style=for-the-badge&logo=supabase&logoColor=white&labelColor=1A202C)](https://supabase.com)
[![REST API](https://img.shields.io/badge/REST%20API-2D3748?style=for-the-badge&logo=rest&logoColor=white&labelColor=1A202C)](https://restfulapi.net)
[![GraphQL](https://img.shields.io/badge/GraphQL-2D3748?style=for-the-badge&logo=graphql&logoColor=white&labelColor=1A202C)](https://graphql.org)
[![GitHub stars](https://img.shields.io/github/stars/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/network/members)
[![GitHub issues](https://img.shields.io/github/issues/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/issues)
[![GitHub pull requests](https://img.shields.io/github/issues-pr/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/pulls)
[![GitHub contributors](https://img.shields.io/github/contributors/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/graphs/contributors)
[![GitHub last commit](https://img.shields.io/github/last-commit/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/commits)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/masterfabric-mobile/osmea?style=for-the-badge&logo=github&logoColor=white&labelColor=1A202C)](https://github.com/masterfabric-mobile/osmea/graphs/commit-activity)
[![License](https://img.shields.io/badge/license-AGPL%20v3.0-2D3748?style=for-the-badge&logo=gnu&logoColor=white&labelColor=1A202C)](https://raw.githubusercontent.com/masterfabric-mobile/osmea/dev/LICENSE)

</div>

<div align="center">
<img src = "https://github.com/masterfabric-mobile/osmea/blob/OSMEA-Docs/docs/assets/osmea_banner_v2.png?raw=true" width="800" alt="OSMEA Banner">
  
  **"OSMEA is not just a framework — it's an ecosystem."**
  
  [🚀 Live Demo](https://components.masterfabric.co) • [📚 Documentation](https://github.com/masterfabric-mobile/osmea/tree/dev/docs) • [🔍 API Explorer](https://github.com/masterfabric-mobile/osmea/tree/dev/projects/api_explorer) • [🎮 Component Showcase](https://components.masterfabric.co)
</div>

---

## 📋 Table of Contents

- [📊 Project Statistics](#-project-statistics)
- [🌟 What is OSMEA?](#-what-is-osmea)
  - [🎯 Our Mission](#-our-mission)
  - [⚡ Why Choose OSMEA?](#-why-choose-osmea)
- [🏗️ OSMEA Ecosystem Architecture](#️-osmea-ecosystem-architecture)
  - [📦 Core Packages](#-core-packages)
  - [🚀 Ready-to-Use Applications](#-ready-to-use-applications)
  - [🛠️ Development Tools](#️-development-tools)
- [🛠️ Technology Stack](#️-technology-stack)
  - [Frontend & Mobile](#frontend--mobile)
  - [Backend & APIs](#backend--apis)
  - [E-commerce Platforms](#e-commerce-platforms)
  - [Development & DevOps](#development--devops)
- [✨ Key Features & Benefits](#-key-features--benefits)
  - [🚀 Developer Experience](#-developer-experience)
  - [🛒 E-commerce Features](#-e-commerce-features)
  - [📱 Cross-Platform Excellence](#-cross-platform-excellence)
- [🚀 Getting Started](#-getting-started)
  - [📋 Prerequisites](#-prerequisites)
  - [⚡ Quick Start](#-quick-start-recommended)
  - [🎯 Choose Your Application](#-choose-your-application)
- [📚 Architecture & Documentation](#-architecture--documentation)
  - [🏗️ Project Structure](#️-project-structure)
  - [📖 Documentation Hub](#-documentation-hub)
  - [🧠 Architecture Principles](#-architecture-principles)
- [📦 Package Details](#-package-details)
  - [🎨 OSMEA Components](#-osmea-components)
  - [🔧 OSMEA Core](#-osmea-core)
  - [🌐 OSMEA APIs](#-osmea-apis)
- [🚀 Application Showcase](#-application-showcase)
- [🤝 Contributing & Community](#-contributing--community)
  - [👥 How to Contribute](#-how-to-contribute)
  - [🎯 Current Opportunities](#-current-opportunities)
  - [🌟 Community Guidelines](#-community-guidelines)
- [📄 License & Legal](#-license--legal)
  - [📎 Legal Information](#-legal-information)
  - [⚖️ Usage Guidelines](#️-usage-guidelines)
- [🌟 Community & Support](#-community--support)

---

## 📊 Project Statistics

| Metric | Value | Metric | Value |
|--------|-------|--------|-------|
| ⭐ GitHub Stars | 101+ | 🍴 Forks | 23+ |
| 📂 Core Packages | 3 | 🚀 Applications | 6 |
| 🐛 Open Issues | 7 | 👥 Contributors | Active |
| 📅 Last Updated | Recently | 🏢 License | AGPL v3.0 |

**🎯 Topics:** `ecommerce` `flutter` `mobile` `shopify` `woocommerce` `supabase`

**🌐 Homepage:** [https://osmea.masterfabric.co](https://osmea.masterfabric.co)

</div>

---

## 🌟 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](packages/apis/)** 
**Backend integration** | ✅ Production Ready  
REST/GraphQL • Shopify • WooCommerce • Auth • Error handling

#### 🎨 **[Components](packages/components/)**
**UI component library** | ✅ Production Ready  
50+ components • Material Design 3 • Responsive layouts

#### 🔧 **[Core](packages/core/)**
**Foundation utilities** | ✅ Production Ready  
DI • Storage • Analytics • Theming • i18n support

### 🚀 **Ready-to-Use Applications** (6)

| Application | Platform | Status | Purpose |
|-------------|----------|--------|---------|
| **[📊 Admin Dashboard](projects/admin_dashboard/)** | Web | 🔄 Development | Management interface with analytics |
| **[🔍 API Explorer](projects/api_explorer/)** | Web | ✅ Ready | API testing & debugging tool |
| **[🎮 Components App](projects/components_app/)** | All Platforms | ✅ Ready | Interactive component showcase |
| **[🛍️ Storefront Supabase](projects/storefront_supabase/)** | iOS/Android | 🔄 Development | Supabase-powered e-commerce app |
| **[🛒 Storefront Woo](projects/storefront_woo/)** | iOS/Android | 🔄 Development | WooCommerce integration app |
| **[📖 Storybook](projects/storybook/)** | Web | ✅ Ready | Component documentation hub |

### 🛠️ **Development Tools**

- ⚙️ **[Automated Setup](setup.sh)** - One-command initialization script
- 📚 **[Comprehensive Docs](docs/)** - Guides, checklists, examples
- 🧪 **Testing Framework** - Unit, widget, integration tests
- 📋 **[Development Rules](rules/)** - Coding standards and guidelines
- 🔌 **[Plugin Documentation](docs/plugins/)** - Extension guides
- 📊 **[Version Logs](docs/versions/)** - 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**

```bash
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/`](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/`](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/`](docs/plugins/)
Custom plugin documentation:
- **MasterFabric Wishlist** - WordPress wishlist plugin
- **OSMEA App Config Manager** - App configuration plugin

#### **📊 Versions** - [`docs/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:

| Principle | Implementation | Benefits |
|-----------|----------------|----------|
| **🏛️ Clean Architecture** | Separation of Concerns, Domain-Driven Design, Dependency Rule | Clear layer boundaries, business logic isolation, testability |
| **⚡ SOLID Principles** | Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion | Maintainable code, easy to extend, reduced coupling |
| **🔄 State Management** | BLoC Pattern, Predictable State, Reactive Programming | Clear state transitions, stream-based architecture, scalability |
| **💉 Dependency Injection** | Injectable code generation, GetIt service locator | Loose coupling, easy testing, flexible architecture |
| **🧩 Modular Design** | Package structure, Plugin architecture, Composition over inheritance | Extensible system, reusable components, maintainability |

---

## 🚀 Getting Started

### 📋 **Prerequisites**

- **Flutter SDK** 3.19.0 or higher ([Install Flutter](https://docs.flutter.dev/get-started/install))
- **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)

```bash
# 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**

```bash
# 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](https://components.masterfabric.co)** - Interactive component playground
- 🔍 **[API Explorer](https://github.com/masterfabric-mobile/osmea/tree/dev/projects/api_explorer)** - API testing interface
- 📚 **[Storybook](https://github.com/masterfabric-mobile/osmea/tree/dev/projects/storybook)** - Component documentation

### 🎯 **Choose Your Application**

```bash
# 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**

```bash
# 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](packages/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:**
```yaml
dependencies:
  osmea_components:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/components
```

### 🔧 [OSMEA Core](packages/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:**
```yaml
dependencies:
  core:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/core
```

### 🌐 [OSMEA APIs](packages/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:**
```yaml
dependencies:
  apis:
    git:
      url: https://github.com/masterfabric-mobile/osmea.git
      path: packages/apis
```

---

## 🚀 Application Showcase

<details>
<summary><strong>📊 Admin Dashboard</strong> - Management interface | 🌐 Web | 🔄 In Development</summary>

### [Admin Dashboard](projects/admin_dashboard/)
**Comprehensive management interface for e-commerce operations**

**Purpose:** Store management, analytics, and administration

**Key Features:**
- 📊 **Analytics Dashboard**: Sales metrics, customer insights
- 📦 **Product Management**: CRUD operations, inventory tracking
- 👥 **Customer Profiles**: User management and history
- 🛒 **Order Processing**: Order management and fulfillment
- 💰 **Revenue Tracking**: Financial reports and analytics
- ⚙️ **Settings**: Store configuration and preferences

</details>

<details>
<summary><strong>🔍 API Explorer</strong> - API testing tool | 🌐 Web | ✅ Production Ready</summary>

### [API Explorer](projects/api_explorer/)
**Interactive API testing and exploration tool**

**Purpose:** API testing, debugging, and documentation

**Key Features:**
- 🔌 **Multi-Platform Support**: Test Shopify, WooCommerce, Supabase APIs
- 📝 **Request Builder**: Interactive API request construction
- 🐛 **Debugging Tools**: Network inspection and error analysis
- 📊 **Response Viewer**: JSON formatter and visualizer
- 💾 **Request History**: Save and replay API requests
- 📚 **API Documentation**: Integrated API reference

</details>

<details open>
<summary><strong>🎮 Components App</strong> - Interactive showcase | 📱 All Platforms | ✅ Production Ready | <a href="https://components.masterfabric.co">🚀 Live Demo</a></summary>

### [Components App](projects/components_app/)
**Interactive showcase of all OSMEA components**

**Purpose:** Component exploration and testing

**Key Features:**
- 🎨 **Live Preview**: Real-time component rendering
- 🎛️ **Customization Controls**: Interactive property adjustment
- 📱 **Responsive Testing**: View on different screen sizes
- 🎨 **Theme Switching**: Test light and dark themes
- 📋 **Code Examples**: Copy-paste ready code snippets
- 🔍 **Search**: Quick component discovery

**🌐 Try it now:** [https://components.masterfabric.co](https://components.masterfabric.co)

</details>

<details>
<summary><strong>🛍️ Storefront Supabase</strong> - Supabase e-commerce | 📱 iOS, Android | 🔄 In Development</summary>

### [Storefront Supabase](projects/storefront_supabase/)
**Modern e-commerce app powered by Supabase**

**Purpose:** Full-featured e-commerce mobile application

**Key Features:**
- 🏪 **Product Catalog**: Browse, search, filter products
- 🛒 **Shopping Cart**: Add, remove, update quantities
- 💳 **Checkout**: Secure payment processing
- 👤 **User Accounts**: Registration, login, profiles
- 📦 **Order History**: Track orders and shipments
- ⭐ **Wishlist**: Save favorite products
- 🔔 **Push Notifications**: Order updates and promotions

</details>

<details>
<summary><strong>🛒 Storefront Woo</strong> - WooCommerce app | 📱 iOS, Android | 🔄 In Development</summary>

### [Storefront Woo](projects/storefront_woo/)
**Complete WooCommerce mobile application**

**Purpose:** WordPress WooCommerce integration

**Key Features:**
- 🏪 **WooCommerce Integration**: Full REST API integration
- 🛒 **E-commerce Features**: Complete shopping experience
- 💳 **Payment Gateways**: Multiple payment options
- 📦 **Order Management**: Complete order lifecycle
- 👤 **WordPress Auth**: Seamless user authentication
- 🎨 **Customizable**: Brand-specific theming
- 🌍 **Multi-language**: i18n support

</details>

<details>
<summary><strong>📖 Storybook</strong> - Documentation hub | 🌐 Web | ✅ Production Ready</summary>

### [Storybook](projects/storybook/)
**Component documentation and testing hub**

**Purpose:** Component documentation and visual testing

**Key Features:**
- 📚 **Comprehensive Docs**: Detailed component documentation
- 🎨 **Visual Testing**: Component state visualization
- 📋 **API Reference**: Props and usage guidelines
- 🔍 **Search**: Quick documentation access
- 💡 **Examples**: Real-world usage scenarios
- 🎨 **Theme Preview**: Test components in different themes

</details>

---

## 🤝 Contributing & Community

### 👥 **How to Contribute**

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

1. **🍴 Fork the Repository**
   ```bash
   git clone https://github.com/masterfabric-mobile/osmea.git
   cd osmea
   ```

2. **🌿 Create a Feature Branch**
   ```bash
   git checkout -b feature/amazing-feature
   ```

3. **💻 Make Your Changes**
   - Follow our [coding standards](rules/)
   - Write tests for new features
   - Update documentation
   - Follow the [commit guidelines](commits.md)

4. **🧪 Test Your Changes**
   ```bash
   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](pull_request_template.md)
   - Provide clear description
   - Link related issues
   - Request reviews

### 🎯 **Current Opportunities**

Check out our [Issues](https://github.com/masterfabric-mobile/osmea/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](CONTRIBUTING.md)** - Detailed contribution instructions
- 📜 **[Code of Conduct](CODE_OF_CONDUCT.md)** - Community standards and expectations
- 🔒 **[Security Policy](SECURITY.md)** - Security reporting guidelines
- 📝 **[Commit Guidelines](commits.md)** - How to write good commit messages

### 💡 **Development Guidelines**

- **Code Style**: Follow [Effective Dart](https://dart.dev/guides/language/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](https://www.conventionalcommits.org/)
- **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](LICENSE) file
- 🏢 **Copyright**: © 2025 MasterFabric Mobile
- 🌐 **Official Website**: [https://osmea.masterfabric.co](https://osmea.masterfabric.co)
- 📧 **Contact**: support@masterfabric.co

---

## 🌟 Community & Support

### 📚 **Resources**

- **[📖 Documentation](https://github.com/masterfabric-mobile/osmea/tree/dev/docs)** - Complete guides and API references
  - [📋 Checklists](docs/checklists/) - Implementation and verification guides
  - [🎯 Guidance](docs/guidance/) - Setup and configuration tutorials
  - [🔌 Plugins](docs/plugins/) - Extension documentation
  - [📊 Versions](docs/versions/) - Release notes and history

- **[🎮 Live Demo](https://components.masterfabric.co)** - Interactive component showcase
- **[📖 Component Storybook](https://github.com/masterfabric-mobile/osmea/tree/dev/projects/storybook)** - Component documentation and testing
- **[🔍 API Explorer](https://github.com/masterfabric-mobile/osmea/tree/dev/projects/api_explorer)** - API testing and exploration tool

### 💬 **Get Help**

- **[🐛 Report Issues](https://github.com/masterfabric-mobile/osmea/issues)** - Bug reports and feature requests
- **[💬 Discussions](https://github.com/masterfabric-mobile/osmea/discussions)** - Community discussions and Q&A
- **[📧 Contact](mailto:support@masterfabric.co)** - Direct support and inquiries
- **[🔒 Security](mailto:security@masterfabric.co)** - Security vulnerability reports

### 🤝 **Contributing**

- **[📋 Contributing Guide](CONTRIBUTING.md)** - How to contribute to OSMEA
- **[📜 Code of Conduct](CODE_OF_CONDUCT.md)** - Community guidelines and expectations
- **[🔒 Security Policy](SECURITY.md)** - Security reporting procedures
- **[📝 Commit Guidelines](commits.md)** - Commit message conventions
- **[📋 Pull Request Template](pull_request_template.md)** - 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

---

### 🚀 **[Try Live Demo →](https://components.masterfabric.co)**

Experience all components in action with our interactive demo application.

**Start building your e-commerce app today!**

</div>

---

**Built with ❤️ by the OSMEA Team**

*MasterFabric represents the architecture of e-commerce mobile apps.*

**🌐 [Website](https://osmea.masterfabric.co)** • **📚 [Documentation](https://github.com/masterfabric-mobile/osmea/tree/dev/docs)** • **🐛 [Issues](https://github.com/masterfabric-mobile/osmea/issues)** • **💬 [Discussions](https://github.com/masterfabric-mobile/osmea/discussions)**

[⬆ Back to Top](#osmea-️)

</div>

osmea

osmea Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

osmea

osmea Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README