kent_logistics_app/README.md

# Kent Logistics Flutter App

A production-ready Flutter mobile application for Kent Logistics.  
This app communicates with a Laravel backend API for authentication, customer onboarding, and logistics operations.

---

# 📌 1. Requirements (Install Before Running Project)

            To run or develop this project, the following tools must be installed:

            ### ✅ Flutter SDK (Latest Stable)
            Download from:  
            https://flutter.dev/docs/get-started/install

            ### ✅ Android Studio
            Required components:
            - Android SDK
            - Android SDK Platform Tools
            - Android Build Tools
            - **Android NDK version 27.0.12077973** (required for Flutter plugins)
            - Android Emulator (Pixel recommended)

            Install NDK via:
            Android Studio → SDK Manager → SDK Tools → NDK (Side by side)


            ### ✅ JDK 17+
            Required for Android Gradle compatibility.

            ### ✅ Git
            Required for version control, cloning, branching, and pushing code.

            ---

# 📌 2. Clone & Run the Project

            You **do NOT need to create a new Flutter project manually.**  
            Just clone and run:

            ```sh
            git clone http://103.248.30.24:3000/kent-logistics/kent_logistics_app.git
            cd kent_logistics_app
            flutter pub get
            flutter run


# 📌 3. Backend API Details

            # ✔ Android Emulator Base URL:
            http://10.0.2.2:8000/api

            # ✔ Physical Android / iPhone Device:

            # Use your computer’s local IP:

            http://192.168.x.x:8000/api

            # ✔ iOS Simulator:
            http://localhost:8000/api


            # Make sure your Laravel backend is running:

            php artisan serve


# 📌 4. Project Structure (Explained)

            The project follows a clean, scalable architecture:

            lib/
            ├── config/        
            │     └── api_config.dart    # API base URLs, global constants
            │
            ├── services/
            │     ├── auth_service.dart       # Login/logout API calls
            │     ├── request_service.dart    # Signup request + OTP flow
            │     └── shipment_service.dart   # (future) shipment APIs
            │
            ├── providers/
            │     ├── auth_provider.dart      # Authentication state, token, user session
            │     └── app_provider.dart       # (future) global app state
            │
            ├── models/
            │     ├── user_model.dart         # User model for parsed API responses
            │     └── shipment_model.dart     # (future) shipment model
            │
            ├── screens/
            │     ├── auth/
            │     │     ├── login_screen.dart
            │     │     ├── signup_screen.dart
            │     │     ├── otp_screen.dart
            │     │     └── waiting_screen.dart
            │     │
            │     ├── dashboard/
            │     │     └── dashboard_screen.dart
            │     │
            │     ├── shipments/
            │     │     ├── shipment_list_screen.dart
            │     │     └── shipment_details_screen.dart
            │     │
            │     └── splash_screen.dart   # App startup logic (check user session)
            │
            ├── widgets/
            │     ├── primary_button.dart       # Reusable styled button
            │     ├── rounded_input.dart        # Input field widget
            │     └── custom_card.dart          # (future) UI card component
            │
            └── main.dart                      # App entry point, Provider setup, Theme


# 📌 5. Folder Purpose Summary

    # 📁 config/
        Stores global settings:
        API base URL
        Theme configs
        App constants

    # 📁 services/
        All API calls using Dio:
        Authentication (login/logout)
        Signup request
        OTP verification

    # 📁 providers/
        State management using Provider:
        User authentication session
        Save/retrieve JWT token
        Notify UI of state changes

    # 📁 models/
        Data structure classes:
        UserModel
        ShipmentModel (future)

    # 📁 screens/
        UI pages:
        Login, Signup, OTP
        Dashboard
        Shipments (list, details)

    # 📁 widgets/
        Reusable UI components:
        Buttons
        Text fields
        Cards

# 📌 6. Notes for Developers
        Always run flutter pub get after pulling new changes
        Use NDK version 27.0.12077973
        If using physical device → use local IP instead of 10.0.2.2
        Splash screen checks stored JWT token → auto-login if session exists

# 📌 7. Support
        For project setup or issues, contact the project admin or team lead.