# UAE Transport Accounting & Operations System

Release: **1.0.0-rc1**  
Stack: **Laravel 13, PHP 8.4, MySQL 8/MariaDB, Blade, local CSS/JavaScript**

This repository is an installable transport-operations and double-entry accounting application for a UAE transport company. It replaces the earlier backend-only foundation with an actual first-run installer, authentication, role-controlled navigation, operational forms, financial posting workflows, reports, branded documents, and deployment configuration.

## Working application modules

### Organisation and security

- First-run browser installer.
- Company, branch, department and cost-centre configuration.
- Users, roles and granular action permissions.
- Branch data isolation and maker-checker approvals.
- Fiscal years, accounting periods, locks and authorised reopening.
- Immutable audit trail and security headers.

### Parties and commercial workflow

- One central party record with customer, vendor, subcontractor and dual-role support.
- Separate customer receivable and vendor payable ledgers.
- Consolidated party exposure and statement views.
- Quotations with versioning, VAT, approval, PDF and conversion to transport jobs.
- Contracts and customer/vendor rate cards.

### Transport operations

- Service types and routes.
- Jobs with customer, contract, PO, dates, locations, service, rates and VAT treatment.
- Multiple trips, vehicles, drivers and vendors.
- Job charges, job costs, margin and profitability.
- Proof-of-delivery private uploads and download permissions.
- Vehicles, drivers, maintenance and fuel records.
- Driver advances, settlement expenses and cash refunds.

### Accounting

- Configurable chart of accounts and UAE-oriented defaults.
- Balanced immutable journals using decimal arithmetic.
- Customer invoices and vendor bills with line items and VAT.
- Receipts and customer-invoice allocations.
- Payments and vendor-bill allocations.
- Expenses with recoverable and non-recoverable VAT.
- Customer/vendor credit and debit notes.
- Authorised receivable/payable contra settlements.
- Manual journal vouchers and reversal journals.
- Bank accounts, statement import and reconciliation.
- Document numbering by branch, type, year and month.

### Documents and reports

- Branded quotation, invoice, vendor bill, receipt, payment, expense and adjustment-note PDFs.
- Dashboard with live operational and accounting totals.
- Trial balance, profit and loss, balance sheet and general ledger.
- Customer and vendor aging.
- VAT sales/purchase working report.
- Job-profitability report and CSV export.

### Integration readiness

- Secured API health endpoint.
- Provider-neutral UAE e-invoicing contract, encrypted configuration and disabled-by-default null provider.
- Queue, scheduler, Supervisor, Nginx, Apache/cPanel and VPS examples.

Provider-specific e-invoice production submission is intentionally not enabled without an accredited provider adapter, valid credentials, sandbox approval and explicit production activation. Optional external AI/OCR, payment, GPS, WhatsApp and bank integrations require the selected provider's API contract and credentials.

## Server requirements

- PHP 8.4+
- BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PDO, PDO MySQL, Tokenizer and XML extensions
- Composer 2
- MySQL 8+ or a compatible MariaDB release
- HTTPS in production
- A web root pointing to `public/`
- A queue worker and one-minute scheduler cron for production operation

## Installation

1. Extract the project outside the public web directory where possible.
2. Run:

```bash
composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate
```

3. Configure the database and `APP_URL` in `.env`.
4. Make `storage` and `bootstrap/cache` writable by the web-server user.
5. Point the domain document root to the project's `public` directory.
6. Open `/install` in the browser and complete company, VAT, branch and administrator setup.
7. Configure the queue worker and scheduler using the files under `deploy/`.
8. Run the complete verification before live use:

```bash
./scripts/verify.sh
```

For full guidance, see `docs/INSTALLATION_GUIDE.md`, `docs/CPANEL_DEPLOYMENT.md`, `docs/VPS_DEPLOYMENT.md`, `docs/ADMINISTRATOR_MANUAL.md`, `docs/ACCOUNTANT_MANUAL.md`, `docs/OPERATIONS_MANUAL.md`, `docs/BACKUP_AND_RESTORE.md` and `docs/PRODUCTION_READINESS_CHECKLIST.md`.

## Development installation

```bash
composer install
cp .env.example .env
php artisan key:generate
# Configure DB_* values, then open /install or run migrations and seeders manually.
npm ci
npm run build
php artisan serve
```

The application layout uses local production assets from `public/assets`; Vite sources are included for continued frontend development.

## Accounting controls

- Posted records cannot be edited or deleted.
- Every posting service validates approval, period, totals, accounts, company and branch.
- Journals must balance before commit.
- Customer receivable and vendor payable never net automatically.
- Contra requires a dedicated authorised document.
- Reports derive from posted journals rather than manually maintained displayed balances.
- VAT treatment is configurable and is not inferred solely from a transport-service name.
- AI and external providers cannot post accounting entries through the supplied core.

## Verification status

The source package passes the included structural verifier, PHP syntax checks, internal class checks, model-to-migration checks, controller/route checks and Blade reference checks. This build environment could not install Composer packages or run MySQL, so the Laravel migration and PHPUnit runtime suite must be executed on the deployment server before production use. See `BUILD_REPORT.md`.
