momshaddinury/flutter_template

This system is a Flutter-based mobile application scaffold implementing Clean Architecture with Riverpod for state management and Retrofit for network transport. It provides a complete, type-safe foundation for user authentication, session management, and localization across English, Arabic, and Bangla. The codebase enforces strict architectural boundaries and design consistency through a custom static analysis tool and a structured, token-driven theming system.

35 changes.

The project underwent a comprehensive architectural overhaul, migrating to Flutter 3.38, Riverpod, and Retrofit while establishing a strict Clean Architecture with domain use cases and typed repositories. This foundation enabled the implementation of core features including a localized authentication flow, session management, and a unified design system with three-tier theme tokens. The period also saw the introduction of custom linting tools and the modernization of native build configurations for both Android and iOS.

16 changes.

This period focused on rebuilding the network transport layer with a structured interceptor pipeline, secure token storage, and single-flight refresh logic. It introduced a strict separation between recoverable infrastructure errors and programmer bugs, mapping them to domain-specific business failures for consistent handling. The work also established reactive session and onboarding state providers and enforced architectural consistency through new static analysis rules in the Flutter Guardian package.

A new LoginResponseEntity has been introduced in the domain layer to represent the signed-in user. This entity exposes core user profile fields (id, username, email, name, gender, image) while explicitly excluding authentication tokens, which are managed separately by the data layer's TokenManager.

lib/src/domain/entities · high confidence

Introduced a new Riverpod provider for managing application locale state. This component initializes the default language to English and exposes methods to change the locale or retrieve the current one, delegating the actual locale switching logic to existing use cases.

_lib/src/presentation/core/application\_state/localization\provider · high confidence

A new Riverpod provider for logout functionality has been introduced. It manages the logout state using AsyncValue and includes a guard to prevent concurrent requests while loading. Upon a successful logout, it triggers a repository cache reset and invalidates the session status provider to ensure the user is fully logged out. It also checks if the provider is still mounted before updating the state after the asynchronous operation completes.

_lib/src/presentation/core/application\_state/logout\provider · high confidence

A new ProfilePage widget has been added to the presentation layer. Currently, it serves as a structural placeholder that renders a generic placeholder widget, laying the groundwork for future profile-related UI components.

lib/src/presentation/features/profile · high confidence

The \flutter\_guardian\ package now provides a suite of static analysis rules that enforce the template's architectural and design conventions. These rules, registered as warnings in the Dart analysis server, ensure that imports follow Clean Architecture layer boundaries, prevent cross-feature and cross-service coupling, and mandate that dependency-injection providers adhere to specific naming and lifetime patterns. Additionally, the linter flags hardcoded text, design values, and route literals, enforces SVG icon usage through a single entry point, and prevents helper functions from returning \Widget\ to preserve element-tree optimization.

_packages/flutter\guardian/lib · high confidence

The new HomePage widget presents a localized home title and a logout button. It integrates with the logout provider to show a loading indicator while the action is in progress and displays user-friendly error messages via snackbar when the logout operation fails, using the business failure UI mapper and current locale.

lib/src/presentation/features/home · high confidence

The flutter\_guardian package is introduced as a new tool for Flutter and Dart projects, providing custom lint rules to enforce repository, service, and use case naming conventions. Users can integrate it by adding it to their dev\_dependencies and including its analysis\_options.yaml, which extends the standard lints/recommended set. The package requires Flutter \>=3.38.4 and Dart ^3.10.3.

_packages/flutter\guardian · high confidence

New use-case classes have been added to the domain layer to encapsulate specific business operations. Authentication flows are now handled by LoginUseCase, LogoutUseCase, and RestoreSessionUseCase, which wrap repository calls with a standard Result type. Localization management is exposed via GetCurrentLocaleUseCase and SetCurrentLocaleUseCase. Router logic, including onboarding and session status checks, is centralized in GetOnboardingStatusUseCase, GetSessionStatusUseCase, and MarkOnboardingCompletedUseCase. Additionally, ResetRepositoryUseCase provides a mechanism to invalidate all repository providers in the dependency injection container, ensuring cached data is cleared when contexts change (e.g., during logout or business switching).

_lib/src/domain/use\cases · high confidence

New Riverpod providers have been added to expose the application's onboarding completion state and current session status (authenticated or unauthenticated) to the presentation layer. The onboarding status provider acts as a thin reactive wrapper over the use case, allowing the router to track when onboarding is finished. The session status provider derives the user's authentication state from stored tokens, enabling the router to enforce the correct authentication gate and navigate users between authenticated and unauthenticated areas based on the validity of their session.

_lib/src/presentation/core/application\_state/onboarding\_status\_provider, lib/src/presentation/core/application\_state/session\_status\provider · high confidence

The login screen now includes a language switcher widget that allows users to change the app's display language, with the login form fields (email and password) displaying localized hints and error messages. Additionally, the login form now enforces validation rules, requiring both email and password fields to be filled, with the password field requiring a minimum length of 6 characters. A 'Remember Me' checkbox and 'Forgot Password' link have also been added to the form footer.

lib/src/presentation/features/authentication/login/widgets · high confidence

This change introduces several new core widgets and a structured failure-handling system. A new \FailureView\ widget and \BusinessFailureUIMapper\ provide a standardized way to display localized error messages and recovery actions (retry, reauthenticate, or inline field errors) based on domain failures. A \LoadingIndicator\ widget is added for consistent loading states. Navigation is updated with a \NavigationShell\ featuring a bottom navigation bar with Home and Profile tabs, and a \NotFoundScreen\ is introduced to handle unmatched routes with a 'Go Home' button. Additionally, a reusable \SvgIcon\ widget is added to centralize SVG icon rendering, and a \HeadingSmall\ widget is created to unify app bar text styling.

lib/src/presentation/core/widgets · high confidence

The application introduces three new domain-layer repositories to manage core user-facing capabilities. AuthenticationRepository defines the contract for user login (including a 'Remember Me' option), logout, and session restoration, ensuring sessions are cleared if the user opts out. LocaleRepository provides methods to get and set the application language, supporting localization switching. RouterRepository manages navigation state by tracking onboarding completion and deriving session existence directly from stored tokens rather than stale flags.

lib/src/domain/repositories · high confidence

The login view now presents a localized interface featuring a language switcher, a 'Remember Me' option, and a loading indicator on the login button. It displays localized error messages via snackbar notifications and provides a link to the registration screen, all wired to the Riverpod login provider.

lib/src/presentation/features/authentication/login/view · high confidence

The network layer now includes a set of new interceptors that handle authentication, localization, error parsing, and debugging. The \AuthHeaderInterceptor\ automatically attaches access tokens to requests based on endpoint requirements, attempting a silent token refresh if the current token is missing or expired, and rejecting requests for protected endpoints if no token is available. The \RefreshRetryInterceptor\ handles 401 responses by refreshing the token and replaying the request once, preventing infinite loops and handling concurrent requests via single-flight deduplication. The \LocaleHeaderInterceptor\ adds the \Accept-Language\ header to all requests using a configurable resolver. The \ErrorAttachmentInterceptor\ parses server error responses and attaches structured error details to Dio exceptions for downstream handling. Finally, the \DebugLoggerInterceptor\ provides a secure, debug-only logging mechanism that omits sensitive data like request bodies, response bodies, and header values.

lib/src/data/services/network/transport/interceptors · high confidence

The registration screen now includes a confirm password field that validates against the primary password entry, ensuring users must match their password and confirmation before proceeding. The form also enforces required fields for first name, last name, email, and password (minimum 6 characters), with toggleable visibility for password inputs and localized labels throughout the interface.

lib/src/presentation/features/authentication/registration · high confidence

A new $ThemeData class has been introduced in the core theme module to assemble Flutter theme data from a single set of color bindings. This builder leverages three-tier design tokens (ColorExtension, TextStyleExtension, and DimensionsExtension) to consistently apply light and dark mode styles across components such as app bars, buttons, checkboxes, and input decorations, ensuring that all UI elements derive their colors and dimensions from the central theme extensions.

lib/src/presentation/core/theme/src · high confidence

The \rest\_client\_kit\ package has been completely removed from the codebase. This deletion eliminates the previous Dio-based HTTP client implementation, including its token management via SharedPreferences, caching and retry interceptors, and the specific exception handling logic that mapped HTTP status codes (such as 401 Unauthorized) to custom failure classes. Applications relying on this package for network requests must migrate to the new network provider.

_packages/rest\_client\kit · high confidence

The application entry point has been refactored to use a new bootstrap mechanism via UncontrolledProviderScope, replacing the previous ProviderScope setup. This change integrates localization support by configuring AppLocalizations delegates and enabling dynamic locale switching through a new provider. Additionally, the UI theme configuration has been expanded to support both light and dark modes, with the app now defaulting to the system's theme preference.

lib · high confidence

The authentication feature has been restructured by removing the entire data layer, including the \AuthenticationDataSource\ interface and its implementation, along with associated model classes (\LoginResponseModel\, \SignUpResponseModel\) and repository implementations. This change eliminates the previous \rest\_client\_kit\ dependency in favor of a new architecture using Retrofit, as indicated by the removal of the old network provider and the commit notes regarding interceptor addition. The domain layer entities and use cases remain, but the presentation layer's login provider and UI pages have been deleted, indicating a temporary removal of the login and registration screens while the new network implementation is integrated.

lib/src/feature/authentication · high confidence

The router now determines the current destination through a single derived provider that composes startup, onboarding, and session status. Users will see a splash screen while the app initializes or if an error occurs, be directed to onboarding if it has not been completed, and then land on either the home screen (if authenticated) or the login screen (if not). This change centralizes navigation logic, ensuring the router reacts only to these high-level states without directly handling tokens or side effects.

_lib/src/presentation/core/router/router\state · high confidence

The core library has been restructured to improve type safety and developer experience. A new \Result\<T, E\>\ type and \Unit\ marker are introduced to standardize repository return values, replacing the previous \Repository\ base class and \UseCase\ abstraction which have been removed. A comprehensive validation framework has been added, featuring a \Validator\ utility and specific validators for email, password, length, and required fields, all integrated with the new localization system. Localization support is now robust, with ARB files for English, Arabic, and Bangla, and extensions to access translations easily. Additionally, a \CrashReporter\ abstraction and global error handlers have been added to centralize error reporting, and dependency injection has been migrated to use Riverpod providers for use cases.

lib/src/core · high confidence

The forgot password flow (Create New Password, Email Verification, Reset Password, and Reset Password Success) now uses the app's unified typography widgets (e.g., HeadingLevel3Text, BodySmallText.muted) and theme-driven spacing (context.dimensions.space) instead of ad-hoc styles and hardcoded sizes. All user-facing strings are localized via context.locale, and layout values such as logo size, field height, and icon size are driven by theme dimensions. The app bar titles are now visible, and navigation routes use the typed Routes API consistently.

_lib/src/presentation/features/authentication/forgot\password · high confidence

The app now uses a typed \Routes\ enum to define all navigation paths, ensuring consistency between route names and URL segments. A new \RedirectGate\ enforces session-based navigation rules: unauthenticated users are redirected to login, while authenticated users visiting auth-specific pages are sent to the home screen. The router is initialized with these gates to prevent redirect loops and ensure correct flow through splash, onboarding, and authentication stages.

lib/src/presentation/core/router · high confidence

Added \LoginResponseModel\ and \LoginRequestModel\ classes in \lib/src/data/models/login\_model.dart\ to represent authentication data with specific fields (such as access and refresh tokens for the response, and username/password for the request). These models utilize the \dart\_mappable\ library for serialization, exposing a static \fromJson\ constant for decoding JSON payloads, which replaces previous ad-hoc or factory-based parsing approaches with a structured, generated mapper pattern.

lib/src/data/models · high confidence

The domain layer now exposes a new \BusinessFailure\ sealed class to represent specific error conditions (such as unauthenticated, permission denied, invalid input, not found, conflict, cancelled, unexpected, and defect) rather than exposing raw infrastructure exceptions. This change allows use cases and the presentation layer to handle errors based on business intent, with the repository layer responsible for translating underlying infrastructure failures into these domain-specific types.

lib/src/domain/failures · high confidence

The theme system now uses a structured token architecture with primitive, semantic, and extension layers. Colors are organized into semantic roles (primary, text, border, background, status) with distinct light and dark mode bindings. Dimensions are exposed via a new extension covering spacing, radii, sizes, elevation shadows, and breakpoints. Typography is unified under a semantic type scale (display, heading, body, label, action) that references a primitive font family and size scale. These tokens are consolidated in the ThemeExtensions mixin for consistent access across the application.

_lib/src/presentation/core/theme/src/theme\extensions · high confidence

The application now uses a structured design token system accessible via \BuildContext\ extensions, providing \color\, \textStyle\, and \dimensions\ tokens that automatically resolve based on the active light or dark theme mode. This change replaces hardcoded layout values and colors with semantic tokens, ensuring consistent styling across the UI and simplifying theme switching for users.

lib/src/presentation/core/theme · high confidence

The data layer now includes concrete repository implementations for authentication, locale management, and routing. AuthenticationRepositoryImpl handles login with optional 'Remember Me' persistence, session restoration, and logout, while delegating token storage to TokenManager and using a new LoginMapper to strip tokens from domain entities. LocaleRepositoryImpl persists and retrieves the user's language preference, and RouterRepositoryImpl tracks onboarding completion and checks for active sessions via token presence.

lib/src/data/repositories · high confidence

The app now uses platform-backed secure storage (AES-GCM on Android, Keychain on iOS) for auth tokens, with read failures returning null instead of throwing to prevent token leakage. Token management includes in-memory caching with write-through persistence and single-flight refresh, where concurrent refresh requests share one HTTP roundtrip. Refresh failures are classified as either auth-definitive (clearing tokens on 400/401/403) or transient (keeping tokens on timeouts/5xx). Network configuration is now runtime-tunable via a NetworkConfig class, and server errors are parsed into a structured ServerError object with optional code and details fields.

lib/src/data/services/network/auth · high confidence

The onboarding experience has been updated to display text in the user's selected language and adapt to the current theme. Hardcoded strings for titles, subtitles, and the 'Get Started' button are now resolved via localization, and layout values (such as spacing and icon sizes) are driven by the theme's dimension extension rather than fixed constants. Additionally, the 'Get Started' button now triggers a use case to mark onboarding as completed instead of directly navigating to the login route.

lib/src/presentation/features/onboarding · high confidence

The network layer now uses a new \DioBuilder\ to construct the HTTP transport and token manager together, establishing a strict FIFO interceptor pipeline: locale headers, authentication injection, error attachment, optional extra interceptors (for telemetry), logging, and finally a refresh-retry interceptor. This change introduces single-flight token refresh logic to prevent concurrent refresh requests and ensures that authentication headers are applied only to endpoints marked with \RequestAuth\, while error bodies are parsed once and attached to exceptions for downstream consumers.

lib/src/data/services/network/transport · high confidence

The network layer has been refactored to use a new authentication model where endpoints are explicitly marked as public, optional, or protected. Protected endpoints automatically attach bearer tokens and handle session expiration by refreshing the token and retrying the request, while public endpoints never carry tokens. This change introduces a centralized endpoint configuration and specific exception handling for missing access tokens, ensuring that unauthenticated users see a proper session-expired flow rather than generic errors.

lib/src/data/services/network · high confidence

The cache implementation has been refactored to use a value-dispatched approach where saving data is routed based on the runtime type of the value (String, int, bool, double) rather than the generic type argument, ensuring that unsupported types throw an error instead of silently coercing data. Additionally, a new 'rememberMe' cache key was added to persist the user's preference for the 'Remember Me' checkbox, and the service interface was moved to the data services layer.

lib/src/data/services/cache · high confidence

The application's navigation logic has been reorganized into distinct, typed route files (authentication, shell, and onboarding) to improve code organization and type safety. This change introduces a bottom navigation shell for the Home and Profile sections, replaces the previous splash screen with a startup widget that handles loading transitions, and removes the automatic onboarding-completion flag from the onboarding route definition. These updates provide a more structured and maintainable routing architecture for the presentation layer.

lib/src/presentation/core/router/parts · high confidence

The login screen now uses a Riverpod provider to manage authentication state, replacing previous custom state classes with AsyncValue. This provider exposes a login method that accepts email, password, and an optional shouldRemember flag, enabling the 'Remember Me' functionality. It handles loading states, pattern-matches on success or error results from the use case, and invalidates the session status provider upon successful login, while guarding against state updates if the widget is unmounted.

lib/src/presentation/features/authentication/login/riverpod · high confidence

The startup provider has been refactored to include additional initialization steps during the application launch sequence. Specifically, it now calls the localization provider to set the current locale and executes the restore session use case to re-establish the user's session. This logic was moved from the core layer to the presentation layer's application state, and the provider was renamed from appStartup to startup.

_lib/src/presentation/core/application\_state/startup\provider, lib/src/presentation/core/widgets/startup · high confidence

The data layer now enforces a strict separation between recoverable infrastructure errors (such as network timeouts, HTTP 4xx/5xx responses, and parsing failures) and programmer bugs (Dart Errors like null dereferences). Repository operations are wrapped in \asyncGuard\ and \syncGuard\ methods that automatically classify exceptions into specific \InfraFailure\ types (e.g., \TimeoutFailure\, \UnauthorizedFailure\, \NotFoundFailure\) and map them to \BusinessFailure\ outcomes. Crucially, any unhandled \Error\ is reported to the \CrashReporter\, rethrown in debug builds for immediate visibility, and folded into a generic \defect\ failure in release builds to prevent silent crashes while preserving the error for monitoring.

lib/src/data/failures · high confidence

The theme system has been restructured to rely on a three-tier design token model (colors, typography, and dimensions) rather than hardcoded values. All UI components—including app bars, buttons, checkboxes, dropdowns, input fields, and the bottom navigation bar—now derive their appearance from these shared tokens. This ensures consistent spacing, sizing, and color usage across the app, with specific behaviors like button press states, input field focus/error borders, and navigation bar label styles now driven by the central theme configuration.

lib/src/presentation/core/theme/src/part · high confidence

The app now uses a new set of semantic text widgets (HeadingLevel1Text, HeadingLevel3Text, BodySmallText, LabelText) that apply design tokens from the theme, replacing ad-hoc styling. These widgets support standard text properties like maxLines, overflow, and softWrap. Additionally, the LinkText widget has been moved to the core presentation layer and its styling updated to use the label token with muted/default colors instead of the previous link text token.

lib/src/presentation/core/widgets/text · high confidence

The iOS native layer has been updated to use the modern UIScene lifecycle by introducing a SceneDelegate and configuring the Info.plist to route scenes through it, replacing the legacy AppDelegate-based launch flow. The AppDelegate now implements FlutterImplicitEngineDelegate to handle plugin registration within this new model. Additionally, the project has been configured to use CocoaPods for dependency management, adding the necessary workspace references, build phases, and framework embedding scripts, while also enabling GPU validation mode in the Xcode scheme for improved debugging.

ios · high confidence

Added comprehensive test coverage for Flutter Guardian lint rules; Added tests for Repository error handling and crash reporting; Added tests for RouterRepositoryImpl session and onboarding logic; Added tests for core error handling, dependency injection, and network smoke tests; Added tests for exception classification logic; Added tests for presentation failure handling and routing logic; Added unit tests for LoginMapper; Added unit tests for the network service layer; Removed default widget smoke test.

The Android build system now uses Gradle 9.1.0 (previously 7.6.3) via the wrapper configuration. This change updates the underlying build tool version used to compile the Android application, which may affect build performance and compatibility with the Android Gradle Plugin and Kotlin versions specified in the project configuration.

android · high confidence

The project has been upgraded to the Flutter 3.38.4 SDK and Dart 3.12.0, with the Android build system migrated to Kotlin DSL (\.kts\) and updated to AGP 9.0.1, Kotlin 2.3.20, and Java 17. This migration includes raising the iOS deployment target to iOS 13, increasing Gradle JVM memory limits, and adjusting the Android compile SDK to 37 to resolve metadata conflicts with \flutter\_secure\_storage\. Additionally, the custom \rest\_client\_kit\ package has been removed in favor of the \retrofit\ and \dio\ libraries, and several core dependencies (such as \go\_router\, \flutter\_riverpod\, and \freezed\) have been updated to newer major versions to support the new architecture and codegen pipeline.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 58.

• Code Health 99
• Architecture 89
• Maturity 67
• Readiness 30
• Security 100
• Domain Modelling 100

• 155 commits — 133 feature/other, 22 fixes

• lib/src — 110 commits
• (root) — 21 commits
• packages/flutter_guardian — 13 commits
• android/app — 2 commits
• ios/Runner — 2 commits
• packages/rest_client_kit — 2 commits
• docs/adr — 1 commit
• docs/architecture.md — 1 commit
• docs/dependency_injection.md — 1 commit
• docs/network.md — 1 commit
• test/data — 1 commit

• fix: feat (failures): CrashReporter seam + bug policy in the repository guards
• fix: fix (28): Remove EmailValidation from LoginForm
• fix: fix (guardian): the SVG rule points at svg_icon.dart
• fix: fix (lints): address code-review findings
• fix: fix (network): address code-review findings
• fix: fix (riverpod): watch in builds, mounted guards after awaits
• fix: fix: Added loading indicator when user taps Login button
• fix: fix: Added new files
• fix: fix: Converted to new architecture
• fix: fix: Converted to relative import
• fix: fix: Fixed android version issue
• fix: fix: Fixed issue with Login API not working
• fix: fix: Fixed repository run time cache issue
• fix: fix: Inconsistency in Login Screen UI implementation
• fix: fix: On 401 exception remove the cached token from rest_client_kit
• fix: fix: Renamed service di variable
• fix: fix: Replaced previous route when user logs in or logs out from the app
• fix: fix: Updated asset gen folder directory
• fix: fix: Updated package imports to relative imports
• fix: fix: handle switch exhaustiveness and remove unused imports
• …and 135 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

momshaddinury/flutter_template was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.