Handoff← Overview
Handoff · Production Readiness · connected asset maintenance
Data Model & Production Data Inventory
The prototype runs on mocked, telematics-like data. This page catalogs every data point it relies on, maps each to a likely telematics source system, and flags whether we’d ingest it directly, derive it, or build it net-new. It’s meant as a worksheet to sit with an engineer and triage what we already have versus what we’d need to build for a production product.
Source-system mappings are best-guess assumptions to validate with engineering — the goal is to start the conversation, not to assert how a telematics platform is structured.
How to read this
Each data point carries one availability status:
AvailableExists in a mature telematics product today — ingest directly.
PartialExists, but coverage / quality / normalization varies.
DerivedHandoff computes it from raw inputs — not stored upstream.
To buildNet-new capture / integration most telematics platforms do not have today.
Source systems
The upstream telematics products Handoff reads from, and how mature each data surface is likely to be for this use case.
| Telematics product / area | What Handoff reads from it | Maturity |
|---|---|---|
| Equipment / Assets | Asset master: VIN, make/model/year, plate, odometer, engine hours, status. | Core |
| Vehicle Diagnostics | Fault codes (SPN/FMI), severity, active-since, recurrence count. | Core |
| Compliance / DVIR | Driver inspection defects and safety flags. | Core |
| Driver app | Driver-reported defects and notes. | Core |
| Telematics (GPS) | Asset location, in/out of yard, usage. | Core |
| Maintenance (Work Orders + PM) | Work orders, categories, service/PM schedules. | Core |
| Routing & Dispatch | Route commitments, ETAs, asset availability. | Partial |
| Parts / Inventory | Part stock, reservations, ETAs. | Gap |
| Workforce / Labor | Technician roster, skills/certs, shift hours, capacity. | Gap |
| Vendors / external service | Approved roster, specialties, live slots. | Gap |
A · Raw / ingested data points
The fields the product must read from source systems, grouped by domain. One row per data point.
Asset / Equipment
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| id / name | Asset identifier and display name (Truck 184). | Equipment / Assets | Available | Core asset master record. |
| type | Asset class (day-cab tractor, reefer trailer, cargo van). | Equipment / Assets | Available | |
| year / make / model | Vehicle spec for context. | Equipment / Assets | Available | |
| vin / plate | VIN and license plate. | Equipment / Assets | Available | |
| odometer / engineHours | Usage readings (drive PM thresholds). | Telematics + Equipment | Available | Live from gateway; freshness matters. |
| status | in_service / available / out_of_service. | Equipment + Dispatch | Partial | “Out of service for maintenance” may need an explicit maintenance-hold concept. |
| location | Yard + bay (Phoenix Yard · Bay 3) or en route. | Telematics (GPS) | Partial | GPS is available; bay-level location is likely to-build. |
| etaLabel | Return ETA when the asset is en route. | Routing & Dispatch | Partial | Derived from route/ETA data. |
| driver | Assigned / last driver. | Driver app + Dispatch | Available |
Faults / Diagnostics
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| code / fmi | Fault code (SPN 789 / FMI 1). | Vehicle Diagnostics | Available | Standard J1939 SPN/FMI. |
| severity | critical / warning / info. | Vehicle Diagnostics | Available | |
| activeSince / count | First-seen time and recurrence count. | Vehicle Diagnostics | Available | Count enables repeat-issue detection. |
| name | Human-readable fault name. | Vehicle Diagnostics | Partial | Code→name mapping; coverage varies by make. |
| description / risks / suggestedActions | Plain-language insight, risk list, and recommended fixes. | Diagnostics insight layer | Derived | Knowledge/LLM-generated insight on top of the raw code. |
| confidence | Diagnostic confidence (low · review required). | Diagnostics insight layer | Derived | Heuristic; gates low-confidence triage. |
DVIR, PM & driver signals
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| DVIR signal + severity | Driver vehicle inspection defect (unsafe brakes). | Compliance / DVIR | Available | Strong telematics surface. |
| driver report | Driver-reported defect / note. | Driver app | Available | |
| PM signal + dueLabel | Preventive-maintenance due (due in 220 mi). | Maintenance (Service schedules) | Available | dueLabel phrasing is derived from schedule + usage. |
| tags: pm_due / pm_overdue | PM timing flags. | Maintenance | Derived | Computed from schedule vs. odometer/clock. |
| signals[] fusion | Multiple signals collapsed into one asset-centered item. | — | Derived | The core fusion step; see Section B. |
Work orders
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| workOrderId | Existing / new work-order id (WO-4471). | Maintenance (Work Orders) | Available | |
| category | Job category (Brakes, Refrigeration). | Maintenance (Work Orders) | Available | |
| title | Single-line job title across fused signals. | — | Derived | Summarized from signals/WO. |
| currentWork | Short label of the job in progress now. | Maintenance (Work Orders) | Partial | Maps to WO status/labor line if present. |
| estLaborHours / requiredSkill | Estimated labor and the skill needed. | Maintenance + labor standards | Partial | Standard-jobs/labor-time data may be incomplete. |
Parts / inventory
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| kind | in_stock / reserved / out_of_stock / unknown. | Parts / Inventory | To build | Real-time parts stock is a likely gap in telematics platforms today. |
| label | Part description / PN (Brake pads FMSI D1707). | Parts / Inventory | Partial | Often lives in a separate inventory/DMS system. |
| etaLabel | Expected arrival when out of stock. | Parts / supplier | To build | Requires supplier/PO integration. |
Technicians / labor
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| id / name | Technician identity. | Workforce / Labor roster | Partial | Identity may exist; not always modeled as a schedulable resource. |
| skills[] | Skill / certification tags (Brakes, DOT inspection). | Workforce / Labor roster | To build | Structured skills + certs are a key gap. |
| totalHours / availableHours | Shift capacity and remaining hours. | Time / scheduling | To build | Real-time remaining capacity must be tracked or integrated. |
| status | available / busy / near_capacity. | — | Derived | Derived from availableHours. |
| location | Bay assignment. | Workforce | To build | Bay-level tech location is likely net-new. |
Vendors / external service
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| id / name / specialty | Approved vendor roster + what they do. | Vendors / external service | Partial | May exist as contacts; not a structured, schedulable roster. |
| distance | Distance from shop. | Maps / Telematics | Available | Computable from addresses. |
| slot | Next available appointment slot. | Vendor scheduling | To build | Live vendor availability requires integration / manual entry. |
| approved | Whether vendor is approved for work. | Vendors / procurement | Partial |
Dispatch / routing
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| route commitments / ETA | What route the asset is committed to and when. | Routing & Dispatch | Available | Core routing data. |
| dispatchImpact | Narrative of routing impact of the work. | — | Derived | Composed from route + asset status. |
| spare availability | Whether a spare asset covers the route. | Dispatch / fleet | To build | Requires fleet-availability logic; often human-known today. |
| requestedRelease | Requested hold/release window for an asset. | Handoff workflow | To build | A Handoff-owned request; see Section C write-backs. |
Shop / shift context
| Data point | Description | Telematics source (assumed) | Availability | Notes / gaps |
|---|---|---|---|---|
| shop / location / shift | Shop identity, geography, and shift window. | Org / config | Available | Configuration data. |
| supervisor | Current supervisor on shift. | Workforce / auth | Available | From the signed-in user / roster. |
| clockMinute / lastReviewedMinute | Current time and last queue review. | System clock + activity | Available | Real time in production; deterministic in the demo. |
B · Derived / computed layer
What Handoff builds on top of the raw inputs. This is the product's logic — it does not exist pre-built in any single source system, so it is the core thing we build.
| Derived value | Inputs consumed | Rule / logic | Status |
|---|---|---|---|
| Primary Workboard state (6) | state, owner.kind | Collapses 12 granular states → 6 supervisor lanes.reducer.ts · primaryStateOf | To build |
| Signal fusion → one work item | DVIR, fault, PM, WO, driver signals per asset | Group multi-source signals into one asset-centered item.data model | To build |
| Priority + reason + factors | safety, route impact, readiness, recurrence, fault severity | Rank work and explain why (urgent / ready / info factors).priorityFactors | To build |
| Readiness + checklist | asset on-site, parts, qualified tech, dispatch conflict | ready / partial / blocked from prerequisite checks.readinessChecklist | To build |
| Recommendation / whyNow / impactIfDeferred | fused item context | Plain-language guidance for the supervisor.narrative fields | To build |
| Technician fit / match | requiredSkill ∩ tech.skills, availableHours, estLaborHours | qualified / partial / none + a recommended tech.reducer.ts · technicianFit / matchInfo | To build |
| Health: unowned | owner.kind, nextAction, state | Active item with no owner or no next action.reducer.ts · isUnowned | Derived |
| Health: over-ETA | expectedCompletionMinute, clockMinute | clock > expectedCompletion while in progress.reducer.ts · isOverEta | Derived |
| Health: aging blockers | blockerStartedMinute, clockMinute | Blocked > 120 min (BLOCKER_AGING_MINUTES).reducer.ts · isBlockerAging | Derived |
| Health: follow-ups due today | followUpMinute | Follow-up scheduled before end of day.reducer.ts · isFollowUpDueToday | Derived |
| ETA math | assignedAtMinute, estLaborHours, progress | expectedCompletion = assignedAt + estLaborHours×60; remaining from progress.reducer.ts / TaskDetailPanel | Derived |
| Capacity: booked / projected | totalHours, availableHours, estLaborHours | booked = total − available; projected adds the pending pick.TechnicianCapacityCard | Derived |
| Available actions | state, owner.kind | Which actions are valid for the item right now.reducer.ts · availableActionsFor | To build |
| Follow-up timing | cadence label, clockMinute | Maps “later today / next shift / tomorrow” to a minute.reducer.ts · followUpMinuteFor | Derived |
C · Write-backs / actions
Supervisor actions are not just UI — each one writes back to a source system or to Handoff-owned workflow state. These imply write APIs and a workflow/event store that mostly do not exist today.
| Action | What it writes | Target system (assumed) | Availability |
|---|---|---|---|
| assign_start / diagnose_assign | Assign technician, set WO in progress, reserve parts, charge capacity. | Work Orders, Parts, Labor | To build |
| request_asset_hold | Ask dispatch to hold an asset on return. | Routing & Dispatch | To build |
| request_dispatch_release | Ask dispatch to release an asset for maintenance. | Routing & Dispatch | To build |
| send_vendor_review | Route work to an external vendor + appointment. | Vendors | To build |
| mark_blocker_cleared | Clear a blocker; advance state and ownership. | Handoff workflow | To build |
| mark_complete | Close work; set disposition (return to service / verify / follow-up / await release). | Work Orders, Equipment | To build |
| defer | Move to a monitor / follow-up lane with a recheck time. | Handoff workflow | To build |
| activity log (15 kinds) | Append an auditable handoff event for every change. | Events / audit store | To build |
D · Key gaps & open questions for engineering
The highest-leverage things to confirm together — the items most likely to be missing or to need new capture.
- Technician model — structured skills/certifications plus real-time remaining capacity and bay location. Do we have a schedulable labor resource, or is this net-new?
- Parts / inventory — live stock status, reservations, and arrival ETAs. Likely a separate inventory/DMS integration.
- Vendors — a structured, approved roster with live appointment slots, not just contacts.
- Dispatch coupling — route commitments and spare-asset availability, plus a hold/release request workflow between maintenance and dispatch.
- Prioritization & readiness engine — the logic that fuses signals, ranks work, explains why, and assesses readiness (Section B). This is the product’s IP.
- Write-backs & audit — write APIs into Work Orders / Dispatch / Vendors, Handoff-owned workflow state (state, owner, blocker, follow-up), and an auditable event log.
- Identity / join keys — stable keys to join asset ↔ work order ↔ fault ↔ DVIR ↔ PM ↔ driver ↔ route across systems.
- Freshness & data quality — latency expectations per source (real-time vs. batch) and how the experience surfaces unknowns when data is missing or low-confidence.