# bagisto/opensource-ecommerce-mobile-app architecture

> Architecture diagram of the GitHub repository bagisto/opensource-ecommerce-mobile-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bagisto/opensource-ecommerce-mobile-app
- Repository: https://github.com/bagisto/opensource-ecommerce-mobile-app

## Overview

##### Project Type & Purpose
- This is a cross-platform mobile (and desktop/web) application built with Flutter.
- It serves as an e-commerce storefront for a Bagisto/Laravel backend, consuming a GraphQL API.
- Core features include product browsing, search (MLKit & ARCore), cart, orders, payments, user account management, push notifications (FCM), theming, localization, and offline support.

##### File Structure & Architectural Patterns
- Top-level “android”, “ios”, “web”, “linux”, “macos”, “windows”: platform-specific Flutter hosts.
- “lib/”: shared Dart code subdivided into:
- data_model/ — DTOs for GraphQL queries & mutations
- screens/ — UI by feature, each using the BLoC (business logic component) pattern
- services/ — network layer (api_client.dart, graph_ql.dart, mutation_query.dart)
- utils/ — helpers (navigation, localization, theme, preferences, connectivity)
- widgets/ — reusable UI components
- assets/: static resources (images, Lottie, localization JSON)
- pubspec.yaml: Flutter/Dart dependencies

##### README Insights
- Frontend only; backend API module lives in a separate Bagisto/Laravel repo.
- Uses GraphQL for real-time sync of products/categories/orders.
- Requires Firebase Cloud Messaging for push notifications.
- Integrates ARCore and MLKit for camera-based search features.

a. Main Components
1. Flutter Client
- UI Layer (screens/widgets)
- BLoC Layer (feature blocs, events, states, repositories)
- Data Model Layer (GraphQL DTOs)
- Service Layer (HTTP/GraphQL client, query builder)
- Utility Layer (preferences, localization, theming, network monitor)
2. Platform Hosts
- Android/iOS/Web/Desktop wrappers invoking the Flutter engine
- Native integrations: FCM, camera permissions, ARCore, MLKit
3. External Services
- Bagisto GraphQL API (Laravel)
- Firebase Cloud Messaging
- (Optionally) Analytics / Crash Reporting
4. Data Stores
- On-device: SharedPreferences for caching tokens, theme/lang
- Remote: MySQL (in Laravel), accessible via GraphQL

b. Relationships & Data Flow
- UI triggers user actions → BLoC Event
- BLoC processes logic → calls Service Layer
- Service Layer issues GraphQL HTTP request → remote Bagisto API
- API returns JSON → Data Model parses into Dart objects
- BLoC emits new State → UI rebuilds
- Push notifications flow from FCM → platform host → Flutter (via FCM plugin) → BLoC → UI
- AR/ML flows: UI invites camera plugin → ARCore/MLKit SDK → returns results → Service Layer (for search)

c. Architectural Patterns & Design Principles
- Presentation/Business/Data separation via BLoC
- Single source of truth in GraphQL backend
- Dependency inversion: BLoCs depend on abstract repositories
- Reusability: shared widgets and utils
- Platform-agnostic core in “lib/”, platform-specific in host folders

d. Key Technologies
- Flutter & Dart
- BLoC state management
- GraphQL (queries + mutations)
- HTTP client (graphql_base_model, mutation_query)
- Firebase Cloud Messaging
- ARCore, MLKit (camera, image processing)
- SharedPreferences

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform Hosts
    subgraph "Platform Hosts"
        direction TB
        Android["Android Host\n(Native)"]:::host
        iOS["iOS Host\n(Native)"]:::host
        WebHost["Web Host Wrapper"]:::host
        LinuxHost["Linux Host Wrapper"]:::host
        MacOSHost["macOS Host Wrapper"]:::host
        WindowsHost["Windows Host Wrapper"]:::host

        Android_ARCore["ARCore Integration"]:::host
        Android_MLKit["MLKit Integration"]:::host
        Android_FCMConfig["FCM Config"]:::host
        iOS_MLKitPlugin["iOS MLKit Plugin"]:::host
        iOS_FCMConfig["iOS FCM Config"]:::host

        Android --> Android_ARCore
        Android --> Android_MLKit
        Android --> Android_FCMConfig
        iOS --> iOS_MLKitPlugin
        iOS --> iOS_FCMConfig

        click Android_ARCore "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/android/app/src/main/kotlin/webkul/bagisto_app_demo/arcore/"
        click Android_MLKit "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/android/app/src/main/kotlin/webkul/bagisto_app_demo/mlkit/"
        click Android_FCMConfig "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/android/app/google-services.json"
        click iOS_MLKitPlugin "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/ios/Runner/Classes/SwiftMlkitPlugin.swift"
        click iOS_FCMConfig "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/ios/GoogleService-Info.plist"
        click WebHost "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/web/"
        click LinuxHost "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/linux/main.cc"
        click MacOSHost "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/macos/Runner/"
        click WindowsHost "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/windows/runner/"
    end

    %% Flutter Core
    subgraph "Flutter Core" 
        direction TB
        subgraph "UI Layer" 
            direction TB
            UI["UI Layer\n(screens & widgets)"]:::ui
            Widgets["Reusable Widgets"]:::ui
        end
        subgraph "BLoC Layer" 
            direction TB
            Bloc["BLoC Layer\n(feature blocs)"]:::biz
        end
        subgraph "Service Layer" 
            direction TB
            APIClient["API Client"]:::svc
            GraphQLClient["GraphQL Client"]:::svc
            MutationQuery["Mutation & Query Builder"]:::svc
        end
        subgraph "Data Model Layer"
            DataModel["GraphQL DTOs"]:::data
        end
        subgraph "Utility Layer"
            direction TB
            Utils["Utility Helpers"]:::util
            PushNotif["PushNotificationsManager"]:::util
            SP_Helpers["SharedPref Helpers"]:::util
        end
    end

    %% External Services & Data Stores
    subgraph "External Services & Data Stores"
        direction TB
        BagistoAPI["Bagisto GraphQL API"]:::cloud
        Firebase["Firebase Cloud Messaging"]:::cloud
        SharedPref["SharedPreferences"]:::db
        MySQL["MySQL Database"]:::db
    end

    %% Connections
    Android -->|hosts Flutter| UI
    iOS -->|hosts Flutter| UI
    WebHost -->|hosts Flutter| UI
    LinuxHost -->|hosts Flutter| UI
    MacOSHost -->|hosts Flutter| UI
    WindowsHost -->|hosts Flutter| UI

    UI -->|"dispatch events"| Bloc
    Bloc -->|"calls"| APIClient
    Bloc -->|"calls"| GraphQLClient
    Bloc -->|"calls"| MutationQuery
    APIClient -->|"HTTP/GraphQL"| BagistoAPI
    GraphQLClient -->|"HTTP/GraphQL"| BagistoAPI
    MutationQuery -->|"builds queries"| BagistoAPI
    BagistoAPI -->|"returns JSON"| DataModel
    DataModel -->|"parsed models"| Bloc
    Bloc -->|"emits state"| UI

    Firebase -->|push notifications| Android
    Firebase -->|push notifications| iOS
    Android -->|via plugin| PushNotif
    iOS -->|via plugin| PushNotif
    PushNotif -->|events| Bloc

    UI -->|camera search| Android_ARCore
    UI -->|camera search| Android_MLKit
    UI -->|camera search| iOS_MLKitPlugin

    Utils -->|reads/writes| SharedPref
    SharedPref -->|caches tokens/theme| Bloc

    BagistoAPI -->|backed by| MySQL

    %% Click Events for Flutter Core
    click DataModel "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/lib/data_model/"
    click Bloc "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/lib/screens/**/bloc/"
    click APIClient "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/services/api_client.dart"
    click GraphQLClient "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/services/graph_ql.dart"
    click MutationQuery "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/services/mutation_query.dart"
    click Utils "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/lib/utils/"
    click Widgets "https://github.com/bagisto/opensource-ecommerce-mobile-app/tree/main/lib/widgets/"
    click PushNotif "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/utils/push_notifications_manager.dart"
    click SP_Helpers "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/utils/shared_preference_helper.dart"
    %% Note: shared_preference_keys is part of helpers directory
    click SP_Helpers "https://github.com/bagisto/opensource-ecommerce-mobile-app/blob/main/lib/utils/shared_preference_keys.dart"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef biz fill:#E0F2E0,stroke:#28A745,color:#28A745
    classDef svc fill:#FFE5CC,stroke:#FF8C00,color:#FF8C00
    classDef data fill:#FFF5D0,stroke:#D4AF37,color:#D4AF37
    classDef util fill:#F0F0F0,stroke:#6C757D,color:#6C757D
    classDef host fill:#EEEEEE,stroke:#6C757D,color:#6C757D
    classDef cloud fill:#E8E8FF,stroke:#6A5ACD,color:#6A5ACD
    classDef db fill:#F5F5F5,stroke:#A9A9A9,color:#A9A9A9
```
