AKSupply Mobile

Flutter mobile app for the AKSupply B2B beverage distribution platform (Ethiopia). Works alongside the AKSupply backend API.

---

Screenshots

Dashboard Overview	Analytics	Quick Actions	Products

---

Features

Feature	Roles
Login / Register / Forgot password (OTP)	All
Product catalog — search, filters, barcode/QR scan	All
Multi-image gallery, variants, tags, supplier info	All
Cart + Checkout (B2B/B2C pricing, promo codes, loyalty redemption, delivery scheduling, on-account payment)	Customer / Shop
Order list & detail (notes, payment timeline, reorder, PDF invoice export)	All
Order templates — save & reuse cart configurations	Customer / Shop
Product bundles — discounted kits ordered in one tap	Customer / Shop
Recurring orders — scheduled standing orders	Customer / Shop
Returns & refunds	Customer / Shop
Loyalty points — earn on orders, redeem at checkout	Customer / Shop
Address book	Customer / Shop
Account statement — credit balance + transaction history	Shop
Biometric login (fingerprint / Face ID)	All
Push notifications (FCM)	All
Admin dashboard with stats & quick actions	Admin
User management + shop approval workflow	Admin
Product management (add / edit / gallery / variants / bundles)	Admin
Inventory management + low-stock FCM alerts	Admin
Volume / bulk discount tiers	Admin
Promo code management	Admin
Supplier / vendor management	Admin
Purchase orders (create → receive → auto-restock)	Admin
Customer-specific price lists	Admin
Payment reconciliation (on-account invoices)	Admin
Audit log with diff viewer	Admin
App settings (tax rate, delivery fee)	Admin
Analytics & reports (charts, exports)	Admin
Delivery dashboard — assigned runs & status updates	Delivery

---

Tech Stack

• Flutter 3.x / Dart 3.x
• State management — Riverpod 2 (StateNotifier + autoDispose)
• Architecture — Clean Architecture (Presentation → Domain → Data)
• HTTP — Dio + pretty_dio_logger + dio_smart_retry
• Local storage — SharedPreferences, FlutterSecureStorage, Drift (SQLite)
• UI — flutter_screenutil, fl_chart, shimmer, cached_network_image
• PDF — pdf + printing
• Scanner — mobile_scanner
• Push notifications — firebase_messaging + flutter_local_notifications
• Auth — JWT (stored in FlutterSecureStorage) + optional biometrics

---

Getting Started

Prerequisites

• Flutter SDK >=3.2.0
• Dart SDK >=3.2.0
• Android Studio (Android) or Xcode (iOS)
• AKSupply backend running — see aksupply

1. Install dependencies

flutter pub get

2. Set the API base URL

Edit lib/core/constants/app_constants.dart:

// Android emulator → localhost backend
return 'http://10.0.2.2:3000/api/v1';

// Physical device on the same Wi-Fi
return 'http://192.168.X.X:3000/api/v1';

// Or pass at build time
// flutter run --dart-define=BASE_URL=http://your-server/api/v1

3. Run

flutter run

Push notifications are optional — the app works fully without Firebase. See Firebase Setup below when you're ready.

---

Project Structure

lib/
├── core/
│   ├── constants/       # AppConstants, route paths, storage keys
│   ├── network/         # DioClient, ApiEndpoints
│   ├── providers/       # Core Riverpod providers (DioClient, SecureStorage, FCM…)
│   ├── services/        # FCMService
│   ├── theme/           # AppColors, AppTheme
│   ├── utils/           # AppLogger, validators, PDF generators
│   └── widgets/         # Shared widgets (CustomButton, LoadingOverlay…)
└── features/
    ├── auth/            # Login, register, forgot password, profile
    ├── home/            # Home screen with role-based banners
    ├── products/        # Product list, detail, add/edit
    ├── orders/          # Cart, checkout, order list/detail, templates
    ├── bundles/         # Product bundles
    ├── deliveries/      # Delivery dashboard & detail
    ├── dashboard/       # Admin dashboard, reports, settings
    ├── inventory/       # Inventory list & detail
    ├── account/         # Account statement
    └── ...

Each feature follows the pattern:

feature/
├── data/
│   ├── datasources/     # Remote API calls (Dio)
│   ├── models/          # Freezed JSON models
│   └── repositories/    # Implements domain repository
├── domain/
│   ├── entities/        # Pure Dart entities
│   ├── repositories/    # Abstract repository contracts
│   └── usecases/        # Single-responsibility use cases
└── presentation/
    ├── providers/        # Riverpod StateNotifiers
    └── screens/          # Flutter widgets

---

Default Credentials (development)

Role	Email	Password
Admin	admin@aksupply.com	Admin@123
Shop	shop@example.com	(set via DB or registration)
Customer	customer@example.com	(set via DB or registration)
Delivery	delivery@example.com	(set via DB or registration)

---

Firebase / Push Notifications

Push notifications require a Firebase project. All other features work without it.

Quick steps:

1. Create a project at console.firebase.google.com
2. Android — Add app (package com.example.aksupply_mobile) → download google-services.json → place at android/app/google-services.json
3. iOS — Add app (bundle ID from Xcode) → download GoogleService-Info.plist → place at ios/Runner/GoogleService-Info.plist
4. Backend — Firebase project settings → Service Accounts → Generate new private key → save as aksupply/config/firebase-service-account.json
5. Rebuild the app: flutter run

These files are gitignored — never commit them.

---

Related

• Backend: aksupply — Node.js / Express / PostgreSQL