A modern, tactile, and highly responsive E-Commerce application built with Flutter and Firebase. ShopEase delivers a seamless shopping experience with elegant "Purple Clay" glassmorphic UI elements and robust state management using Clean Architecture principles.
- Claymorphism Design System: A custom Material 3 theme incorporating soft, pillowy drop shadows and inner shadows to create a "tactile" 3D button effect.
- Dynamic "Purple Clay" Palette: Utilizing deep purples, soft slates, and white glassmorphic backgrounds to create a premium shopping environment.
- Animated Splash Screen: A beautiful 2.5-second sequence using
AnimatedBuilderandTweenSequencefor bouncing scaling effects and graceful opacity fades before the app initiates.
- Multi-Provider Support: Seamlessly integrate with Firebase Authentication to offer Email/Password login, Anonymous Guest Login, and structured logic ready for Google Sign-In.
- Real-Time Route Guards: Integrating a custom
GoRouterRefreshStreamthat continuously monitors theAuthBlocstream, instantly booting unauthenticated users back to the/loginscreen if a token expires or state changes.
- Declarative Routing: Powered by
go_router, allowing for URL-based navigation (/app/products/:productId). - Stateful Bottom Navigation: Implementing a
ShellRoutealongside anIndexedStackto maintain the scroll positions and state of the Home, Products, and Profile tabs without reloading the widgets on every tab switch. - Reactive URL Query Filtering: The Products page dynamically reads URL query parameters (e.g.,
?category=electronics) to filter the catalog, making the app deeply linkable and SEO/Web ready.
- Predictable Global State: Leveraging
flutter_blocfor complex, global states (like Authentication) to guarantee consistent state emission and UI updates. - Error Handling via Functional Programming: Utilizing the
dartzpackage to returnEither<AuthFailure, User>from repositories. This guarantees that UI widgets gracefully handle all failure edge cases without relying on riskytry/catchblocks at the UI level.
ShopEase strictly adheres to Uncle Bob's Clean Architecture to separate concerns, ensure extreme testability, and completely decouple the UI from external frameworks.
The absolute core of the app. It has zero dependencies on Flutter, Firebase, or external APIs.
- Entities: Pure Dart classes representing core business objects (e.g.,
User,Product). - Failures: Abstract failure classes (e.g.,
AuthFailure) to represent business errors. - Repositories (Interfaces): Abstract contracts defining what data operations are possible, without caring how they are implemented.
Responsible for interacting with APIs, Local Storage, and Firebase.
- Repository Implementations: Concrete implementations of the Domain interfaces (e.g.,
AuthRepositoryImplmapping Firebase calls). - Models / DTOs: Data Transfer Objects containing
fromJson/toJsonfactories to translate external, messy API JSON into clean Domain Entities. - Exception Mapping: Catches external
FirebaseAuthExceptions and translates them into our safe DomainAuthFailureobjects.
Responsible for rendering pixels and capturing user input.
- Pages / Screens: The Flutter
StatelessWidgetandStatefulWidgetclasses. - State Management (Bloc/Provider): Receives events from the UI, communicates with the Domain layer repositories, and emits new States for the UI to consume via
BlocConsumerorBlocBuilder.
- Core: Flutter & Dart
- State Management: flutter_bloc & provider
- Routing: go_router
- Backend Services: firebase_auth & cloud_firestore
- Architecture Utilities:
- Design & UI:
- google_fonts (Plus Jakarta Sans & Inter)
- flutter_launcher_icons (Automated icon generation)
- Flutter SDK (stable channel)
- Dart SDK
- A Firebase Project (for Authentication & Database services)
-
Clone the repository:
git clone https://github.com/yourusername/shopease.git cd shopease -
Install dependencies:
flutter pub get
-
Configure Firebase: Ensure you have the Firebase CLI installed. Run the following command to link the app to your Firebase backend:
flutterfire configure
(Note: The
firebase_options.dartfile will be automatically generated in yourlib/directory). -
Launch the App:
flutter run
lib/
├── core/
│ └── theme/
│ └── app_theme.dart # Centralized Material 3 Theme tokens & Clay shadows
├── features/
│ ├── auth/ # Authentication Feature
│ │ ├── application/ # AuthBloc, States, and Events
│ │ ├── data/ # AuthRepositoryImpl, FirebaseAuth integration
│ │ ├── domain/ # User Entity, AuthFailures, Repository Interfaces
│ │ └── presentation/ # Login, Register, Forgot Password UI screens
│ ├── cart/ # Shopping Cart Feature
│ ├── checkout/ # Checkout Flow
│ ├── home/ # Landing Page / Dashboard with interactive chips
│ ├── orders/ # Order History
│ ├── products/ # Product Listing, Details, & Reactive filtering
│ ├── profile/ # User Settings & Profile
│ └── splash/ # Custom Animated Boot Screen
├── main.dart # App Entry Point, Bloc Providers, & GoRouter Config
└── firebase_options.dart # Generated Firebase Configuration
- Firestore Cart Synchronization: Migrate the local cart state to
cloud_firestoreto allow users to sync their shopping carts across multiple devices (users/{userId}/cart). - Payment Gateway Integration: Wire up Stripe or an equivalent payment processor in the Checkout flow.
- Advanced Animations: Introduce Hero animations for seamless transitions between the Product List grid and the Product Details screen.
- Image Caching: Implement
cached_network_imageto persist product images on disk for offline viewing and performance improvements.
Contributions, issues, and feature requests are welcome! If you're planning to contribute, please ensure you adhere to the Clean Architecture boundaries established in the features/ directory.