Flutter Shop Case (Layered Mobile E-Commerce Architecture)

A mobile shopping application built with Flutter, featuring authentication, product browsing, cart management, and checkout flow.

TL;DR

• Designed and implemented a modular, testable Flutter shopping application featuring authentication, dynamic product browsing, persistent cart management, and a complete checkout flow — all structured via a clean layered architecture (Presentation → State Management → Services → Models + Local Storage).

• Authentication & Session: Built sign-in/sign-up forms with floating labels, demo credentials (demouser/demouser), and persistent login state via SharedPreferences; auth state managed through AuthProvider with clear separation from UI logic.

• Product Discovery & Search: Implemented real-time search across name/description/category with relevance-based sorting (Name > Description > Category); keyword persists across navigation tabs and clears on Home return; category filter chips and popularity-based grid sorting enhance UX.

• State Management & Navigation: Leveraged Provider pattern across 5 dedicated providers (Auth, Product, Cart, Theme, Navigation) for reactive, testable state updates; tab-based navigation with IndexedStack preserves page state and supports "Enter to Search" and "See All" shortcuts.

• Background Processing & Performance: Engineered isolate-based background tasks (cache cleanup, analytics sync, prefetching) to maintain 60fps UI responsiveness; theme persistence and session caching optimized via SharedPreferences with minimal I/O overhead.

• Backend Integration Ready: All network-dependent operations (signIn(), getProducts(), etc.) are clearly marked with NOTE: placeholders; companion docs (BACKEND_DATA_FETCH.md) provide endpoint specs, JSON contracts, and file-level update guidance for seamless API adoption.

• Testing & Maintainability: Comprehensive test suite covering models, services, providers, and widget integration; code annotations (IMPORTANT:, SESSION CACHE:) accelerate onboarding and reduce integration errors.

• Tech Stack: Flutter ≥3.11.4, Dart ≥3.11.4, provider, shared_preferences, http, uuid, intl; architecture documented via Mermaid diagrams in HLD.md.

• Outcome: Delivered a scalable, locally-functional e-commerce foundation that balances developer ergonomics (clear separation of concerns, annotated integration points) with end-user experience (smooth navigation, persistent state, responsive search) — ready for backend integration or white-label adaptation.

Features

• Authentication — Sign-in and sign-up forms with demo credentials (demouser / demouser), floating labels, scrollable forms
• Landing Page — Search bar with "Enter to Search" navigation, banner, category shortcuts, and popular products grid
• Items Page — Search bar (persists keyword from home), category filter chips, product grid with relevance-based sorting
• Profile Page — User info, accessible theme settings (light/dark/system), and sign out
• Cart & Checkout — Quantity controls, order summary, payment processing with success flow
• Search — Real-time product search by name, category, or description; keyword persists across pages; results sorted by relevance (Name > Description > Category); clears when returning to Home tab
• Theme Support — Light and dark themes with system auto-detection, persisted via SharedPreferences
• Background Tasks — Periodic cache cleanup, analytics sync, and data prefetching using isolates
• Session Caching — Persistent login state via SharedPreferences
• Navigation — Tab-based navigation managed by NavigationProvider (includes "See All" and "Enter to Search" shortcuts)

Getting Started

Prerequisites

• Flutter SDK >= 3.11.4
• Dart SDK >= 3.11.4
• Android SDK (for Android builds) or Xcode (for iOS builds)

Installation

# Clone the repository
git clone https://github.com/prothegee/flutter_shop_case.git
cd flutter_shop_case

# Install dependencies
flutter pub get

# Run the app
flutter run

Running on Emulator

# List available Android emulators
$ANDROID_SDK_ROOT/emulator/emulator -list-avds

# Launch an emulator: change <avd_name> from list, i.e. `pixel_d_a36`
$ANDROID_SDK_ROOT/emulator/emulator -avd <avd_name> &

# Run the app on the emulator: <emulator_id> could be something like `emulator-5554`
flutter run -d <emulator_id>

In case of fire when debugging is too slow:

• Try clear cache.
• Increase memory usage.
• run $ANDROID_SDK_ROOT/emulator/emulator -avd <avd_name> -wipe-data

Hot Reload

While the app is running in debug mode:

• Press r for hot reload
• Press R for hot restart
• Press q to quit

Project Structure

lib/
├── main.dart                          # Entry point, theme definitions, provider setup
├── models/                            # Data models (User, Product, CartItem)
├── services/                          # Business logic and data access
│   ├── auth_service.dart              # Authentication (NOTE: network request placeholders)
│   ├── product_service.dart           # Product fetching (NOTE: network request placeholders)
│   ├── cart_service.dart              # Local cart operations
│   ├── theme_service.dart             # Theme persistence (SharedPreferences)
│   └── background_task_service.dart   # IMPORTANT: Isolate-based background tasks
├── providers/                         # State management (Provider pattern)
│   ├── auth_provider.dart             # Auth state management
│   ├── product_provider.dart          # Product data state, search filtering
│   ├── cart_provider.dart             # Shopping cart state
│   ├── theme_provider.dart            # Theme state
│   └── navigation_provider.dart       # Bottom navigation tab index, tab change listener
├── pages/                             # UI screens
│   ├── home/                          # Sign-in / Sign-up forms
│   ├── landing/                       # Search bar, main page after login
│   ├── items/                         # Search bar, product listing with categories
│   ├── profile/                       # User profile and settings
│   └── checkout/                      # Cart and payment processing
└── widgets/                           # Reusable UI components
    └── main_navigation_wrapper.dart   # Conditional routing (auth vs main app), IndexedStack + NavigationProvider

Architecture

This app follows a layered architecture:

Presentation (Pages/Widgets)
        ↓
State Management (Providers)
        ↓
Services (Business Logic)
        ↓
Models + Storage (SharedPreferences)

See docs/HLD.md for detailed architecture diagrams and state flow documentation.

Dependencies

Package	Purpose
provider	State management
shared_preferences	Local data persistence (sessions, theme)
http	HTTP client for future API integration
uuid	Unique ID generation
intl	Internationalization and date formatting

Backend Integration

Network requests are marked with NOTE: comments indicating where real API calls should be added. The current implementation uses mock/local data.

See docs/BACKEND_DATA_FETCH.md for:

• API endpoint specifications
• JSON request/response structures
• File reference map for what to update

Quick Reference: What Needs Backend

Feature	File	Method to Update
Sign in	lib/services/auth_service.dart	signIn()
Sign up	lib/services/auth_service.dart	signUp()
All products	lib/services/product_service.dart	getProducts()
Popular products	lib/services/product_service.dart	getPopularProducts()
Products by category	lib/services/product_service.dart	getProductsByCategory()
Categories	lib/services/product_service.dart	getCategories()

Local Features (No Backend Needed)

Feature	File	Method
Search products	lib/providers/product_provider.dart	setSearchQuery(), clearSearch()
Navigation tabs	lib/providers/navigation_provider.dart	setIndex(), goToHome(), etc.

Testing

# Run all tests
flutter test

# Run unit tests only
flutter test test/unit/

# Run widget tests only
flutter test test/widget_test.dart

Test Coverage

Test File	What It Tests
test/unit/user_model_test.dart	UserModel fromJson, toJson, copyWith
test/unit/product_model_test.dart	ProductModel fromJson, toJson, copyWith, defaults
test/unit/cart_item_model_test.dart	CartItemModel totalPrice, serialization
test/unit/cart_service_test.dart	Cart operations: add, remove, quantity, clear
test/unit/auth_service_test.dart	Auth: signIn, signUp, session cache
test/unit/auth_provider_test.dart	AuthProvider state transitions
test/unit/theme_service_test.dart	ThemeService SharedPreferences roundtrip
test/unit/cart_provider_test.dart	CartProvider state updates
test/widget_test.dart	Widget integration tests

Code Annotations

Throughout the codebase, you'll find these markers:

Marker	Purpose
NOTE:	Network request placeholder — replace with actual API call
TODO:	Implementation pending — backend integration points
IMPORTANT:	Critical implementation detail (e.g., isolate-based background tasks)
SESSION CACHE:	Local storage operation using SharedPreferences

Documentation

• HLD.md — High-Level Design with Mermaid state diagrams
• BACKEND_DATA_FETCH.md — Backend API contract and data structures

License

Private project. All rights reserved.

end of readme