Vehicles Module

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/(app)/vehicles/page.tsx
• src/lib/actions/vehicles.ts
• src/app/(app)/vehicles/[id]/page.tsx
• src/components/VehicleListClient.tsx
• ios-shell/www/app.js
• src/lib/chat/tools.ts
• e2e/specs/21-vehicles-module.spec.ts
• CLAUDE.md

The Vehicles module tracks household automotive assets, maintenance records, and regulatory compliance. It provides tools to manage vehicle specifications, service history, registration (rego) expiry, and insurance renewals. Users utilize this module to centralize vehicle-related documentation and receive automated reminders for upcoming service or expiration dates.

The module is an opt-in feature within the Hearth platform. You must enable it via the Household settings before accessing vehicle records or adding new data. It integrates with the core notification and document management systems to provide a comprehensive ownership history for every vehicle in a household.

Sources: CLAUDE.md:61-65, PRODUCT.md:14-19, src/app/(app)/vehicles/page.tsx:18

Data Architecture

The module uses two primary data entities: Vehicle and VehicleItem. A Vehicle represents the physical asset, while a VehicleItem represents a specific event in that vehicle's lifecycle, such as a service, repair, or purchase.

Vehicle Entity

The Vehicle entity stores primary identification and compliance dates. It tracks registration and insurance expiry to drive the household's reminder system.

Field	Type	Description
label	String	A descriptive name for the vehicle.
make	String	The manufacturer of the vehicle.
model	String	The specific model name.
year	Integer	The manufacturing year.
licensePlate	String	The registration plate number.
vin	String	Vehicle Identification Number.
regoExpiry	DateTime	Date when the registration expires.
insuranceExpiry	DateTime	Date when insurance coverage ends.
nextServiceDue	DateTime	Date for the next scheduled maintenance.

Sources: src/app/(app)/vehicles/[id]/page.tsx:94-110, ios-shell/www/app.js:106-123

Vehicle Item (Service Records)

Service records track maintenance activities and costs. Every item can have multiple associated documents, such as invoices or inspection certificates.

Field	Type	Description
type	Enum	The category: SERVICE, REPAIR, ROADWORTHY, MODIFICATION, PURCHASE, or OTHER.
title	String	A summary of the work performed.
provider	String	The mechanic or service center.
date	DateTime	When the service or event occurred.
cost	Float	The monetary amount spent.
currency	String	The currency used for the transaction.

Sources: src/app/(app)/vehicles/[id]/page.tsx:173-205, ios-shell/www/app.js:124-138

Core Workflows

The Vehicles module follows a standard lifecycle of creation, maintenance, and eventual disposal (soft-deletion).

Management Flow

The following diagram illustrates how users interact with vehicle records and service items.

The system validates inputs via Zod schemas and processes changes through Server Actions.
Sources: src/lib/actions/vehicles.ts:54-184, CLAUDE.md:74-81

Service Record Processing

When adding a service record, the system optionally processes an attached file.

1. Authentication: The requireUser() function verifies the session and confirms the module is enabled.
2. Validation: vehicleItemSchema validates the form data.
3. Command Execution: createServiceRecordCommand writes the record to the database.
4. Document Attachment: If a file is provided, addDocumentCommand saves the file and links it to the new VehicleItem.
5. Revalidation: The application redirects to the vehicle detail page, triggering a data refresh.

Sources: src/lib/actions/vehicles.ts:133-162

Reminders and Health

The module calculates the "health" of a vehicle based on its compliance dates. It surfaces these as alerts on the Dashboard and the Vehicle Detail page.

Reminder Thresholds

Users define thresholds (e.g., "30,14,7,1") representing days before an expiry date when the system should send notifications. These thresholds apply to:

• Registration Expiry
• Insurance Expiry
• Next Service Due Date

Sources: src/app/(app)/vehicles/[id]/page.tsx:55-58, ios-shell/www/app.js:636-654

Health Calculation Logic

The health status is computed in real-time. On the dashboard, vehicles with Danger or Warning status appear in the "Needs Attention" queue.
Sources: ios-shell/www/app.js:672-687, src/app/(app)/dashboard/page.tsx:117-133

Technical Implementation

Server Actions

The module relies on Server Actions for data mutations, ensuring authorization and validation are enforced on the server.

Action	Purpose
createVehicle	Validates and saves a new vehicle record.
updateVehicle	Updates an existing vehicle with fullFormUpdate.
deleteVehicle	Moves a vehicle to the Trash (soft-delete).
addVehicleItem	Creates a service record and handles file uploads.
deleteVehicleItem	Moves a service record to the Trash.

Sources: src/lib/actions/vehicles.ts:54-173

LLM Tool Integration

The module provides read-only tools for AI assistants to query vehicle data. The list_vehicles tool allows an LLM to retrieve vehicle lists, optionally filtering for those needing attention.

const listVehiclesTool = defineTool({
  name: "list_vehicles",
  description: "List vehicles with registration/insurance expiry...",
  moduleKey: "VEHICLES",
  schema: z.object({ attentionOnly: z.boolean().optional() }),
  run: async ({ attentionOnly }) => queryVehicles(attentionOnly),
});

Sources: src/lib/chat/tools.ts:167-183

Mobile Shell Support

In the mobile shell (standalone mode), the Vehicles module operates using a local encrypted SQLite database. It mirrors the web application's logic for data entry and reminder calculation but stores data locally on the device.

• Database Schema: Creates vehicles and vehicle_items tables locally.
• Local Notifications: Uses LocalNotifications plugin to schedule device-native alerts instead of server-side SMTP/ntfy.
• Module Toggling: Managed via Preferences on the device, allowing users to hide the Vehicles UI if not needed.

Sources: ios-shell/www/app.js:106-138, ios-shell/www/app.js:847-862

Summary

The Vehicles module provides a structured environment for managing automotive records. By combining asset tracking with service history and an automated reminder system, it ensures that household vehicle maintenance and compliance tasks remain visible. Its architecture supports both a multi-user server environment and a privacy-focused mobile standalone mode.