# Quick Start Guide - Retail POS App ## Prerequisites 1. **Flutter SDK** (3.35.x or higher) ```bash flutter --version ``` 2. **Dart SDK** (3.9.2 or higher) ```bash dart --version ``` 3. **Connected Device or Emulator** ```bash flutter devices ``` --- ## Initial Setup ### 1. Install Dependencies ```bash cd /Users/ssg/project/retail flutter pub get ``` ### 2. Generate Code This step is **CRITICAL** - the app won't run without it! ```bash # Generate all Riverpod and Hive code flutter pub run build_runner build --delete-conflicting-outputs ``` **What this does:** - Generates `.g.dart` files for all providers - Generates Hive type adapters - Creates necessary code for dependency injection **Watch mode** (for development): ```bash # Automatically regenerates when files change flutter pub run build_runner watch --delete-conflicting-outputs ``` ### 3. Verify Code Generation Check that these files exist: ```bash # Check providers were generated ls lib/features/home/presentation/providers/*.g.dart ls lib/features/products/presentation/providers/*.g.dart ls lib/features/categories/presentation/providers/*.g.dart ls lib/features/settings/presentation/providers/*.g.dart # Check models were generated ls lib/features/home/data/models/*.g.dart ls lib/features/products/data/models/*.g.dart ls lib/features/categories/data/models/*.g.dart ls lib/features/settings/data/models/*.g.dart ``` --- ## Running the App ### Option 1: Default Device ```bash flutter run ``` ### Option 2: Specific Device ```bash # List available devices flutter devices # Run on specific device flutter run -d # Examples: flutter run -d chrome # Web flutter run -d macos # macOS flutter run -d emulator-5554 # Android emulator flutter run -d "iPhone 15" # iOS simulator ``` ### Option 3: Release Mode ```bash flutter run --release ``` ### Option 4: With Hot Reload (Development) ```bash # Run in debug mode with hot reload enabled flutter run # While running: # Press 'r' to hot reload # Press 'R' to hot restart # Press 'h' for help # Press 'q' to quit ``` --- ## Development Workflow ### Run with Watch Mode Open **two terminals**: **Terminal 1:** Run build_runner in watch mode ```bash cd /Users/ssg/project/retail flutter pub run build_runner watch --delete-conflicting-outputs ``` **Terminal 2:** Run the app ```bash cd /Users/ssg/project/retail flutter run ``` This allows: - Automatic code regeneration when you modify providers - Hot reload for UI changes - Continuous development without manual rebuilds --- ## Common Commands ### Clean Build ```bash # Clean build artifacts flutter clean # Get dependencies again flutter pub get # Regenerate code flutter pub run build_runner build --delete-conflicting-outputs # Run app flutter run ``` ### Analyze Code ```bash # Check for issues flutter analyze # Format code dart format . # Fix formatting dart fix --apply ``` ### Testing ```bash # Run all tests flutter test # Run specific test flutter test test/path/to/test_file.dart # With coverage flutter test --coverage ``` ### Build for Production **Android APK:** ```bash flutter build apk --release # Output: build/app/outputs/flutter-apk/app-release.apk ``` **Android App Bundle:** ```bash flutter build appbundle --release # Output: build/app/outputs/bundle/release/app-release.aab ``` **iOS:** ```bash flutter build ios --release ``` **macOS:** ```bash flutter build macos --release ``` **Web:** ```bash flutter build web --release # Output: build/web/ ``` --- ## Troubleshooting ### Issue: "No providers found" or "Provider not generated" **Solution:** ```bash # Delete old generated files flutter clean # Reinstall dependencies flutter pub get # Regenerate all code flutter pub run build_runner build --delete-conflicting-outputs ``` ### Issue: "MissingPluginException" **Solution:** ```bash # Stop the app # Clean and rebuild flutter clean flutter pub get flutter run ``` ### Issue: Hive errors **Solution:** Check that Hive boxes are registered in `main.dart`: ```dart // Ensure these are uncommented after code generation: Hive.registerAdapter(ProductModelAdapter()); Hive.registerAdapter(CategoryModelAdapter()); Hive.registerAdapter(CartItemModelAdapter()); Hive.registerAdapter(AppSettingsModelAdapter()); ``` ### Issue: Build runner conflicts **Solution:** ```bash # Use delete-conflicting-outputs flag flutter pub run build_runner build --delete-conflicting-outputs ``` ### Issue: Hot reload not working **Solution:** ```bash # Press 'R' for hot restart instead of 'r' # Or restart the app entirely flutter run ``` --- ## App Features Overview Once running, you can: ### 1. Home Tab (POS) - View available products in a grid - Tap product to add to cart - Adjust quantity before adding - View cart with items and total - Manage cart quantities - Clear cart - Checkout (when implemented) ### 2. Products Tab - Search products by name/description - Filter by category using chips - Sort products (name, price, date) - Pull to refresh - Responsive grid layout ### 3. Categories Tab - View all categories in a grid - See product count per category - Tap category to filter products - Pull to refresh ### 4. Settings Tab - Change theme (Light/Dark/System) - Select language - Choose currency - Set store name - Configure tax rate - Sync data - Clear cache - View app info --- ## Development Tips ### 1. Use VS Code Extensions - **Flutter** (Dart-Code.flutter) - **Dart** (Dart-Code.dart-code) - **Flutter Riverpod Snippets** - **Error Lens** (usernamehw.errorlens) ### 2. Enable DevTools ```bash # While app is running flutter run # Open DevTools in browser # Click the URL shown in terminal (e.g., http://127.0.0.1:9101/) ``` ### 3. Use Flutter Inspector - Open DevTools - Click "Flutter Inspector" tab - Inspect widget tree - Debug layout issues - Toggle debug paint - Measure render times ### 4. Performance Profiling ```bash # Run in profile mode flutter run --profile # Open DevTools > Performance # Record timeline # Analyze frame rendering ``` ### 5. Hot Reload Tips - Works for UI changes - Doesn't work for: - Adding new dependencies - Changing provider annotations - Modifying main() - Use Hot Restart (R) for those changes --- ## Project Structure Quick Reference ``` lib/ ├── main.dart # Entry point - START HERE ├── app.dart # App shell with tabs │ ├── features/ │ ├── home/presentation/pages/home_page.dart # Home/POS page │ ├── products/presentation/pages/products_page.dart # Products page │ ├── categories/presentation/pages/categories_page.dart # Categories page │ └── settings/presentation/pages/settings_page.dart # Settings page │ └── core/ ├── theme/app_theme.dart # Material 3 themes └── constants/ # App constants ``` --- ## Quick Commands Cheat Sheet ```bash # Setup flutter pub get # Install dependencies flutter pub run build_runner build --delete-conflicting-outputs # Generate code # Run flutter run # Run app flutter run -d chrome # Run on web flutter run --release # Release mode # Development flutter pub run build_runner watch --delete-conflicting-outputs # Watch mode dart format . # Format code flutter analyze # Analyze code # Build flutter build apk --release # Android APK flutter build appbundle --release # Android Bundle flutter build ios --release # iOS flutter build web --release # Web # Testing flutter test # Run tests flutter test --coverage # With coverage # Maintenance flutter clean # Clean build flutter doctor # Check environment flutter upgrade # Upgrade Flutter ``` --- ## Environment Verification Before running, verify your setup: ```bash # Check Flutter installation flutter doctor -v # Should show: # ✓ Flutter (version 3.35.x or higher) # ✓ Dart (version 3.9.2 or higher) # ✓ Android toolchain (if targeting Android) # ✓ Xcode (if targeting iOS/macOS) # ✓ Connected devices # Check dependencies flutter pub get # Verify pubspec.lock exists ls pubspec.lock # Check generated files ls lib/**/*.g.dart ``` --- ## Expected Output When running successfully, you should see: ``` Launching lib/main.dart on in debug mode... Running Gradle task 'assembleDebug'... ✓ Built build/app/outputs/flutter-apk/app-debug.apk. Flutter run key commands. r Hot reload. R Hot restart. h List all available interactive commands. d Detach (terminate "flutter run" but leave application running). c Clear the screen q Quit (terminate the application on the device). An Observatory debugger and profiler on is available at: http://127.0.0.1:xxxxx/ The Flutter DevTools debugger and profiler on is available at: http://127.0.0.1:9100/ ``` --- ## Next Steps After Running 1. **Explore the App:** - Navigate through all 4 tabs - Try adding products to cart - Search and filter products - Change theme in settings 2. **Check Functionality:** - Add items to cart - Remove items from cart - Filter by category - Search products - Sort products - Change settings 3. **Test Responsiveness:** - Resize window (if on desktop/web) - Try portrait and landscape (if on mobile) - Check different screen sizes 4. **Review Code:** - Check generated `.g.dart` files - Review provider implementations - Understand the flow --- ## Support If you encounter issues: 1. Check `flutter doctor` output 2. Ensure code generation completed successfully 3. Review error messages in the terminal 4. Check PAGES_SUMMARY.md for known issues 5. Verify all dependencies in pubspec.yaml are compatible --- **Ready to Go!** ```bash # Quick start (copy-paste): cd /Users/ssg/project/retail && \ flutter pub get && \ flutter pub run build_runner build --delete-conflicting-outputs && \ flutter run ``` Happy coding! 🚀