# bizz84/complete-flutter-course architecture

> Architecture diagram of the GitHub repository bizz84/complete-flutter-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bizz84/complete-flutter-course
- Repository: https://github.com/bizz84/complete-flutter-course

## Overview

##### Project Type & Purpose
- This is a full-stack, cross-platform Flutter eCommerce application (mobile: Android/iOS, desktop: macOS/Windows, web) built using the Controller-Service-Repository pattern with Riverpod. The “backend” in this course is represented by fake repositories and local persistence (Sembast) to simulate remote services (e.g., Firebase Auth, Firestore), but the architecture is fully layered and ready to plug in real cloud services.

##### File Structure Analysis
- Top‐level shells: `android/`, `ios/`, `macos/`, `windows/`, `web/` each contain the native project that loads the Flutter engine.
- Core Flutter code: under `lib/` subdivided into:
- `src/presentation`: Widgets and screens (UI layer).
- `src/routing`: GoRouter setup.
- `src/utils`, `src/common_widgets`: UI helpers and utils.
- `src/features`: By feature (authentication, products, cart, checkout, orders, reviews). Each feature follows Feature → Domain → Data → Presentation → Application (controllers/services).
- Test suites mirror the feature structure under `test/`.
- Config/build: `pubspec.yaml`, Gradle, Cocoapods, CMake, GitHub workflows.

##### Insights from README
- Uses Riverpod for state management.
- Applies Controller-Service-Repository pattern.
- Swappable “fake” repositories for local/in-memory persistence.
- Placeholder for Firebase & real back‐end connectivity.
- GoRouter manages navigation.

##### Diagramming the Architecture
a. Main Components
- Platform Shells: Android, iOS, macOS, Windows, Web
- Flutter Engine & Framework
- App Core:
- Presentation Layer (Widgets, Screens)
- State Controllers (Riverpod StateNotifiers/Providers)
- Services Layer (CartService, ReviewsService, etc.)
- Repository Layer (FakeAuthRepository, RemoteCartRepository, SembastCartRepository)
- Domain Layer (Entities: Product, Order, Cart, User)
- Data Sources:
- Local DB (Sembast)
- InMemoryStore (RxDart)
- Remote API (simulated/fake)
- External Services (for real prod): Firebase Auth, Firestore, Payment Gateway

b. Relationships & Interactions
- UI widgets send user actions to Controllers via Riverpod providers.
- Controllers invoke corresponding Services.
- Services call Repositories through abstract interfaces.
- Repositories delegate to Data Sources (local vs remote) based on environment or user offline/online status.
- Local Data Source persists to Sembast; Remote Data Source calls cloud APIs.
- Services may synchronize local and remote (e.g., CartSyncService listens to changes and pushes updates).
- Domain entities flow up from data sources → repositories → services → controllers → widgets.

c. Architectural Patterns & Principles
- Layered architecture (Presentation → Application → Domain → Data → Infrastructure).
- Feature-first project organization.
- Controller-Service-Repository pattern.
- Dependency injection via Riverpod.
- Separation of concerns: navigation (GoRouter), UI, state, business logic, persistence.

d. Key Technologies & Frameworks
- Flutter (Dart)
- Riverpod (state management + code generation)
- GoRouter (routing)
- Sembast (local persistence)
- RxDart (in-memory reactive store)
- GitHub Actions (CI tests)

##### Essential Details to Capture
- Clearly distinguish Fake vs Local vs Remote repositories.
- How `CartSyncService` hooks into the app startup (e.g., via a ProviderObserver or top-level ProviderContainer).
- GoRouter entry in `app_router.dart`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Device & Platform Shells"
        Android["Android"]:::platform
        iOS["iOS"]:::platform
        macOS["macOS"]:::platform
        Windows["Windows"]:::platform
        Web["Web"]:::platform
    end

    Android --> FlutterEngine["Flutter Engine & Framework"]:::core
    iOS --> FlutterEngine
    macOS --> FlutterEngine
    Windows --> FlutterEngine
    Web --> FlutterEngine

    subgraph "Presentation Layer" 
        Router["GoRouter"]:::presentation
        Refresh["GoRouter Refresh Stream"]:::presentation
        NotFound["NotFound Screen"]:::presentation
        SharedWidgets["Common Widgets"]:::presentation
        AuthUI["Authentication UI"]:::presentation
        ProductUI["Products UI"]:::presentation
        CartUI["Cart UI"]:::presentation
        CheckoutUI["Checkout UI"]:::presentation
        OrdersUI["Orders UI"]:::presentation
        ReviewsUI["Reviews UI"]:::presentation
    end

    FlutterEngine --> Router
    Router --> SharedWidgets
    Router --> AuthUI
    Router --> ProductUI
    Router --> CartUI
    Router --> CheckoutUI
    Router --> OrdersUI
    Router --> ReviewsUI

    subgraph "Application Layer"
        AccountController["AccountController"]:::application
        SignInController["EmailPasswordSignInController"]:::application
        CartService["CartService"]:::application
        CartSyncService["CartSyncService"]:::application
        CheckoutService["FakeCheckoutService"]:::application
        OrdersProvider["UserOrdersProvider"]:::application
        ReviewsService["ReviewsService"]:::application
    end

    AuthUI --> AccountController
    AuthUI --> SignInController
    CartUI --> CartService
    CartService --> CartSyncService
    CheckoutUI --> CheckoutService
    OrdersUI --> OrdersProvider
    ReviewsUI --> ReviewsService

    subgraph "Domain Layer"
        User["User Entity"]:::domain
        Product["Product Entity"]:::domain
        CartEntity["Cart & Item Entities"]:::domain
        OrderEntity["Order Entity"]:::domain
        ReviewEntity["Review Entity"]:::domain
        Address["Address Entity"]:::domain
    end

    AccountController --> User
    SignInController --> User
    ProductUI --> Product
    CartService --> CartEntity
    OrdersProvider --> OrderEntity
    ReviewsService --> ReviewEntity

    subgraph "Repository Layer"
        FakeAuthRepo["FakeAuthRepository"]:::data
        FakeProductsRepo["FakeProductsRepository"]:::data
        FakeLocalCartRepo["FakeLocalCartRepository"]:::data
        LocalCartRepo["LocalCartRepository"]:::data
        SembastCartRepo["SembastCartRepository"]:::data
        FakeRemoteCartRepo["FakeRemoteCartRepository"]:::data
        RemoteCartRepo["RemoteCartRepository"]:::data
        FakeOrdersRepo["FakeOrdersRepository"]:::data
        FakeReviewsRepo["FakeReviewsRepository"]:::data
    end

    AccountController --> FakeAuthRepo
    SignInController --> FakeAuthRepo
    ProductUI --> FakeProductsRepo
    CartService --> FakeLocalCartRepo
    CartService --> LocalCartRepo
    CartService --> SembastCartRepo
    CartService --> FakeRemoteCartRepo
    CartService --> RemoteCartRepo
    OrdersProvider --> FakeOrdersRepo
    ReviewsService --> FakeReviewsRepo

    subgraph "Data Sources & Persistence"
        SembastDB[(Sembast DB)]:::infra
        InMemoryStore[(InMemory Store)]:::infra
        FakeRemoteAPI[(Fake Remote API)]:::infra
    end

    SembastCartRepo --> SembastDB
    LocalCartRepo --> InMemoryStore
    FakeLocalCartRepo --> InMemoryStore
    FakeRemoteCartRepo --> FakeRemoteAPI
    RemoteCartRepo --> FakeRemoteAPI
    FakeAuthRepo --> FakeRemoteAPI
    FakeProductsRepo --> FakeRemoteAPI
    FakeOrdersRepo --> FakeRemoteAPI
    FakeReviewsRepo --> FakeRemoteAPI

    subgraph "External Cloud Services"
        FirebaseAuth[(Firebase Auth)]:::external
        Firestore[(Firestore)]:::external
        PaymentGateway[(Payment Gateway)]:::external
    end

    FakeRemoteAPI --> FirebaseAuth
    FakeRemoteAPI --> Firestore
    FakeRemoteAPI --> PaymentGateway

    %% Click Events
    click Android "https://github.com/bizz84/complete-flutter-course/tree/main/ecommerce_app/android/"
    click iOS "https://github.com/bizz84/complete-flutter-course/tree/main/ecommerce_app/ios/"
    click macOS "https://github.com/bizz84/complete-flutter-course/tree/main/ecommerce_app/macos/"
    click Windows "https://github.com/bizz84/complete-flutter-course/tree/main/ecommerce_app/windows/"
    click Web "https://github.com/bizz84/complete-flutter-course/tree/main/ecommerce_app/web/"
    click Router "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/routing/app_router.dart"
    click Refresh "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/routing/go_router_refresh_stream.dart"
    click NotFound "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/routing/not_found_screen.dart"
    click SharedWidgets "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/common_widgets/"
    click AuthUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/authentication/presentation/"
    click ProductUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/products/presentation/"
    click CartUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/cart/presentation/"
    click CheckoutUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/checkout/presentation/"
    click OrdersUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/orders/presentation/"
    click ReviewsUI "https://github.com/bizz84/complete-flutter-course/tree/main/lib/src/features/reviews/presentation/"
    click AccountController "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/authentication/presentation/account/account_screen_controller.dart"
    click SignInController "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/authentication/presentation/sign_in/email_password_sign_in_controller.dart"
    click CartService "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/application/cart_service.dart"
    click CartSyncService "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/application/cart_sync_service.dart"
    click CheckoutService "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/checkout/application/fake_checkout_service.dart"
    click OrdersProvider "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/orders/application/user_orders_provider.dart"
    click ReviewsService "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/reviews/application/reviews_service.dart"
    click FakeAuthRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/authentication/data/fake_auth_repository.dart"
    click FakeProductsRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/products/data/fake_products_repository.dart"
    click FakeLocalCartRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/data/local/fake_local_cart_repository.dart"
    click LocalCartRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/data/local/local_cart_repository.dart"
    click SembastCartRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/data/local/sembast_cart_repository.dart"
    click FakeRemoteCartRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/data/remote/fake_remote_cart_repository.dart"
    click RemoteCartRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/data/remote/remote_cart_repository.dart"
    click FakeOrdersRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/orders/data/fake_orders_repository.dart"
    click FakeReviewsRepo "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/reviews/data/fake_reviews_repository.dart"
    click User "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/authentication/domain/app_user.dart"
    click Product "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/products/domain/product.dart"
    click CartEntity "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/cart/domain/cart.dart"
    click OrderEntity "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/orders/domain/order.dart"
    click ReviewEntity "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/reviews/domain/review.dart"
    click Address "https://github.com/bizz84/complete-flutter-course/blob/main/lib/src/features/address/domain/address.dart"

    classDef platform fill:#f9f,stroke:#333,stroke-width:1px
    classDef core fill:#eef,stroke:#333,stroke-width:1px
    classDef presentation fill:#bbf,stroke:#333,stroke-width:1px
    classDef application fill:#bfb,stroke:#333,stroke-width:1px
    classDef domain fill:#ddd,stroke:#333,stroke-width:1px
    classDef data fill:#f96,stroke:#333,stroke-width:1px
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px
    classDef external fill:#dcb,stroke:#333,stroke-width:1px
```
