f9834564ab
CLAUDE.md: cached context file covering project identity, tech stack, codebase map, schema quick-ref, API gotchas, fix history, working rules, fleet state, and open items. Structured for maximum cache efficiency — stable content first, dynamic state at the end. docs/CONNECTIONS.md: connection parameter shapes (no secrets) for SSH, DB, API, container resolution, Forgejo, Grafana, n8n. docs/PROJECT_CONTEXT.md: client business context (telco field service, 3 cities, service types), data quality gaps, KPI framework by domain, integration roadmap. docs/KPI_FRAMEWORK.md: living KPI register with status tracking, thresholds, client feedback log, and review checklist. To be co-developed with client iteratively. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
131 lines
6.1 KiB
Markdown
131 lines
6.1 KiB
Markdown
# 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 |
|