# CargoFlow - Professional Cargo Management System

## 🚀 Project Overview

A complete, production-ready cargo management system built with Laravel 11 and modern UI/UX design using Tailwind CSS. This system provides comprehensive functionality for managing cargo operations, customer relationships, pricing, and shipment tracking.

## ✨ Key Features

### 1. Customer Management
- **Complete Customer Profiles**: Store detailed contact information including name, email, phone, company
- **Multiple Addresses**: Support for multiple delivery addresses per customer
- **Customer Notes**: Add custom notes and special instructions
- **Status Management**: Active/Inactive customer status tracking
- **CRUD Operations**: Full create, read, update, delete functionality

### 2. Rate Management
- **Flexible Pricing**: Define rates by KG, CBM, or Per Carton
- **Customer-Specific Rates**: Set special negotiated rates for individual customers
- **General Rates**: Default rates applicable to all customers
- **Rate Validity**: Set valid from/to dates for seasonal or promotional pricing
- **Active/Inactive Status**: Enable or disable rates as needed

### 3. Booking Entry & Management
- **Unique CNTR Numbers**: Each booking has a unique container number
- **Complete Shipment Data**: Capture booking date, pickup date, delivery date
- **Location Tracking**: Record pickup and delivery locations
- **Cargo Details**: Weight (KG), Volume (CBM), Carton Count
- **Cargo Description**: Detailed description of cargo contents
- **Pricing**: Calculate and store total amount
- **Status Tracking**: Track shipment through multiple stages
- **Notes**: Add special instructions or remarks

### 4. Shipment Status & Tracking
- **Real-Time Status**: Track shipments through 5 stages:
  - Pending
  - Loaded
  - In Transit
  - Arrived
  - Delivered
- **Location History**: Record location at each status change
- **Timestamp Tracking**: Date/time stamp for each status update
- **Public Tracking**: Allow customers to track by CNTR number
- **Status Remarks**: Add notes for each status change

### 5. Invoice/PDF Report Generation
- **Professional Invoices**: Generate beautifully formatted PDF invoices
- **Complete Information**: Includes all booking, customer, and cargo details
- **Downloadable**: One-click PDF download
- **Print-Ready**: Optimized for printing
- **Branding**: Customizable with company branding

### 6. Operational Analytics Dashboard
- **Key Metrics**:
  - Total Bookings
  - Total Customers
  - Active Shipments
  - Delivered Shipments
- **Visual Analytics**:
  - Status Distribution Chart (Doughnut Chart)
  - Monthly Volume Trends
- **Recent Activity**: View latest bookings at a glance
- **Shipment Volume Reports**: Track CBM/KG shipped by delivery location

## 🎨 UI/UX Features

### Modern Design
- **Gradient Backgrounds**: Beautiful purple-to-indigo gradients
- **Card-Based Layout**: Clean, organized information display
- **Hover Effects**: Smooth transitions and interactive elements
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Professional Color Scheme**: Purple (#667eea) and Indigo (#764ba2) theme

### User Experience
- **Intuitive Navigation**: Sidebar navigation with active state indicators
- **Icon Integration**: Font Awesome icons throughout
- **Form Validation**: Real-time validation with helpful error messages
- **Success Messages**: Clear feedback for user actions
- **Loading States**: Visual feedback during operations
- **Empty States**: Helpful messages when no data exists

### Accessibility
- **Semantic HTML**: Proper HTML5 structure
- **Color Contrast**: WCAG compliant color combinations
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader Friendly**: Proper ARIA labels

## 📁 Project Structure

```
cargo-management-system/
├── app/
│   ├── Http/Controllers/
│   │   ├── BookingController.php
│   │   ├── CustomerController.php
│   │   ├── DashboardController.php
│   │   └── RateController.php
│   └── Models/
│       ├── Booking.php
│       ├── Customer.php
│       ├── Rate.php
│       └── ShipmentTracking.php
├── database/
│   └── migrations/
│       ├── create_customers_table.php
│       ├── create_rates_table.php
│       ├── create_bookings_table.php
│       └── create_shipment_tracking_table.php
├── resources/
│   └── views/
│       ├── layouts/
│       │   └── app.blade.php
│       ├── bookings/
│       │   ├── index.blade.php
│       │   ├── create.blade.php
│       │   ├── edit.blade.php
│       │   ├── show.blade.php
│       │   ├── track.blade.php
│       │   └── pdf.blade.php
│       ├── customers/
│       │   ├── index.blade.php
│       │   ├── create.blade.php
│       │   └── edit.blade.php
│       ├── rates/
│       │   ├── index.blade.php
│       │   ├── create.blade.php
│       │   └── edit.blade.php
│       └── dashboard.blade.php
└── routes/
    └── web.php
```

## 🛠️ Technology Stack

### Backend
- **Framework**: Laravel 11 (Latest)
- **PHP**: 8.2+
- **Database**: MySQL/MariaDB
- **ORM**: Eloquent
- **PDF Generation**: DomPDF (barryvdh/laravel-dompdf)

### Frontend
- **CSS Framework**: Tailwind CSS 3 (via CDN)
- **JavaScript**: Vanilla JS + Alpine.js ready
- **Charts**: Chart.js
- **Icons**: Font Awesome 6
- **Template Engine**: Blade

### Development Tools
- **Package Manager**: Composer
- **Asset Bundler**: Vite
- **Code Style**: Laravel Pint

## 📊 Database Schema

### Customers Table
- id, name, email, phone, company_name
- address, city, state, postal_code, country
- notes, is_active, timestamps

### Rates Table
- id, customer_id (nullable)
- rate_type (KG/CBM/Per Carton)
- base_rate, special_rate
- cargo_type, service_type
- valid_from, valid_to
- is_active, timestamps

### Bookings Table
- id, cntr_no (unique), customer_id
- booking_date, pickup_date, delivery_date
- pickup_location, delivery_location
- cargo_description
- weight_kg, volume_cbm, carton_count
- total_amount, status, notes
- timestamps

### Shipment Tracking Table
- id, booking_id
- status, location, remarks
- status_date, timestamps

## 🔒 Security Features

- **CSRF Protection**: All forms protected
- **SQL Injection Prevention**: Eloquent ORM parameterized queries
- **XSS Protection**: Blade template escaping
- **Input Validation**: Server-side validation on all inputs
- **Mass Assignment Protection**: Fillable properties defined
- **Password Hashing**: Bcrypt (if auth added)

## 📱 Responsive Breakpoints

- **Mobile**: < 768px
- **Tablet**: 768px - 1024px
- **Desktop**: > 1024px

## 🎯 Use Cases

1. **Freight Forwarders**: Manage international cargo shipments
2. **Logistics Companies**: Track domestic deliveries
3. **Shipping Agencies**: Handle customer bookings and invoicing
4. **Warehouse Operations**: Monitor incoming/outgoing cargo
5. **E-commerce Fulfillment**: Track bulk shipments

## 🚀 Quick Start

```bash
# 1. Install dependencies
composer install

# 2. Install PDF library
composer require barryvdh/laravel-dompdf

# 3. Configure environment
cp .env.example .env
php artisan key:generate

# 4. Setup database
# Edit .env with your database credentials
php artisan migrate

# 5. Start server
php artisan serve
```

Visit: http://localhost:8000

## 📈 Future Enhancements (Optional)

- User authentication and roles
- Email notifications for status changes
- SMS tracking updates
- Multi-language support
- API for mobile apps
- Advanced reporting and exports
- Integration with shipping carriers
- Automated rate calculations
- Document management (POD, BOL)
- Payment gateway integration

## 📝 License

This project is open-source and available for commercial use.

## 🤝 Support

For technical support or questions:
- Check the INSTALLATION_GUIDE.md
- Review the README_SETUP.md
- Ensure all dependencies are installed

---

**Built with ❤️ using Laravel & Tailwind CSS**

Version: 1.0.0
Last Updated: 2024
