enesakbal/Flutter-Clean-Architecture-Example

This is a Flutter-based movie and actor information application that fetches data from remote APIs and caches details locally. It implements a clean architecture with distinct layers for data, domain, and presentation, utilizing state management via Cubits to handle loading, success, and error states. The system supports browsing popular and top-rated movies, viewing detailed cast and crew information, managing user bookmarks, and switching between light and dark themes.

32 changes.

The project underwent a significant architectural shift to a clean, domain-driven structure, introducing comprehensive repositories, use cases, and data sources for movies and actors. This period also delivered new features including deep linking, infinite scrolling, theme management, and local storage integration.

12 changes.

This period focused on implementing new features for displaying actor and movie details, including UI components, data models, and URL launching utilities. The work was heavily supported by comprehensive unit testing across the data, domain, and presentation layers, alongside establishing a local database and dependency management scripts.

A new BaseIndicator widget has been introduced in the core components, displaying an adaptive circular progress spinner centered on the screen with a 2.5px stroke width.

lib/src/core/components/indicator · medium confidence

Introduced new exception classes to handle specific error scenarios. A DatabaseException class was added to manage database-related errors, specifically mapping Isar errors. Additionally, a NetworkException class was introduced to handle network-related errors, including various DioException types such as timeouts, connection errors, and bad responses, with specific handling for SocketException errors.

lib/src/core/exceptions · medium confidence

A new Dart extension on the int type has been added to map numeric genre IDs to their corresponding string names (e.g., 28 becomes 'Action'). This provides a convenient way to convert integer identifiers into human-readable genre labels within the application.

lib/src/core/extensions · high confidence

A new ToggleBookmarkCubit and its associated states (Initial, Loading, Success, Error) have been introduced to handle the logic for bookmarking and unbookmarking movies. This change enables users to toggle their bookmark status for a specific movie through the presentation layer, utilizing the existing MovieUsecases.

_lib/src/presentation/cubit/movie/toggle\bookmark · high confidence

A new abstract class ActorRepository has been introduced in the domain layer, defining two methods: getActorDetail to retrieve an actor's detailed information, and getActorSocialMedia to fetch their social media profiles. The implementation relies on fpdart's Either type for error handling, indicating a shift from the previous dartz-based approach.

lib/src/domain/repositories/actor · high confidence

A new GetMovieCreditsCubit and its associated state classes (Initial, Loading, Loaded, Error) have been introduced to handle the retrieval of movie credits. This component bridges the presentation layer to the movie use cases, allowing the UI to request and display credits for a specific movie.

_lib/src/presentation/cubit/movie/get\_movie\credits · high confidence

A new GetSavedMoviesCubit and its associated states (Initial, Loading, Loaded, Error) have been introduced to handle the retrieval of saved movies. This component exposes the getSavedMovieDetails method, which interacts with the domain layer to fetch and manage the state of saved movie details.

_lib/src/presentation/cubit/movie/get\_saved\movies · high confidence

New cubits have been introduced to manage the loading, success, and error states for fetching an actor's detailed information and their social media profiles. This includes the corresponding state classes and an export file to centralize access to these presentation-layer components.

lib/src/presentation/cubit/actor · high confidence

A new ActorUsecases class has been introduced to handle actor-related domain logic. It provides methods to fetch an actor's details and social media information, utilizing the fpdart library for error handling and the ActorRepository for data retrieval.

lib/src/domain/usecases/actor · high confidence

A new local data source for movie details has been introduced, enabling the app to cache and store detailed movie information (such as title, overview, and ratings) in the local Isar database. This change allows the application to access movie details offline or from a local cache, improving performance and reliability by reducing reliance on network requests for this specific data.

_lib/src/data/datasources/local/\collections · high confidence

Users can now browse popular and top-rated movies, view detailed information about specific films, and access a dedicated bookmarks list. The app's main navigation has been updated to include a bottom bar for switching between the movie listings and the bookmarks section, with error states in the movie and bookmarks views now displaying a retry button for improved usability.

lib/src/presentation/view · high confidence

Introduced abstract interfaces and concrete implementations for fetching movie and actor data from remote APIs. The movie data source now provides methods to retrieve popular and top-rated movie listings, as well as movie credits. The actor data source provides methods to fetch actor details and social media information. A shared \EntityConvertible\ mixin was added to standardize entity-to-model conversion logic across data sources.

lib/src/data/datasources/remote · high confidence

A new shell script, refresh\_script.sh, has been added to the scripts directory. This script automates the process of refreshing project dependencies by running flutter clean, flutter pub get, and pod install, streamlining the setup process for developers.

scripts · high confidence

A new \NetworkErrorModel\ class has been introduced to represent structured error responses from the network layer. This model parses \status\_code\ and \status\_message\ fields from JSON, enabling the application to handle network errors with specific, typed data rather than generic exceptions. The accompanying generated serialization code ensures reliable conversion between JSON and the Dart object.

lib/src/core/network/model · high confidence

The application now uses dedicated constant classes to manage configuration and routing paths. App configuration (base URL and API token) is loaded from environment variables via flutter\_dotenv. Image URLs for the TMDB service are generated through a dedicated helper. Path and URL endpoints for movies, actors, and bookmarks are centralized in their respective constant files, providing a single source of truth for navigation routes and API paths.

lib/src/core/constants · high confidence

A new injector configuration file has been introduced to centralize the registration of all application dependencies. This includes network clients, database instances, data sources, repositories, use cases, and various Cubits (such as GetMovieCreditsCubit and GetActorSocialMediaCubit). This change provides a single, unified entry point for initializing the dependency injection container, ensuring that all components are properly wired together at startup.

lib/src · high confidence

Added new repository implementations for handling movie and actor data. The MovieRepositoryImpl now supports fetching popular and top-rated movies, retrieving movie credits, and managing local storage of movie details using Isar. The ActorRepositoryImpl provides methods to fetch actor details and social media information. Both implementations utilize fpdart's Either type for error handling and integrate with remote and local data sources.

lib/src/data/repositories · high confidence

A new MovieUsecases class is added to the domain layer, exposing methods to fetch popular and top-rated movies, retrieve movie credits, and manage local movie details (saving, deleting, and bookmarking). This provides a unified interface for movie-related domain logic, leveraging the existing MovieRepository.

lib/src/domain/usecases/movie · high confidence

Added a new LocalDatabase class that manages the initialization of the Isar local database. This class handles opening the database with the MovieDetailCollection schema and provides a safe accessor for the database instance, ensuring it is only used after initialization.

lib/src/core/database · high confidence

Added new data models for actor details, actor social media, movie credits (cast and crew), and movie listings. These models, located in lib/src/data/models, provide the data structures and JSON serialization logic for the application's domain entities, enabling the app to parse and map API responses for actors, movies, and their associated credits.

lib/src/data/models · high confidence

The application now includes a dedicated theme configuration in \lib/src/core/theme/app\_theme.dart\ that defines light and dark themes using the \flex\_color\_scheme\ library with Material 3. Additionally, a \ThemeCubit\ and its associated state class have been added to manage and persist the user's preferred theme mode (light, dark, or system) via the BLoC/HydratedBloc pattern.

lib/src/core/theme · high confidence

Added a new \DioClient\ class in the core network layer that wraps the Dio HTTP client library. This client is configured with a base URL, JSON content-type headers, a bearer token for authorization, and 15-second connect/receive timeouts. It provides standard HTTP methods (GET, POST, PUT, PATCH, DELETE) and includes a pretty logger for debugging API interactions.

lib/src/core/network · high confidence

Added the MovieRepository interface defining the domain contract for movie data access. The interface includes remote data source methods for retrieving top-rated and popular movies, as well as movie credits, all returning Either types for error handling. It also defines local data source methods for saving, deleting, and checking the status of saved movie details in the database. This establishes the abstraction layer for movie-related domain operations.

lib/src/domain/repositories/movie · high confidence

A new \UrlLauncherManager\ class has been added to centralize URL launching logic. It provides static methods to redirect to specific social media platforms (Instagram, Twitter, Facebook, YouTube, IMDb, and TikTok) using their respective IDs, handling the underlying \url\_launcher\ calls and logging errors if a URL cannot be launched.

lib/src/core/utils · high confidence

The movie detail screen now includes a new \_ActorCard widget that displays an actor's photo, name, and character role in a styled card, and a \_TagContainer widget that renders movie tags as styled pills. These components enhance the visual presentation of cast and metadata within the movie detail view.

_lib/src/presentation/\_widget/movie\detail · high confidence

Users can now view an actor's social media accounts via a new bottom sheet that displays icons for Instagram, Twitter, Facebook, YouTube, IMDb, and TikTok, with the actor's name shown in the header. Additionally, a new movie card component has been introduced, featuring a blurred background overlay with the movie title, which can be bookmarked for later viewing.

_lib/src/core/components/bottom\sheet · high confidence

Added three new UI components in the core buttons directory: a BookmarkButton that allows users to save and toggle movie bookmarks using a state-aware icon; a SocialButton that provides platform-specific buttons for Instagram, Twitter, Facebook, YouTube, IMDb, and TikTok, each linking to the corresponding social profile; and a RetryButton that displays a text prompt and a button to trigger a retry action. These components introduce new interactive elements for user engagement and error handling.

lib/src/core/components/buttons · high confidence

Added new domain entities to model actor details, social media links, and movie credits (cast and crew), as well as movie detail and listing structures. These entities, all extending Equatable for value-based equality, provide the data models required to represent actor information and movie metadata within the application's domain layer.

lib/src/domain/entities · high confidence

A new \\_MovieListingWidget\ has been introduced in the movies presentation layer, rendering a scrollable grid of movie cards. The widget implements infinite scroll behavior by detecting when the user reaches the bottom of the list and triggering a callback, while also supporting hero animations for individual movie detail transitions.

_lib/src/presentation/\widget/movies · medium confidence

Added new barrel files (export\_datasources.dart, export\_repositories.dart, export\_usecases.dart) that re-export specific data source, repository, and use-case classes. This change simplifies imports for consumers by providing single entry points for the local/remote data sources (movie and actor), the actor and movie repositories, and the actor and movie use cases.

lib/src/data/datasources, lib/src/domain/repositories, lib/src/domain/usecases · high confidence

The BaseNetworkImage widget has been introduced to handle network image loading with a new hasRadius parameter. When enabled, images are displayed with an 8px border radius; when disabled, images are shown without rounded corners. This change allows consumers of the image component to control whether images are displayed with rounded corners or as sharp rectangles.

lib/src/core/components/image · high confidence

The application entry point now initializes environment variables, sets up a global service locator (GetIt), and configures HydratedBloc storage. The main widget tree is restructured to use MultiBlocProvider for state management (ThemeCubit, GetMovieCreditsCubit, GetSavedMoviesCubit) and integrates AutoRouter for navigation. This replaces the previous minimal setup with a full architecture supporting movie credits, saved movies, and theme management.

lib · medium confidence

The local data source for movie details is now defined by the \MovieLocalDataSource\ interface, which specifies methods for saving, deleting, checking, and retrieving movie details. The \MovieLocalDataSourceImpl\ class implements this interface, using the \LocalDatabase\ dependency to perform the actual database operations. This change abstracts the data source, separating the contract from the implementation.

lib/src/data/datasources/local/movie · medium confidence

The GetPopularMoviesCubit and GetTopRatedMoviesCubit now implement lazy loading. Each cubit maintains an internal list of movies and a page counter, appending new results to the existing list rather than replacing it. The UI will see incremental updates as more movies are fetched, and the cubits stop requesting new pages once the server returns fewer than 20 movies, preventing unnecessary network calls.

_lib/src/presentation/cubit/movie/get\_popular\_movies, lib/src/presentation/cubit/movie/get\_top\_rated\movies · high confidence

The app now uses a new \AppRouter\ configuration that defines navigation for the Movies, Bookmarks, and Movie Detail screens, including a fade transition for the movie detail view. Additionally, a generated assets file (\assets.gen.dart\) has been added to provide typed access to new social media SVG icons (Facebook, IMDb, Instagram, TikTok, Twitter, and YouTube).

lib/src/config · medium confidence

The iOS minimum deployment target has been increased from 11.0 to 12.0, requiring devices running iOS 12 or later. The project has been updated to use the \@main\ attribute for the app entry point and now includes a \LSApplicationQueriesSchemes\ configuration for \sms\ and \tel\ URL schemes. Additionally, the Xcode project has been restructured to include the \Pods\ group and \Pods\_Runner\ framework, indicating the integration of CocoaPods for dependency management.

ios · high confidence

Added test utilities for JSON reading and mocking; Added unit tests for actor and movie repository implementations; Added unit tests for actor and movie use cases; Added unit tests for actor detail and social media Cubits; Added unit tests for movie and actor remote data sources; Added unit tests for movie presentation cubits; Initial code coverage report added.

The project's dependencies have been updated to newer versions, including auto\_route (7.8.3 → 8.1.4), flutter\_bloc (8.1.2 → 9.0.0), hydrated\_bloc (9.1.2 → 10.0.0), and build\_runner (2.4.6 → 2.4.13). New packages were added to the project: cached\_network\_image for image caching, flex\_color\_scheme for theming, fpdart for functional programming, flutter\_dotenv for environment variables, flutter\_gen for asset generation, isar for local storage, json\_annotation for API models, pretty\_dio\_logger for network logging, shimmer for loading effects, and url\_launcher for deep linking. The iOS platform target was also raised from 11.0 to 12.0.

(dependencies) · medium confidence

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

• CAI 57 → 61 (+4.0)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 100 → 97 (-2.7)
• Architecture 100 → 88 (-12.5)
• Maturity 50 → 62 (+12.8)
• Readiness 35 → 41 (+5.8)
• Security 100 → 100 (+0.0)
• Domain Modelling 100 → 100 (+0.0)

• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• No exposed public API
• Test reliability not included
• complexity unreadable for .dart, .kt, .swift — churn × complexity hotspots could not be measured
• single-maintainer — knowledge-concentration (bus factor) risk

• Dependency hygiene PARTLY measured — Maven/Gradle declarations read, no dependency graph resolved
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (14 lines × 2) (lib/src/presentation/_widget/movies/movie_listing_widget.dart)
• Duplicated block (14 lines × 2) (lib/src/presentation/cubit/movie/get_popular_movies/get_popular_movies_cubit.dart)
• Duplicated block (15 lines × 2) (lib/src/data/datasources/local/_collections/movie_detail/movie_detail_collection.dart)
• Duplicated block (16 lines × 2) (lib/src/data/models/actor_social_media/actor_social_media_model.dart)
• Duplicated block (17 lines × 2) (lib/src/data/models/movie_credit/cast_model.dart)
• Duplicated block (19 lines × 2) (lib/src/data/models/actor_detail/actor_detail_model.dart)
• Duplicated block (26 lines × 2) (lib/src/presentation/cubit/movie/get_popular_movies/get_popular_movies_state.dart)
• MethodTooLong: _MovieDetailView.build (lib/src/presentation/view/movie_detail_view.dart)
• TodoComment (test/domain/repositories/movie/movie_repository_test.dart)
• TodoComment (test/domain/usecases/movie/movie_usecases_test.dart)

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

enesakbal/Flutter-Clean-Architecture-Example 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.