# uuttssaavv/flutter-clean-architecture-riverpod architecture

> Architecture diagram of the GitHub repository uuttssaavv/flutter-clean-architecture-riverpod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uuttssaavv/flutter-clean-architecture-riverpod
- Repository: https://github.com/uuttssaavv/flutter-clean-architecture-riverpod

## Overview

#### Purpose and runtime
This is a Flutter/Dart mobile client demonstrating clean architecture with Riverpod. It authenticates against DummyJSON, persists the logged-in user locally, and presents paginated/searchable products. Flutter renders the UI; Android and iOS host the Flutter engine via `android/app/src/main/kotlin/com/example/flutter_project/MainActivity.kt` and `ios/Runner/AppDelegate.swift`.

#### Bootstrap, environments, and routing
Application startup initializes services and installs Riverpod’s dependency container before building the root app. Environment-specific launch files support development/staging configuration. The root Material app owns generated AutoRoute navigation, including splash, login, and dashboard transitions.
- `lib/main.dart`
- `lib/main/app.dart`
- `lib/main/main_dev.dart`
- `lib/routes/app_route.dart`

#### Clean-architecture feature boundary
Authentication and dashboard are independently organized into `data`, `domain`, and `presentation` layers. Domain repository interfaces define feature contracts; data repositories bind those contracts to local/remote sources; presentation consumes Riverpod providers and state notifiers rather than concrete transport/storage implementations.
- `lib/features/authentication/domain/repositories/auth_repository.dart`
- `lib/features/authentication/data/repositories/authentication_repository_impl.dart`
- `lib/features/dashboard/domain/repositories/dashboard_repository.dart`
- `lib/features/dashboard/data/repositories/dashboard_repository.dart`

#### Authentication and session persistence
The login screen dispatches through presentation state, which invokes domain login providers and the authentication repository. Remote authentication obtains user data; local authentication and the app-level user-cache service persist/read the current user. This cached session is the likely input to splash-driven initial navigation.
- `lib/features/authentication/presentation/providers/state/auth_notifier.dart`
- `lib/features/authentication/data/datasource/auth_remote_data_source.dart`
- `lib/features/authentication/data/datasource/auth_local_data_source.dart`
- `lib/services/user_cache_service/domain/providers/current_user_provider.dart`

#### Dashboard product flow
Dashboard state initializes product retrieval and manages pagination/search. Its notifier depends on a repository abstraction; the repository delegates to dashboard data sources, which retrieve product pages/search results and may cache locally. UI observes state and renders loading, error, or product results.
- `lib/features/dashboard/presentation/providers/state/dashboard_notifier.dart`
- `lib/features/dashboard/presentation/screens/dashboard_screen.dart`
- `lib/features/dashboard/data/datasource/dashboard_remote_datasource.dart`
- `lib/features/dashboard/data/datasource/dashboard_local_datasource.dart`

#### Shared infrastructure and data contracts
A `NetworkService` abstraction is implemented by Dio, isolating HTTP configuration and error translation from features. `StorageService` is implemented with SharedPreferences for simple persistent state. Shared models represent users, products, paginated API responses, and functional/error result boundaries; Freezed and JSON-generated model artifacts support immutable serialization.
- `lib/shared/data/remote/network_service.dart`
- `lib/shared/data/remote/dio_network_service.dart`
- `lib/shared/data/local/shared_prefs_storage_service.dart`
- `lib/shared/domain/models/paginated_response.dart`
- `lib/shared/exceptions/http_exception.dart`

#### State and UI boundaries
Riverpod providers compose concrete dependencies from shared services through feature repositories and into `StateNotifier` state machines. Presentation remains Flutter-specific: screens emit user events and subscribe to immutable auth/dashboard state, while shared theme and reusable loading/error widgets standardize rendering.
- `lib/features/authentication/presentation/providers/auth_providers.dart`
- `lib/features/authentication/presentation/providers/state/auth_state.dart`
- `lib/features/dashboard/presentation/providers/dashboard_state_provider.dart`
- `lib/shared/widgets/app_error.dart`

Main entry points: [`lib/routes/app_route.dart`](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/routes/app_route.dart) (App routes), [`lib/main.dart`](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main.dart) (Bootstrap), [`lib/features/authentication/presentation/providers/auth_providers.dart`](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/presentation/providers/auth_providers.dart) (Auth providers), [`lib/features/authentication/data/repositories/authentication_repository_impl.dart`](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/data/repositories/authentication_repository_impl.dart) (Auth repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Native Hosts"]
  node_android["Android host<br/>Kotlin entrypoint<br/>[MainActivity.kt]"]
  node_ios["iOS host<br/>Swift entrypoint<br/>[AppDelegate.swift]"]
end

subgraph group_app["App Shell"]
  node_bootstrap["Bootstrap<br/>Flutter startup<br/>[main.dart]"]
  node_environments["Environment launchers<br/>Dart entrypoints<br/>[main_dev.dart]"]
  node_root_app["Root app<br/>Material app<br/>[app.dart]"]
  node_routes["App routes<br/>AutoRoute graph<br/>[app_route.dart]"]
end

subgraph group_auth["Authentication"]
  node_auth_ui_state["Auth UI state<br/>Riverpod StateNotifier<br/>[auth_notifier.dart]"]
  node_auth_providers{{"Auth providers<br/>Riverpod composition"}}
  node_auth_contract["Auth repository contract<br/>domain interface"]
  node_auth_repository["Auth repository<br/>data implementation"]
  node_auth_sources["Auth data sources<br/>remote + local"]
  node_current_user{{"Current user cache<br/>session provider"}}
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard screen<br/>Flutter screen"]
  node_dashboard_state["Dashboard state<br/>Riverpod StateNotifier"]
  node_dashboard_contract["Dashboard repository contract<br/>domain interface"]
  node_dashboard_repository["Dashboard repository<br/>data repository"]
  node_product_sources["Product data sources<br/>remote + local"]
end

subgraph group_shared["Shared Infrastructure"]
  node_network["Network service<br/>Dio HTTP adapter"]
  node_storage[("Storage service<br/>SharedPreferences adapter")]
  node_contracts["Shared data contracts<br/>models and errors"]
  node_error_ui["Error widget<br/>shared Flutter widget<br/>[app_error.dart]"]
end

node_android -->|"hosts"| node_bootstrap
node_ios -->|"hosts"| node_bootstrap
node_environments -->|"launches"| node_bootstrap
node_bootstrap -->|"builds"| node_root_app
node_root_app -->|"uses"| node_routes
node_routes -->|"login flow"| node_auth_ui_state
node_routes -->|"dashboard flow"| node_dashboard_ui
node_current_user -.->|"restores session for splash"| node_routes
node_auth_ui_state -->|"resolves dependencies"| node_auth_providers
node_auth_providers -->|"depends on"| node_auth_contract
node_auth_repository -.->|"implements"| node_auth_contract
node_auth_providers -->|"binds implementation"| node_auth_repository
node_auth_repository -->|"uses"| node_auth_sources
node_auth_sources -->|"login request"| node_network
node_auth_sources -->|"persist user"| node_storage
node_current_user -->|"reads user"| node_storage
node_dashboard_ui -->|"observes and dispatches"| node_dashboard_state
node_dashboard_state -->|"depends on"| node_dashboard_contract
node_dashboard_repository -.->|"implements"| node_dashboard_contract
node_dashboard_state -->|"retrieves products"| node_dashboard_repository
node_dashboard_repository -->|"delegates"| node_product_sources
node_product_sources -->|"pages and search"| node_network
node_product_sources -.->|"optional cache"| node_storage
node_network -->|"maps responses and errors"| node_contracts
node_dashboard_ui -->|"renders failures"| node_error_ui

click node_android "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/android/app/src/main/kotlin/com/example/flutter_project/MainActivity.kt"
click node_ios "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/ios/Runner/AppDelegate.swift"
click node_bootstrap "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main.dart"
click node_environments "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main/main_dev.dart"
click node_root_app "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main/app.dart"
click node_routes "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/routes/app_route.dart"
click node_auth_ui_state "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/presentation/providers/state/auth_notifier.dart"
click node_auth_providers "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/presentation/providers/auth_providers.dart"
click node_auth_contract "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/domain/repositories/auth_repository.dart"
click node_auth_repository "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/data/repositories/authentication_repository_impl.dart"
click node_auth_sources "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/data/datasource/auth_remote_data_source.dart"
click node_current_user "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/services/user_cache_service/domain/providers/current_user_provider.dart"
click node_dashboard_ui "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/presentation/screens/dashboard_screen.dart"
click node_dashboard_state "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/presentation/providers/state/dashboard_notifier.dart"
click node_dashboard_contract "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/domain/repositories/dashboard_repository.dart"
click node_dashboard_repository "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/data/repositories/dashboard_repository.dart"
click node_product_sources "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/data/datasource/dashboard_remote_datasource.dart"
click node_network "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/data/remote/dio_network_service.dart"
click node_storage "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/data/local/shared_prefs_storage_service.dart"
click node_contracts "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/domain/models/paginated_response.dart"
click node_error_ui "https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/widgets/app_error.dart"

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_android,node_ios toneBlue
class node_bootstrap,node_environments,node_root_app,node_routes toneAmber
class node_auth_ui_state,node_auth_providers,node_auth_contract,node_auth_repository,node_auth_sources,node_current_user toneMint
class node_dashboard_ui,node_dashboard_state,node_dashboard_contract,node_dashboard_repository,node_product_sources toneRose
class node_network,node_storage,node_contracts,node_error_ui toneIndigo
```

## Components

### Native Hosts

- [Android host](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/android/app/src/main/kotlin/com/example/flutter_project/MainActivity.kt): Kotlin entrypoint · Hosts the Flutter engine. · `android/app/src/main/kotlin/com/example/flutter_project/MainActivity.kt`
- [iOS host](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/ios/Runner/AppDelegate.swift): Swift entrypoint · Hosts the Flutter engine. · `ios/Runner/AppDelegate.swift`

### App Shell

- [Bootstrap](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main.dart): Flutter startup · Initializes services and Riverpod before rendering. · `lib/main.dart`
- [Environment launchers](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main/main_dev.dart): Dart entrypoints · Development and staging launch configuration. · `lib/main/main_dev.dart`
- [Root app](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/main/app.dart): Material app · Owns the app shell and navigation setup. · `lib/main/app.dart`
- [App routes](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/routes/app_route.dart): AutoRoute graph · Routes splash, login, and dashboard. · `lib/routes/app_route.dart`

### Authentication

- [Auth UI state](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/presentation/providers/state/auth_notifier.dart): Riverpod StateNotifier · Processes login events and exposes immutable auth state. · `lib/features/authentication/presentation/providers/state/auth_notifier.dart`
- [Auth providers](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/presentation/providers/auth_providers.dart): Riverpod composition · Wires presentation to authentication dependencies. · `lib/features/authentication/presentation/providers/auth_providers.dart`
- [Auth repository contract](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/domain/repositories/auth_repository.dart): domain interface · `lib/features/authentication/domain/repositories/auth_repository.dart`
- [Auth repository](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/data/repositories/authentication_repository_impl.dart): data implementation · Combines remote login and local session access. · `lib/features/authentication/data/repositories/authentication_repository_impl.dart`
- [Auth data sources](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/authentication/data/datasource/auth_remote_data_source.dart): remote + local · Authenticates remotely and persists the user locally. · `lib/features/authentication/data/datasource/auth_remote_data_source.dart`
- [Current user cache](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/services/user_cache_service/domain/providers/current_user_provider.dart): session provider · Reads the persisted user for session restoration. · `lib/services/user_cache_service/domain/providers/current_user_provider.dart`

### Dashboard

- [Dashboard screen](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/presentation/screens/dashboard_screen.dart): Flutter screen · Renders loading, errors, and product results. · `lib/features/dashboard/presentation/screens/dashboard_screen.dart`
- [Dashboard state](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/presentation/providers/state/dashboard_notifier.dart): Riverpod StateNotifier · Manages product loading, paging, and search. · `lib/features/dashboard/presentation/providers/state/dashboard_notifier.dart`
- [Dashboard repository contract](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/domain/repositories/dashboard_repository.dart): domain interface · `lib/features/dashboard/domain/repositories/dashboard_repository.dart`
- [Dashboard repository](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/data/repositories/dashboard_repository.dart): data repository · Delegates product retrieval to data sources. · `lib/features/dashboard/data/repositories/dashboard_repository.dart`
- [Product data sources](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/features/dashboard/data/datasource/dashboard_remote_datasource.dart): remote + local · Retrieves or caches product pages and searches. · `lib/features/dashboard/data/datasource/dashboard_remote_datasource.dart`

### Shared Infrastructure

- [Network service](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/data/remote/dio_network_service.dart): Dio HTTP adapter · Isolates HTTP configuration and error translation. · `lib/shared/data/remote/dio_network_service.dart`
- [Storage service](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/data/local/shared_prefs_storage_service.dart): SharedPreferences adapter · Provides persistent local state. · `lib/shared/data/local/shared_prefs_storage_service.dart`
- [Shared data contracts](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/domain/models/paginated_response.dart): models and errors · Defines paginated responses and HTTP failure boundaries. · `lib/shared/domain/models/paginated_response.dart`
- [Error widget](https://github.com/uuttssaavv/flutter-clean-architecture-riverpod/blob/master/lib/shared/widgets/app_error.dart): shared Flutter widget · `lib/shared/widgets/app_error.dart`

## Connections

- Android host → Bootstrap: hosts
- iOS host → Bootstrap: hosts
- Environment launchers → Bootstrap: launches
- Bootstrap → Root app: builds
- Root app → App routes: uses
- App routes → Auth UI state: login flow
- App routes → Dashboard screen: dashboard flow
- Current user cache → App routes: restores session for splash
- Auth UI state → Auth providers: resolves dependencies
- Auth providers → Auth repository contract: depends on
- Auth repository → Auth repository contract: implements
- Auth providers → Auth repository: binds implementation
- Auth repository → Auth data sources: uses
- Auth data sources → Network service: login request
- Auth data sources → Storage service: persist user
- Current user cache → Storage service: reads user
- Dashboard screen → Dashboard state: observes and dispatches
- Dashboard state → Dashboard repository contract: depends on
- Dashboard repository → Dashboard repository contract: implements
- Dashboard state → Dashboard repository: retrieves products
- Dashboard repository → Product data sources: delegates
- Product data sources → Network service: pages and search
- Product data sources → Storage service: optional cache
- Network service → Shared data contracts: maps responses and errors
- Dashboard screen → Error widget: renders failures
