MokoSuiteLogistics/README.md

<!--
 Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 SPDX-License-Identifier: GPL-3.0-or-later
-->

# MokoSuite Logistics

Delivery management, route optimization, courier dispatch, and proof of delivery for MokoSuite on Joomla 6.

## Overview

MokoSuiteLogistics is a **Layer 2** extension in the MokoSuite platform, building on MokoSuiteClient (Layer 0) and MokoSuiteCRM (Layer 1) to provide complete logistics and delivery operations management. Customers and drivers are CRM contacts -- no duplicate user tables.

## Package Contents

| Extension | Type | Description |
|---|---|---|
| `plg_system_mokosuitelogistics` | System Plugin | Core helpers, SQL schema, service classes |
| `com_mokosuitelogistics` | Component | Admin dashboard, list views, configuration |
| `plg_webservices_mokosuitelogistics` | Webservices Plugin | REST API endpoints |

## Features

- **Order Management** -- standard, express, same-day, scheduled, and bulk delivery types with full status lifecycle
- **Delivery Tracking** -- real-time delivery status with attempt tracking and failure reasons
- **Route Optimization** -- planned routes with sequenced stops, distance tracking, and completion status
- **Warehouse Management** -- multiple warehouse locations with manager assignments
- **Driver Management** -- CRM contact-linked profiles, vehicle descriptions, rating aggregation
- **Pricing Rules** -- configurable per order type with base fees, per-km/kg rates, express multipliers
- **Proof of Delivery** -- signature capture, photo proof, geolocation verification
- **REST API** -- full CRUD for orders, deliveries, routes, warehouses, pricing rules, drivers, and proofs

## Database Schema

8 tables covering the full logistics domain:

| Table | Purpose |
|---|---|
| `#__mokosuitelogistics_orders` | Order lifecycle with customer, address, package, payment details |
| `#__mokosuitelogistics_deliveries` | Delivery assignments with driver, route, timestamps, attempts |
| `#__mokosuitelogistics_routes` | Planned delivery routes with distance and stop counts |
| `#__mokosuitelogistics_route_stops` | Sequenced stops within routes with arrival tracking |
| `#__mokosuitelogistics_delivery_proofs` | Signature, photo, and geolocation proof of delivery |
| `#__mokosuitelogistics_pricing_rules` | Fee structures per order type |
| `#__mokosuitelogistics_drivers` | Driver profiles linked to CRM contacts |
| `#__mokosuitelogistics_warehouses` | Warehouse locations with manager contacts |

## Order Status Flow

```
pending --> confirmed --> assigned --> picked_up --> in_transit --> delivered
   |            |            |            |              |
   +--> cancelled +--> cancelled +--> failed    +--> failed     +--> failed
                                                                     |
                                                                     +--> returned
```

## Requirements

- Joomla 6.x
- PHP 8.3+
- MokoSuiteClient (Layer 0)
- MokoSuiteCRM (Layer 1)

## Installation

Install via Joomla Extension Manager using the package file `pkg_mokosuitelogistics.zip`. The package installs all three extensions (system plugin, component, webservices plugin) in the correct order.

Updates are delivered automatically via the [MokoGitea update server](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteLogistics/updates.xml).

## Configuration

Settings are managed via the system plugin parameters:

| Fieldset | Key Settings |
|---|---|
| **Basic** | Company name, default currency, timezone, distance unit |
| **Delivery** | Max delivery radius, default time window, auto-assign |
| **Pricing** | Base delivery fee, per-distance rate, express multiplier, minimum charge |
| **Notifications** | Order confirmation, dispatch notification, delivery proof |

## License

GNU General Public License v3.0 or later.

## Links

- [Documentation](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteLogistics/wiki)
- [Issues](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteLogistics/issues)
- [MokoSuite Platform](https://mokoconsulting.tech)