add readme file

README.md

@@ -1,25 +1,157 @@
 # Kent Logistics Flutter App
 
-A Flutter mobile application for Kent Logistics.
+A production-ready Flutter mobile application for Kent Logistics.  
+This app communicates with a Laravel backend API for authentication, customer onboarding, and logistics operations.
 
-## Setup
+---
 
-1. Install Flutter SDK
+# 📌 1. Requirements (Install Before Running Project)
-2. Run `flutter pub get`
-3. Run `flutter run`
 
-## Backend API
+            To run or develop this project, the following tools must be installed:
-This project connects to a Laravel API running locally or on server.
 
-Base URL:  
+            ### ✅ Flutter SDK (Latest Stable)
-`http://10.0.2.2:8000/api` (Android emulator)
+            Download from:  
+            https://flutter.dev/docs/get-started/install
 
-## Project Structure
+            ### ✅ Android Studio
-- lib/config/
+            Required components:
-- lib/services/
+            - Android SDK
-- lib/providers/
+            - Android SDK Platform Tools
-- lib/screens/
+            - Android Build Tools
-- lib/widgets/
+            - **Android NDK version 27.0.12077973** (required for Flutter plugins)
+            - Android Emulator (Pixel recommended)
 
-## Development
+            Install NDK via:
-Push changes to main or dev branch as per team workflow.
+            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.