Skip to content

Book 5 — Fleet & Logistics (Index)

Bizwiz Guide · Book 5 of 7 · Review instrument How the distributor's trucks, the fuel that moves them, the tyres they run on, the workshops that service them, and the inbound goods they collect are all tracked, controlled, and turned into accounting entries.

If Books 1–3 move value (sell, stock, buy) and Book 4 is the book-of-record, Book 5 is the physical fleet that does the moving — plus three purpose-built spend verticals (fuel, tyres, service) that each hand off into the same AP/GL spine, and the telematics layer that watches every vehicle. Read it as: one App\Vehicle master feeds five satellites (fuel, tyres, service, compliance, logistics), each satellite is largely self-contained, and each touches the shared financial ledgers at exactly one guarded seam.

# Chapter One-line scope
18 Vehicles & Tracking The App\Vehicle master, cab↔trailer pairing, tracking-device/SIM catalogue, immobilisation, vehicle assets & expense/mileage reports — the operational source of the Fixed-Asset Vehicle
19 Fuel Management Fuel suppliers/stations, the LPO lifecycle, statement upload/verification/reconciliation, and fuel invoices that settle as payable_type='fuel'
20 Tyre Management A full parallel sub-ERP — tyre procurement→inventory→operations→driver-workflow→retreading, converging on AP/GL only at invoice time
21 Vehicle Service & Route Compliance Workshop service records + the telematics compliance layer (corridor deviation, geomapping, idle geofencing, immobilisation)
22 Logistics & Inbound Deliveries Inbound deliveries → offloading → GRN gate, small-pack dispatch, inspection routines, and the Device Center repair/SIM lifecycle

The fleet-and-money flow

flowchart TD
    subgraph FLEET[Book 5 — Fleet & Logistics]
      V[(App\Vehicle master · Ch18<br/>plate/VIN unique · cab↔trailer<br/>tracking device + SIM · garage/offline state)]
      FUEL[Fuel · Ch19<br/>LPO → statement → verify → invoice]
      TYRE[Tyre sub-ERP · Ch20<br/>PO → receipt → fit → retread → dispose]
      SVC[Service · Ch21<br/>request → record → complete]
      COMP[Route Compliance · Ch21<br/>corridor / geomap / idle geofence]
      LOG[Inbound Logistics · Ch22<br/>delivery → offload]
    end
    V --> FUEL & TYRE & SVC & COMP & LOG
    FUEL -->|WaSuppTran + 3 GL legs<br/>PaymentVoucherItem payable_type='fuel'| SPINE
    TYRE -->|WaSuppTran + Dr TyreAsset/Dr VAT/Cr Creditors| SPINE
    SVC -->|petty-cash LPO · vehicle_service_record_id<br/>→ VehicleCost| PC[Petty Cash · Book 4 Ch17]
    PC --> SPINE
    COMP -->|engine-cut command via SIM channel| V
    LOG -->|offloading_end_time gate<br/>inbound_deliveries.document_id| GRN[GRN · Book 2 Ch9]
    GRN --> SPINE
    FA[Fixed Assets · Book 4 Ch16] -.assetable_type='App\Vehicle'<br/>plate→name, vin→serial.-> V
    SPINE[(wa_supp_trans + wa_gl_trans<br/>shared AP / GL spine · Books 3–4)]

The one-sentence version: every fleet satellite reads the same App\Vehicle, and each pushes money out through the same wa_supp_trans + wa_gl_trans spine — fuel and tyres as direct supplier invoices, service via a petty-cash LPO — while Fixed Assets (Book 4) pulls the vehicle into the balance sheet and the telematics layer pushes control (engine-cut) back down onto the vehicle.

Cross-chapter & cross-book seams

Within Book 5 (everything hangs off the vehicle): - Ch18 is the hub. App\Vehicle exposes the relations the other four chapters consume: fuelEntries()/latestFuelEntry() (Ch19), currentTyreFits()/tyreMovements()/VehicleAxleTyreMapping (Ch20), serviceRecords()/serviceIntervals() (Ch21), scopeAvailableForGrnSelection()/inspections (Ch22). Vehicle state is derived (booleans + telemetry freshness + garage_status + switch_off_status), not a single status column. - Ch21 → Ch18 (control loop): route-compliance and geofencing don't just observe — on a dwell/gate-pass/idle violation they issue a real engine-cut through the vehicle's SIM/immobiliser channel (Vehicle::activateImmobilizer()), logged to vehicle_immobilizations, guarded by RouteComplianceImmobilisationLockService. - Ch22 ↔ Ch18 (device disambiguation): two different "device" models — Ch18's TrackingDevice/tracking_devices (GPS master + on/off commands, assigned to a vehicle) versus Ch22's Device/devices (portable-hardware repair + SIM lifecycle). Same word, different tables. Worth calling out to reviewers.

To other books — Book 5 is a major money-OUT feeder, via THREE distinct guarded seams into the shared spine: - Ch19 → Book 3/4 (fuel invoice): FuelInvoiceController@store writes one WaSuppTran + three WaGlTran legs (Cr creditors / Dr fuel-expense / Dr VAT input) keyed on invoice_number, then settles through a PaymentVoucherItem with payable_type = 'fuel' — i.e. fuel is one more payable type on Book 3 Ch13's shared voucher engine. Code-proven. - Ch20 → Book 3/4 (tyre invoice): TyreSupplierInvoiceController::postGLEntries creates a shared WaSuppTran and posts Dr Tyre-Asset / Dr VAT-Input / Cr Creditors-Control; it throws if those GL accounts aren't configured in Company Preferences — a guarded, not silent, seam. This is the only point where the otherwise self-contained tyre sub-ERP touches the main ledgers. - Ch21 → Book 4 Ch17 (service cost): service-record costs settle via a petty-cash LPO carrying vehicle_service_record_id, which posts VehicleCost lines (reference_type='petty_cash_lpo') — routing workshop spend through the Book 4 petty-cash engine rather than direct AP. - Ch22 → Book 2 Ch9 (GRN): an inbound delivery is the physical precursor to receiving; inbound_deliveries.document_id → wa_purchase_orders.id, and under ENFORCE_DELIVERY_OFFLOADING_FOR_INBOUND_DELIVERIES the GRN receive is blocked (422) until the delivery has an offloading_end_time. Physical-half → inventory-half handoff. - ← Book 4 Ch16 (Fixed Assets, the inbound seam): FixedAsset::assetable() is a morphTo over App\Enums\FixedAssetLinkableModel, which has three cases — Vehicle, Device, PropertyUnit — but only Vehicle is fully wired: only it has a populated fieldMap() (name ← license_plate_number, serial_no ← vin); Device and PropertyUnit are empty TODOs. So Ch18 is the operational source of the one fixed-asset type that actually onboards today. Caveat (open): the seam is proven from the FixedAsset side only; whether Vehicle declares the inverse morph was not found.

Two look-alikes that are NOT the same thing (flag for reviewers)

  1. Fixed-Asset depreciation vs. fleet Amortization Schedules. vehicle_asset_amortizations / VehicleAssetAmortization (Ch18 nav → "Assets") belongs directly to a Vehicle and has no assetable relation — it is a separate, vehicle-scoped depreciation system that is not the Book 4 fixed-asset link. A vehicle can therefore be depreciated in two unrelated places. Which one is authoritative per tenant is a standing question.
  2. Tracking devices vs. Device Center devices — see the Ch22↔Ch18 disambiguation above (tracking_devices vs devices).

Consolidated open questions (the review agenda)

Grouped from each chapter's §7. CODE-PROVEN items are asserted in the chapters; the below need human/dev confirmation.

Configuration / "which is live per client": - ENFORCE_DELIVERY_OFFLOADING_FOR_INBOUND_DELIVERIES (Ch22), verify_fuel_entries per station (Ch19), VEHICLE_COST_CATEGORIES_SHOWN_ON_MOBILE (Ch21), route-compliance per-route toggles (alerts_on_violations, immobilisation_on_violations, tolerances) — all tenant/branch-gated; which distributor runs which is unknown. - GL account configuration — tyre postings require tyreAssetGlAccount, VAT-input and Creditors-Control to be set (throws otherwise); fuel uses fuelExpenseGlAccount. Whether these are seeded per tenant is unconfirmed. - Threshold defaults are migration/model defaults, not confirmed live values: corridor 100 m buffer, idle-branch 500 m radius, travel-delay 15 min / dwell 10 min tolerances, service "almost-due" 1000 km band.

Ownership / architecture boundaries: - Who runs the compliance evaluators. No scheduler/worker was read — a background telematics-ingest job is inferred from the pending_immobilizations queue table and backfill-delay-baselines. Confirm the cron/queue that actually detects violations and issues cuts. - Does driver comp post automatically? Approved driver_tyre_incentives / driver_tyre_mismatch_charges (Ch20) flip an incentive_status, but no code was found posting them to payroll or the ledger — confirm manual vs automated. - Vehicle inverse morph (Ch18) — is the Fixed-Asset link ever read from the Vehicle side, or only from FixedAsset? - GRN auto-creation (Ch22) — completing offloading gates the GRN; it was not observed to auto-create one. Confirm whether receive is still manual. - Legacy coexistence — tyre Admin/* legacy controllers, inbound_delivery_penalty_bands vs inbound_delivery_processing_penalties, route_change_requests vs inbound_delivery_route_changes, two fuel_statements create migrations — in each case both exist; which is live is unconfirmed.

Data-integrity quirks / naming to verify: - Verbatim class typo: VehicleCommandContoller (Ch18/Ch21). - Nav bug: fleet "Approved" fuel item is guarded by pending-fuel-lpos___view and links to fuel-lpos.pending with model string 'Approved-fuel-lpos' (Ch19). - Status lives off the header: fuel lifecycle status is on the entry row (entry_status), not fuel_lpos; confirmLpo sets Processed (no Confirmed enum case exists).

Recurring Bizwiz patterns reinforced by Book 5

  • One master, many satellites — App\Vehicle is to Fleet what wa_gl_trans is to Finance and the voucher engine is to AP: a single durable spine that every satellite reads. The now-familiar Bizwiz shape.
  • Parallel purpose-built verticals — the tyre sub-ERP re-implements procurement + inventory (tyre_* tables) rather than configuring Books 2/3, converging on the shared ledgers only at invoice time. "Purpose-built vertical, not a configuration of the general modules." Fuel is a lighter version of the same idea.
  • Approval queues everywhere — tyre driver-workflow (request→verify→mismatch-verify→approve→fitting→incentive-approve), fuel LPO (pending→verified→approved), service (approved→in_progress→completed), inbound-delivery stages. Another dense "approvers not curators" surface with rich maker-checker audit data.
  • Real external integrations & control loops — this book adds telematics/GPS + modem immobilisation (Flespi trackers, setparam/switch-off commands over the SIM channel) and OSRM road-distance enrichment to the M-Pesa / Equity-H2H / Supplier-Portal dependencies already found. Bizwiz doesn't just record the fleet, it controls it.
  • The strongest "better algorithms" AI surface found so far — the Ch21 compliance layer is explicitly flagged (as opportunity, not current behaviour): learned multi-day delay baselines, time-of-day/traffic-aware dynamic corridor buffers, per-driver/route re-violation likelihood scoring, immobilisation risk-scoring vs today's binary threshold, and predictive "due-for-service" forecasting from mileage trends. Plus fuel-consumption anomaly detection (driver_fuel_penalties) and tyre design-life/incentive modelling. Carry these into the AI-leverage phase.

Book 5 complete: 5 chapters (18–22) + this index, from static analysis of the bizwiz monolith. Verified on disk (2,822 / 2,406 / 3,471 / 2,962 / 2,854 words; all 8 template sections each). Next in the fan-out: Book 6 — HR & Payroll (Employees & Payroll, Benefits & Deductions, Leave & Attendance, Sacco). Then Book 7 — Platform & Admin, the Manufacturing/Laboratory placeholders, and the cross-module handoff map.