SaapaduGo — Technical Document

📈 Key Statistics

⚙ Technology Stack

🏗 System Architecture

The app follows a feature-first clean architecture pattern with Riverpod as the single source of truth. Customer, admin, and delivery-partner data is served by a live Laravel 12 REST API via ApiRepository (35+ methods) and ApiClient (Dio + auth interceptor). Riverpod ApiProviders fetch data from the API, while StateNotifierProvider manages in-app state. Hive caches responses for offline-first support.

Three-Role Architecture

A single Flutter app serves three distinct user roles via role-based navigation:

📁 Folder Structure

saapadugo/
├── lib/
│   ├── main.dart                          # Entry point (Hive init + ProviderScope)
│   ├── app/
│   │   ├── app.dart                       # MaterialApp.router + localization
│   │   └── routes.dart                    # GoRouter with 45+ routes, ShellRoutes
│   ├── core/
│   │   ├── constants/
│   │   │   ├── app_constants.dart         # Unsplash URLs, app config
│   │   │   ├── payment_config.dart        # Razorpay keys, demo mode detection
│   │   │   └── storage_keys.dart          # Hive box names
│   │   ├── enums/
│   │   │   ├── order_status.dart          # 10 statuses with fromJson
│   │   │   ├── payment_method.dart        # 9 methods with fromJson
│   │   │   └── health_mode.dart           # 9 dietary modes
│   │   ├── network/
│   │   │   ├── api_client.dart            # Dio HTTP client with auth interceptor
│   │   │   └── api_repository.dart        # 35+ typed API methods (NEW)
│   │   ├── providers/
│   │   │   └── api_providers.dart         # Riverpod FutureProviders (NEW)
│   │   ├── theme/
│   │   │   ├── app_theme.dart             # Light theme (CardThemeData, TabBarThemeData)
│   │   │   └── app_dark_theme.dart        # Dark theme
│   │   ├── utils/
│   │   │   ├── formatters.dart            # Price, rating, date formatters
│   │   │   ├── validators.dart            # Phone, email, address validators
│   │   │   └── whatsapp_helper.dart       # WhatsApp URL launcher helper
│   │   └── widgets/
│   │       ├── food_card.dart             # Restaurant/food card with favorites
│   │       ├── menu_item_card.dart        # Menu item with ADD/quantity controls
│   │       ├── order_status_stepper.dart  # Visual order progress
│   │       ├── saapadu_button.dart        # Branded buttons
│   │       ├── saapadu_card.dart          # Glass morphism cards
│   │       ├── saapadu_text_field.dart    # Styled text fields
│   │       ├── saapadu_shimmer.dart       # Loading shimmer effects
│   │       ├── empty_state.dart           # Empty state widget
│   │       ├── glass_container.dart       # Glassmorphism container
│   │       ├── price_tag.dart             # Price display tag
│   │       ├── whatsapp_button.dart       # 5 WhatsApp button widgets
│   │       └── whatsapp_icon.dart         # WhatsApp PNG icon loader
│   ├── features/
│   │   ├── shell/
│   │   │   ├── placeholder_screens.dart   # Splash, Onboarding, Login, OTP,
│   │   │   │                               Home, Search, Orders, Favorites, Profile,
│   │   │   │                               SlidingBanners
│   │   │   ├── extra_screens.dart         # Restaurant, Cart, Checkout, OrderTracking,
│   │   │   │                               Voice/Image Order, MealPlanner, Subscriptions,
│   │   │   │                               HomeChefs, FoodFeed, GroupOrder, Wallet,
│   │   │   │                               Addresses, Notifications, Settings, HelpSupport,
│   │   │   │                               Categories/Offers/Trending SeeAll
│   │   │   ├── admin_screens.dart         # 16 admin screens (Dashboard, CRUD all entities)
│   │   │   ├── delivery_screens.dart      # Delivery Home, Active, History, Earnings
│   │   │   ├── role_selection_screen.dart # Role selector (Customer/Admin/Delivery)
│   │   │   ├── bottom_nav_shell.dart      # 5-tab bottom nav + WhatsApp FAB
│   │   │   └── admin_shell.dart           # Desktop sidebar (collapsible) + mobile NavigationBar
│   │   └── home/data/
│   │       ├── mock_data.dart             # All mock data (~1,800 lines)
│   │       ├── providers.dart             # 55+ Riverpod providers (~830 lines)
│   │       └── models/                    # Data models (BannerModel)
│   │       ├── restaurant/data/models/    # RestaurantModel, MenuItemModel
│   │       ├── orders/data/models/        # OrderModel, OrderItemModel, DeliveryPartnerModel
│   │       ├── cart/data/models/          # CartModel, CartItemModel
│   │       ├── auth/data/models/          # UserModel, AddressModel
│   │       ├── home/data/models/          # CategoryModel, OfferModel, BannerModel
│   │       ├── social/data/models/        # ReviewModel
│   │       ├── subscriptions/data/models/ # SubscriptionModel
│   │       └── home_chef/data/models/     # HomeChefModel
│   ├── l10n/
│   │   ├── app_en.arb                     # English (495 strings)
│   │   └── app_ta.arb                     # Tamil (495 strings)
├── assets/
│   └── images/
│       ├── logo.png                       # App logo
│       ├── whatsapp.png                   # WhatsApp icon
│       └── whatsapp.svg                   # WhatsApp SVG source
├── pubspec.yaml                           # Dependencies & config
└── doc/
    └── sappadugo-technical-document.html  # This document

🔄 Data Flow — Cart → Checkout → Order

Complete order lifecycle from adding items to delivery tracking:

Admin Order Flow

State Propagation

Providers fetch from the Laravel API — changes propagate via state updates:

• Admin adds/edits restaurant → restaurantsFutureProvider refreshes → customer sees updated list
• Admin toggles menu item availability → API updates → customer sees unavailable item
• Admin updates banner → bannersFutureProvider refreshes → home screen sliding banner updates
• Admin assigns delivery partner → Delivery partner sees new order in queue
• Customer places order → ordersFutureProvider refreshes → admin sees new order
• Customer adds money to wallet → walletFutureProvider refreshes → balance updates

🍔 Customer Features

🛠 Admin Panel Features

Desktop-responsive sidebar layout. On screens ≥800px, shows collapsible sidebar navigation. On mobile, shows NavigationBar (5 tabs: Dashboard, Orders, Restaurants, Partners, More) + Drawer for extra sections (Categories, Offers, Banners, Menu Items, Users, Settings).

🚚 Delivery Partner Features

Default partner: Murugan K (partner_1) — logged in automatically in mock mode.

💬 WhatsApp Integration

Full WhatsApp chat integration using url_launcher with cross-platform support.

Components

Configuration

• Phone Number: +919944576702 (configurable in admin settings)
• Default Message: "Hi Please let us know how we can help you."
• Admin Configurable: Phone number and support name in /admin/settings

Integration Points

• OrderTrackingScreen — "Help" AppBar button + "Chat with Support" button
• RestaurantScreen — "WhatsApp [Restaurant]" button below info
• ProfileScreen — "Chat on WhatsApp" menu item
• BottomNavShell — Floating WhatsApp FAB on every customer tab

📦 Data Models (16 Models)

⚡ State Providers (66)

State is managed via Riverpod providers across two files: providers.dart (~830 lines, 55+ providers) and api_providers.dart (11 FutureProviders for API data).

API Data Providers (NEW)

Core Providers

Admin CRUD Providers

Computed Providers

🚧 Routing Table (45+ Routes)

Declarative routing via GoRouter with StatefulShellRoute for tab navigation and ShellRoute for admin sidebar.

Auth Flow

Customer (ShellRoute with BottomNavShell)

Feature Routes

Admin (ShellRoute with AdminShellScreen)

Delivery Partner

📄 Enums

OrderStatus (10 values)

PaymentMethod (9 values)

HealthMode (9 values)

🎨 Theme & Design System

Design Principles

• Material 3 design system with custom tokens
• Glassmorphism cards with backdrop blur and transparency
• 24px rounded corners on all cards
• Poppins font family via Google Fonts
• Shimmer loading skeletons for all data lists
• CachedNetworkImage for all remote images with placeholders
• withValues(alpha:) used throughout (not deprecated withOpacity)
• CardThemeData / TabBarThemeData / DialogThemeData for Flutter 3.x compatibility

🔨 Reusable Widgets (19)

🌐 Localization

• Flutter localization via flutter_localizations SDK
• ARB format with flutter: generate: true in pubspec.yaml
• Full Tamil translations for all UI strings
• Language selector in SettingsScreen

📦 Dependencies

Production Dependencies (16)

Dev Dependencies (3)

🔌 Backend Architecture (Live — Laravel 12)

The app integrates with a live Laravel 12 REST API at http://localhost:8000 (dev) / https://api.saapadugo.com (prod). Authentication uses Laravel Sanctum bearer tokens. All responses are cached locally in Hive for offline-first behaviour.

Backend Stack

API Endpoints (v1 — 61 routes)

// ─── Auth (public) ───────────────────────────────────
POST   /api/v1/auth/send-otp
POST   /api/v1/auth/verify-otp
POST   /api/v1/auth/social

// ─── Public read-only ────────────────────────────────
GET    /api/v1/restaurants
GET    /api/v1/restaurants/:id
GET    /api/v1/restaurants/:id/menu
GET    /api/v1/menu-items
GET    /api/v1/menu-items/:id
GET    /api/v1/home-chefs
GET    /api/v1/home-chefs/:id
GET    /api/v1/coupons
GET    /api/v1/subscriptions
GET    /api/v1/banners

// ─── Protected (auth:sanctum) ────────────────────────

// Auth
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout
GET    /api/v1/auth/me

// Profile
GET    /api/v1/profile
PUT    /api/v1/profile

// Addresses
GET    /api/v1/addresses
POST   /api/v1/addresses
PUT    /api/v1/addresses/:id
DELETE /api/v1/addresses/:id
POST   /api/v1/addresses/:id/default

// Cart
GET    /api/v1/cart
POST   /api/v1/cart/items
PUT    /api/v1/cart/items/:id
DELETE /api/v1/cart/items/:id
DELETE /api/v1/cart
POST   /api/v1/cart/coupon

// Orders
GET    /api/v1/orders
POST   /api/v1/orders
GET    /api/v1/orders/:id
GET    /api/v1/orders/:id/tracking
POST   /api/v1/orders/:id/cancel

// Search
GET    /api/v1/search
POST   /api/v1/ai/search
POST   /api/v1/ai/recommendations
POST   /api/v1/ai/meal-plan
POST   /api/v1/ai/recognize

// Payments
POST   /api/v1/payments/create
POST   /api/v1/payments/verify

// Wallet
GET    /api/v1/wallet
POST   /api/v1/wallet
GET    /api/v1/wallet/history

// Coupons (apply)
POST   /api/v1/coupons/:code/apply

// Subscriptions
POST   /api/v1/subscriptions/:id/subscribe
POST   /api/v1/subscriptions/:id/unsubscribe
POST   /api/v1/subscriptions/:id/pause
POST   /api/v1/subscriptions/:id/resume

// Notifications
GET    /api/v1/notifications
POST   /api/v1/notifications/:id/read

// Favorites
GET    /api/v1/favorites
POST   /api/v1/favorites/:restaurantId/toggle

// Group Orders
POST   /api/v1/group-orders
POST   /api/v1/group-orders/join/:code
DELETE /api/v1/group-orders/:id/leave
GET    /api/v1/group-orders/:id/items
POST   /api/v1/group-orders/:id/items
DELETE /api/v1/group-orders/:id/items/:itemId

Database Schema (26 Tables)

Seeded Data

🚀 Future Roadmap

Backend Deployment

The Laravel 12 backend lives in I:\xampp8212\htdocs\saapadugo-api\ alongside the Flutter app. It runs on PHP 8.2, MySQL 8, and Redis with Laravel Sanctum for token-based auth. The Flutter app connects via http://10.0.2.2:8000 (Android emulator) and caches responses in Hive for offline-first performance.

API Integration

The Flutter ApiRepository (35+ typed methods) and ApiProviders (11 FutureProviders) connect the app to the Laravel backend. Providers in providers.dart fetch data from the API instead of MockData. Restaurants, menu items, cart, orders, wallet, addresses, favorites, subscriptions, banners, and coupons all use real API data.

Environment Configuration

• API Base URL: http://10.0.2.2:8000 (dev) / https://api.saapadugo.com (prod)
• Firebase: Placeholder config — replace with real credentials
• Google Maps: Replace API key in AndroidManifest.xml
• Razorpay: Demo mode auto-detected with placeholder keys
• WhatsApp: +919944576702 (configurable in admin settings)

Pre-existing Errors (Known)

The following errors exist in pre-existing skeleton files and do not affect the app:

• api_client.dart — Non-exhaustive switch on DioExceptionType
• saapadu_card.dart — Undefined class ImageFilter (blur filter)
• widget_test.dart — MyApp reference in default test

Configuration Placeholders (Required for Production)

• firebase_options.dart — REPLACE_WITH_* placeholders
• google-services.json — REPLACE_WITH_* placeholders
• AndroidManifest.xml — Google Maps API key placeholder
• .env — Copy from .env.example and fill in real values