mafralp@geo-tracker-api:~$

GeoTracker API

A real-time telemetry API for last-mile delivery operations, built to ingest GPS positions securely, process them with PostGIS, and deliver vehicle updates to authorized operational viewers.

GitHub

I built GeoTracker API around a simple rule: a GPS ping is evidence first and an operational map point second. Raw device data must remain intact for audit and reprocessing, while the live tracking experience uses only derived, route-aware positions.

What I built

• An authenticated POST /telemetry endpoint for tracker devices, with strict coordinate, accuracy, timestamp and vehicle validation.
• An append-only raw_telemetry record that preserves the exact received GPS fact and cannot be updated or deleted.
• A PostGIS processing pipeline that snaps positions to the vehicle’s active planned route and calculates route deviation in meters.
• A processed_locations projection for operational use, separating source evidence from derived map data.
• Vehicle-scoped WebSocket updates through tracking.position.updated, emitted only after the database transaction succeeds.
• M2M JWT authorization: tracker tokens ingest only for their vehicle; viewer tokens subscribe only to that vehicle’s live channel.
• Swagger/OpenAPI documentation, Prometheus-compatible runtime metrics, Docker Compose development and PostGIS integration tests.

Product capabilities

Auditable telemetry ingestion
Each valid GPS event is saved before processing. Original latitude, longitude, reported accuracy and capture timestamp remain available for investigation, replay and future processing improvements.

Route-aware location processing
When a vehicle has an active route, PostGIS projects the raw point onto its LineString with ST_ClosestPoint and measures raw-to-route deviation using geography-aware ST_Distance.

Real-time operational updates
Authorized viewers receive processed—not raw—coordinates through a vehicle-specific WebSocket room. This keeps the map useful while preventing unnecessary exposure of device-level payloads.

Clear security boundaries
Machine-to-machine JWTs include vehicle_id and role claims. The API enforces ownership at ingestion and subscription boundaries instead of trusting a client-selected vehicle identifier.

Operational visibility
The API exposes health and Prometheus-compatible metrics for ingestion volume, processed positions, validation failures, processing duration and active WebSocket connections. Structured logs avoid recording full raw coordinates.

Technical decisions worth exploring

• Raw and processed telemetry are separate so map-matching logic can evolve without rewriting received evidence.
• PostGIS handles spatial processing where geospatial indexes and the database transaction already live, avoiding application-side geometry handling.
• Broadcasts happen only after persistence succeeds, so clients never receive positions that failed to commit.
• WebSocket messages contain the derived operational point rather than the original tracker payload.
• The application separates domain, application, infrastructure, HTTP, realtime, auth and observability boundaries, keeping Fastify, PostgreSQL and WebSocket details out of core ingestion.

Architecture

Tracker device + M2M JWT
          │
          ▼
POST /telemetry ──> raw_telemetry (append-only)
                          │
                          ▼
              PostGIS snap-to-route processing
                          │
                          ▼
                processed_locations
                          │
                          ▼
Viewer JWT + vehicle-scoped WebSocket

Stack

Core
TypeScript, Node.js 22+, Fastify, PostgreSQL, PostGIS, Kysely, JWT and WebSockets.

Developer experience
Docker Compose, Swagger UI / OpenAPI, TypeScript type checking, native node:test, integration tests and a terminal-based realtime demo.

Status

GeoTracker API is a portfolio demonstration project at version 0.1.0. Its realtime channel manager is intentionally in-memory for a single API instance; production horizontal scaling would require shared pub/sub infrastructure such as Redis or NATS.

Type cd .. to return home.