tracksolid_timescale_grafana_prod/docs/PROJECT_CONTEXT.md

Project Context — Fireside Communications Fleet Intelligence

The Client

A first-line technical support operation contracted by a large Kenyan/East African telco. The client manages field technicians who handle the full spectrum of last-mile broadband support:

Service Type	Description
New installations	Fibre/broadband installs at home and business premises
Fault resolution	LOS (Loss of Signal) troubleshooting, slow service investigations
Outside plant maintenance	Physical cable, cabinet, and pole infrastructure maintenance
Migrations	Customer plan or technology upgrades requiring a site visit
Business customer support	Prioritised SLA-driven support for commercial accounts

Operational Geography

City	Status	Notes
Nairobi	Primary — fully operational	Main depot at Kikuyu Rd corridor (~-1.237, 36.727)
Mombasa	Deploying	Fleet being onboarded
Kampala, Uganda	1 device confirmed	X3-63282 at 0.196, 32.540 — status under investigation

All three cities managed from a single Tracksolid Pro account and a single database instance. A city field or grouping by device group should be used for per-city analytics rather than separate schemas.

The Fleet

• ~80 vehicles total (63 currently registered in Tracksolid Pro)
• Mix of motorcycles (courier/light inspection) and vans/4WDs (equipment and crew)
• Device models in use: AT4 (hardwired), JC400P (camera-capable), X3 (compact), GT06E (OBD)
• Vehicle identity (plate numbers, driver assignments) not yet populated in Tracksolid Pro — primary data quality gap

Data Quality Gaps (as of April 2026)

Gap	Impact	Resolution path
No driver names assigned	Reports show IMEIs instead of people	Assign in Tracksolid Pro UI → DB syncs nightly
No vehicle numbers populated	Cannot link vehicle to job/plate	Manual UPDATE or CSV import
44 of 63 devices never reported GPS	Cannot track these vehicles	Verify SIM installation + activation
fuel_100km null for all devices	Fuel cost calculations inactive	Set by vehicle type via UPDATE
No geofences defined	Cannot alert on depot departures or route deviations	Define depot polygons + city zones
Webhooks not registered	OBD, fuel, temperature tables empty	Register in Tracksolid Pro account settings

---

KPI Framework

This section is developed iteratively with the client. KPIs are grouped by operational domain. As client feedback arrives, move items from "Proposed" to "Active" and add the Grafana panel reference.

Domain 1 — Fleet Utilisation

Measures whether vehicles are productively deployed during working hours.

KPI	Definition	Target	Status
Utilisation rate	Drive time / shift hours × 100	> 60%	Proposed
Idle time %	Engine-on-stationary / total shift	< 15%	Proposed
Vehicles not moved today	COUNT where no trip recorded	0	Proposed
Fleet km per day	SUM(distance_km) across all trips	Baseline TBD	Proposed

Domain 2 — Field Technician Productivity

Measures output per technician per day. Requires job management system integration or manual job log.

KPI	Definition	Target	Status
Jobs completed per technician per day	Count of closed jobs	Baseline TBD	Proposed
First-time fix rate	Jobs resolved on first visit %	> 80%	Proposed
Mean time to arrive (MTTA)	Job assignment → vehicle on-site	< 45 min	Proposed
Mean time to repair (MTTR)	Job creation → job closed	< 2 hours	Proposed
SLA compliance rate	% jobs closed within SLA window	> 95%	Proposed

Note: MTTA and MTTR require job timestamps from the telco's ticketing system. Integration point TBD.

Domain 3 — Driver Behaviour & Safety

Measures driving quality. Feeds into insurance, safety, and coaching programmes.

KPI	Definition	Target	Status
Speeding events per 100 km	GPS fixes > 80 km/h / total km × 100	< 0.5	Proposed
Harsh driving index	Speed delta > 30 km/h in < 60s per 100 km	< 0.5	Proposed
After-hours movement	Trips starting before 06:00 or after 20:00 EAT	0	Proposed
Late starts	First ignition after 07:45 EAT	< 2/month	Proposed
Early knock-off	Last trip ended before 17:00 EAT	< 2/month	Proposed

Domain 4 — Route & Dispatch Efficiency

Measures how well vehicles are matched to jobs geographically.

KPI	Definition	Target	Status
Avg distance per job	Total km / jobs completed	Baseline TBD	Proposed
Nearest available vehicle ETA	PostGIS dispatch query	< 30 min	Proposed
Return-to-depot rate	% trips ending at primary depot	Baseline TBD	Proposed

Domain 5 — Asset Health & Cost

Measures maintenance burden and fuel efficiency.

KPI	Definition	Target	Status
Estimated idle fuel cost (KES)	Idle hours × 0.8 L/h × KES 180/L	Minimise	Proposed
Vehicles approaching service interval	Odometer > threshold	0 overdue	Proposed
Alarm rate per vehicle per week	COUNT(alarms) / 7	< 2	Proposed
GPS offline rate	Devices with fix age > 10 min / total	< 10%	Proposed

Shift Schedule Assumptions

Adjust these as confirmed with client:

Parameter	Assumed Value
Shift start	07:30 EAT
Late threshold	After 07:45 EAT
Shift end	17:00 EAT
After-hours	Before 06:00 or after 20:00 EAT
Working days	Monday–Saturday (confirm with client)
Shift length for utilisation	10 hours

---

Integration Roadmap

Integration	What it unlocks	Priority
Telco ticketing system (job timestamps)	MTTA, MTTR, first-time fix rate, jobs/day	HIGH
Tracksolid webhook registration	OBD, fuel, temperature, tamper events	HIGH
Driver assignment in Tracksolid Pro	All driver-attributed KPIs	HIGH
Geofence definition	Depot departure alerts, city zone coverage	MEDIUM
Fuel sensor webhook (/pushoil)	Actual fuel consumption vs estimated	MEDIUM
Temperature sensor (/pushtem)	Cold-chain compliance (if applicable)	LOW