Vehicle Service Log

Every vehicle in your fleet has a Service Log — a chronological audit trail of everything operational that happened to it. Maintenance, damage, out-of-service events, inspections.

Where to find it

/dashboard/vehicles/[id] → scroll to Service Log section.

The section appears under the live status card and above the debug logging section.

Event types

The categories drive color-coding in the UI but don't trigger downstream behavior — they're for clarity, not enforcement.

Adding an event

1. On the vehicle detail page, click + Log event in the Service Log section header
2. Pick the event type from the dropdown
3. Enter a description (required)
4. Optional: cost in dollars (parts + labor)
5. Submit

Special behaviors based on type:

• maintenance → also stamps last_maintenance_at on the vehicle
• returned_to_service → also clears out_of_service_at, out_of_service_reason, out_of_service_until on the vehicle

Out-of-service lifecycle

The Service Log section has a dedicated Take out of service / Mark in service toggle separate from the event-add form. Use this for the OOS state machine — the event log gets a row automatically.

See Out-of-service lifecycle for the full state machine.

Damage events at return

Damage logged via the damage-at-return endpoint creates a service log row automatically with:

• event_type = 'damage'
• reservation_uuid linking to the booking
• damage_charge_cents set
• Photos in photo_urls array

You don't have to manually log damage events from the service log UI — the return flow handles it.

Photo URLs

Each event can attach an array of photo URLs. The Service Log section doesn't have a built-in upload widget yet — most operators:

• Take photos on the iPad
• Upload to a folder in their cloud storage
• Paste the share-links into the event's photo_urls array (via API)

Native upload-to-Storage UI is on the roadmap.

Cost tracking

The cost_cents field captures the parts + labor cost of the work. Useful for fleet TCO reporting:

SELECT
  v.vehicle_number,
  v.serial_number,
  count(vsl.id) AS service_events,
  sum(vsl.cost_cents + vsl.damage_charge_cents) / 100.0 AS total_cost_usd
FROM vehicles v
LEFT JOIN vehicle_service_log vsl ON vsl.vehicle_uuid = v.id
WHERE v.subaccount_id = '<your-subaccount-id>'
  AND vsl.occurred_at &gt;= '2026-01-01'
GROUP BY v.id
ORDER BY total_cost_usd DESC;

High-cost vehicles signal candidates for replacement.

Maintenance scheduling

Two related fields on the vehicles table itself:

• last_maintenance_at — auto-stamped when you log a maintenance event with the "record maintenance timestamp" flag
• next_maintenance_due_at — set manually; powers a future "due for maintenance" filter

Currently neither field drives automatic notifications. Operators can query bikes with next_maintenance_due_at < now() to find overdue work. We're considering adding a maintenance-due cron in a future release.

Common patterns

After every rental

Don't log a service event for every clean return — that's noise. Only log events when:

• Maintenance was actually performed
• Damage was found
• The bike's status changed (OOS or back-in-service)

Routine maintenance schedule

Most shops do:

• Daily: visual inspection (optional log entry)
• Weekly: chain lube, tire pressure check (optional)
• Monthly: brake adjustment, drivetrain check (log as inspection)
• Quarterly: full tune-up (log as maintenance with cost)
• Annually: deep tear-down, cable replacement (log as maintenance)

Tracking a specific issue

If a bike has recurring issues (e.g., dropping the chain), log every incident. The service log becomes a paper trail for warranty claims or returning the bike to the manufacturer.

What's NOT in the service log

• GPS / telemetry data — that's in the vehicles table proper, not the service log
• Rental history — find that via reservations.vehicle_uuid
• Rider feedback / reviews — separate flow

Service log permissions

Logging events requires vehicle:update_status permission. Most operator and mechanic roles have it. Reading the log is permitted for anyone with vehicle view access.