# theemomo/flutter-e-commerce-app architecture

> Architecture diagram of the GitHub repository theemomo/flutter-e-commerce-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theemomo/flutter-e-commerce-app
- Repository: https://github.com/theemomo/flutter-e-commerce-app

## Overview

##### Project type and purpose
- This is a cross-platform (Android, iOS, Web, Linux, macOS, Windows) e-commerce client built in Flutter.
- It uses Firebase for authentication and Firestore for persistent data (products, cart, favorites, users).

##### Key architectural layers (from top to bottom)
A. Platform Shells
- Android (MainActivity.kt)
- iOS (AppDelegate.swift)
- Web (index.html + Flutter Web loader)
- Desktop (linux/main.cc, macos/AppDelegate.swift, windows/main.cpp)
B. Flutter Engine & Dart VM
- Embeds Dart code on each platform
C. Presentation Layer (lib/views)
- Pages (e.g., home_page, cart_page, product_details_page)
- Widgets (reusable UI components)
D. State Management Layer (lib/view_models)
- Cubits (AuthCubit, HomeCubit, CartCubit, etc.)
- States (AuthState, HomeState, etc.)
E. Domain / Service Layer (lib/services + lib/utils)
- Service classes (AuthServicesImpl, FirestoreServices, CartServicesImpl, etc.)
- Utility helpers (api_paths.dart, app_router.dart)
F. Data Models (lib/models)
- DTOs/models (ProductItemModel, CartItemModel, PromoCodeModel, UserData, etc.)
G. External Backend (Firebase)
- Firebase Authentication
- Cloud Firestore (collections: products, cart, favorites, users)

##### Relationships & Data Flow
- UI Widgets emit user events →
- Corresponding Cubit handles event →
- Cubit calls a Service method →
- Service interacts with Firebase SDK →
- Firebase returns data →
- Service maps raw data to Models →
- Cubit emits new State →
- UI rebuilds based on updated State.

##### Architectural Patterns & Design Principles
- BLoC/Cubit Pattern: clear separation of presentation and business logic.
- Clean Architecture: UI → State → Services → Data → External.
- Single Responsibility: each Cubit and Service has one job.
- Modular Structure: Models ↔ Services ↔ Cubits ↔ Views.

##### Technologies & Frameworks
- Flutter & Dart
- flutter_bloc (Cubit) for state management
- firebase_auth, cloud_firestore for back-end
- flutter_carousel_widget, cached_network_image, equatable, fluttertoast

- A title (“Flutter E-Commerce App Architecture”) and a brief footnote listing the BLoC + Clean Services pattern.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Platform Shells
    subgraph "Platform Shells"
        direction TB
        Android["Android\n(MainActivity.kt)"]:::platform
        IOS["iOS\n(AppDelegate.swift)"]:::platform
        Web["Web\n(index.html)"]:::platform
        Linux["Linux\n(main.cc)"]:::platform
        macOS["macOS\n(AppDelegate.swift)"]:::platform
        Windows["Windows\n(main.cpp)"]:::platform
    end

    %% Engine
    FlutterEngine["Flutter Engine & Dart VM\n(lib/main.dart)"]:::engine

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Pages["Pages\n(lib/views/pages)"]:::presentation
        Widgets["Widgets\n(lib/views/widgets)"]:::presentation
    end

    %% State Management Layer
    subgraph "State Management Layer"
        direction TB
        AuthCubit["AuthCubit"]:::state
        HomeCubit["HomeCubit"]:::state
        CartCubit["CartCubit"]:::state
        ProductDetailsCubit["ProductDetailsCubit"]:::state
        FavoriteCubit["FavoriteCubit"]:::state
        LocationCubit["LocationCubit"]:::state
        CheckoutCubit["CheckoutCubit"]:::state
        PaymentMethodsCubit["PaymentMethodsCubit"]:::state
        UserDataCubit["UserDataCubit"]:::state
    end

    %% Domain / Services & Utilities
    subgraph "Domain / Service Layer"
        direction TB
        Services["Services"]:::services
        Utils["Utilities"]:::services
    end

    %% Data Models
    Models["Data Models"]:::models

    %% External Backend
    subgraph "Firebase Backend"
        direction TB
        AuthBackend["Firebase Auth"]:::external
        Firestore["Cloud Firestore"]:::external
    end

    %% Connections
    Android --> FlutterEngine
    IOS --> FlutterEngine
    Web --> FlutterEngine
    Linux --> FlutterEngine
    macOS --> FlutterEngine
    Windows --> FlutterEngine

    FlutterEngine --> Pages
    FlutterEngine --> Widgets

    Pages --> AuthCubit
    Pages --> HomeCubit
    Pages --> CartCubit
    Pages --> ProductDetailsCubit
    Pages --> FavoriteCubit
    Pages --> LocationCubit
    Pages --> CheckoutCubit
    Pages --> PaymentMethodsCubit
    Pages --> UserDataCubit

    Widgets --> AuthCubit
    Widgets --> HomeCubit

    AuthCubit --> Services
    HomeCubit --> Services
    CartCubit --> Services
    ProductDetailsCubit --> Services
    FavoriteCubit --> Services
    LocationCubit --> Services
    CheckoutCubit --> Services
    PaymentMethodsCubit --> Services
    UserDataCubit --> Services

    Services --> AuthBackend
    Services --> Firestore

    AuthBackend --> Services
    Firestore --> Services

    Services --> AuthCubit
    Services --> HomeCubit
    Services --> CartCubit
    Services --> ProductDetailsCubit
    Services --> FavoriteCubit
    Services --> LocationCubit
    Services --> CheckoutCubit
    Services --> PaymentMethodsCubit
    Services --> UserDataCubit

    AuthCubit --> Pages
    HomeCubit --> Pages
    CartCubit --> Pages
    ProductDetailsCubit --> Pages

    %% Click Events
    click Android "https://github.com/theemomo/flutter-e-commerce-app/blob/master/android/app/src/main/kotlin/com/example/e_commerce/MainActivity.kt"
    click IOS "https://github.com/theemomo/flutter-e-commerce-app/blob/master/ios/Runner/AppDelegate.swift"
    click Web "https://github.com/theemomo/flutter-e-commerce-app/blob/master/web/index.html"
    click Linux "https://github.com/theemomo/flutter-e-commerce-app/blob/master/linux/runner/main.cc"
    click macOS "https://github.com/theemomo/flutter-e-commerce-app/blob/master/macos/Runner/AppDelegate.swift"
    click Windows "https://github.com/theemomo/flutter-e-commerce-app/blob/master/windows/runner/main.cpp"
    click FlutterEngine "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/main.dart"

    click Pages "https://github.com/theemomo/flutter-e-commerce-app/tree/master/lib/views/pages"
    click Widgets "https://github.com/theemomo/flutter-e-commerce-app/tree/master/lib/views/widgets"

    click AuthCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/auth_cubit/auth_cubit.dart"
    click HomeCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/home_cubit/home_cubit.dart"
    click CartCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/cart_cubit/cart_cubit.dart"
    click ProductDetailsCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/product_details_cubit/product_details_cubit.dart"
    click FavoriteCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/favorite_cubit/favorite_cubit.dart"
    click LocationCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/location_cubit/location_cubit.dart"
    click CheckoutCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/checkout_cubit/checkout_cubit.dart"
    click PaymentMethodsCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/payment_methods_cubit/payment_methods_cubit.dart"
    click UserDataCubit "https://github.com/theemomo/flutter-e-commerce-app/blob/master/lib/view_models/user_data_cubit/user_data_cubit.dart"

    click Services "https://github.com/theemomo/flutter-e-commerce-app/tree/master/lib/services"
    click Utils "https://github.com/theemomo/flutter-e-commerce-app/tree/master/lib/utils"

    click Models "https://github.com/theemomo/flutter-e-commerce-app/tree/master/lib/models"

    %% Styles
    classDef platform fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef engine fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef state fill:#90EE90,stroke:#333,stroke-width:1px
    classDef services fill:#FFA500,stroke:#333,stroke-width:1px
    classDef models fill:#FFFF66,stroke:#333,stroke-width:1px
    classDef external fill:#F08080,stroke:#333,stroke-width:1px
```
