# Architecture & Production Hardening

## Key boundaries
1. **Vehicle ownership vs. operation:** `vehicles` is Carzz fleet inventory. `vehicle_ownerships` records actual ownership. `vehicle_lease_agreements` and `vehicle_lease_items` record Carzz supplier rentals.
2. **Contract vs. trip:** Corporate contracts set commercial terms; bookings request services; dispatch assigns vehicles; trips record actual execution.
3. **Revenue vs. cost:** Retail/corporate invoices and receipts are distinct from supplier bills/payments. Profitability joins revenue and cost by vehicle/period.
4. **Corporate monthly cycle:** Completed billable trips/retainers become `billable_charges`; each charge may be invoiced once through unique `invoice_charge_allocations.billable_charge_id`.
5. **Pricing:** Pricing plans, rate conditions, route fares, and contract rates support effective dates. Snapshot quoted pricing at booking and trip charge creation.

## Before production launch (must implement)
- Transactional availability locks with half-open intervals `[start,end)`; account for holds, trips, maintenance, dedicated contracts, and supplier lease expiry. MySQL lacks native exclusion constraints.
- Enforce `customer_type` and correct customer account FK; validate retail/corporate booking policy and payment status transitions.
- Enforce non-overlapping supplier lease periods, vehicle ownership history, contract rate versions, driver assignments and dedicated fleet allocations.
- Add composite indexes after real workload review: `(vehicle_id,start_at,end_at)` for blocks; `(vehicle_id,starts_at,ends_at)` for holds; `(corporate_account_id,period_start,period_end)` for billing cycles.
- Enforce amounts >= 0, invoice debit/credit balancing, valid trip odometer ordering, chronological dates and nonnegative credit availability.
- Do not treat `payments` as successful until verified by payment gateway callbacks; make gateway callbacks idempotent.
- Protect NID, license, supplier banking details and transaction payloads; encrypt at rest where necessary, redact logs, restrict access, store document files privately.
- Support refundable security deposits in separate liability ledger before enabling live supplier contracts.
- Build tax/VAT configuration and invoice numbering to match actual local legal requirements.
- Reconcile `roles` tables with chosen permission package; avoid duplicate vendor migrations.
- Add `deleted_at` only to approved master entities; never soft-delete or overwrite financial ledger history.
- Implement automated tests for monthly lease accrual, invoice generation, duplicate invoicing, contract amendments, credit limits, partial payments, cancellations and concurrency.
- Review status enums and exact accounting policy with stakeholders before production deployment; status fields are strings intentionally to allow configurable workflows.

## Relationship diagram
Open `ERD.mmd`. It is a comprehensive logical FK graph and may be visually dense; filter by module for daily development.