Fleet-platform status — week 1 of 5

Greenfield rebuild of the Fireside telematics stack · Solo engineer · Started 2026-05-22

Headline metrics

Timeline & pacing

Capabilities live today

Live map

• ~144 vehicles refreshed every 15 s on a light Carto Positron basemap
• Markers tinted by cost-centre always; opacity carries state (moving 1.0 / parked 0.75 / offline grey 0.55)
• White directional arrow on every moving vehicle, zoom-scaled
• Plate-tail label per vehicle, hidden below zoom 11 to declutter
• Hover popup: plate, driver, speed, heading, reverse-geocoded address, age of last fix
• Fireside Group HQ POI (red dot at -1.2409, 36.7288) with permanent label from zoom 9

Filters (multi-select dropdowns)

• Cost centre + assigned city pickers with "All …" default + per-option checkboxes
• Cost-centre options carry a colour swatch matching the marker tint — filter doubles as a live colour legend
• Single selection → server-side filter (counts in FLEET NOW reflect the filter)
• Multi-selection → client-side narrowing via setFilter (markers hide, counts stay full for population context)

Trip dock (click any vehicle)

• Slides up from the bottom; day totals header (trips / km / drive·idle·stop minutes)
• Per-trip cards with start→end times, distance, duration, idling minutes, end-reason badge
• Each trip drawn on the map in its own colour from a 12-colour palette; matching swatch on the trip card's left edge
• Click a trip card → animated marker traces the polyline over ~10 s
• Date picker (defaults to today EAT, scrolls back through history)
• CSV download (per-trip rows: date · plate · reporting_time · trip_id · start · end · duration · distance · idling · end_reason)
• ⌘-click a second vehicle → multi-vehicle overlay; routes in distinct colours; dock switches to compact rows + aggregate KPIs

Auth + API

• JWT login at /login.html (bcrypt + PyJWT, scopes read:fleet / write:ops / admin:fleet)
• Rate limited (60/min dashboards, 30/min CSV)
• All times displayed in EAT (Africa/Nairobi); all storage in UTC; conversion at the serve layer

Architecture

One FastAPI image, three container roles selected by APP_ROLE. Fate isolation is the point — a heavy report in the worker doesn't stall the gateway.

Deployment

• Coolify-managed Docker Compose app since 2026-05-27 (was manual docker run before)
• Compose file: docker-compose.coolify.yml at repo root
• Forgejo registry + git: repo.rahamafresh.com/kianiadee/fleet-platform
• Networks: each container is attached to (a) its Coolify project network, (b) bo3nov… (the DB project's network — where timescale_db alias resolves), (c) gateway also on coolify shared network so Traefik can reach it
• TimescaleDB: separate Coolify project. DB user postgres, db fleet_platform. Read-only reporting role: reporting_reader
• Domain: api.rahamafresh.com via Coolify-generated Traefik labels + Let's Encrypt
• Deploy flow: git push origin main → Coolify UI → Redeploy (auto-deploy webhook not wired yet)

awk "/^-- migrate:down/{exit} {print}" db/migrations/NNNN.sql \
    | docker exec -i "$PG" psql -U postgres -d fleet_platform -v ON_ERROR_STOP=1

Data model

Layered by purpose, not by feature. Read top-down: events are truth, state is derived.

API endpoints

Migrations history

Trip detection algorithm

One server-side function (serve.fn_vehicle_trips(vehicle_id, date_eat)), single forward pass over state.position_history for the day.

Rules

• Reporting time = first acc_state=1 fix of the day in EAT
• Trip starts at every ACC_ON transition (or first fix if already on/moving)
• Trip ends when ONE of:
  • ACC_OFF + stationary (< 5 km/h) for ≥ 5 min → work_stop
  • No new fix for ≥ 5 min (engine assumed off) → nofix_stop
  • Fix gap > 30 min → long_gap
  • End of day's data → day_end
• Within a trip: ACC_ON + stationary ≥ 5 min logged as an idling segment (no split — engine still running)
• Distance only accumulates when current fix is > 5 km/h (excludes GPS jitter at standstill)
• Fallback: when acc_state is null across the day (some Tracksolid devices don't expose it), algorithm degrades to speed-only segmentation; data_quality.has_acc_data: false flagged in the response

Calibration vs legacy DB

5-min thresholds (work stop + no-fix stop) locked in. Sim tool at scripts/simulate_trips_from_legacy.py replays any legacy JSON dump through the algorithm offline.

Known issues & follow-ups

Roadmap

P1 — remaining

P2 — next

• History page (per-vehicle timeline)
• Routes page (per-trip detail + KPIs)
• Geofence ingest + entry/exit events
• Trips/idling/stops projector (materialized — currently on-demand)

P3 — operations + cut-over

• Push receiver cut-over (see next section)
• Driver roster (domain.drivers + domain.driver_assignments with effective dates)
• Device lifecycle admin UI
• Alarm console
• Legacy decommission

P4 — driver KPIs + cost allocation

• Driver scorecards, shift attribution
• Fuel ingest from existing WhatsApp microservice
• Cost allocation by cost-centre
• Executive summary dashboards

Push-receiver cut-over plan (P3)

Currently Tracksolid posts to a legacy endpoint at https://tshook.rahamafresh.com/pushalarm (a separate project that no longer benefits us). We poll every 30 s as a workaround. The cut-over moves us off polling and onto real-time push.

Why it's worth doing

What's already in place

• 7 push receivers wired at /push/jimi/{pushgps,pushalarm,pushhb,pushobd,pushfaultinfo,pushtripreport,pushevent}
• Shared-token auth via TRACKSOLID_PUSH_TOKEN in form body (matches Tracksolid's documented push pattern)
• Gateway contract honoured: form parse + token verify + INSERT events.raw + NOTIFY + return {code:0, msg:"success"}. Nothing else.
• Parsers for 4 of 7 types: pushgps, pushalarm, pushhb, pushevent (the other 3 ingest to events.raw but aren't parsed yet — fine, can parse later)
• Rate limit 1000/min per endpoint via slowapi

What needs to happen (in order)

1. Add dedup to state.position_history — migration 21. Add a unique index on (imei, occurred_at, source) (or insert with ON CONFLICT DO NOTHING). Without this, push + polling overlap will duplicate fixes during the mirror window and inflate trip distances.
2. Synthetic-payload smoke test — curl a realistic Tracksolid push body at each receiver, confirm events.raw row appears, parser produces an events.parsed row, projector updates state.live_positions. Validates the path end-to-end before depending on real traffic.
3. Tracksolid console: add the new URL alongside the legacy URL — this is a vendor-portal step, done by whoever manages the Fireside Tracksolid account. The exact URL list to paste:

   https://api.rahamafresh.com/push/jimi/pushgps
   https://api.rahamafresh.com/push/jimi/pushalarm
   https://api.rahamafresh.com/push/jimi/pushhb
   https://api.rahamafresh.com/push/jimi/pushevent
   https://api.rahamafresh.com/push/jimi/pushobd
   https://api.rahamafresh.com/push/jimi/pushfaultinfo
   https://api.rahamafresh.com/push/jimi/pushtripreport

   Token: the value of TRACKSOLID_PUSH_TOKEN (set in Coolify env).
4. Mirror window (≥3 days) — both push and polling run. Compare daily counts per IMEI between push-derived and poll-derived fixes. Watch for: parser errors, auth failures, payload-shape surprises, dedup hit rate.
5. Cut polling cadence — once mirror data shows push is delivering >95% of fixes, drop main polling from 30 s → 10 min as a sparse safety net (or disable entirely). Keep the stale-IMEI sweep for offline-recovery.
6. Tracksolid console: remove legacy URL — once dispatchers confirm the new dashboard is showing identical or better real-time data, drop the legacy URL from Tracksolid. Hot-standby on our side for 48 h as fallback.
7. Decommission legacy receiver project — final step; the old project at tshook.rahamafresh.com can be shut down.

What needs decisions before starting

• Tracksolid admin access — who edits the push URL list, what's their lead time
• Mirror duration — 3 days (faster ship), 7 days per PRD (full week), or indefinite (no commit to a cut-over)
• Polling fate after push — disable entirely / keep at 5-min sparse / keep at 30 s belt-and-braces
• Auth scheme check — current impl uses form-body token; PRD specifies HMAC X-Jimi-Signature. Either the PRD spec is aspirational and Tracksolid only offers shared-token (likely), OR Tracksolid does offer HMAC and we should switch. Verify before the mirror starts.

Expected outcomes

• Dashboard latency drops from ~30 s to ~5 s for live position updates
• Trip polylines visually trace real routes (no more straight-line shortcuts)
• Alarm and ACC events become first-class instead of derived from polling snapshots
• Trip detection becomes more accurate (denser fix stream, fewer false nofix_stop boundaries)
• Tracksolid API call budget freed up for the contract checker + ad-hoc queries

Decisions log (significant ones)

— end —