SmartGrocery SaaS - Documentation

## Introduction

SmartGrocery SaaS is a complete grocery delivery solution with:

- Laravel Admin Panel + REST API (`laravel_code`)
- Next.js Customer Website (`grocery-web`)
- Flutter Mobile App (`flutter_code`)

Important: This package does not ship with any default admin password. You must set your own admin credentials during installation.

## Requirements

### Backend (Laravel)

- PHP 8.2+
- MySQL 8+ or MariaDB 10.3+
- Composer

### Website (Next.js)

- Node.js (Active LTS recommended)
- npm

### Mobile (Flutter)

- Flutter SDK (stable)
- Android Studio or VS Code
- JDK 17

### iOS

- macOS + Xcode
- Apple Developer account (for App Store)

## Security Defaults

- `.env` is not included in the package. Use `.env.example` placeholders.
- `APP_ENV=production` and `APP_DEBUG=false` are set in `.env.example`.
- Laravel session encryption is enabled by default.
- API authentication and sensitive endpoints are rate-limited.
- Flutter stores auth tokens using secure storage.

## Laravel Installation

### 1) Upload

Upload the `laravel_code` folder to your server.

### 2) Environment

Copy `.env.example` to `.env` and set your values (do not use placeholders in production).

    cp .env.example .env
    php artisan key:generate

### 3) Install & Migrate

    composer install
    php artisan migrate --seed
    php artisan storage:link

## Create Admin Account

Set these values in your Laravel `.env` before running `php artisan migrate --seed`:

    SUPER_ADMIN_EMAIL=your-admin-email@example.com
    SUPER_ADMIN_PASSWORD=your-strong-password

Tip: Use a strong password (12+ characters) and change it regularly.

## Cron & Queue

If you use scheduled tasks (notifications, cleanups), set up a cron job:

    * * * * * cd /path/to/laravel_code && php artisan schedule:run >> /dev/null 2>&1

If you use queue features, configure a queue worker (recommended: Supervisor).

## License Verification (DRM)

This item uses an external license server for purchase code validation. The default server is:

    https://burhanlabs.xyz

You can configure it in Laravel via:

    LICENSE_SERVER_URL=https://burhanlabs.xyz
    LICENSE_KEY=YOUR_PURCHASE_CODE_OR_LICENSE_KEY

Availability: If the license server is temporarily unavailable, license checks may fail until service is restored. If that happens, please contact the author for support.

## Next.js Installation

    cd grocery-web
    npm install

### Build

    npm run build
    npm start

## Website Configuration

Copy `.env.example` to `.env.local` and set your URLs:

    NEXT_PUBLIC_API_URL=https://your-admin-domain.com/api
    NEXT_PUBLIC_SITE_URL=https://your-website-domain.com

If you use Next.js Image with your own domain, update `next.config.ts` `images.remotePatterns` with your domain(s).

## Flutter Setup

### 1) Configure API

Update `flutter_code/lib/config.dart`:

    static const String webBaseUrl = 'https://your-admin-domain.com';

### 2) Install Dependencies

    flutter pub get

## Firebase Setup

Firebase is required for push notifications and Google services if enabled.

1. Create a Firebase project.
2. Add an Android app using your package name.
3. Download `google-services.json` and place it in `flutter_code/android/app/`.

## Build Android (APK / AAB)

### APK

    flutter build apk --release

### AAB (Play Store)

    flutter build appbundle --release

## Android Signing

Android release builds must be signed with your own keystore. Follow these steps:

### 1) Generate keystore

    keytool -genkey -v -keystore c:\path\to\keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias your_key_alias -storepass your_store_password -keypass your_key_password -dname "CN=Your Name, OU=YourOrgUnit, O=YourOrg, L=YourCity, S=YourState, C=US"

### 2) Create `android/key.properties`

Copy the provided `android/key.properties.example` to `android/key.properties` and set values:

    storeFile=/absolute/path/to/keystore.jks
    storePassword=your_store_password
    keyAlias=your_key_alias
    keyPassword=your_key_password

### 3) Build

The project is pre-configured to read `key.properties`. If present, the release build will use it automatically.

    flutter build appbundle --release
    flutter build apk --release

The Gradle config uses your `key.properties` if available and falls back to debug keys for local release runs only. For publishing to Play Store, always use a proper keystore.

## Change App IDs (Branding)

### Android (applicationId)

1. Edit `android/app/build.gradle.kts` and change:

       defaultConfig {
         applicationId = "com.yourcompany.yourapp"
       }

2. Refactor package for MainActivity (recommended):
   - Move `android/app/src/main/kotlin/.../MainActivity.kt` into folders matching the new package.
   - Update the first line in `MainActivity.kt`:

         package com.yourcompany.yourapp

### iOS (Bundle Identifier)

1. Open `ios/Runner.xcworkspace` in Xcode.
2. Select the Runner target → General → Bundle Identifier → set to `com.yourcompany.yourapp`.
3. Ensure the same identifier is used for targets and test targets if present.

## Build iOS (IPA)

Requires macOS + Xcode.

    flutter build ipa

## iOS Release (App Store)

### 1) Firebase for iOS (optional)

1. In Firebase Console, add an iOS app using your Bundle ID.
2. Download `GoogleService-Info.plist`.
3. Open Xcode and drag `GoogleService-Info.plist` into `ios/Runner` (select Copy if needed, add to Runner target).

### 2) Signing & Capabilities

1. In Xcode → Runner target → Signing & Capabilities:
2. Select your Team.
3. Set the correct Bundle Identifier.
4. Use Automatic signing or add a provisioning profile (from Apple Developer portal).

### 3) Archive & Upload

1. Set build mode to Any iOS Device (arm64).
2. From Xcode: Product → Archive.
3. In Organizer, validate and distribute to App Store (or export IPA and upload via Transporter).

Ensure all icons and launch images meet App Store guidelines. Push notifications require proper capabilities and APNs setup.

## Stripe

1. Create a Stripe account.
2. In Admin Panel: go to Payment Methods and enable Stripe.
3. Add your Stripe Publishable Key and Secret Key (sandbox/live).

Stripe keys are stored in the Admin Panel payment configuration. The mobile app receives the publishable key via API when initiating a payment.

## OneSignal

1. Create a OneSignal app.
2. Copy your OneSignal App ID.
3. In Admin Panel settings, set `onesignal_app_id` (and related fields if available).
4. Deploy the OneSignal service worker files to your website public root if your hosting requires them.

## Paytm (India-only)

Note: Paytm is available for India merchants only. If you are outside India, disable Paytm and use Stripe / PayPal / COD.

1. Create a Paytm merchant account (India).
2. In Admin Panel: enable Paytm payment method.
3. Set Merchant ID (MID), Merchant Key, Website/Industry Type, and environment (TEST/LIVE).

## AI Feature

The Admin Panel includes AI tools for product content and SEO generation.

### Backend keys

Set these in Laravel `.env`:

    AI_API_KEY=YOUR_AI_PROVIDER_KEY
    AI_API_BASE_URL=https://openrouter.ai/api/v1
    AI_MODEL=openai/gpt-4.1-mini

### Background Removal

    REMOVEBG_API_KEY=YOUR_REMOVEBG_KEY

## Postman Collection

A Postman collection is included at:

    Documentation/Postman/SmartGrocery_SaaS.postman_collection.json

Set your environment variables in Postman:

    base_url = https://your-admin-domain.com
    token = (Bearer token from /api/login)

## Changelog

See `CHANGELOG.md` in the package root for full version history.