MokoSuiteAuto/CLAUDE.md

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

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
• 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