3PL Warehouse Management System - User Manual

Version: 1.1.0 Last Updated: March 4, 2026 Framework: Laravel 12 | PHP 8.2+ | MySQL | Tailwind CSS | Alpine.js

Table of Contents

1. System Overview
2. Getting Started
3. Login & Authentication
4. Admin Panel Modules
   • 4.1 Dashboard
   • 4.2 Customer Management
   • 4.3 Supplier Management
   • 4.4 Product Management
   • 4.5 Warehouse Management
   • 4.6 Container Tracking (Import/FCL)
   • 4.7 Purchase Orders
   • 4.8 Inventory Management
   • 4.9 Inbound Receiving (Goods Receiving)
   • 4.10 Order Fulfillment
   • 4.11 VAS Orders (Value-Added Services)
   • 4.12 Return Processing
   • 4.13 Invoice Management
   • 4.14 Financial Management
   • 4.15 Reports & Analytics
   • 4.16 Data Exports
   • 4.17 User Management
   • 4.18 System Settings
5. Customer Portal Modules
   • 5.1 Customer Dashboard
   • 5.2 Goods Management
   • 5.3 Inventory View
   • 5.4 Inbound Orders
   • 5.5 Consign Orders
   • 5.6 My Customers (Sub-Customers)
   • 5.7 Return Requests
   • 5.8 Orders
   • 5.9 Invoices & Costs
   • 5.10 Analytics
6. Key Workflows
7. Database Architecture
8. Complete Module Reference Table
9. Technical Stack & File Structure
10. Troubleshooting & FAQ

1. System Overview

The 3PL Warehouse Management System is a comprehensive web application designed for Third-Party Logistics (3PL) providers. It manages the full lifecycle of warehouse operations including:

• Multi-tenant customer management - Each customer has isolated products, inventory, and orders
• Import/Container tracking - Track FCL/LCL shipments from origin port to warehouse
• Inbound goods receiving - Barcode-based receiving with scan & verify workflow
• Inventory management - Real-time stock levels across warehouses with batch/lot/serial tracking
• Order fulfillment - Complete pick-pack-ship workflow
• Consignment operations - Customers can ship goods to their own customers through the warehouse
• Value-Added Services (VAS) - Kitting, labeling, repackaging, inspection, assembly, etc.
• Return processing - Full return workflow with item condition tracking
• Financial management - Invoicing, payment tracking, supplier ledger
• Reporting & data exports - Business analytics and Excel exports

Dual-Role Architecture

2. Getting Started

System Requirements

• PHP 8.2 or higher
• MySQL 5.7+ or MariaDB 10.3+
• Composer (PHP dependency manager)
• Node.js & npm (for frontend assets)
• Apache/Nginx web server (XAMPP recommended for local development)

Installation

# 1. Navigate to the project directory
cd C:\xampp\htdocs\3pl_warehouse

# 2. Install PHP dependencies
composer install

# 3. Install frontend dependencies
npm install

# 4. Copy environment file and configure database
cp .env.example .env
php artisan key:generate

# 5. Configure your .env file
#    DB_DATABASE=3pl_warehouse
#    DB_USERNAME=root
#    DB_PASSWORD=your_password

# 6. Run database migrations
php artisan migrate

# 7. Seed the admin user
php artisan db:seed

# 8. Build frontend assets
npm run build

# 9. Start the development server
php artisan serve

Default Admin Login

After seeding, use the default admin credentials to log in (check database/seeders/AdminSeeder.php for the default email and password).

3. Login & Authentication

How to Login

1. Navigate to http://yoursubdomain/3pl_warehouse/login
2. Enter your Email and Password
3. Click Login

Role-Based Redirection

• Admin users are redirected to the Admin Dashboard (/)
• Customer users are redirected to the Customer Portal (/customer/dashboard)

Logout

Click the Logout button in the top-right corner of the navigation bar, or navigate to the user menu and select Logout.

4. Admin Panel Modules

The admin panel is accessible only to users with the admin role. The sidebar navigation organizes modules into the following sections: Operations, Warehouse, Fulfillment, Finance, and Reports.

4.1 Dashboard

Route: / Controller: DashboardController

The admin dashboard provides a high-level overview of warehouse operations with key performance indicators (KPIs):

• Total Customers - Active customer count
• Total Products - Products in the system
• Total Orders - All fulfillment orders
• Pending Orders - Orders awaiting processing
• Revenue Overview - Total invoiced amounts
• Recent Activity - Latest system activities

4.2 Customer Management

Route: /customers Controller: CustomerController

Features:

• List Customers - View all customers with search and status filtering
• Create Customer - Add a new customer company with:
  • Company name, customer code (auto-generated or manual)
  • Contact email, phone, website
  • Billing address (street, city, state, zip, country)
  • Payment terms and credit limit
  • Warehouse zone assignment
  • Special instructions
• Edit Customer - Update customer information
• View Customer Details - See full customer profile including:
  • Contact persons
  • Shipping addresses
  • Order history
  • Invoice history

Managing Customer Contacts:

1. Go to a customer's detail page
2. Click Add Contact
3. Fill in: Name, Email, Phone, Title, Department
4. Save the contact

Managing Shipping Addresses:

1. Go to a customer's detail page
2. Click Add Shipping Address
3. Fill in: Address name, Street, City, State, ZIP, Country
4. Save the address

Creating Portal Access for Customers:

1. Go to User Management > Create User
2. Set role to Customer
3. Link the user to a customer account
4. Share login credentials with the customer

4.3 Supplier Management

Route: /suppliers Controller: SupplierController

Features:

• List Suppliers - View all suppliers
• Create Supplier - Add new supplier with:
  • Company name, supplier code
  • Contact person, email, phone
  • Address details
  • Payment terms
• Edit Supplier - Update supplier information
• Delete Supplier - Remove a supplier record

How to Add a Supplier:

1. Navigate to Operations > Suppliers
2. Click Create Supplier
3. Fill in company details and contact information
4. Set payment terms (e.g., Net 30, Net 60)
5. Click Save

4.4 Product Management

Route: /products Controller: ProductController

Features:

• List Products - View all products with search and filter
• Create Product - Add a new product SKU:
  • Assign to a specific customer
  • SKU (unique identifier), Name, Description
  • Category and Barcode
  • Unit of measure (pcs, kg, box, pallet, etc.)
  • Dimensions: Weight, Length, Width, Height
  • Unit cost and Selling price
  • Reorder point and Reorder quantity
  • Flags: Perishable, Serial-tracked
• Edit Product - Update product details
• Delete Product - Remove a product

How to Create a Product:

1. Navigate to Operations > Products
2. Click Create Product
3. Select the Customer this product belongs to
4. Enter the SKU, Name, and Description
5. Fill in dimensions, costs, and reorder settings
6. Mark as Perishable or Serial-tracked if applicable
7. Click Save

4.5 Warehouse Management

Route: /warehouses Controller: WarehouseController

Features:

• List Warehouses - View all warehouse locations
• Create Warehouse - Add a new warehouse:
  • Name and Code
  • Address (street, city, state, zip, country)
  • Contact person, email, phone
  • Total capacity
  • Status: Active / Inactive / Maintenance
• Edit Warehouse - Update warehouse details
• Delete Warehouse - Remove a warehouse

4.6 Container Tracking (Import/FCL)

Route: /containers Controller: ContainerController

This module manages import container shipments from overseas suppliers to the warehouse.

Features:

• List Containers - View all containers with status filters
• Create Container - Register a new import container:
  • Container number (unique), Booking number, Bill of Lading
  • Shipping line and Container type (20ft, 40ft, 40ft HC, 45ft HC)
  • Shipment type: FCL (Full Container Load) / LCL (Less Container Load)
  • Assign to Customer and Supplier
  • Port of origin and Port of destination
  • Booking date, ETA, and Arrival date
  • Total weight, CBM, and Item count
  • Cost tracking: Freight, Customs, Duty, Handling, Demurrage
  • Customs status tracking
• Update Status - Track container through lifecycle:
  • booked → in_transit → arrived → unloading → completed → returned
• View Container Details - See all container information and linked purchase orders

Container Lifecycle:

1. Booked - Container booked with shipping line
2. In Transit - Container shipped from origin
3. Arrived - Container arrived at destination port
4. Unloading - Container being unloaded at warehouse
5. Completed - All goods received and processed
6. Returned - Empty container returned to shipping line

4.7 Purchase Orders

Route: /purchase-orders Controller: PurchaseOrderController

Features:

• List Purchase Orders - View all POs with status tracking
• Create Purchase Order - Create a new PO:
  • PO number (auto-generated)
  • Select Customer and Supplier
  • Link to a Container (optional)
  • Add line items: Product, Expected quantity, Unit cost
  • Cost breakdown: Subtotal, Freight, Duty, Customs, Handling, Total
  • Order date and Expected delivery date
• Receive Goods - Process goods receipt against PO:
  • Enter received quantities per item
  • Track discrepancies between expected and received
• Update Payment Status - Track PO payment (Unpaid / Partial / Paid)

Purchase Order Statuses:

draft → confirmed → in_transit → partially_received → received → completed → cancelled

4.8 Inventory Management

Route: /inventory Controller: InventoryController

Features:

• View Inventory - See all inventory records with:
  • Product details and SKU
  • Warehouse and Zone location
  • Quantity on hand, Reserved, Available
  • Batch/Lot/Serial numbers
  • Expiry dates for perishable items
  • Unit cost and Status
• Filter Inventory - Filter by customer, warehouse, zone, or status
• Adjust Inventory - Make inventory adjustments with:
  • Adjustment reason (audit, damage, correction, etc.)
  • New quantity
  • Audit trail automatically recorded

Inventory Statuses:

Inventory Movement Tracking:

Every inventory change is automatically logged with:

• Movement type (receive, ship, adjust, return)
• Previous and new quantities
• User who made the change
• Timestamp

4.9 Inbound Receiving (Goods Receiving)

Route: /inbound-receiving Controller: AdminInboundController

This module handles the physical receiving of goods when they arrive at the warehouse.

Features:

• View Pending Inbounds - List all inbound orders awaiting receiving
• Receive Inbound Order - Process goods receiving:
  • Scan barcodes for each inbound item
  • Verify item details against expected quantities
  • Mark items as Received or Rejected
  • Enter actual received quantities
  • Add rejection reasons if applicable
• Complete Inbound - Finalize the receiving process:
  • Inventory is automatically updated with received quantities
  • Inbound order status changes to received

Receiving Workflow:

1. Customer submits inbound order (from portal)
2. Admin views the inbound order in Inbound Receiving
3. When goods arrive, admin opens the inbound order
4. Scan each item's barcode or manually select items
5. Enter received quantity and mark as received/rejected
6. Click Complete Receiving
7. Inventory is automatically updated

4.10 Order Fulfillment

Route: /orders Controller: OrderController

Features:

• List Orders - View all fulfillment orders with status filters
• Create Order - Create a new fulfillment order:
  • Select Customer
  • Order type: Standard, Rush, Wholesale, Return
  • Add line items: Product, Quantity, Unit price
  • Recipient details: Name, Address, Phone, Email
  • Shipping: Carrier, Method, Ship-by date
• Update Order Status - Progress order through workflow
• Add Tracking Info - Enter carrier tracking number
• View Order Details - See complete order information

Order Statuses:

pending → processing → picking → packing → shipped → delivered Optional: cancelled | returned

How to Fulfill an Order:

1. Navigate to Fulfillment > Orders
2. Find the pending order
3. Click Process to start fulfillment
4. Update status to Picking when warehouse staff begin picking
5. Update to Packing when items are packed
6. Enter tracking number and update to Shipped
7. Order automatically marked as Delivered upon confirmation

4.11 VAS Orders (Value-Added Services)

Route: /vas-orders Controller: VasOrderController

Features:

• List VAS Orders - View all VAS requests
• Create VAS Order - Create a new service order:
  • VAS number (auto-generated)
  • Select Customer and optionally link to an Order
  • Service type: Kitting, Labeling, Repackaging, Quality Inspection, Assembly, Photography, Gift Wrapping, Other
  • Priority: Low, Normal, High, Urgent
  • Description and Special instructions
  • Quantity of items
  • Labor: Hours, Rate, Cost
  • Material cost
  • Upload before/after photos
• Update Status - Track VAS progress:
  • pending → in_progress → completed → cancelled
• Complete VAS - Record completion notes and upload after photos

Available Service Types:

4.12 Return Processing

Route: /return-processing Controller: AdminReturnController

Features:

• View Pending Returns - List all return requests awaiting processing
• Process Return - Handle return requests:
  • Review return reason and customer notes
  • Approve or Reject the return
  • Process individual items:
    • Check item condition (Good, Damaged, Expired, Unknown)
    • Add inspection notes
    • Return items to inventory or discard
  • Record admin notes
• Complete Return - Finalize return processing

Return Workflow:

1. Customer submits return request (from portal)
2. Admin reviews the request in Return Processing
3. Admin approves or rejects the request
4. If approved, warehouse receives returned items
5. Admin inspects each item and records condition
6. Good items returned to inventory; damaged items flagged
7. Return marked as completed

4.13 Invoice Management

Route: /invoices Controller: InvoiceController

Features:

• List Invoices - View all invoices with status filters
• Create Invoice - Generate a new invoice:
  • Invoice number (auto-generated)
  • Select Customer
  • Invoice date and Due date
  • Add line items: Description, Quantity, Unit price, Amount
  • Tax amount calculation
  • Totals: Subtotal, Tax, Total amount
• Send Invoice - Mark invoice as sent to customer
• Record Payment - Log payment received:
  • Payment amount
  • Payment date
  • Automatically updates balance due
• View Invoice - Detailed invoice view

Invoice Statuses:

4.14 Financial Management

Route: /financial Controller: FinancialController

Features:

• Financial Dashboard - Overview of financial health:
  • Total revenue
  • Outstanding receivables
  • Total payables
  • Recent transactions
• Transaction History - View all financial transactions:
  • Payments received from customers
  • Payments made to suppliers
  • Adjustments and corrections
• Supplier Ledger - Track supplier balances:
  • View outstanding payments per supplier
  • Record supplier payments
  • Track payment history

Recording a Supplier Payment:

1. Navigate to Finance > Financial
2. Go to Supplier Ledger
3. Select the supplier
4. Click Record Payment
5. Enter payment amount, reference number, and date
6. Click Save

4.15 Reports & Analytics

Route: /reports Controller: ReportController

Available Reports:

How to Generate a Report:

1. Navigate to Reports in the sidebar
2. Select the desired report type
3. Apply date range and filters if applicable
4. View the report data on screen

4.16 Data Exports

Controller: ExportController

Export data to Excel format for external analysis:

How to Export Data:

1. Navigate to the respective module (e.g., Customers)
2. Click the Export button (usually in the top-right area)
3. The Excel file will download automatically

4.17 User Management

Route: /users Controller: UserController

Features:

• List Users - View all system users
• Create User - Add a new user:
  • Name, Email, Phone
  • Password (minimum 8 characters)
  • Role: Admin or Customer
  • If Customer role: Link to a customer account
  • Active/Inactive status
• Edit User - Update user details
• Activate/Deactivate - Enable or disable user access

How to Create a Customer Portal User:

1. Navigate to Settings > Users (or User Management)
2. Click Create User
3. Enter the user's name and email
4. Set a password
5. Select role: Customer
6. Select the Customer Account to link
7. Mark as Active
8. Click Save
9. Share the login credentials with the customer

4.18 System Settings

Route: /settings Controller: SettingsController

Configurable Settings:

• Currency - Set the default currency (symbol and code)
• Country - Set the default country for addresses
• System Defaults - Configure default values for various fields

5. Customer Portal Modules

The Customer Portal is accessible to users with the customer role. All portal routes are prefixed with /customer.

5.1 Customer Dashboard

Route: /customer/dashboard

The customer dashboard provides an overview of:

• Total inventory held in the warehouse
• Pending inbound orders
• Active outbound/consign orders
• Recent invoices and outstanding balance
• Quick action buttons

5.2 Goods Management

Route: /customer/goods Controller: CustomerGoodsController

Features:

• View Goods - See all goods/products registered
• Add New Goods - Register a new product:
  • SKU, Name, Description
  • Category, Barcode
  • Unit of measure
  • Dimensions and weights
  • Costs and pricing
• Edit Goods - Update product details
• Delete Goods - Remove a product record

5.3 Inventory View

Route: /customer/inventory

Features:

• Inventory Overview - View all inventory held in the warehouse:
  • Product name and SKU
  • Warehouse location
  • Quantity on hand, Reserved, Available
  • Batch/Lot numbers
  • Expiry dates
• Inventory Record (/customer/inventory/record) - Detailed inventory record view
• Inventory Health (/customer/inventory/health) - Low stock alerts and reorder notifications

5.4 Inbound Orders

Route: /customer/inbound Controller: InboundOrderController

Features:

• View Inbound Orders - List all submitted inbound orders
• Create Inbound Order - Submit a new inbound shipment:
  • Select warehouse destination
  • Expected arrival date
  • Tracking number and Shipping carrier
  • Add items: Select product, Enter expected quantity
  • Special instructions
• View Inbound Details - Track inbound order status
• Download Barcodes - Generate and download barcodes for each inbound item (for warehouse scanning)

Inbound Order Statuses:

draft → submitted → shipped → arrived → receiving → received Optional: cancelled | rejected

How to Submit an Inbound Order:

1. Navigate to Inbound Orders in the customer portal
2. Click Create Inbound Order
3. Select the destination Warehouse
4. Enter the Expected Arrival Date
5. Add a Tracking Number and Carrier (if available)
6. Add products:
   • Select each product from the dropdown
   • Enter the expected quantity
7. Click Submit
8. Download barcodes for each item to attach to the shipment
9. Track the status as the warehouse receives your goods

5.5 Consign Orders

Route: /customer/consign-orders Controller: ConsignOrderController

Consignment orders allow customers to ship goods held in the warehouse directly to their own customers (sub-customers).

Features:

• View Consign Orders - List all consignment orders
• Create Consign Order - Submit a new consignment:
  • Select a sub-customer (from My Customers)
  • Select warehouse
  • Add items from available inventory
  • Enter quantities and unit prices
  • Shipping carrier and Special instructions
• View Consign Details - Track consignment status
• Edit/Cancel - Modify or cancel pending consignments

Consign Order Statuses:

pending → confirmed → picking → packing → shipped → delivered Optional: cancelled

5.6 My Customers (Sub-Customers)

Route: /customer/my-customers

Manage your own customer base for consignment operations.

Features:

• View Sub-Customers - List all your customers
• Add Sub-Customer - Register a new sub-customer:
  • Company name
  • Contact email and Phone
  • Shipping address
  • Active/Inactive status
• Edit Sub-Customer - Update sub-customer details
• Delete Sub-Customer - Remove a sub-customer

5.7 Return Requests

Route: /customer/returns Controller: ReturnRequestController

Features:

• View Return Requests - List all submitted returns
• Create Return Request - Submit a new return:
  • Select warehouse
  • Add items to return: Product, Quantity
  • Return reason
  • Additional notes
• View Return Details - Track return status and admin notes

Return Request Statuses:

pending → approved → processing → completed Optional: rejected

5.8 Orders

Route: /customer/orders

Features:

• View All Orders - List all fulfillment orders placed by the warehouse on your behalf
• Order Details (/customer/orders/{id}) - View complete order information:
  • Order items and quantities
  • Shipping details and Tracking number
  • Order status and Timeline

5.9 Invoices & Costs

Route: /customer/invoices

Features:

• View All Invoices - List all invoices with status (Draft, Sent, Paid, Overdue)
• Invoice Details (/customer/invoices/{id}) - View complete invoice:
  • Line items with descriptions and amounts
  • Tax and Total amounts
  • Payment status and Balance due

5.10 Analytics

Route: /customer/analytics

View analytics and performance metrics specific to your account:

• Inventory trends
• Order volume over time
• Cost analysis
• Shipment performance

6. Key Workflows

Workflow 1: Goods Receiving (Inbound Process)

Customer Portal                          Admin Panel
─────────────────                        ──────────────
1. Customer creates
   Inbound Order          ──────►    2. Admin sees inbound
   (adds products &                     in Inbound Receiving
    quantities)
                                     3. Goods arrive at
3. Customer downloads                   warehouse
   barcodes for items
                                     4. Admin scans barcodes
                                        or selects items

                                     5. Admin enters received
                                        quantities

                                     6. Admin marks items as
                                        Received / Rejected

                                     7. Admin clicks Complete
                                        ► Inventory auto-updated

Workflow 2: Import Container to Inventory

1. Create Container (with shipping details & costs)
       │
2. Create Purchase Order(s) linked to Container
       │
3. Track Container status: Booked → In Transit → Arrived
       │
4. Unload Container at warehouse
       │
5. Receive goods against Purchase Order
       │
6. Inventory automatically updated with received quantities
       │
7. Mark Container as Completed → Return empty container

Workflow 3: Order Fulfillment (Outbound)

1. Create Order (select customer, add items, enter recipient)
       │
2. Order Status: Pending → Processing
       │
3. Warehouse picks items → Status: Picking
       │
4. Items packed → Status: Packing
       │
5. Enter tracking number → Status: Shipped
       │
6. Delivery confirmed → Status: Delivered
       │
7. Invoice generated for the order

Workflow 4: Consignment Order

Customer Portal                          Admin Panel
─────────────────                        ──────────────
1. Customer manages
   sub-customers
   (My Customers)

2. Customer creates
   Consign Order           ──────►   3. Admin confirms
   (selects sub-customer,               consignment order
    picks items from
    inventory)                       4. Warehouse picks &
                                        packs items

                                     5. Admin ships to
                                        sub-customer

                                     6. Marks as Delivered

Workflow 5: Return Processing

Customer Portal                          Admin Panel
─────────────────                        ──────────────
1. Customer submits
   Return Request          ──────►   2. Admin reviews request
   (products, quantities,
    reason)                          3. Admin Approves / Rejects

                                     4. If approved, goods
                                        arrive at warehouse

                                     5. Admin inspects items,
                                        records condition:
                                        Good / Damaged / Expired

                                     6. Good items → back to
                                        inventory

                                     7. Return completed

Workflow 6: Value-Added Services

1. Create VAS Order (select service type, customer, quantity)
       │
2. Status: Pending → In Progress
       │
3. Upload "Before" photo
       │
4. Perform service (kitting, labeling, etc.)
       │
5. Record labor hours and material costs
       │
6. Upload "After" photo
       │
7. Complete VAS order with notes
       │
8. Total cost calculated (labor + materials)

7. Database Architecture

Tables Overview (32 Tables)

Core Tables

Product & Inventory Tables

Import/Procurement Tables

Inbound Tables

Outbound Tables

Return Tables

VAS Tables

Financial Tables

System Tables

8. Complete Module Reference Table

9. Technical Stack & File Structure

Technology Stack

### Key Statistics

| Metric | Count |
|--------|-------|
| Controllers | 27 |
| Models | 27 |
| Database Tables | 32 |
| Blade Templates | 85 |
| Migration Files | 32 |
| Total Controller Lines | 4,270+ |
| Total Model Lines | 1,760+ |

---

## 10. Troubleshooting & FAQ

### Common Issues

**Q: I can't log in**
A: Ensure you have run `php artisan migrate` and `php artisan db:seed` to create the default admin user. Check your `.env` file for correct database credentials.

**Q: The page shows a 500 error**
A: Check the Laravel log at `storage/logs/laravel.log` for detailed error messages. Common causes: missing `.env` file, database connection issues, or missing migrations.

**Q: Inventory is not updating after receiving goods**
A: Ensure you click **Complete Receiving** on the inbound order. Inventory only updates when the receiving process is finalized.

**Q: Customer can't see their inventory**
A: Verify the customer user is linked to the correct customer account. Check that products and inventory records exist for that customer.

**Q: Exports are not working**
A: Ensure the `storage` directory is writable. Run `php artisan storage:link` if public storage is not accessible.

**Q: How do I reset a user's password?**
A: Go to **User Management**, find the user, click **Edit**, and enter a new password.

### Useful Artisan Commands

```bash
# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# Run pending migrations
php artisan migrate

# Rollback last migration
php artisan migrate:rollback

# Seed database
php artisan db:seed

# List all routes
php artisan route:list

# Start development server
php artisan serve

# Monitor logs in real-time
php artisan pail

End of User Manual For additional support, contact the system administrator.