Trip and Route Management

The one-minute version

A route is a template. Someone draws a corridor on a map and hangs checkpoints, no-go zones and stops off it. Approving the route freezes a route version: a snapshot plus geometry that never changes again.

A trip is one vehicle running one frozen version of that template. While the trip runs, every telemetry packet for that vehicle is measured against the trip's geometry, and that produces alerts: left the corridor, entered a restricted zone, missed a checkpoint, arrived at a stop, running late.

Two shapes, deliberately kept apart:

• Discrete zones (stops, checkpoints, no-go) are closed shapes with enter and exit edges. Point in polygon, debounced.
• The corridor is a polyline with a width. Continuous distance to line on every packet. It is not a geofence and it never becomes one.

That split decides where code lives. Corridor, ETA, delay and CHECKPOINT_MISSED derivation live in trip execution. Zone membership is shared maths held in step by a golden corpus.

How to review this

If you have an hour, this is the order that gets you to the risky parts fastest.

1. Read What the platform does and Wiring. Ten minutes. The rest only makes sense once the route-template-versus-trip distinction and the one-writer Redis key are in your head.
2. Go straight to Things that look wrong and are not. Four decisions in there look like sloppiness and are load-bearing: the duplicated spatial primitive, the pinned quirk corpus, the negated stop-notification predicate, and the inert TRIP_CODE_ROOT. If you are going to disagree with something, disagree with these first, because the rest of the design leans on them.
3. Read the lifecycle with the route and dispatch endpoints open beside it. The guardrails are all state machine rules: PATCH cannot approve, structural edits demote to DRAFT, dispatch never mints a version, one live trip per vehicle. Each one is a real bug that was closed.
4. Then per-packet evaluation. This is where correctness actually lives. Pay attention to the write-once snapshot, the dedup and cooldown model, and the debounce counters.
5. Finish on the defect ledger and what this pass found. Six items are still open and named, including one that has no owner yet.

What the platform does

The objects

Trip statuses

The status column is the whole state machine. Nothing else gates the lifecycle.

Once a trip is DISPATCHED or later it is execution owned: the API refuses to let a human write trip_zone.status and answers 409 EXECUTION_OWNED. Only the evaluator moves those rows.

Route statuses

Services and repos

Division of labour

Wiring and data flow

The Redis pivot

fleetgo:trip:active:{IMEI} is the one piece of shared mutable state in the whole feature, and the rule around it is short:

One writer, two readers, no second cache to keep coherent. That coupling survived the repo split on purpose.

What replaced geofence.trip_meta

Trip context used to be stamped as a JSONB column onto shared geofence rows at dispatch. That meant route-trip-mgmt wrote to a legacy table it does not own, and two live trips could not share a geofence: the second dispatch overwrote the first.

The column is gone. The geofencing stream now reads the vehicle's own active-trip blob from Redis and admits zones by id (trip_zone_lookup.js). That is strictly narrower than the old account-wide scan, and one geofence can now serve two trips at once. route-trip-mgmt's migrations touch zero legacy tables.

Data model

One shared Postgres database, usermanagement. Thirteen tables are owned by these migrations. Everything else the service reads is a narrow read-only mirror declared in schema.prisma without relations, so Prisma never tries to migrate it.

Owned

operational_stop, route, route_stop, route_zone, route_version, trip_template, trip, trip_assignment, trip_zone, alert, audit_event, outbox, idempotency_key.

Read-only mirrors, never migrated

geofence, device, users, asset_details, asset_assignment, ref_data, upload_tasks.

tables the migrations touch : 27
tables live in UAT          : 44
intersection                :  0

The template and version relationship

This is the part most worth understanding, because four separate guardrails exist only to protect it.

route (template, editable)
  |
  |-- route_stop      ordered, points at operational_stop
  |-- route_zone      role = 'checkpoint' | 'no_go', points at geofence_id
  |-- geometry        GeoJSON LineString, from OSRM or straight line
  |-- corridor_width_m
  |
  +-- approve --> route_version { version, snapshot, geometry, approved_by }
                        ^
                        |  pinned at trip creation
                  trip.route_version_id

A trip pins route_version_id at creation and rides that frozen snapshot for its whole life. Editing the route afterwards never retunes a trip already on the road. Corridor width in particular is read from snapshot.corridor_width_m, not live, so a mid-trip PATCH cannot silently change what a running vehicle is measured against.

Key columns

Timestamps: the 5h30m bug

Worth reading even though it is closed, because it explains a migration that carries a deploy gate.

The trip tables originally stored timestamp WITHOUT time zone, a wall clock. That only works while every writer agrees out of band which clock it means, and two did not. route-trip-mgmt writes through Prisma, which uses UTC. Execution wrote through node-postgres, which used local. On an IST host the same column held both conventions 5 hours 30 minutes apart, so planned_arrival read back five and a half hours in the past and every dispatched trip raised TRIP_DELAYED within one packet, reporting about 330 minutes. 330 minutes is the offset.

Fixed by 20260826000000_trip_timestamps_timestamptz: 33 columns across 11 tables, converted with USING col AT TIME ZONE 'UTC' so the conversion is pinned rather than depending on the session zone.

API conventions and auth

One service serves the whole API: route-trip-mgmt on port 8100. Everything sits under /api/v1 except /health. route-trip-execution has no HTTP surface at all, so there is nothing to call on it and it needs no gateway route.

Base URLs

Authentication

Two modes, selected by TRIP_AUTH_MODE, and the service fails at boot rather than on the first request if the pair is invalid.

Authorization: Bearer <portal token>

X-Account-Id: 11
X-User-Id: bf-local
X-Role-Type: SuperAdmin   (optional)

Permissions

Tiers are the platform's existing role.type values, keyed lowercase because the casing in the platform's own data is inconsistent. An unknown tier is treated as the least privileged known tier, so a typo in role.type cannot grant everything.

Idempotency

Four endpoints require an Idempotency-Key header and reject the call with 400 IDEMPOTENCY_REQUIRED without one:

• POST /api/v1/trips
• POST /api/v1/trips/:id/dispatch
• POST /api/v1/trips/:id/driver-events
• POST /api/v1/driver/sync

The key is claimed with an INSERT first, so concurrent retries race on the unique constraint instead of both reading "no cached response yet" and both proceeding. A read-then-write here produced duplicate trips and double dispatches. Cached responses live 24 hours. A failed attempt releases the claim so a retry actually retries.

Shared shapes

• List endpoints return { items: [...] }. Trip event feeds return { events: [...] }. The driver router returns { trips: [...] }.
• Errors return { error: "<message>", code: "<CODE>" }.
• Every read is scoped to the caller's effective account. There is no endpoint that returns another tenant's rows without the cross-account path above.
• Coordinates in request bodies are latitude first for bare pairs. GeoJSON objects are accepted and follow GeoJSON order (longitude first). This is deliberate and both are handled by one normaliser.
• List caps: trips 100, alerts and exceptions 200, devices 200, events 100 default and 200 maximum.

Endpoint index

Click any row to jump. Cards below expand.

Stops

The reusable catalogue. A stop is a place, not a step in a journey. Routes reference stops through route_stop with a sequence, so the same depot can appear on fifty routes.

{
  "name": "Electronic City Depot",      // required
  "stop_type": "DEPOT",                 // validated against ref_data type 'stop_type'
  "latitude": 12.8452,
  "longitude": 77.6602,
  "address": "Hosur Road, Bengaluru",
  "geofence_id": 4412                   // optional, and usually null
}

{ "items": [ { "id": 12, "name": "...", "latitude": ..., ... } ] }

Routes

The zone-attachment endpoints are all full replace PUTs, not partial merges. Send the complete list every time. That is what makes the Route Builder able to treat the map as the source of truth.

{
  "name": "E-City to Whitefield",   // required
  "description": "morning line haul",
  "trip_type": "LH",                 // validated against ref_data 'trip_type', default LH
  "corridor_width_m": 120            // default 100
}

{ "items": [ {
  "id": 101, "name": "...", "status": "APPROVED",
  "corridor_width_m": 120,
  "published_version": { "id": 62, "version": 3, "approved_by": "...", "approved_dt": "..." },
  "working_copy_dirty": false
} ] }

{ "name": "...", "description": "...", "trip_type": "LH",
  "corridor_width_m": 150, "status": "DRAFT" | "ARCHIVED" }

{ "waypoints": [
  { "sequence": 1, "latitude": 12.8452, "longitude": 77.6602 },
  { "sequence": 2, "latitude": 12.9100, "longitude": 77.6400 }
] }

{ "stops": [
  { "operational_stop_id": 12, "sequence": 1, "dwell_time_min": 15 },
  { "operational_stop_id": 19, "sequence": 2 }
] }

{ "checkpoints": [
  { "sequence": 1, "geofence_id": 5501, "name": "A - Hosur Road toll", "required": true },
  { "sequence": 2, "geofence_id": 5502, "name": "B - Silk Board", "required": true }
] }

{ "zones": [
  { "geofence_id": 5610, "no_go_type": "HARD", "name": "School zone" },
  { "geofence_id": 5611, "no_go_type": "SOFT", "name": "Market lane" }
] }

{ "restrictions": { "max_speed_kmh": 60, "night_driving": false } }

{
  "geometry": { "type": "LineString", "coordinates": [[77.66,12.84],[77.64,12.91]] },
  "distance_m": 12000,
  "duration_s": 1800
}

{
  "route_id": 101,
  "geometry": { "type": "LineString", "coordinates": [...] },
  "distance_m": 24188.4,
  "duration_s": 2735,
  "planned_via_osrm": true
}

Trips

{ "name": "Morning E-City run", "route_id": 101,
  "checklist": [ { "id": "vehicle_inspection", "label": "...", "required": true } ],
  "config": {} }

{ "items": [ ... ] }

Idempotency-Key: trip-create-<uuid>    // required

{
  "route_id": 101,          // or template_id, whose route_id is used
  "template_id": 4,
  "trip_type": "LH",        // defaults to the route's
  "trip_number": "TRP-...", // auto-generated when omitted
  "scheduled_start": "2026-08-28T04:30:00Z",
  "scheduled_end":   "2026-08-28T09:00:00Z",
  "external_ref": { "erp_id": "SO-88123" },
  "status": "PLANNED"       // DRAFT | PLANNED | SCHEDULED only
}

{ "items": [ {
  "trip_id": 512, "trip_number": "TRP-...", "status": "EN_ROUTE",
  "imei": "10000005000006", "driver_user_id": "drv-7",
  "route_name": "E-City to Whitefield", "corridor_width_m": 120,
  "monitored": true,
  "position": { "lat": 12.91, "lng": 77.64, "recorded_at": "2026-08-27T09:12:03Z" },
  "inside_corridor": true,
  "speed_kmh": 38.4,          // smoothed EMA, not a single noisy fix
  "progress_m": 8120, "route_distance_m": 24188,
  "stops_done": 1, "stops_total": 2,
  "checkpoints_hit": 2, "checkpoints_total": 3,
  "polyline": [[12.84,77.66], ...],
  "eta": { "eta_dt": "...", "planned_arrival_dt": "...", "delay_seconds": 420 }
} ] }

{ "events": [ { "id": "8812", "action": "TRIP_DISPATCHED", "actor_id": "...", "payload": {...}, "created_dt": "..." } ] }

{ "status": "PENDING", "planned_arrival": "2026-08-28T05:10:00Z", "planned_departure": "..." }

{ "status": "PENDING" }

{ "eventType": "START_TRIP", "clientTimestamp": "2026-08-28T04:32:11Z", "payload": {} }

Dispatch

These are mounted on the same /api/v1/trips prefix. They are the lifecycle transitions, and each one has a guard that came from a real failure.

{ "device_id": "MT013-0007", "driver_user_id": "drv-7" }   // both required

{ "trip": { ... }, "validation": { "device_valid": true, "blocks": [], "warnings": [ ... ] } }

{ "device_id": "MT013-0011", "driver_user_id": "drv-9", "reason": "breakdown at Silk Board" }

{ "status": "PASSED",     // PASSED | FAILED | PENDING, defaults to PASSED
  "items": [ { "id": "vehicle_inspection", "checked": true },
             { "id": "documents", "checked": true } ] }

{ "trip": { ... }, "route_version_id": 62, "zones_armed": 5, "event": "TRIP_DISPATCHED" }

{ "reason": "customer cancelled" }

Alerts

?trip_id=512
?status=OPEN,ACKNOWLEDGED      // comma list

{
  "id": 9912, "alert_type": "ROUTE_DEVIATION", "severity": "WARN", "status": "OPEN",
  "message": "Vehicle off route (266m from corridor)",
  "metadata": {
    "distance_m": 266, "lat": 12.9312, "lng": 77.6221,
    "snapshot": { "soc": 61, "speed": 42.1, "odometer": 88213,
                  "ignition": true, "gps_fix": true, "heading": 118 }
  },
  "trip": { "id": 512, "trip_number": "...", "vehicle_imei": "...", "driver_user_id": "..." },
  "elapsed_s": 1840
}

Exceptions and cases

{ "alert_id": 9912,          // promote this alert
  "trip_id": 512,            // or raise a standalone case on a trip
  "owner_user_id": "ops-3",  // defaults to the caller
  "severity": "MEDIUM",
  "root_cause": "driver took the service road",
  "sla_due_dt": "2026-08-28T18:00:00Z",
  "notes": "..." }

{ "owner_user_id": "ops-3", "severity": "HIGH", "status": "CLOSED",
  "root_cause": "...", "notes": "..." }

Driver

Mounted at /api/v1/driver. Built for the driver app, which is offline-first, so the sync endpoint accepts a batch.

{ "trips": [ ... ] }

{ "events": [
  { "eventType": "START_TRIP", "tripId": 512, "clientTimestamp": "..." },
  { "eventType": "STOP_ARRIVE", "tripId": 512, "clientTimestamp": "...", "payload": { "tripStopId": 88 } }
] }

{ "results": [ { "ok": true, ... }, { "ok": false, "error": "..." } ],
  "synced": 1, "failed": 1 }

Devices, events, health

{ "items": [ { "device_id": "MT013-0007", "imei": "10000005000006",
               "vehicle_number": "KA53AB0191", "driver_name": "...",
               "driver_user_id": "drv-7" } ] }

{ "status": "ok", "service": "trip-core", "phase": "2-dispatch-api", "auth_mode": "jwt" }

Error codes

Every error is { "error": "<message>", "code": "<CODE>" }. The message is written for a human and is safe to show in the UI.

Lifecycle, end to end

One pass from an empty map to a completed trip, naming the call, the gate and the side effects at each step.

1. Draw the zones. In the Route Builder, each circle or polygon becomes a real geofence row, created through spring-custm-os with the caller's bearer token. Trip zones are born the same way every other geofence is, not inserted directly and unauthenticated as they once were.
   Spring answers business failures with 404

   Not 400, not 422. The message is in the body, so error handling branches on the message and not the status code. Anyone touching that path needs to know this before they "fix" it.

2. Create the route and attach everything. POST /routes, then the full-replace PUTs for waypoints, stops, checkpoints and no-go zones. Status is DRAFT throughout.
3. Plan. POST /routes/:id/plan asks OSRM for a road-snapped line and stores geometry, distance and duration. Check planned_via_osrm. The builder now previews the routed line before anything can be published.
4. Approve. POST /routes/:id/approve freezes a route_version and sets current_version_id. A different person from the author, unless the local self-approval flag is on. This is the moment the corridor becomes something a vehicle can be judged against.
5. Create the trip. POST /trips with an idempotency key. It pins the version and expands stops and checkpoints into trip_zone rows. Status PLANNED.
6. Assign. POST /trips/:id/assign attaches vehicle and driver, denormalises the IMEI, records assignment history. Status ASSIGNED.
7. Checklist. POST /trips/:id/checklist with status: PASSED and every required item checked.
8. Dispatch. POST /trips/:id/dispatch. Re-validates the assignment, checks the checklist, checks the zones are monitorable, checks no other live trip holds this IMEI. Then, in one transaction: status DISPATCHED, an audit row, and an outbox row for TRIP_DISPATCHED.
9. The outbox publisher picks it up. A 1 to 2 second poll reads unpublished rows, wraps each in an envelope and produces to trip.events partitioned by account_id:trip_id, then marks the row published. Publish failures leave the row unpublished so the next poll retries.
10. Execution activates the trip. It consumes TRIP_DISPATCHED, loads the trip from Postgres bound to the account the event claims, and writes fleetgo:trip:active:{IMEI}. From here every packet for that IMEI is evaluated.
11. Packets flow. First packet sets EN_ROUTE and emits TRIP_STARTED. Then corridor, no-go, checkpoints, stops and ETA, in that order, on every packet. See below.
12. Complete. When the trip reaches its end, execution sweeps any required checkpoint never reached into CHECKPOINT_MISSED, marks the trip COMPLETED, emits TRIP_COMPLETED and deletes the hot state. Cancel does the same teardown from the API side at any non-terminal status.

The event envelope

Everything on trip.events has the same shape, from both producers.

{
  "schema_version": "1.0",
  "event_id": "<uuid>",
  "event_type": "TRIP_DISPATCHED",
  "occurred_at": "2026-08-27T09:12:03.881Z",
  "account_id": 11,
  "trip_id": 512,
  "correlation_id": "<uuid>",
  "payload": { "imei": "...", "route_version_id": 62 }
}

Partition key is account_id:trip_id, so every event for one trip lands on one partition and stays ordered.

Per-packet evaluation

This is the whole of route-trip-execution. It consumes location-packet-topic, looks up the IMEI, and if there is an active trip it runs five evaluators in a fixed order.

Packet path

packet arrives (keyed by tags.IMEINumber)
  |
  +-- fleetgo:trip:notrip:{IMEI} set?  -> drop, no Postgres hit (60s negative cache)
  +-- fleetgo:trip:active:{IMEI}?      -> use it
  +-- miss                             -> rebuild from Postgres, or mark notrip
  |
  +-- offline gap > OFFLINE_GAP_MS?    -> reset all hysteresis streaks
  +-- first packet?                    -> status EN_ROUTE, emit TRIP_STARTED
  +-- freeze vitals snapshot for this packet (once, before the evaluators)
  |
  +-- 1. corridor      distance to the simplified polyline
  +-- 2. no-go         point in polygon, edge triggered
  +-- 3. checkpoints   point in polygon, sequence aware
  +-- 4. stops         point in polygon, debounced enter and exit
  +-- 5. ETA and delay (skipped once completed)
  |
  +-- reached the end? -> sweep missed checkpoints, COMPLETED, delete hot state

ETA runs last on purpose: it reads progress along the same corridor the checks above use, and a completed trip should not forecast an arrival it has already made.

Hysteresis and debounce

Nothing fires on a single fix. Every transition needs a streak, so one bad GPS sample cannot raise an alert.

Dedup and cooldown

An alert is identified by (account_id, alert_type, dedup_key) while its status is OPEN.

The write is insert-first with ON CONFLICT ... DO NOTHING against the partial unique index. If the insert lands, this is a new alert and it notifies. If it does not, an open alert already exists, and an UPDATE decides whether the cooldown has elapsed. The row itself reports whether this call is the one that re-notifies, and NOW() is fixed for the statement so the comparison is exact.

A SELECT-then-INSERT here would race: two packets for the same trip could both see no open alert and each insert one.

Who notifies what

Exactly one notifier per event, and the split is structural rather than a convention.

The vitals snapshot

Every alert freezes the vehicle's state into alert.metadata.snapshot: SOC, speed, odometer, ignition, GPS fix and heading. Computed once per packet, before the evaluators run, so they all see the same values. No migration was needed, because that column is already jsonb and the packet already carried the fields. The topic ships about 38 of them and execution declared seven.

Alert catalogue

The delivery shape

Trip alerts are bridged onto gps-notifications, the platform's existing inbox and FCM path, in the shape that path already expects.

{
  "accountId": 11,
  "alert_time": "27-08-2026 09:12:03",   // UTC, dd-MM-yyyy HH:mm:ss
  "alert_time_dt": 1756285923881,
  "latitude": 12.9312, "longitude": 77.6221,
  "message": "Vehicle off route (266m from corridor)",
  "trip_id": 512, "trip_number": "TRP-...",
  "alert_type": "ROUTE_DEVIATION",
  "tags": { "IMEINumber": "...", "type": "trip_alert",
            "event_type": "ROUTE_DEVIATION", "trip_id": 512 },
  "payload": { ... }
}

notification-service filters on tags.type == "trip_alert", resolves users by IMEI, applies their preference keys and delivers.

Topics, keys and ownership

Kafka topics

Consumer groups

Separate groups, so trip lag never blocks geofence consumption. Retries are bounded by HANDLER_MAX_ATTEMPTS (3) with a HANDLER_RETRY_BACKOFF_MS (250 ms) backoff, and anything that exhausts them goes to trip.dlq.

Redis keys

If Redis dies: execution rebuilds lost hot state from Postgres on the next packet, and the mgmt live views degrade to "no live position" rather than erroring. Neither service exits on a Redis error.

Feeds that land on the packet topic

The trip stack is strictly downstream of ingestion and never asks which OEM a packet came from. Dual-feed reconciliation, where two sources report the same IMEI, happens at the ingestion layer and none of its keys are read here.

Fields the trip stack actually uses: Latitude, Longitude, Speed, CurrentDate plus CurrentTime, the GPS fix flag, and tags.IMEINumber.

Who does what in the portal

One sidebar card, Trips, at /trip-dispatch. The old Route Management and Trip Exceptions pages are gone. Everything is a mode of the same card.

Dispatcher: get a vehicle on the road

1. Open Trips. Full-bleed map, corridors coloured by health: blue is fine, amber is late, red is off corridor or has alerts, grey means no fix.
2. Click Assign Trip. One search box across three numbered slots: 1 Route, 2 Vehicle, 3 Driver. Picking a route draws a dashed preview and fits the camera. Picking a vehicle auto-fills the driver from the active asset assignment.
3. Press dispatch. The portal runs create, assign, checklist and dispatch as four calls in sequence. A 409 ROUTE_NOT_APPROVED means somebody edited the route since it was published; the panel refetches and shows the new version.
4. Watch the floating panel. Fleet view has counts and a needs-attention list with in-place acknowledge and resolve. Hovering a vehicle gives an ID card. Selecting one gives per-trip ops: warnings, cancel, a link to detail, and a lazy overlay with start and end pins, checkpoint dots and shaded no-go areas.

Route author and approver

1. Open the builder. Search swaps between builder and catalogue; catalogue rows load routes editable, keeping endpoints, zones, corridor and mid shape points.
2. Draw. Checkpoints come out as a lettered A, B, C series with a connector and place names resolved by geocoder, written into the zone name on save. Rider radius is fixed at 50 m.
3. Preview. The builder shows the routed line before anything can be published, and refuses to publish checkpoints no vehicle can reach.
4. Press Publish. One button: plan through OSRM, then approve. A 403 from self-approval is caught and shown as "awaiting approval" rather than an error.
5. A second person opens the same route and presses Approve as-is. That button is gated on the role tiers that hold route:approve.

Support and ops lead

• Alerts and Cases merges the old exceptions page. A case is an alert row with a case status, so promoting an alert does not copy it anywhere.
• Opening an alert shows what the vehicle was doing at the moment it fired, from the frozen vitals snapshot, plus how far into the trip it was.
• The mobitrasupport tier can see and triage. It cannot dispatch and cannot approve.

Driver

The driver app reads GET /api/v1/driver/trips, which scopes to the token subject, and posts actions to driver-events, or a whole batch to /driver/sync when it has been offline. Every write carries an idempotency key, because an offline-first client retries.

UAT rollout, in order

Written for the two standalone services. The older runbook in geofencing/UAT_DEPLOY.md describes the hosted-inside-geofencing shape and should not be followed for these two.

0. Once, on the VM

sudo mkdir -p /root/mobitra-uat-compose-files/apins/route-trip-mgmt \
              /root/mobitra-uat-compose-files/kafka/route-trip-execution

Copy each repo's deploy/uat/docker-compose.yaml into its directory, and put the secret in a .env beside the mgmt one:

TRIP_JWT_SECRET=<byte identical to spring-custm-os app.usermanagement.secretkey>
DATABASE_URL=postgresql://...@164.52.207.108:5432/usermanagement

Leave the image tags as REPLACE_ME. The first deploy rewrites them.

Directory placement is meaningful. mgmt goes under apins/ because it serves HTTP. Execution goes under kafka/, the same shelf as notification and status-info, because it is a pure consumer: no ports, no Kong route, no nginx vhost. Nothing reaches it, it reaches the bus.

1. Kafka topics

sudo docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --if-not-exists --topic trip.events --partitions 6 --replication-factor 1
sudo docker exec kafka kafka-topics --bootstrap-server localhost:9092 \
  --create --if-not-exists --topic trip.dlq --partitions 1 --replication-factor 1

Confluent packaging drops the .sh, so the binary is kafka-topics. The kafka-topics.sh form in the older geofencing runbook is the Apache distribution's name and comes back "not found" on this image.

2. Schema, before any container boots

Run the migrate_uat job in route-trip-mgmt. It prints migrate status, applies, then prints status again, so the job log is the record of what the database now contains. Expect 5 migrations and 13 tables on a fresh database.

3. Deploy, execution first

build_image_uat then deploy_image_uat, in route-trip-execution first, then route-trip-mgmt. Both manual. Both gate on health and roll the image tag back on failure.

Execution first because it has no inbound surface. If it crash-loops, nothing else has changed.

4. Kong

A=http://localhost:8001
curl -s -X PUT $A/services/mobitra-uat-trip-service \
  -d name=mobitra-uat-trip-service -d url=http://route-trip-mgmt-container:8100
curl -s -X PUT $A/routes/mobitra-uat-trip-route \
  -d name=mobitra-uat-trip-route -d 'paths[]=/fleet-trip' -d strip_path=true \
  -d 'protocols[]=http' -d 'protocols[]=https' -d service.name=mobitra-uat-trip-service
curl -s -X POST $A/routes/mobitra-uat-trip-route/plugins -d name=cors \
  -d 'config.origins[]=https://web-uat.testmbtrsas.com' \
  -d 'config.methods[]=GET' -d 'config.methods[]=POST' -d 'config.methods[]=PUT' \
  -d 'config.methods[]=PATCH' -d 'config.methods[]=DELETE' -d 'config.methods[]=OPTIONS' \
  -d 'config.headers[]=Content-Type' -d 'config.headers[]=Authorization' \
  -d 'config.headers[]=Idempotency-Key' -d 'config.headers[]=X-Account-Id' \
  -d config.credentials=true -d config.max_age=3600
curl -s -X POST $A/routes/mobitra-uat-trip-route/plugins -d name=jwt \
  -d config.key_claim_name=iss -d 'config.claims_to_verify[]=exp' \
  -d 'config.header_names[]=authorization' -d config.run_on_preflight=true

The Kong service points at the container by name rather than at an nginx hostname. The sibling services all go Kong, then nginx, then container, which is a hop that buys nothing here and would need a new vhost baked into the nginx image. nginx needs no change at all: proxy.testmbtrsas.com already forwards every path to Kong.

Idempotency-Key must be in the CORS allowed headers or four endpoints break from the browser and work from curl, which is a confusing bug to chase.

5. Portal, last

REACT_APP_TRIP_CORE_URL=https://proxy.testmbtrsas.com/fleet-trip

CRA bakes environment variables into the bundle at build time, so a portal built before the Kong route exists is a portal pointing at a 404. Build after step 4, not before.

Rollback

CI and CD jobs

Both repos build on branch UAT only, on the mobitra-uat runner, and every job is when: manual.

The health gates

Secrets

CI variables would be the tidier home, but mobitra_developer2 is a Developer on these projects and the variables API answers 403, so they cannot be set from the repo side. The VM .env file is therefore the primary source and CI variables are the override if someone with Maintainer adds them later. Either way the secret never enters git. If neither exists the job writes a template with FILL_ME, tells you exactly what to put in it, and exits 1.

Image build notes

• npm ci, not --omit=dev. The Prisma CLI is a devDependency and generate needs it. With --omit=dev, generate would not fail loudly: it would reach the network for a newer CLI major and produce a subtly wrong client in a build reporting success.
• OpenSSL is installed explicitly. The slim image does not ship it and the Prisma engine then mis-detects libssl and dies with an unparseable "Could not parse schema engine response".
• The build asserts @prisma/client imports and dist/index.js exists. An un-generated client imports fine and only dies when something queries, which in a container means a green start and a service that breaks on its first real call.
• CMD is node dist/index.js, not npm start. npm start would run migrations, and the deploy applies them out of band on purpose.

Configuration reference

route-trip-mgmt

route-trip-execution

The UAT compose file leaves every tuning constant commented out and at its code default, deliberately.

Verification and smoke tests

In order. Stop at the first failure.

1. The containers

docker exec route-trip-mgmt-container node -e \
  "fetch('http://localhost:8100/health').then(r=>r.text()).then(console.log)"
# expect: {"status":"ok","service":"trip-core","phase":"2-dispatch-api","auth_mode":"jwt"}

docker inspect -f '{{.State.Status}} restarts={{.RestartCount}}' route-trip-execution-container
# expect: running restarts=0

2. The consumer groups

docker exec kafka kafka-consumer-groups --bootstrap-server localhost:9092 \
  --describe --group trip-execution-location
docker exec kafka kafka-consumer-groups --bootstrap-server localhost:9092 \
  --describe --group trip-execution-trip-events
# expect both Stable with 1 member. Consumers take 15 to 20 s to join after a restart.

3. The schema

psql "$DATABASE_URL" -c "\dt route*"
psql "$DATABASE_URL" -c "select count(*) from route; select count(*) from trip;"
psql "$DATABASE_URL" -c \
  "select column_name, data_type from information_schema.columns
   where table_name='trip' and column_name like '%_start%';"
# expect: timestamp with time zone, not 'timestamp without time zone'

4. Through the gateway

curl -s -o /dev/null -w '%{http_code}\n' \
  https://proxy.testmbtrsas.com/fleet-trip/api/v1/routes
# expect 401 without a token. A 404 here means strip_path is wrong.

curl -s -H "Authorization: Bearer $TOKEN" \
  https://proxy.testmbtrsas.com/fleet-trip/api/v1/routes | head -c 300
# expect {"items":[...]}

5. One route, end to end

The portal path is: builder, draw, Publish, then a second user presses Approve as-is, then Assign Trip and dispatch. Watch for:

• planned_via_osrm: true on the plan response, if OSRM was provisioned. False means straight-line geometry got stored.
• zones_armed on the dispatch response matching what you drew.
• The trip appearing in GET /api/v1/trips/live with monitored: true within a couple of seconds. False means execution has not loaded it.

6. Scripted

Troubleshooting

Local development

# everything: postgres, redis, kafka, all services
cd local-native && ./run-native.sh up

# drive a real route over telemetry, firing every alert type
node local-dev/scripts/drive-route.js --route 101 --ride-sec 200

Per service

# route-trip-mgmt
npm ci && npx prisma generate
npm run dev            # tsx watch, :8100
npm test               # tsx --test, unit plus live tests that self-skip

# route-trip-execution
npm ci && npm run build
npm start              # node dist/index.js
npm test               # builds first, then node --test over dist

Local auth

TRIP_AUTH_MODE=header
curl -H 'X-Account-Id: 11' -H 'X-User-Id: bf-local' localhost:8100/api/v1/routes

Header mode defaults roleType to SuperAdmin so the scripts keep working. Pass X-Role-Type to exercise a narrower tier. TRIP_ALLOW_SELF_APPROVAL=true is needed locally because the rig creates and approves as the same user.

Portal

Login bf-local, account 11, Administrator. Structure changes need a re-login, because the sidebar structure is cached in localStorage. The login submit chain takes about 800 ms; do not navigate away early.

Things that look wrong and are not

Five decisions that read as sloppiness and are load-bearing. If you are going to push back on the design, push back here first.

1. The spatial primitive is duplicated on purpose

geofencing/point_in_polygon.js and route-trip-execution/src/utils/point_in_polygon.ts are the same maths. Two services in two repositories cannot import each other, so the copies are real.

They were proved identical before being separated: a differential over 106,751 generated cases found zero disagreements. Both repos now carry spatial_golden.json and replay it on every build, so a change to either that alters a single answer fails the build. "Keep in sync" used to be a comment. It is a test now.

2. The quirk corpus is a characterisation lock, not a specification

spatial_golden.json records 2297 cases of behaviour nobody would design on purpose:

• A falsy radius never matches, even at the exact centre.
• Polygon boundaries are half-open and direction-dependent, while circles are inclusive.
• Object-shaped coordinates return false down one branch and throw down the other.

3. The stop-notification predicate is a deliberate negation

tripExecutionNotifiesStop returns true when a stop's geofenceId is not a positive integer. That looks like an inverted condition. It is the exact negation of the geofencing stream's admission test, and that is what guarantees one notifier per stop and no double delivery.

Change one and the other must change with it. Drift one way is a silent drop, the other a duplicate.

4. HARD and SOFT do not change routing

They are runtime severity and nothing else. HARD maps to CRITICAL, SOFT to WARN. Same detection, same edge trigger, same cooldown. The planner does not know no-go zones exist and does not route around either kind. If someone expects avoidance, that is a feature request, not a bug.

5. TRIP_CODE_ROOT is inert

Still set in geofencing's Dockerfile and compose examples. Nothing reads it. Removing it touches deploy config for no gain, so it stays until something else is being changed there anyway.

Deliberately not done

Defects, fixed and open

Fixed

Open, flagged not fixed

Found while writing this

Three things surfaced during this pass that are not in any earlier document. All verified against the code on branch UAT.

$ npx tsx --test tests/osrm-coverage-guard.test.ts
ok degenerate Ok answer falls back to straight line
ok degenerate Ok answer is a hard error under ROUTING_ENGINE=osrm
ok a sane answer passes through untouched
# pass 3  fail 0

What needs DevOps

Shorter than it was. Three of the six items previously listed as blockers turned out not to be.

Still genuinely needed

No longer blockers

Open questions to answer before the schema step

1. What is TRIP_JWT_SECRET? Someone with the spring-custm-os config has to hand it over.
2. Does anyone object to _prisma_migrations gaining trip rows? It is safe, and it is still the one shared object. The owner of notification-service should hear it from us rather than from a warning.
3. Where does the OSRM repo live? osrm-india/ is not a git repository at all: no remote, no CI, one laptop. And the gateway has no authentication of any kind, which is correct on a private docker network and completely wrong for anything with a public address.

Document map

What to read for what, and which documents have gone stale.