# Flutter Retail POS App Expert Guidelines ## 🎯 App Overview A Flutter-based Point of Sale (POS) retail application for managing products, categories, inventory, sales transactions, and business analytics with an intuitive tab-based interface and comprehensive inventory management system. --- ## πŸ€– SUBAGENT DELEGATION SYSTEM πŸ€– **CRITICAL: BE PROACTIVE WITH SUBAGENTS! YOU HAVE SPECIALIZED EXPERTS AVAILABLE!** ### 🚨 DELEGATION MINDSET **Instead of thinking "I'll handle this myself"** **Think: "Which specialist is BEST suited for this task?"** ### πŸ“‹ AVAILABLE SPECIALISTS You have access to these expert subagents - USE THEM PROACTIVELY: #### 🎨 **flutter-widget-expert** - **MUST BE USED for**: Product cards, category grids, cart UI, tab navigation, custom widgets, dashboard charts - **Triggers**: "create widget", "build UI", "product card", "category grid", "layout", "animation", "chart", "dashboard" #### πŸ“Š **riverpod-expert** - **MUST BE USED for**: Cart state, product selection, category filtering, inventory state, sales state management - **Triggers**: "state management", "provider", "cart", "async state", "data flow", "sales state", "inventory state" #### πŸ—„οΈ **hive-expert** - **MUST BE USED for**: Product storage, category database, sales history, inventory tracking, local cache - **Triggers**: "database", "cache", "hive", "products", "categories", "persistence", "offline", "inventory" #### 🌐 **api-integration-expert** - **MUST BE USED for**: Product sync, inventory API, order processing, backend integration, CSV import/export - **Triggers**: "API", "HTTP", "sync", "dio", "REST", "backend", "import", "export" #### πŸ—οΈ **architecture-expert** - **MUST BE USED for**: Feature organization, dependency injection, clean architecture setup - **Triggers**: "architecture", "structure", "organization", "clean code", "refactor" #### ⚑ **performance-expert** - **MUST BE USED for**: Product image caching, grid scrolling, memory optimization, dashboard performance - **Triggers**: "performance", "optimization", "memory", "image cache", "slow", "lag", "scroll" ### 🎯 DELEGATION STRATEGY **BEFORE starting ANY task, ASK YOURSELF:** 1. "Which of my specialists could handle this better?" 2. "Should I break this into parts for different specialists?" 3. "Would a specialist complete this faster and better?" ### πŸ’Ό WORK BALANCE RECOMMENDATION: - **Simple Tasks (20%)**: Handle independently - quick fixes, minor updates - **Complex Tasks (80%)**: Delegate to specialists for expert-level results ### πŸ”§ HOW TO DELEGATE ``` # Explicit delegation examples: > Use the flutter-widget-expert to create the product card widget with price and image > Have the riverpod-expert design the shopping cart state management > Ask the hive-expert to create the product and category database schema > Use the api-integration-expert to implement product sync with backend > Have the architecture-expert organize the inventory feature structure > Ask the performance-expert to optimize the product grid scrolling ``` --- ## Flutter Best Practices - Use Flutter 3.x features and Material 3 design - Implement clean architecture with Riverpod for state management - Use Hive CE for local database and offline-first functionality - Follow proper dependency injection with GetIt - Implement proper error handling and user feedback - Follow platform-specific design guidelines - Use proper localization for multi-language support ## Retail App Project Structure ``` lib/ core/ constants/ api_constants.dart # API endpoints, timeouts app_constants.dart # App config, defaults ui_constants.dart # Spacing, sizes, durations storage_constants.dart # Hive box names, keys theme/ app_theme.dart # Material 3 theme colors.dart # Color schemes typography.dart # Text styles network/ dio_client.dart # HTTP client setup api_interceptor.dart # Auth, logging interceptors network_info.dart # Connectivity status errors/ exceptions.dart # Custom exceptions failures.dart # Failure classes utils/ formatters.dart # Price, date formatters validators.dart # Input validation extensions.dart # Dart extensions csv_helper.dart # CSV import/export widgets/ custom_button.dart # Reusable buttons loading_indicator.dart # Loading states error_widget.dart # Error displays empty_state.dart # Empty list UI features/ home/ data/ datasources/ cart_local_datasource.dart models/ cart_item_model.dart repositories/ cart_repository_impl.dart domain/ entities/ cart_item.dart repositories/ cart_repository.dart usecases/ add_to_cart.dart remove_from_cart.dart clear_cart.dart calculate_total.dart apply_discount.dart presentation/ providers/ cart_provider.dart cart_total_provider.dart discount_provider.dart pages/ home_page.dart widgets/ product_selector.dart cart_item_card.dart cart_summary.dart checkout_button.dart discount_dialog.dart products/ data/ datasources/ product_remote_datasource.dart product_local_datasource.dart models/ product_model.dart product_variant_model.dart supplier_model.dart repositories/ product_repository_impl.dart domain/ entities/ product.dart product_variant.dart supplier.dart repositories/ product_repository.dart usecases/ get_all_products.dart get_products_by_category.dart search_products.dart sync_products.dart create_product.dart update_product.dart delete_product.dart manage_variants.dart import_products_csv.dart export_products_csv.dart presentation/ providers/ products_provider.dart product_search_provider.dart product_filter_provider.dart product_form_provider.dart pages/ products_page.dart product_detail_page.dart product_form_page.dart widgets: product_grid.dart product_card.dart product_search_bar.dart product_filter_chip.dart product_form.dart variant_list.dart categories/ data/ datasources/ category_remote_datasource.dart category_local_datasource.dart models/ category_model.dart tag_model.dart repositories/ category_repository_impl.dart domain/ entities/ category.dart tag.dart repositories/ category_repository.dart usecases: get_all_categories.dart get_category_by_id.dart sync_categories.dart create_category.dart update_category.dart delete_category.dart manage_tags.dart presentation/ providers/ categories_provider.dart selected_category_provider.dart tags_provider.dart pages/ categories_page.dart category_form_page.dart widgets/ category_grid.dart category_card.dart category_form.dart tag_chip.dart inventory/ data/ datasources/ inventory_local_datasource.dart models/ inventory_alert_model.dart repositories/ inventory_repository_impl.dart domain/ entities/ inventory_alert.dart repositories/ inventory_repository.dart usecases: get_low_stock_products.dart update_stock_levels.dart batch_update_stock.dart presentation/ providers: inventory_provider.dart stock_alerts_provider.dart pages: low_stock_alerts_page.dart widgets: stock_level_indicator.dart alert_badge.dart batch_update_form.dart orders/ data/ datasources/ order_local_datasource.dart models/ order_model.dart order_item_model.dart repositories/ order_repository_impl.dart domain/ entities: order.dart order_item.dart repositories: order_repository.dart usecases: create_order.dart get_order_history.dart presentation: providers: orders_provider.dart pages: order_history_page.dart widgets: order_card.dart dashboard/ data: datasources: analytics_local_datasource.dart models: sales_stats_model.dart product_performance_model.dart repositories: analytics_repository_impl.dart domain: entities: sales_stats.dart product_performance.dart repositories: analytics_repository.dart usecases: get_daily_revenue.dart get_monthly_revenue.dart get_best_selling_products.dart get_category_performance.dart presentation: providers: dashboard_provider.dart revenue_provider.dart best_sellers_provider.dart pages: dashboard_page.dart widgets: revenue_chart.dart sales_summary_card.dart best_sellers_list.dart category_performance_chart.dart settings/ data/ datasources/ settings_local_datasource.dart models/ app_settings_model.dart repositories/ settings_repository_impl.dart domain/ entities/ app_settings.dart repositories/ settings_repository.dart usecases: get_settings.dart update_settings.dart presentation/ providers/ settings_provider.dart theme_provider.dart pages/ settings_page.dart widgets/ settings_section.dart theme_selector.dart language_selector.dart shared/ widgets/ app_bottom_nav.dart # Tab navigation custom_app_bar.dart # Reusable app bar price_display.dart # Currency formatting stock_badge.dart # Stock level indicator main.dart app.dart # Root widget with ProviderScope test/ unit/ features/ products/ categories/ inventory/ orders/ dashboard/ widget/ integration/ ``` --- # App Context - Retail POS Application ## About This App A comprehensive Flutter-based Point of Sale (POS) application designed for retail businesses. The app enables merchants to manage their complete product inventory with variants, track stock levels, process sales transactions, analyze business performance, and maintain business settingsβ€”all through an intuitive tab-based interface optimized for speed and efficiency. ## Target Users - **Retail Store Owners**: Small to medium-sized retail businesses - **Cashiers/Sales Staff**: Front-line employees processing transactions - **Store Managers**: Inventory and business configuration management - **Mobile Vendors**: On-the-go sales at markets, events, or mobile locations ## Core Features ### πŸ“± Tab-Based Navigation (4 Main Tabs + Extended Features) #### Tab 1: Home/POS Screen **Purpose**: Primary sales interface for selecting products and processing transactions **Key Components**: - **Product Selector**: Quick access to frequently sold products with variants - **Shopping Cart**: Real-time cart display with items, quantities, prices - **Cart Management**: Add, remove, update quantities - **Cart Summary**: Subtotal, tax, discounts, total calculation - **Checkout Flow**: Complete transaction and process payment - **Quick Actions**: Clear cart, apply discounts, process returns, create order - **Discount System**: Apply percentage or fixed amount discounts to cart or items **State Management**: - Cart state (items, quantities, totals) - Selected product and variant state - Discount state (cart-level and item-level) - Transaction state - Order creation state **Data Requirements**: - Real-time cart updates - Price calculations with variants - Tax computation - Transaction logging - Order generation **Business Logic**: - Calculate subtotals including variants - Apply discounts (percentage, fixed, promotional) - Compute tax based on settings - Generate order from cart - Validate stock before checkout - Process payment and create transaction record #### Tab 2: Products Grid **Purpose**: Browse, search, and manage all available products **Key Components**: - **Product Grid**: Responsive grid layout with product cards - **Product Cards**: Image, name, price, stock status, category, variants - **Search Bar**: Real-time product search across name, description, SKU - **Filter Options**: Category filter, price range, availability, supplier, tags - **Sort Options**: Name, price, category, popularity, stock level - **Empty States**: No products found UI - **Quick Actions**: Add product, edit product, manage stock - **Batch Operations**: Select multiple products for bulk updates **Product Management**: - **Add/Edit Products**: - Basic info (name, description, SKU, barcode) - Pricing (cost, retail price, sale price) - Stock levels - Product images (multiple) - Category assignment - Tags for organization - Supplier information - **Product Variants**: - Size variants (S, M, L, XL) - Color variants - Custom variant types - Individual SKU per variant - Separate pricing per variant - Separate stock per variant - **Supplier Management**: - Add/edit suppliers - Link products to suppliers - Track supplier contact info - View products by supplier **State Management**: - Products list state (all products) - Search query state - Filter state (category, price, supplier, tags) - Sort state - Product form state - Variant management state - Supplier state **Data Requirements**: - Product list from Hive (offline-first) - Product images (cached with variants) - Product search indexing - Category relationships - Supplier relationships - Tag associations - Variant data with individual stock #### Tab 3: Categories Grid **Purpose**: View and manage product categories and tags **Key Components**: - **Category Grid**: Visual grid of all categories - **Category Cards**: Icon/image, name, product count - **Category Selection**: Navigate to products in category - **Empty States**: No categories UI - **Category Management**: Add, edit, delete categories - **Tag Management**: Create and manage product tags - **Quick Actions**: Create category, manage tags **Category Management**: - Create new categories - Edit category details (name, icon, description) - Delete categories (with product reassignment) - Set category colors - Organize products by category **Tag Management**: - Create product tags for organization - Apply multiple tags to products - Filter products by tags - Color-coded tags **State Management**: - Categories list state - Selected category state - Products by category state - Tags state - Category form state **Data Requirements**: - Category list from Hive - Product count per category - Category images (cached) - Category-product relationships - Tag associations #### Tab 4: Settings **Purpose**: App configuration and business settings **Key Components**: - **Theme Settings**: Light/dark mode toggle - **Language Settings**: Multi-language support - **Currency Settings**: Currency format and symbol - **Tax Configuration**: Tax rates and rules - **Business Info**: Store name, contact, address - **Data Management**: Sync, backup, clear cache, CSV import/export - **About**: App version, credits, legal **State Management**: - App settings state - Theme mode state - Language state - Sync state - Import/export state **Data Requirements**: - App settings from Hive - User preferences - Business configuration - CSV templates --- ### πŸ“¦ Inventory Management (Extended Feature) **Purpose**: Basic inventory monitoring and alerts **Key Features**: #### Low Stock Alerts - **Alert Configuration**: - Set minimum stock level per product - Enable/disable alerts - Alert threshold (e.g., alert when < 10 units) - **Alert Notifications**: - Dashboard badge showing low-stock count - Low stock products list - Visual indicators on product cards - Sort products by stock level #### CSV Import/Export - **Import Products**: - CSV template download - Bulk product import - Validation and error reporting - Preview before import - Update existing or create new - **Export Products**: - Export all products to CSV - Export filtered products - Include variants in export - Custom field selection #### Batch Updates - **Multi-Select Mode**: Select multiple products - **Bulk Operations**: - Update prices (increase/decrease by %) - Update stock levels - Change categories - Apply tags - Update supplier - Delete multiple products - **Preview Changes**: Review before applying **Data Models**: ```dart InventoryAlert: - productId, alertThreshold, isActive - currentStock, minimumStock ``` **State Management**: - Inventory state (stock levels) - Low stock alerts state - Import/export progress state - Batch operation state --- ### πŸ’° Orders & Sales Management (Extended Feature) **Purpose**: Simple order tracking and basic discounts **Key Features**: #### Order Management - **Create Orders**: Convert cart to order - **Order Details**: - Order number (auto-generated) - Order items with quantities - Subtotal, discount, total - Payment method - Order status (completed, cancelled) - Order date/time - **Order History**: View all past orders - **Order Actions**: View details, basic order info #### Basic Discount System - **Discount Types**: - Percentage discount (e.g., 10% off) - Fixed amount discount (e.g., $5 off) - Cart-level discounts only - **Apply Discounts**: During checkout to entire cart #### Order History - **Simple List**: Chronological display of orders - **Order Details**: Tap to view full order information - **Basic Filter**: Filter by date (today, week, month) **Data Models**: ```dart Order: - id, orderNumber - items (List) - subtotal, discount, total - paymentMethod, orderStatus - createdAt OrderItem: - productId, productName, variantInfo - quantity, unitPrice, lineTotal ``` **State Management**: - Orders list state - Order creation state - Basic discount state --- ### πŸ“Š Sales Dashboard (Extended Feature) **Purpose**: Business analytics and performance insights **Key Features**: #### Revenue Analytics - **Daily Revenue**: - Today's total sales - Number of transactions - Average transaction value - Revenue trend chart (hourly) - **Monthly Revenue**: - Current month total - Month-over-month comparison - Revenue trend chart (daily) - Projected month-end revenue - **Custom Date Range**: Select any date range for analysis - **Revenue by Payment Method**: Cash vs Card breakdown #### Best-Selling Products - **Top Products**: - Ranked by quantity sold - Ranked by revenue generated - Timeframe selector (today, week, month, all-time) - **Product Performance**: - Units sold - Revenue generated - Average price - Trend indicators (↑↓) - **Visual Display**: Charts and lists #### Category Performance - **Sales by Category**: - Revenue per category - Units sold per category - Category comparison - Pie chart visualization - **Category Trends**: Growth/decline indicators #### Dashboard Widgets - **Summary Cards**: - Total Revenue (today/week/month) - Total Transactions - Average Transaction Value - Low Stock Alerts Count - **Charts**: - Revenue line chart - Category pie chart - Best sellers bar chart - Sales trend graph - **Quick Stats**: - Products sold today - Most popular product - Total products in inventory - Categories count **Data Requirements**: - Transaction history from database - Product sales data - Category sales data - Time-series data for charts - Aggregated statistics **State Management**: - Dashboard stats state - Revenue data state - Best sellers state - Category performance state - Date range filter state - Chart data state **Analytics Calculations**: - Sum revenue by period - Count transactions - Calculate average transaction value - Rank products by sales - Group sales by category - Trend analysis (increase/decrease %) --- ## Technical Architecture ### State Management (Riverpod 3.0) #### Core Providers ```dart // Cart Management final cartProvider = NotifierProvider>(Cart.new); final cartTotalProvider = Provider((ref) { ... }); final discountProvider = NotifierProvider(Discount.new); // Products Management final productsProvider = AsyncNotifierProvider>(Products.new); final filteredProductsProvider = Provider>((ref) { ... }); final productFormProvider = NotifierProvider(ProductForm.new); final variantsProvider = NotifierProvider>(Variants.new); // Categories Management final categoriesProvider = AsyncNotifierProvider>(Categories.new); final tagsProvider = NotifierProvider>(Tags.new); // Inventory Management final inventoryProvider = NotifierProvider>(Inventory.new); final stockAlertsProvider = Provider>((ref) { ... }); // Orders Management final ordersProvider = AsyncNotifierProvider>(Orders.new); // Dashboard Analytics final dashboardStatsProvider = Provider((ref) { ... }); final revenueProvider = Provider((ref) { ... }); final bestSellersProvider = Provider>((ref) { ... }); // Settings Management final settingsProvider = AsyncNotifierProvider(AppSettings.new); ``` ### Database Schema (Hive CE) #### Core Hive Boxes ```dart // Box Names const String productsBox = 'products'; const String variantsBox = 'variants'; const String categoriesBox = 'categories'; const String tagsBox = 'tags'; const String suppliersBox = 'suppliers'; const String cartBox = 'cart'; const String ordersBox = 'orders'; const String settingsBox = 'settings'; ``` #### Product Model (Enhanced) ```dart @HiveType(typeId: 0) class Product extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String name; @HiveField(2) final String description; @HiveField(3) final double price; @HiveField(4) final double? costPrice; @HiveField(5) final double? salePrice; @HiveField(6) final String? sku; @HiveField(7) final String? barcode; @HiveField(8) final List? imageUrls; @HiveField(9) final String categoryId; @HiveField(10) final int stockQuantity; @HiveField(11) final bool isAvailable; @HiveField(12) final List tags; @HiveField(13) final String? supplierId; @HiveField(14) final bool hasVariants; @HiveField(15) final List variantIds; @HiveField(16) final int? lowStockThreshold; @HiveField(17) final DateTime createdAt; @HiveField(18) final DateTime updatedAt; } ``` #### Product Variant Model ```dart @HiveType(typeId: 1) class ProductVariant extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String productId; @HiveField(2) final String name; // e.g., "Large - Red" @HiveField(3) final String? sku; @HiveField(4) final double? priceAdjustment; @HiveField(5) final int stockQuantity; @HiveField(6) final Map attributes; // {size: "L", color: "Red"} @HiveField(7) final String? imageUrl; @HiveField(8) final DateTime createdAt; } ``` #### Category Model ```dart @HiveType(typeId: 2) class Category extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String name; @HiveField(2) final String? description; @HiveField(3) final String? iconPath; @HiveField(4) final String? color; @HiveField(5) final int productCount; @HiveField(6) final DateTime createdAt; } ``` #### Tag Model ```dart @HiveType(typeId: 3) class Tag extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String name; @HiveField(2) final String? color; @HiveField(3) final DateTime createdAt; } ``` #### Supplier Model ```dart @HiveType(typeId: 4) class Supplier extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String name; @HiveField(2) final String? contactPerson; @HiveField(3) final String? email; @HiveField(4) final String? phone; @HiveField(5) final String? address; @HiveField(6) final DateTime createdAt; } ``` #### Order Model ```dart @HiveType(typeId: 5) class Order extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String orderNumber; @HiveField(2) final List items; @HiveField(3) final double subtotal; @HiveField(4) final double discount; @HiveField(5) final double total; @HiveField(6) final String paymentMethod; @HiveField(7) final String orderStatus; // completed, cancelled @HiveField(8) final DateTime createdAt; } ``` #### Order Item Model ```dart @HiveType(typeId: 6) class OrderItem extends HiveObject { @HiveField(0) final String id; @HiveField(1) final String productId; @HiveField(2) final String productName; @HiveField(3) final String? variantId; @HiveField(4) final String? variantName; @HiveField(5) final double price; @HiveField(6) final int quantity; @HiveField(7) final double lineTotal; } ``` ## UI/UX Design Guidelines ### Material 3 Design System - **Primary Color**: Represents brand identity (customizable) - **Secondary Color**: Accents and highlights - **Surface Colors**: Cards, sheets, backgrounds - **Typography**: Material 3 type scale (Display, Headline, Title, Body, Label) ### Product Card Design ```dart // Product card should display: - Product image (with placeholder/error handling) - Product name (2 lines max with ellipsis) - Price (formatted with currency, show sale price if applicable) - Stock status badge (in stock, low stock, out of stock) - Category badge - Variant indicator (if product has variants) - Add to cart button/icon - Quick edit button (for managers) - Tap to view details ``` ### Category Card Design ```dart // Category card should display: - Category icon/image - Category name - Product count - Background color (category-specific) - Tap to filter products by category ``` ### Dashboard Charts - Use **fl_chart** package for charts - Revenue line chart with time axis - Category pie chart with percentages - Best sellers horizontal bar chart - Responsive chart sizing - Interactive tooltips ### Stock Level Indicators - **High Stock**: Green badge - **Medium Stock**: Orange badge - **Low Stock**: Red badge with alert icon - **Out of Stock**: Grey badge with warning ## Performance Optimization ### Image Management - Use `cached_network_image` for product images - Implement proper placeholder and error widgets - Optimize image sizes (thumbnails for grids, full size for details) - Cache images in memory and disk - Lazy load images in grid views ### Grid Performance ```dart GridView.builder( itemCount: products.length, gridDelegate: SliverGridDelegateWithFixedCrossAxisCount( crossAxisCount: 2, childAspectRatio: 0.75, crossAxisSpacing: 12, mainAxisSpacing: 12, ), itemBuilder: (context, index) { return RepaintBoundary( child: ProductCard(product: products[index]), ); }, ); ``` ### Database Optimization - Use lazy boxes for large product datasets - Implement pagination for product lists - Create indexes for frequent queries - Regular database compaction - Efficient query filtering ### State Management Optimization - Use `.select()` for granular rebuilds - Implement proper provider disposal - Cache computed values - Debounce search queries - Optimize cart calculations ## Offline-First Strategy ### Data Flow 1. **Read**: Always read from Hive first (instant UI) 2. **Sync**: Background sync with API when online 3. **Update**: Update Hive and UI when sync completes 4. **Conflict**: Handle conflicts with last-write-wins strategy ### Sync Logic ```dart @riverpod class DataSync extends _$DataSync { @override Future build() async { return await _performSync(); } Future _performSync() async { if (!await ref.read(networkInfoProvider).isConnected) { return SyncStatus.offline; } try { // Sync categories first await ref.read(categoriesProvider.notifier).syncCategories(); // Then sync products and variants await ref.read(productsProvider.notifier).syncProducts(); // Sync suppliers await ref.read(suppliersProvider.notifier).syncSuppliers(); // Update last sync time await ref.read(settingsProvider.notifier).updateLastSync(); return SyncStatus.success; } catch (e) { return SyncStatus.failed; } } } ``` ## Key Features Implementation ### Search Functionality - Real-time search with debouncing (300ms) - Search by product name, description, SKU, barcode - Search across variants - Display search results count - Clear search button - Search history (optional) ### Filter System - **Category Filter**: Filter by one or multiple categories - **Price Range**: Min/max price slider - **Stock Status**: In stock, low stock, out of stock - **Supplier Filter**: Filter by supplier - **Tag Filter**: Filter by tags - **Variant Filter**: Show only products with variants ### Cart Operations - Add to cart with quantity - Add variant to cart with selected options - Update quantity with +/- buttons - Remove item with swipe or tap - Clear entire cart with confirmation - Calculate totals in real-time - Apply discounts (cart-level or item-level) - Persist cart between sessions ### Inventory Operations - **Alerts**: Show low-stock products - **Batch Updates**: Update multiple products at once ### Order Processing - Validate cart (not empty, stock available) - Select payment method - Apply cart-level discount (optional) - Calculate subtotal and discount - Generate unique order number - Save order to database - Clear cart after successful order ### CSV Import/Export - **Import**: - Download CSV template - Select CSV file - Parse and validate - Preview import - Confirm and import - Handle errors gracefully - **Export**: - Select data to export (all, filtered, selected) - Generate CSV - Save/share file ### Dashboard Analytics - **Calculate Revenue**: Sum all transactions by period - **Best Sellers**: Rank products by quantity/revenue - **Category Performance**: Group sales by category - **Trend Analysis**: Compare periods (today vs yesterday, month vs last month) - **Charts**: Generate chart data from transactions ## Error Handling ### Network Errors - Display user-friendly error messages - Show retry button for failed operations - Indicate offline mode - Queue operations for retry when online ### Validation Errors - Validate cart before checkout - Check product availability and stock - Validate quantity inputs - Validate price inputs (product form) - Display inline error messages ### Data Errors - Handle empty states (no products, no categories, no orders) - Handle missing images gracefully - Validate data integrity on load - Provide fallback values ## Testing Strategy ### Unit Tests - Cart calculations (total, tax, discounts) - Search filtering logic - Category filtering logic - Price formatting - Data validation - Stock calculations - Revenue calculations ### Widget Tests - Product card rendering - Category card rendering - Cart item rendering - Tab navigation - Search bar functionality - Dashboard charts ### Integration Tests - Complete checkout flow - Product CRUD operations - Category management - CSV import/export - Order creation and history ## Development Workflow ### Feature Development Process 1. **Define Requirements**: User stories and acceptance criteria 2. **Design Data Layer**: Models, repositories, data sources 3. **Implement Domain Layer**: Entities, use cases 4. **Create Providers**: Riverpod state management 5. **Build UI**: Widgets, pages, navigation 6. **Test**: Unit, widget, integration tests 7. **Optimize**: Performance profiling and optimization ### Code Review Checklist - [ ] Follows clean architecture principles - [ ] Proper error handling implemented - [ ] Offline-first approach maintained - [ ] Performance optimizations applied - [ ] Proper state management with Riverpod - [ ] Hive models and adapters properly defined - [ ] UI follows Material 3 guidelines - [ ] Accessibility considerations addressed - [ ] Tests written and passing - [ ] Code documentation provided ## Future Enhancements (Roadmap) ### Phase 1 - Current - βœ… Core POS functionality - βœ… Product and category management - βœ… Product variants support - βœ… Basic cart and checkout - βœ… Inventory tracking - βœ… Stock alerts - βœ… Order management - βœ… Sales dashboard - βœ… CSV import/export - βœ… Batch operations - βœ… Settings management ### Phase 2 - Near Future - πŸ”„ Customer management - πŸ”„ Loyalty program - πŸ”„ Advanced reporting - πŸ”„ Receipt printing - πŸ”„ Barcode scanning - πŸ”„ Multiple payment methods - πŸ”„ Staff management with roles - πŸ”„ Promotional campaigns ### Phase 3 - Future - πŸ“‹ Multi-store support - πŸ“‹ Cloud sync with backend - πŸ“‹ Integration with accounting software - πŸ“‹ Advanced analytics and forecasting - πŸ“‹ Supplier portal - πŸ“‹ Purchase order management - πŸ“‹ Integration with payment gateways - πŸ“‹ E-commerce integration --- ## Remember: ALWAYS DELEGATE TO SPECIALISTS FOR BETTER RESULTS! When working on this retail POS app: - **UI Tasks** β†’ flutter-widget-expert - **State Management** β†’ riverpod-expert - **Database/Caching** β†’ hive-expert - **API Integration** β†’ api-integration-expert - **Architecture Decisions** β†’ architecture-expert - **Performance Issues** β†’ performance-expert **Think delegation first, implementation second!**