Flutter Movie Clean Architecture

Flutter Movie App built with Riverpod, Clean Architecture, and GoRouter that showcases movies and TV series fetched from TMDB API. It includes now playing, popular, top-rated, and upcoming Movies, TV series and Celebrity with support for pagination, search, and detailed views.

✨ Features

Movies

🎞 Now Playing, Popular, Top Rated & Upcoming movie sections (paginated)
🔍 Movie Detail Pages with Cast & Crew
🎯 Recommended Movies
🔍 Search Movies (debounced)
👤 Artist/Actor Detail Page with navigation from movie cast
❤️ Favorite Movies (saved locally using Hive database)

TV Series

📺 Airing Today, On The Air, Popular & Upcoming TV series sections (paginated)
🔍 TV Series Detail Pages with Cast & Crew
🎯 Recommended TV Series
🔍 Search TV Series (debounced)
👤 Artist/Actor Detail Page with navigation from TV series cast
❤️ Favorite TV Series (saved locally using Hive database)

Celebrity

🌟 Popular and Trending Celebrities/Persons sections (paginated)
🔍 Celebrity Search functionality (debounced)
👤 Celebrity Detail Page with navigation from movie/tv cast
❤️ Favorite Celebrities (saved locally using Hive database)

Common Features

📃 Infinite Scroll Pagination across all list views
🔄 Bottom Navigation with tab switching
🌐 Multi-language Support with Localization (English & Spanish)
🧭 Declarative Routing with GoRouter
🧱 Clean Architecture (Presentation / Domain / Data) — no empty abstraction layers
🧪 Riverpod State Management
🌐 Network layer using Dio with Logging
🚀 Smooth UX with loading indicators and cached images
❤️ Favorite Management with Local Storage (Hive)
🎨 Dark/Light/System Theme Toggle (persisted)
🔍 Unified Universal Search with debounced API calls

🏗️ Architecture

This project follows Clean Architecture principles with pragmatic simplifications:

Layers:

Presentation Layer: UI components (pages/widgets), state management (Riverpod providers)
Domain Layer: Business entities, repository interfaces
Data Layer: Remote data sources (Dio), local persistence (Hive), repository implementations, data models

Key Architectural Decisions:

No empty use case layer: Use cases that only delegate to repositories were removed. Providers call repositories directly. Use cases are only added when they contain actual business logic.
Shared entities: Duplicate Cast/Crew classes across features merged into core/entities/credit_entity.dart.
Shared widgets: MediaCard, DescriptionSection, RecommendationsSection, CreditsSection reused across movie and TV series features.
Favorites as a proper feature: Favorites provider and model moved from core/hive/ and movie/ into features/favorites/ with proper Clean Architecture layers.

📁 Project Structure

flutter_movie_clean_architecture/
├── .env                                    # TMDB API key (gitignored)
├── lib/
│   ├── main.dart
│   ├── core/
│   │   ├── config/
│   │   │   └── app_constant.dart           # URLs, reads apiKey from .env
│   │   ├── entities/
│   │   │   └── credit_entity.dart          # Shared Cast/Crew entities
│   │   ├── hive/
│   │   │   └── hive_helper.dart            # Hive initialization
│   │   ├── localization/
│   │   │   ├── app_localizations.dart
│   │   │   └── localization_helper.dart
│   │   ├── network/
│   │   │   └── dio_provider.dart           # Dio HTTP client
│   │   ├── theme/
│   │   │   ├── app_theme.dart
│   │   │   ├── theme_providers.dart        # ThemeModeNotifier (direct Hive)
│   │   │   └── theme_toggle_widget.dart
│   │   ├── utils/
│   │   │   ├── pagination_consumer_state.dart  # Reusable pagination logic
│   │   │   └── utils.dart
│   │   └── widgets/
│   │       ├── media_card.dart             # Unified card for movie/tv/person
│   │       └── detail_sections.dart        # Shared Description/Recommendations/Credits
│   ├── routing/
│   │   └── app_router.dart
│   ├── presentation/
│   │   ├── pages/
│   │   │   └── main_tab_page.dart
│   │   └── widgets/
│   │       └── universal_search.dart       # Debounced universal search
│   └── features/
│       ├── celebrity/
│       │   ├── data/
│       │   │   ├── datasources/
│       │   │   ├── models/
│       │   │   └── repositories/
│       │   ├── domain/
│       │   │   ├── entities/
│       │   │   └── repositories/
│       │   └── presentation/
│       │       ├── pages/
│       │       └── providers/
│       ├── favorites/                      # Proper Clean Architecture layers
│       │   ├── data/models/
│       │   │   ├── favorite_model.dart
│       │   │   └── favorite_model.g.dart
│       │   ├── presentation/providers/
│       │   │   └── favorite_provider.dart  # Single favorites StateNotifier
│       │   └── favorites_page.dart
│       ├── movie/
│       │   ├── data/
│       │   │   ├── datasources/
│       │   │   ├── models/
│       │   │   └── repositories/
│       │   ├── domain/
│       │   │   ├── entities/
│       │   │   └── repositories/
│       │   └── presentation/
│       │       ├── pages/
│       │       │   ├── movie_main_page.dart
│       │       │   ├── movie_detail_page.dart
│       │       │   ├── artist_detail_page.dart
│       │       │   ├── now_playing_page.dart    # Paginated
│       │       │   ├── popular_page.dart        # Paginated
│       │       │   ├── top_rated_page.dart
│       │       │   └── upcoming_movies_page.dart
│       │       └── providers/
│       │           └── movie_provider.dart
│       └── tv_series/
│           ├── data/
│           ├── domain/
│           └── presentation/
│               ├── pages/
│               └── providers/
├── test/
├── pubspec.yaml
├── analysis_options.yaml
├── .env
└── .gitignore

🚀 Getting Started

Prerequisites

Flutter SDK (3.24.1 or higher)
Dart SDK (3.8.0 or higher)
Git
TMDB API Key (free, register at https://www.themoviedb.org/settings/api)

Installation

Clone the repository:

git clone git@github.com:piashcse/flutter-movie-clean-architecture.git
cd flutter-movie-clean-architecture

Set up environment variables:

# Edit .env and add your TMDB API key
TMDB_API_KEY=your_api_key_here

Install dependencies:

flutter pub get

Generate code (build runner):

flutter pub run build_runner build --delete-conflicting-outputs

Run the app:

flutter run

🛠️ Built With

Flutter - Google's UI toolkit
Riverpod - Composable state management
GoRouter - Declarative routing
Dio - HTTP client
flutter_dotenv - Environment variable management
JsonSerializable - JSON code generation
Flutter Localizations - Multi-language support
PrettyDioLogger - HTTP request logging
Hive - Local key-value database
CachedNetworkImage - Image caching

👨‍💻 Developed By

Mehedi Hassan Piash

📄 License

Copyright 2025 piashcse (Mehedi Hassan Piash)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Name		Name	Last commit message	Last commit date
android		android
assets/l10n		assets/l10n
ios		ios
lib		lib
screen_shots		screen_shots
test		test
.gitignore		.gitignore
.metadata		.metadata
README.md		README.md
analysis_options.yaml		analysis_options.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Navigation Menu

Repository navigation

About

Repository files navigation

Flutter Movie Clean Architecture

✨ Features

Movies

TV Series

Celebrity

Common Features

🏗️ Architecture

Layers:

Key Architectural Decisions:

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

🛠️ Built With

👨‍💻 Developed By

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Flutter Movie Clean Architecture

✨ Features

Movies

TV Series

Celebrity

Common Features

🏗️ Architecture

Layers:

Key Architectural Decisions:

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

🛠️ Built With

👨‍💻 Developed By

📄 License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages