# maxonflutter/grocery-shopping-app-with-flutter-dart-frog architecture

> Architecture diagram of the GitHub repository maxonflutter/grocery-shopping-app-with-flutter-dart-frog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog
- Repository: https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog

## Overview

##### Project type and purpose
- Full-stack mobile application
- Flutter front-end using BLoC for state management
- Dart Frog back-end providing RESTful endpoints
- Purpose: Grocery Shopping App (browse products/categories, manage cart, view orders)

##### File structure
- Front-end (root)
- lib/
– blocs/ (home, category, cart)
– screens/ (intro, login, home, cart, category, search, order)
– repositories/ (cart, category, product)
– services/api_client.dart
– navigation/app_router.dart
– widgets/ (UI components)
- assets/ (videos, images)
- android/, ios/ (platform projects)
- Back-end (api/)
- routes/ (categories, products, users, cart endpoints)
- packages/
– models (shared data models)
– cart_repository, category_repository, product_repository (domain logic)
- README.md, pubspec.yaml (Dart Frog setup)
- Config files: pubspec.yaml, analysis_options.yaml, .gitignore, platform-specific build files

##### Main components
- Front-end
- UI Screens (Flutter widgets)
- BLoC Layer (cart_bloc, category_bloc, home_bloc)
- Repository Layer (wrapping HTTP calls)
- ApiClient (HTTP client + JSON serialization)
- Navigation (app_router)
- Back-end
- HTTP Server (Dart Frog router & middleware)
- Route Handlers (controllers for each path)
- Domain Packages (repositories & models)
- External / Future
- Database (placeholder for future integration)
- Cloud Hosting (GCP deployment)

##### Relationships and data flow
- UI fires events → BLoC handles events → calls Repository → ApiClient sends HTTP request
- Dart Frog server receives request → Router routes to handler → handler invokes domain repository → constructs response using models → sends JSON back
- ApiClient parses JSON → Repository returns domain objects → BLoC emits new state → UI updates
- Future: domain repositories connect to an external database instead of in-memory or stub data

##### Architectural patterns and design principles
- Front-end: BLoC (unidirectional data flow, separation of concerns)
- Back-end: Modular monolith with Clean-style separation
- RESTful API design (resources under /categories, /products, /users/:id/cart)
- Shared model package ensures type safety across front-end and back-end

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Flutter App Container
    subgraph "Flutter App"
        direction TB
        subgraph "Screens"
            direction TB
            Intro["Intro Screen"]:::frontend
            Login["Login Screen"]:::frontend
            Register["Register Screen"]:::frontend
            HomeScreen["Home Screen"]:::frontend
            CategoryScreen["Category Screen"]:::frontend
            CartScreen["Cart Screen"]:::frontend
            OrderScreen["Order Screen"]:::frontend
            OrderDetails["Order Details Screen"]:::frontend
            Search["Search Screen (UI only – backend TBD)"]:::frontend
            Scan["Scan Screen (UI only – backend TBD)"]:::frontend
        end
        subgraph "BLoC Layer"
            direction TB
            HomeBloc["HomeBloc"]:::frontend
            CategoryBloc["CategoryBloc"]:::frontend
            CartBloc["CartBloc"]:::frontend
        end
        subgraph "Repository Layer"
            direction TB
            ProductRepoFE["ProductRepository"]:::frontend
            CategoryRepoFE["CategoryRepository"]:::frontend
            CartRepoFE["CartRepository"]:::frontend
        end
        ApiClient["ApiClient"]:::frontend
        AppRouter["AppRouter"]:::frontend
    end

    %% Dart Frog Server Container
    subgraph "Dart Frog Server"
        direction TB
        Router["Router & Middleware"]:::backend
        subgraph "Route Handlers"
            direction TB
            ListCategories["GET /categories"]:::backend
            GetCategory["GET /categories/{id}"]:::backend
            CategoryProducts["GET /categories/{id}/products"]:::backend
            ListProducts["GET /products"]:::backend
            GetProduct["GET /products/{id}"]:::backend
            PopularProducts["GET /products/popular"]:::backend
            TrendingProducts["GET /products/trending"]:::backend
            UserCartList["GET /users/{userId}/cart"]:::backend
            UserCartItem["CRUD /users/{userId}/cart/{itemId}"]:::backend
        end
        subgraph "Domain Packages"
            direction TB
            CartRepoBE["cart_repository"]:::backend
            CategoryRepoBE["category_repository"]:::backend
            ProductRepoBE["product_repository"]:::backend
            Models["Shared Models"]:::backend
        end
    end

    ExternalDB["External Database (future)"]:::future

    %% Front-end Data Flow
    Intro -->|event| HomeBloc
    Login -->|event| HomeBloc
    Register -->|event| HomeBloc
    HomeScreen -->|event| HomeBloc
    CategoryScreen -->|event| CategoryBloc
    CartScreen -->|event| CartBloc
    OrderScreen -->|event| CartBloc
    OrderDetails -->|event| CartBloc

    HomeBloc -->|calls| ProductRepoFE
    CategoryBloc -->|calls| CategoryRepoFE
    CartBloc -->|calls| CartRepoFE

    ProductRepoFE -->|uses| ApiClient
    CategoryRepoFE -->|uses| ApiClient
    CartRepoFE -->|uses| ApiClient

    ApiClient -->|"HTTP Request (JSON)"| Router
    Router -->|"HTTP Response (JSON)"| ApiClient

    ApiClient --> ProductRepoFE
    ApiClient --> CategoryRepoFE
    ApiClient --> CartRepoFE

    ProductRepoFE --> HomeBloc
    CategoryRepoFE --> CategoryBloc
    CartRepoFE --> CartBloc

    HomeBloc --> HomeScreen
    CategoryBloc --> CategoryScreen
    CartBloc --> CartScreen

    %% Front-end navigation
    AppRouter --> Intro

    %% Back-end internal flow
    Router --> ListCategories
    Router --> GetCategory
    Router --> CategoryProducts
    Router --> ListProducts
    Router --> GetProduct
    Router --> PopularProducts
    Router --> TrendingProducts
    Router --> UserCartList
    Router --> UserCartItem

    ListCategories --> CartRepoBE
    GetCategory --> CategoryRepoBE
    CategoryProducts --> CategoryRepoBE
    ListProducts --> ProductRepoBE
    GetProduct --> ProductRepoBE
    PopularProducts --> ProductRepoBE
    TrendingProducts --> ProductRepoBE
    UserCartList --> CartRepoBE
    UserCartItem --> CartRepoBE

    CartRepoBE --> Models
    CategoryRepoBE --> Models
    ProductRepoBE --> Models

    %% Future external database
    CartRepoBE -.->|dashed| ExternalDB
    CategoryRepoBE -.->|dashed| ExternalDB
    ProductRepoBE -.->|dashed| ExternalDB

    %% Click Events Front-end
    click HomeScreen "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/home_screen.dart"
    click CategoryScreen "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/category_screen.dart"
    click CartScreen "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/cart_screen.dart"
    click OrderScreen "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/order_screen.dart"
    click OrderDetails "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/order_details_screen.dart"
    click Intro "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/intro_screen.dart"
    click Login "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/login_screen.dart"
    click Register "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/register_screen.dart"
    click Search "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/search_screen.dart"
    click Scan "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/screens/scan_screen.dart"

    click HomeBloc "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/blocs/home/home_bloc.dart"
    click CategoryBloc "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/blocs/category/category_bloc.dart"
    click CartBloc "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/blocs/cart/cart_bloc.dart"

    click ProductRepoFE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/repositories/product_repository.dart"
    click CategoryRepoFE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/repositories/category_repository.dart"
    click CartRepoFE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/repositories/cart_repository.dart"

    click ApiClient "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/services/api_client.dart"
    click AppRouter "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/lib/navigation/app_router.dart"

    %% Click Events Back-end
    click Router "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/index.dart"
    click ListCategories "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/categories/index.dart"
    click GetCategory "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/categories/[categoryId]/index.dart"
    click CategoryProducts "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/categories/[categoryId]/products/index.dart"
    click ListProducts "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/products/index.dart"
    click GetProduct "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/products/id/[productId].dart"
    click PopularProducts "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/products/popular/index.dart"
    click TrendingProducts "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/products/trending/index.dart"
    click UserCartList "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/users/[userId]/cart/index.dart"
    click UserCartItem "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/routes/users/[userId]/cart/[itemId].dart"

    click CartRepoBE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/packages/cart_repository/lib/src/cart_repository.dart"
    click CategoryRepoBE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/packages/category_repository/lib/src/category_repository.dart"
    click ProductRepoBE "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/packages/product_repository/lib/src/product_repository.dart"
    click Models "https://github.com/maxonflutter/grocery-shopping-app-with-flutter-dart-frog/blob/main/api/packages/models/lib/models.dart"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1F618D
    classDef backend fill:#A9DFBF,stroke:#196F3D,color:#196F3D
    classDef future fill:#F5B041,stroke:#A04000,color:#A04000
```
