# felipecastrosales/virtual-store architecture

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

- Interactive diagram: https://gitdiagram.com/felipecastrosales/virtual-store
- Repository: https://github.com/felipecastrosales/virtual-store

## Overview

##### Project Type and Purpose
- This is a mobile full-stack (client-heavy) e-commerce application built with Flutter (Dart) as the frontend, backed by Firebase services (Auth, Firestore, Storage, etc.).
- Users can browse products, manage a cart (CRUD), apply coupons, track orders (prep → transport → delivery), view store location (Google Maps), and contact via phone.

##### High-Level Components
a. Mobile Client (Flutter App)
- UI Layer: screens, tabs, tiles, widgets
- State Management Layer: models (e.g., cart_model.dart, user_model.dart)
- Data Access Layer: datas (e.g., product_data.dart, cart_product.dart)
b. Firebase Backend Services
- Authentication: sign-up / login
- Firestore Database: products, carts, orders, users
- Storage (optional): product images, demo assets
- (Potentially) Cloud Functions: coupon validation, order status updates
c. External Integrations
- Google Maps API (store location)
- Phone dialer (tel:// link)

##### Architectural Patterns & Design Principles
- Layered Architecture (Presentation → State → Data → Backend)
- MVVM / ScopedModel (models publish state changes to UI)
- Single codebase for Android & iOS via Flutter
- Asynchronous, event-driven calls to Firebase SDK

##### Relationships & Interactions
1) User taps a UI widget (e.g., “Add to Cart” button in product_tile.dart).
2) UI calls CartModel (in lib/models/cart_model.dart) → updates in-memory cart state.
3) CartModel invokes CartProduct data class (in lib/datas/cart_product.dart) → persists to Firestore via Firebase SDK.
4) Firestore triggers snapshot listeners → Model updates are propagated back to UI.
5) Authentication flows (signup_screen.dart, login_screen.dart) call Firebase Auth SDK → user credentials stored in Firestore user collection.
6) Order tracking screen subscribes to order document updates for status changes.
7) “View Location” link uses Maps Intent; “Call” link uses platform phone dialer.

1. Flutter UI Layer (Screens, Tabs, Tiles, Widgets)
2. State Management Layer (ScopedModel/ViewModel classes)
3. Data Access Layer (Dart data classes + Firebase SDK calls)
4. Firebase Cloud Services (Auth, Firestore, Storage) + External APIs
- Use rectangles for components:
- Blue for UI components (e.g., HomeScreen, ProductTile)
- Green for Models/ViewModels (e.g., CartModel, UserModel)
- Orange for Data classes & SDK interfaces (e.g., ProductData, CartProduct, Firebase SDK)
- Purple for Backend services (Auth, Firestore, Storage)
- UI → Model (user actions)
- Model → Data layer (CRUD calls)
- Data layer → Firebase services (network I/O)
- Firebase → Data layer → Model → UI (data updates)

##### Final Recommendations
- Every directory‐to‐class mapping: e.g., “lib/screens/cart_screen.dart → CartScreen widget.”
- Do not over-complicate: four to five major blocks, with subcomponents grouped inside.
- Iterate: start with a high-level sketch, then drill down to show key classes and interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Main["Main (lib/main.dart)"]:::ui
        subgraph Screens
            direction TB
            HomeScreen["HomeScreen"]:::ui
            ProductScreen["ProductScreen"]:::ui
            CartScreen["CartScreen"]:::ui
            OrderScreen["OrderScreen"]:::ui
            CategoryScreen["CategoryScreen"]:::ui
            LoginScreen["LoginScreen"]:::ui
            SignupScreen["SignupScreen"]:::ui
        end
        subgraph Tabs
            direction TB
            HomeTab["HomeTab"]:::ui
            ProductsTab["ProductsTab"]:::ui
            OrdersTab["OrdersTab"]:::ui
            PlacesTab["PlacesTab"]:::ui
        end
        subgraph Tiles
            direction TB
            ProductTile["ProductTile"]:::ui
            CartTile["CartTile"]:::ui
            CategoryTile["CategoryTile"]:::ui
            OrderTile["OrderTile"]:::ui
            PlaceTile["PlaceTile"]:::ui
            DrawerTile["DrawerTile"]:::ui
        end
        subgraph Widgets
            direction TB
            CustomDrawer["CustomDrawer"]:::ui
            CartButton["CartButton"]:::ui
            CartPrice["CartPrice"]:::ui
            DiscountCart["DiscountCart"]:::ui
            ShipCard["ShipCard"]:::ui
        end
    end

    %% State Management Layer
    subgraph "State Management Layer"
        direction TB
        CartModel["CartModel"]:::model
        UserModel["UserModel"]:::model
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        ProductData["ProductData"]:::data
        CartProduct["CartProduct"]:::data
        FirebaseSDK["Firebase SDK"]:::data
    end

    %% Backend & External Services
    subgraph "Firebase & External"
        direction TB
        Auth["Auth (Firebase Auth)"]:::service
        Firestore["Firestore"]:::service
        Storage["Storage"]:::service
        CloudFunctions["Cloud Functions"]:::service
        Maps["Google Maps API"]:::external
        Phone["Phone Dialer"]:::external
        AndroidShell["Android Project"]:::service
        iOSShell["iOS Project"]:::service
        Assets["Assets (demos, fonts, icons)"]:::service
        Pubspec["pubspec.yaml"]:::service
    end

    %% Connections
    Main -->|launches| HomeScreen
    HomeScreen -->|"tap AddToCart"| CartModel
    ProductTile -->|display| HomeScreen
    CartModel -->|"addItem()"| CartProduct
    CartProduct -->|"persist()"| FirebaseSDK
    FirebaseSDK -->|"write/read"| Firestore
    Firestore -->|"snapshotListener()"| CartModel
    LoginScreen -->|"signInWithEmail()"| Auth
    SignupScreen -->|"createUser()"| Auth
    Auth -->|"credentials stored"| Firestore
    OrderScreen -->|"subscribeOrder()"| Firestore
    PlacesTab -->|"launch MapsIntent"| Maps
    PlaceTile -->|"launch MapsIntent"| Maps
    DrawerTile -->|"tap Call"| Phone
    Assets -->|"packaged into"| Main
    Pubspec -->|"defines deps"| Main

    %% State to UI updates
    CartModel -->|"notifyListeners()"| HomeScreen
    UserModel -->|"notifyListeners()"| HomeScreen

    %% Native shells
    Main -->|build targets| AndroidShell
    Main -->|build targets| iOSShell

    %% Click Events
    click Main "https://github.com/felipecastrosales/virtual-store/blob/master/lib/main.dart"
    click HomeScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/home_screen.dart"
    click ProductScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/product_screen.dart"
    click CartScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/cart_screen.dart"
    click OrderScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/order_screen.dart"
    click CategoryScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/category_screen.dart"
    click LoginScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/login_screen.dart"
    click SignupScreen "https://github.com/felipecastrosales/virtual-store/blob/master/lib/screens/signup_screen.dart"
    click HomeTab "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tabs/home_tab.dart"
    click ProductsTab "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tabs/products_tab.dart"
    click OrdersTab "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tabs/orders_tab.dart"
    click PlacesTab "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tabs/places_tab.dart"
    click ProductTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/product_tile.dart"
    click CartTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/cart_tile.dart"
    click CategoryTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/category_tile.dart"
    click OrderTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/order_tile.dart"
    click PlaceTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/place_tile.dart"
    click DrawerTile "https://github.com/felipecastrosales/virtual-store/blob/master/lib/tiles/drawer_tile.dart"
    click CustomDrawer "https://github.com/felipecastrosales/virtual-store/blob/master/lib/widgets/custom_drawer.dart"
    click CartButton "https://github.com/felipecastrosales/virtual-store/blob/master/lib/widgets/cart_button.dart"
    click CartPrice "https://github.com/felipecastrosales/virtual-store/blob/master/lib/widgets/cart_price.dart"
    click DiscountCart "https://github.com/felipecastrosales/virtual-store/blob/master/lib/widgets/discount_cart.dart"
    click ShipCard "https://github.com/felipecastrosales/virtual-store/blob/master/lib/widgets/ship_card.dart"
    click CartModel "https://github.com/felipecastrosales/virtual-store/blob/master/lib/models/cart_model.dart"
    click UserModel "https://github.com/felipecastrosales/virtual-store/blob/master/lib/models/user_model.dart"
    click ProductData "https://github.com/felipecastrosales/virtual-store/blob/master/lib/datas/product_data.dart"
    click CartProduct "https://github.com/felipecastrosales/virtual-store/blob/master/lib/datas/cart_product.dart"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef model fill:#DFFFD0,stroke:#28A745,stroke-width:2px
    classDef data fill:#FFE5B4,stroke:#F39C12,stroke-width:2px
    classDef service fill:#E5DBFF,stroke:#6F42C1,stroke-width:2px
    classDef external stroke-dasharray: 5 5,stroke:#55555
```
