# tharwatsamy/e_commerce_app architecture

> Architecture diagram of the GitHub repository tharwatsamy/e_commerce_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tharwatsamy/e_commerce_app
- Repository: https://github.com/tharwatsamy/e_commerce_app

## Overview

1. **Overall shape**
   - This is a **Flutter mobile app** named `buy_it`, built once in `lib/` and packaged for **Android and iOS** through the standard Flutter platform shells under `android/` and `ios/`.

2. **Primary feature split**
   - The app is organized around two user roles:
     - **Customer/user flow**: browse products, view details, manage cart.
     - **Admin flow**: manage products and orders.
   - That split is explicit in `lib/screens/user/` and `lib/screens/admin/`, with `adminMode.dart` acting as a role/state switch.

3. **App entry and bootstrap**
   - `lib/main.dart` is the app entrypoint and likely wires up global providers, theming, and initial routing/auth checks.
   - The presence of `provider/` suggests the app uses **Provider-based state management** rather than local widget state alone.

4. **UI layer**
   - Screens are the main presentation boundary:
     - `login_screen.dart`, `signup_screen.dart`
     - user screens: `homePage.dart`, `productInfo.dart`, `CartScreen.dart`
     - admin screens: `adminHome.dart`, `addProduct.dart`, `editProduct.dart`, `manageProduct.dart`, `OrdersScreen.dart`, `order_details.dart`
   - Shared widgets in `lib/widgets/` encapsulate reusable UI such as product cards, custom text fields, menu, and logo.

5. **State and interaction model**
   - `provider/modelHud.dart` likely controls async/loading UI state.
   - `provider/cartItem.dart` represents cart state and cart item behavior.
   - `provider/adminMode.dart` manages whether the app is in admin or customer mode.
   - These providers form the main bridge between screens and business logic.

6. **Domain models**
   - `models/product.dart` and `models/order.dart` define the core data entities used across the app.
   - These models are the shared contract between UI, state, and backend services.

7. **Backend/service boundary**
   - `services/auth.dart` handles authentication concerns.
   - `services/store.dart` likely handles product/order persistence and retrieval.
   - The existence of `android/app/google-services.json` strongly suggests **Firebase** is the backend integration layer, even though the repo tree alone doesn’t show the exact products used.

8. **Data flow through the app**
   - Typical flow is:
     - user signs in/signs up through auth screens
     - app loads product catalog through store service
     - user adds items to cart through cart provider
     - checkout/order data moves into the order model and then into admin order views
   - Admin flows branch off the same core data, but with create/update/delete operations for products and order management.

9. **Asset and content layer**
   - Static assets live outside `lib/` in `images/` and `fonts/`.
   - Product imagery is organized by category folders such as `jackets`, `shoes`, `t-shirts`, and `trousers`, which matches the app’s e-commerce domain.
   - `images/icons` likely holds UI icons used by custom widgets and menus.

10. **Platform integration**
    - `android/` and `ios/` are mostly generated Flutter host projects, but they matter architecturally because they carry:
      - app startup shells
      - native manifests/configuration
      - Firebase/Google services wiring on Android
      - iOS app lifecycle setup in `AppDelegate.swift`
    - These layers are thin wrappers around the shared Flutter code.

11. **Navigation and composition**
    - The app is likely screen-driven with navigation between auth, catalog, product detail, cart, and admin management pages.
    - `custom_menu.dart` suggests some reusable navigation or drawer/menu component that mediates access to major sections.

12. **Testing and maintenance**
    - `test/widget_test.dart` is the default Flutter test entrypoint, so automated coverage appears minimal or starter-level.
    - The repo is otherwise feature-complete for a single-client mobile commerce app with role-based screens and backend-backed state.

13. **What to draw in an architecture diagram**
    - Show three major layers:
      - **Presentation**: user/admin screens + shared widgets
      - **State/domain**: providers + models
      - **Services/backend**: auth/store, likely Firebase
    - Add separate platform shells for Android and iOS, and a shared asset layer for product images/icons.

Main entry points: [`lib/main.dart`](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/main.dart) (Main), [`lib/services/store.dart`](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/services/store.dart) (Store), [`lib/screens/admin/manageProduct.dart`](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/manageProduct.dart) (Manage Product), [`lib/screens/admin/OrdersScreen.dart`](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/OrdersScreen.dart) (Orders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_main["Main<br/>flutter entrypoint<br/>[main.dart]"]
  node_login["Login<br/>auth screen<br/>[login_screen.dart]"]
  node_signup["Sign Up<br/>auth screen<br/>[signup_screen.dart]"]
  node_home["Home<br/>customer screen<br/>[homePage.dart]"]
  node_product_info["Product Info<br/>customer screen<br/>[productInfo.dart]"]
  node_cart["Cart<br/>customer screen<br/>[CartScreen.dart]"]
  node_admin_home["Admin Home<br/>admin screen<br/>[adminHome.dart]"]
  node_manage_product["Manage Product<br/>admin screen<br/>[manageProduct.dart]"]
  node_add_product["Add Product<br/>admin screen<br/>[addProduct.dart]"]
  node_edit_product["Edit Product<br/>admin screen<br/>[editProduct.dart]"]
  node_orders["Orders<br/>admin screen<br/>[OrdersScreen.dart]"]
  node_order_details["Order Details<br/>admin screen<br/>[order_details.dart]"]
  node_product_view["Product View<br/>shared widget<br/>[productView.dart]"]
  node_menu["Menu<br/>shared widget<br/>[custom_menu.dart]"]
end

subgraph group_state["State & Domain"]
  node_admin_mode(("Admin Mode<br/>provider<br/>[adminMode.dart]"))
  node_cart_state(("Cart State<br/>provider<br/>[cartItem.dart]"))
  node_loading_state(("Loading State<br/>provider<br/>[modelHud.dart]"))
  node_product_model{{"Product<br/>model<br/>[product.dart]"}}
  node_order_model{{"Order<br/>model<br/>[order.dart]"}}
end

subgraph group_services["Services"]
  node_auth_service["Auth<br/>[auth.dart]"]
  node_store_service[("Store<br/>[store.dart]")]
end

subgraph group_platform["Platform Shells"]
  node_android_shell["Android<br/>platform shell"]
  node_ios_shell["iOS<br/>platform shell"]
  node_google_services["Firebase Config<br/>native config"]
end

subgraph group_assets["Assets"]
  node_images[("Images<br/>asset library")]
  node_fonts[("Fonts<br/>asset library")]
end

node_main -->|"starts at"| node_login
node_main -->|"loads"| node_home
node_main -->|"branches to"| node_admin_home
node_main -->|"uses"| node_admin_mode
node_main -->|"uses"| node_loading_state
node_login -->|"authenticates via"| node_auth_service
node_signup -->|"registers via"| node_auth_service
node_home -->|"renders"| node_product_view
node_home -->|"shows"| node_product_model
node_product_info -->|"adds to"| node_cart_state
node_cart -->|"reads"| node_cart_state
node_cart_state -->|"contains"| node_product_model
node_admin_home -->|"navigates to"| node_manage_product
node_manage_product -->|"creates"| node_add_product
node_manage_product -->|"updates"| node_edit_product
node_admin_home -->|"navigates to"| node_orders
node_orders -->|"opens"| node_order_details
node_orders -->|"lists"| node_order_model
node_order_details -->|"shows"| node_order_model
node_manage_product -->|"persists via"| node_store_service
node_orders -->|"retrieves via"| node_store_service
node_store_service -->|"stores"| node_product_model
node_store_service -->|"stores"| node_order_model
node_store_service -->|"backed by"| node_google_services
node_auth_service -->|"backed by"| node_google_services
node_product_view -->|"uses"| node_images
node_menu -->|"switches"| node_admin_mode
node_android_shell -->|"includes"| node_google_services
node_ios_shell -->|"hosts"| node_main
node_android_shell -->|"hosts"| node_main
node_main -->|"uses"| node_fonts

click node_main "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/main.dart"
click node_login "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/login_screen.dart"
click node_signup "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/signup_screen.dart"
click node_home "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/homePage.dart"
click node_product_info "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/productInfo.dart"
click node_cart "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/CartScreen.dart"
click node_admin_home "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/adminHome.dart"
click node_manage_product "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/manageProduct.dart"
click node_add_product "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/addProduct.dart"
click node_edit_product "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/editProduct.dart"
click node_orders "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/OrdersScreen.dart"
click node_order_details "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/order_details.dart"
click node_product_view "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/widgets/productView.dart"
click node_menu "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/widgets/custom_menu.dart"
click node_admin_mode "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/adminMode.dart"
click node_cart_state "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/cartItem.dart"
click node_loading_state "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/modelHud.dart"
click node_product_model "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/models/product.dart"
click node_order_model "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/models/order.dart"
click node_auth_service "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/services/auth.dart"
click node_store_service "https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/services/store.dart"
click node_android_shell "https://github.com/tharwatsamy/e_commerce_app/tree/master/android"
click node_ios_shell "https://github.com/tharwatsamy/e_commerce_app/tree/master/ios"
click node_google_services "https://github.com/tharwatsamy/e_commerce_app/blob/master/android/app/google-services.json"
click node_images "https://github.com/tharwatsamy/e_commerce_app/tree/master/images"
click node_fonts "https://github.com/tharwatsamy/e_commerce_app/tree/master/fonts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_login,node_signup,node_home,node_product_info,node_cart,node_admin_home,node_manage_product,node_add_product,node_edit_product,node_orders,node_order_details,node_product_view,node_menu toneBlue
class node_admin_mode,node_cart_state,node_loading_state,node_product_model,node_order_model toneAmber
class node_auth_service,node_store_service toneMint
class node_android_shell,node_ios_shell,node_google_services toneRose
class node_images,node_fonts toneIndigo
```

## Components

### Presentation

Auth, customer, and admin screens plus reusable widgets.

- [Main](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/main.dart): flutter entrypoint · App bootstrap, routing, and top-level wiring. · `lib/main.dart`
- [Login](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/login_screen.dart): auth screen · Sign-in entry screen. · `lib/screens/login_screen.dart`
- [Sign Up](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/signup_screen.dart): auth screen · Account creation screen. · `lib/screens/signup_screen.dart`
- [Home](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/homePage.dart): customer screen · Product browsing and catalog landing page. · `lib/screens/user/homePage.dart`
- [Product Info](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/productInfo.dart): customer screen · Detailed product view and add-to-cart actions. · `lib/screens/user/productInfo.dart`
- [Cart](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/user/CartScreen.dart): customer screen · Cart review and checkout-related flow. · `lib/screens/user/CartScreen.dart`
- [Admin Home](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/adminHome.dart): admin screen · Admin landing page and role-specific entry. · `lib/screens/admin/adminHome.dart`
- [Manage Product](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/manageProduct.dart): admin screen · Product administration hub. · `lib/screens/admin/manageProduct.dart`
- [Add Product](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/addProduct.dart): admin screen · Create new catalog items. · `lib/screens/admin/addProduct.dart`
- [Edit Product](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/editProduct.dart): admin screen · Update existing catalog items. · `lib/screens/admin/editProduct.dart`
- [Orders](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/OrdersScreen.dart): admin screen · Order list and fulfillment view. · `lib/screens/admin/OrdersScreen.dart`
- [Order Details](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/screens/admin/order_details.dart): admin screen · Single order inspection and detail view. · `lib/screens/admin/order_details.dart`
- [Product View](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/widgets/productView.dart): shared widget · Reusable product card/view composition. · `lib/widgets/productView.dart`
- [Menu](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/widgets/custom_menu.dart): shared widget · Reusable navigation/menu component. · `lib/widgets/custom_menu.dart`

### State & Domain

Provider state and shared data models.

- [Admin Mode](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/adminMode.dart): provider · Role toggle between customer and admin flows. · `lib/provider/adminMode.dart`
- [Cart State](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/cartItem.dart): provider · Cart items and cart behavior. · `lib/provider/cartItem.dart`
- [Loading State](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/provider/modelHud.dart): provider · Async and busy-state handling. · `lib/provider/modelHud.dart`
- [Product](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/models/product.dart): model · Shared product domain entity. · `lib/models/product.dart`
- [Order](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/models/order.dart): model · Shared order domain entity. · `lib/models/order.dart`

### Services

Auth and backend persistence boundary.

- [Auth](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/services/auth.dart): service · Authentication and session access. · `lib/services/auth.dart`
- [Store](https://github.com/tharwatsamy/e_commerce_app/blob/master/lib/services/store.dart): service · Product and order persistence access. · `lib/services/store.dart`

### Platform Shells

Flutter host projects and native integration points.

- [Android](https://github.com/tharwatsamy/e_commerce_app/tree/master/android): platform shell · Android host project and native configuration. · `android`
- [iOS](https://github.com/tharwatsamy/e_commerce_app/tree/master/ios): platform shell · iOS host project and native configuration. · `ios`
- [Firebase Config](https://github.com/tharwatsamy/e_commerce_app/blob/master/android/app/google-services.json): native config · Android Firebase/Google services wiring. · `android/app/google-services.json`

### Assets

Static images and fonts used by the app.

- [Images](https://github.com/tharwatsamy/e_commerce_app/tree/master/images): asset library · Category-organized product imagery. · `images`
- [Fonts](https://github.com/tharwatsamy/e_commerce_app/tree/master/fonts): asset library · Custom font assets. · `fonts`

## Connections

- Main → Login: starts at · App bootstrap routes into authentication.
- Main → Home: loads · Customer flow entry after app startup.
- Main → Admin Home: branches to · Admin flow entry after role detection.
- Main → Admin Mode: uses · Top-level role state influences navigation.
- Main → Loading State: uses · Shared loading and async UI state.
- Login → Auth: authenticates via · Sign-in is handled through the auth service.
- Sign Up → Auth: registers via · Account creation goes through auth.
- Home → Product View: renders · Catalog content uses the shared product component.
- Home → Product: shows · Home screen is built from product data.
- Product Info → Cart State: adds to · Product details feed cart behavior.
- Cart → Cart State: reads · Cart screen reflects cart provider state.
- Cart State → Product: contains · Cart items are product-based domain data.
- Admin Home → Manage Product: navigates to · Admin landing links to product management.
- Manage Product → Add Product: creates · Product management opens product creation.
- Manage Product → Edit Product: updates · Product management opens editing flow.
- Admin Home → Orders: navigates to · Admin landing links to orders.
- Orders → Order Details: opens · Order list drills into order detail view.
- Orders → Order: lists · Orders screen is driven by order entities.
- Order Details → Order: shows · Detail view presents one order entity.
- Manage Product → Store: persists via · Admin product CRUD goes through store service.
- Orders → Store: retrieves via · Order data is loaded through the store service.
- Store → Product: stores · Store layer works with product entities.
- Store → Order: stores · Store layer works with order entities.
- Store → Firebase Config: backed by · Backend integration is wired through Firebase config.
- Auth → Firebase Config: backed by · Authentication is likely Firebase-backed on Android.
- Product View → Images: uses · Product presentation relies on asset images.
- Menu → Admin Mode: switches · Shared navigation mediates role-based sections.
- Android → Firebase Config: includes · Android host carries Firebase configuration.
- iOS → Main: hosts · iOS shell runs the shared Flutter app.
- Android → Main: hosts · Android shell runs the shared Flutter app.
- Main → Fonts: uses · App styling may reference bundled fonts.
