# FleetLume UI v6 Dark Control Center

This package includes the complete FleetLume portal with the approved premium dark interface, a fixed sticky desktop sidebar, colorful module icons, responsive inner pages, a mobile navigation drawer, and the existing operational, accounting, compliance, GPS, HOS, fuel, reefer, border, and AI functionality.

See `RELEASE_NOTES_UI_V6.md` and `UI_SYSTEM_V6.md` for the design and responsive behavior.

# FleetLume Operations Platform

A complete daily-use platform for dispatch operations, drivers, fleet management, border crossings, documents, accounting, and reporting.

## Portals and Access

The administrator can create an individual account for every team member and assign one of these portals:

- Owner / Administrator
- Dispatcher
- Driver
- Accountant
- Maintenance team
- General team member

Custom permissions can be added to individual accounts from **Users & Portals**.

## Operations Features

- Executive dashboard with urgent operational and financial alerts
- Driver, truck, trailer, broker, customer, vendor, and customs broker records
- Load management with multiple pickup and delivery stops
- Dispatch board and monthly pickup/delivery calendar
- Driver, truck, and trailer availability
- Team tasks with priorities, due dates, and status tracking
- Global search across loads, invoices, drivers, equipment, border crossings, and documents
- Notification center for driver, expense, and border updates
- Full activity history for important actions

## Driver Mobile Portal

- Assigned and upcoming loads
- Pickup and delivery stop workflow
- Start and stop live trip tracking
- Manual and automatic location updates
- Load status updates
- Stop completion with GPS position
- Mobile camera uploads for:
  - Load photos
  - Stop photos
  - BOL and POD
  - Rate confirmations
  - Seal photos
  - Inspection documents
  - Challans and tickets
  - Accident and damage photos
  - Fuel, toll, scale, lumper, and parking receipts
- Expense and reimbursement submissions
- Settlement history and downloadable settlement PDFs
- Border crossing workflow and document checklist

## Live GPS and Dispatcher Map

- Driver consent-based tracking session
- Location updates at a configurable interval
- Latitude, longitude, accuracy, speed, heading, and battery level where the device provides them
- Current location and location history connected to the load
- Dispatcher live map with driver, truck, trailer, load, and last-update information
- Online, stopped, and stale-location visibility
- Border geofence support to detect when a driver is approaching or arriving at a configured crossing

Browser tracking works while the driver portal remains open and the device allows location access. Mobile operating systems may pause browser tracking after the screen is locked or the browser is closed.

## Border Crossing Management

- International load crossing records
- Port, country, direction, crossing time, broker, references, seal, commodity, weight, and package details
- Configurable border statuses
- Required document checklist with review and approval
- Driver border workflow
- Border photo, document, inspection, receipt, seal, and challan uploads
- Holds, inspection issues, references, authority details, costs, and resolution notes
- Queue, inspection, clearance, and crossing timestamps
- Waiting time, detention minutes, rate, and calculated detention amount
- GPS geofence events and dispatcher alerts
- Branded border packet PDF
- Border expense connection to load profitability

## Accounting Features

- Customer invoices and invoice line items
- Professional branded invoice preview and PDF
- Taxes, discounts, deductions, due dates, terms, notes, and payment instructions
- Partial and full customer payments
- Branded payment receipt PDFs and customer statement PDFs
- Receivable aging report
- Driver settlements and branded settlement PDFs
- Driver, load, truck, trailer, border, and vendor expenses
- Receipt and challan attachments
- Expense submission, review, approval, rejection, reimbursement, and posting
- Vendors and vendor bills
- Partial and full vendor bill payments
- Bank, cash, credit card, and fuel card accounts
- Transactions and reconciliation status
- Factoring submissions, advances, fees, reserves, releases, and chargebacks
- Chart of accounts
- Manual and automatic journal entries
- General ledger
- Trial balance
- Balance sheet account report
- Cash activity report
- Profit and loss report
- Load profitability with revenue, driver pay, expenses, and net profit
- Accounting audit protection for posted invoices and settlements

## Documents and Fleet

- Central document center
- Driver, truck, trailer, broker, load, stop, invoice, border, expense, and vendor bill attachments
- Document expiry dates and alerts
- Truck and trailer maintenance history
- Service dates, next-service reminders, mileage, status, cost, and notes
- License, medical card, registration, insurance, and inspection expiry tracking

## Branding and PDFs

Company settings support:

- Company name and logo
- Address, phone, and email
- MC and DOT numbers
- Currency symbol
- Invoice payment instructions
- Invoice terms and footer
- GPS update interval

Invoice, settlement, and border packet PDFs use a fixed professional print layout and include the uploaded company logo when the server supports the uploaded image format.


## Local testing before deployment

The application is not restricted to `fleetlume.space`. It can run on localhost, a staging domain, or the live domain.

### XAMPP / WAMP / Laragon

1. Extract the project into your web root, for example `htdocs/fleetlume`.
2. Open `http://localhost/fleetlume/install.php`.
3. Use:
   - Site URL: `http://localhost`
   - Base URL: `/fleetlume/public`
   - Environment: `Local`
   - Debug mode: enabled
   - Database host: `127.0.0.1`
   - Database port: `3306`
4. Complete the installer and open `http://localhost/fleetlume/public/login`.

### PHP built-in server

From the project folder run:

```bash
php -S localhost:8000 -t public
```

Use `http://localhost:8000` as the Site URL and leave Base URL blank. The database must still be created through the installer or configured manually.

### Moving from local to live

On live hosting, run `install.php?unlock=1` and change:

- Site URL to `https://fleetlume.space`
- Base URL to blank when the domain points to the public application, or to the correct subfolder path
- Environment to `Production`
- Debug mode to disabled
- Database credentials to the live database

The installer updates configuration without intentionally deleting existing records. Always back up the database before upgrading.

## Installation

1. Upload the project folder to your server.
2. Open:

```text
https://your-domain.com/your-folder/install.php
```

3. Enter the application URL, database details, and administrator account details.
4. Click **Install System**.
5. Open the generated login URL.

For common shared hosting setups, the database host is usually `localhost` and the port is commonly `3306`. Enter the database host only, not a website or hosting-panel URL.

Recommended Base URL when the project is in a subfolder:

```text
/your-folder/public
```

When the domain document root points directly to the `public` folder, the Base URL can be blank.

## Updating an Existing Installation

1. Back up the current files and database.
2. Upload and replace the project files.
3. Open:

```text
https://your-domain.com/your-folder/install.php?unlock=1
```

4. Enter the same database details and run setup again.

The updater creates the new tables and adds missing columns without intentionally deleting existing records.

## Security and Production

- Keep `storage/installed.lock` in place after installation.
- Remove or restrict access to `install.php` after setup when possible.
- Use HTTPS, especially for login, GPS, and camera uploads.
- Point the domain document root to the `public` folder when hosting allows it.
- Make regular database and upload-folder backups.
- Give users only the permissions required for their work.


## Compact Navigation and Fuel Allocation Update

This package includes a redesigned collapsible sidebar and a complete fuel allocation workflow. Dispatchers and accountants can calculate an allowance from route miles, target MPG, expected fuel price, and a reserve percentage; issue it by fuel card, cash advance, company card, or reimbursement limit; and reconcile driver fuel purchases and receipts. Approved fuel purchases automatically create accounting expenses. Drivers can view their available balance and submit fuel receipts from mobile devices.

## Driver Logbooks and Hours of Service

This release adds a mobile driver logbook and HOS workspace for United States, Canadian, and cross-border operations.

- Driver HOS profiles with home terminal, time zone, log-day start, operating region, and cycle settings
- United States property-carrying clocks with 60/7 and 70/8 cycle options
- Canada south-of-60 and north-of-60 clocks with Cycle 1 and Cycle 2 options
- Duty-status changes with location, GPS, odometer, engine hours, load, truck, and trailer references
- Personal Conveyance and Yard Move statuses
- Daily graph, totals, declarations, notes, certification, and recertification
- Correction-request workflow that retains the original event
- Dispatcher HOS board and roadside inspection view
- Current-day PDF and recent-day history
- Responsive driver controls for phones and tablets

FleetLume provides an operational logbook and clock-assistance workflow. It is not represented as a registered United States ELD or a third-party-certified Canadian ELD. See `HOS_COMPLIANCE_NOTES.md` before production use.


## FleetLume AI setup

The package includes a server-side Gemini integration with:

- Read-only operations assistant
- Customer and broker update drafting
- Operational risk summaries
- Transportation document extraction from PDF/JPG/PNG/WebP
- Fuel allowance review
- HOS operational summaries with mandatory human review
- Per-user hourly request limits and usage metadata

After running the installer, sign in as an owner or administrator and open **FleetLume AI**. Enter the Gemini API key, choose a supported model, enable the module, and run **Test Connection**. The key is stored in `config/gemini.php`; it is not stored in the database or sent to browsers.

The server requires the PHP cURL and fileinfo extensions and outbound HTTPS access to `generativelanguage.googleapis.com`.

AI output never posts accounting entries, approves payments, dispatches loads, certifies HOS records, or changes operational data. Human review is required.

## UI v3 and FleetLume Autopilot

This release introduces a new responsive workspace across desktop, tablet, and mobile:

- Compact collapsible desktop navigation
- Touch-friendly mobile drawer and bottom shortcut dock
- Global command/search palette with `Ctrl/Command + K`
- Responsive data tables that convert to labeled mobile cards
- Responsive forms, dashboards, dispatch boards, calendars, HOS screens, accounting pages, and AI tools
- New visual design system for cards, controls, status badges, alerts, and approval workflows
- Refreshed sign-in experience

FleetLume Autopilot adds auditable operational automation:

- Scheduled scans for late/stalled loads, missing POD/BOL, reefer temperature exceptions, fuel overages, HOS review items, border delays, overdue invoices, and carrier compliance expiries
- Gemini-assisted prioritization and action drafting when AI is enabled
- Safe automatic actions limited to notifications and team-task creation
- Approval queue for message drafts and future higher-impact actions
- AI change feed showing exactly what automation changed
- Owner/admin notifications after every completed AI action
- Run history, failure visibility, duplicate suppression, role targets, and per-rule frequency

To run scheduled automations on shared hosting, configure a cron job similar to:

```bash
php /full/path/to/fleetlume/automation_runner.php
```

Hourly is recommended. Rules configured as daily or every four hours are automatically skipped until due. The runner is CLI-only and cannot be opened from the browser.

FleetLume does not allow AI to automatically approve payments, post or reverse accounting entries, change load assignments, certify HOS logs, clear borders, or make safety-critical decisions.
