# 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 |