# MokoSuiteAuto

Auto dealership management for Joomla 6 — VIN inventory, sales deals, F&I, trade-ins, test drives, financing, service department.

## Quick Reference

| Field | Value |
|---|---|
| **Package** | `pkg_mokosuiteauto` |
| **Layer** | 4 (requires: Client → CRM → ERP → POS) |
| **Language** | PHP 8.3+ |
| **Branch** | develop on `dev`, merge to `main` (protected) |
| **Wiki** | [MokoSuiteAuto Wiki](https://git.mokoconsulting.tech/MokoConsulting/MokoSuiteAuto/wiki) |

## Architecture

Joomla **package** (`pkg_mokosuiteauto`) — Layer 4 add-on extending MokoSuitePOS.

### Dependencies
- MokoSuiteClient (Layer 0) — base platform
- MokoSuiteCRM (Layer 1) — contacts, deals, invoicing
- MokoSuiteERP (Layer 2) — inventory, accounting
- MokoSuitePOS (Layer 3) — transactions, cash register

### Helpers (6)
- `VehicleHelper` — inventory filters, VIN lookup, dashboard, aging report
- `DealHelper` — deal creation, gross profit (front+back), sales dashboard
- `TradeInHelper` — appraisal, equity calculation, pending review
- `TestDriveHelper` — scheduling, mileage check-out/in, vehicle history
- `FinancingHelper` — loan calculator, term comparison, deal desking
- `ServiceDeptHelper` — repair orders, VIN history, service dashboard

### Key Patterns
- VIN format: `[A-HJ-NPR-Z0-9]{17}` (post-1981, excludes I/O/Q per NHTSA)
- Gross profit: `Front = Sale - Invoice - Recon - Trade` / `Back = SUM(F&I profits)`
- Negative trade equity rolls into financed amount
- Deal workflow: `prospect → negotiating → pending_finance → approved → delivered → unwound`

## Source Directory

- `source/pkg_mokosuiteauto.xml` — package manifest
- `source/packages/` — sub-extensions

## Rules

- **Never commit** `.claude/`, `.mcp.json`, `TODO.md`, `*.min.css`/`*.min.js`
- **Attribution**: `Authored-by: Moko Consulting`
- **Workflow directory**: `.mokogitea/`
- **Wiki**: documentation lives in the Gitea wiki, not `docs/` files
- **Standards**: [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoCLI/wiki)
- **Changelog**: `[Unreleased]` only — release system assigns versions
- **No upstream references**: never reference competitor products

## Coding Standards

- PHP 8.3+ / Joomla 6 patterns
- `$this->getDatabase()` in models, `Factory::getContainer()->get(DatabaseInterface::class)` in helpers
- `Factory::getApplication()->getIdentity()` for user
- `FOR UPDATE` inside transactions for race-condition-prone operations