feat: publish route_id and start_date in the driver-reported TripDescriptor

ARCHITECTURE.md

@@ -272,7 +272,7 @@ When a driver application reports a vehicle position, the following sequence occ
 
 1. Consumer sends `GET /gtfs-rt/vehicle-positions` (optionally `?format=json`).
 2. Handler calls `tracker.ActiveVehicles()`, which reads the in-memory map and returns only vehicles whose `UpdatedAt` is newer than `time.Now().Add(-maxAge)`.
-3. `buildFeed()` constructs a `gtfs.FeedMessage` with a `FULL_DATASET` header and one `VehiclePosition` entity per active vehicle. `TripDescriptor` is omitted when `trip_id` is empty.
+3. `buildFeed()` constructs a `gtfs.FeedMessage` with a `FULL_DATASET` header and one `VehiclePosition` entity per active vehicle. `TripDescriptor` carries `trip_id`, `route_id` and `start_date` as sent, and is omitted when both `trip_id` and `route_id` are empty.
 4. Response is serialized with `proto.Marshal` (protobuf, default) or `protojson.Marshal` (`?format=json`) and written with the appropriate `Content-Type`.
 
 ### 5.3 Sequence Diagrams
@@ -361,7 +361,9 @@ Authentication is per endpoint, not global:
 ```json
 {
   "vehicle_id":  "bus-42",
-  "trip_id":     "route-5",
+  "trip_id":     "t_5_0830",
+  "route_id":    "5",
+  "start_date":  "20260715",
   "latitude":    -1.2921,
   "longitude":   36.8219,
   "bearing":     90.0,
@@ -374,7 +376,9 @@ Authentication is per endpoint, not global:
 | Field | Required | Description |
 |-------|----------|-------------|
 | `vehicle_id` | ✅ | Non-empty string identifier for the vehicle. |
-| `trip_id` | ❌ | Optional trip identifier; empty string is allowed and results in no `TripDescriptor` in the feed. |
+| `trip_id` | ❌ | GTFS `trip_id`. Empty when the driver only knows the route; never a route id. Max 100 characters. |
+| `route_id` | ❌ | GTFS `route_id`. Max 100 characters. |
+| `start_date` | ❌ | Service date `YYYYMMDD`; accepted only with `trip_id` or `route_id`. |
 | `latitude` | ✅ | Decimal degrees, range `-90` to `90`. Cannot be `0` when `longitude` is also `0`. |
 | `longitude` | ✅ | Decimal degrees, range `-180` to `180`. |
 | `bearing` | ❌ | Direction of travel in degrees. |
@@ -389,6 +393,11 @@ Authentication is per endpoint, not global:
 - `latitude` must be in the range `-90` to `90`. Error: `latitude must be between -90 and 90`.
 - `longitude` must be in the range `-180` to `180`. Error: `longitude must be between -180 and 180`.
 - `timestamp` must be positive. Error: `timestamp must be positive`.
+- `trip_id` is capped at 100 characters. Error: `trip_id must be at most 100 characters`.
+- `route_id` is capped at 100 characters. Error: `route_id must be at most 100 characters`.
+- `start_date` must match `YYYYMMDD`. Error: `start_date must be YYYYMMDD`.
+- `start_date` must be a real calendar date. Error: `start_date must be a valid YYYYMMDD date`.
+- `start_date` requires `trip_id` or `route_id` to be non-empty. Error: `start_date requires trip_id or route_id`.
 
 **Decoding behavior:**
 
@@ -408,7 +417,7 @@ The feed is generated on every request entirely from the in-memory Tracker — t
 - **Header:** GTFS-Realtime version `2.0`, incrementality `FULL_DATASET`, current Unix timestamp.
 - One `FeedEntity` per active vehicle (`id = vehicle_id`).
 - Each entity carries a `VehiclePosition` with `Position` (latitude, longitude, bearing, speed), a `VehicleDescriptor` (`id` only), and an epoch `Timestamp` copied from the incoming report.
-- A `TripDescriptor` (`trip_id`) only when `trip_id` is non-empty.
+- A `TripDescriptor` with `trip_id`, `route_id` and `start_date` as reported, only when `trip_id` or `route_id` is non-empty.
 
 Consumers can request JSON encoding by appending `?format=json` to the URL. The default response is binary protobuf (`application/x-protobuf`). Any other `format` value falls back to protobuf because only the exact string `json` is checked.
 

README.md

@@ -201,7 +201,7 @@ The server produces a standard `FeedMessage` containing `VehiclePosition` entiti
 ```protobuf
 vehicle {
   trip {
-    trip_id: "route_5_0830"
+    trip_id: "t_5_0830"
     route_id: "5"
     start_time: "08:30:00"
     start_date: "20260715"
@@ -245,7 +245,9 @@ Each location report is a single point sent directly from the Android app as it
 ```json
 {
   "vehicle_id": "vehicle-042",
-  "trip_id": "route_5_0830",
+  "trip_id": "t_5_0830",
+  "route_id": "5",
+  "start_date": "20260715",
   "latitude": -1.2921,
   "longitude": 36.8219,
   "bearing": 180.0,
@@ -257,6 +259,8 @@ Each location report is a single point sent directly from the Android app as it
 
 The server updates its in-memory state with the latest position and persists the point to the database. Points older than a configurable staleness threshold (default 5 minutes) are excluded from the GTFS-RT feed.
 
+> `trip_id`, `route_id` and `start_date` are all optional. `trip_id` is the GTFS `trip_id` and must be left empty when the driver only knows the route — never send a route id in `trip_id`. `route_id` is the GTFS `route_id`; when `trip_id` is empty it is the only thing a consumer can match on. `start_date` is the service date, `YYYYMMDD`, and is accepted only alongside `trip_id` or `route_id`. The feed's `TripDescriptor` carries exactly the fields that were sent, and is omitted entirely when both `trip_id` and `route_id` are empty.
+
 **`POST /api/v1/locations` validation and error contract**
 
 The ingest endpoint performs strict request validation before writing data:
@@ -265,6 +269,7 @@ The ingest endpoint performs strict request validation before writing data:
 - The request body must contain exactly one JSON object.
 - Unknown JSON fields are rejected.
 - Standard payload validation still applies (`vehicle_id`, coordinates, timestamp).
+- `trip_id` and `route_id` are capped at 100 characters; `start_date` must be a real `YYYYMMDD` date.
 
 Response codes:
 
@@ -278,7 +283,7 @@ Examples:
 # Valid request
 curl -i -X POST http://localhost:8080/api/v1/locations \
   -H "Content-Type: application/json" \
-  -d '{"vehicle_id":"bus-1","trip_id":"route-5","latitude":-1.29,"longitude":36.82,"timestamp":1752566400}'
+  -d '{"vehicle_id":"bus-1","route_id":"5","latitude":-1.29,"longitude":36.82,"timestamp":1752566400}'
 
 # Invalid content type -> 415
 curl -i -X POST http://localhost:8080/api/v1/locations \

cmd/simulator/main.go

@@ -18,6 +18,7 @@ import (
 
 type locationReport struct {
 	VehicleID string  `json:"vehicle_id"`
+	RouteID   string  `json:"route_id"`
 	Latitude  float64 `json:"latitude"`
 	Longitude float64 `json:"longitude"`
 	Bearing   float64 `json:"bearing"`
@@ -64,9 +65,10 @@ func main() {
 		wg.Add(1)
 		vehicleID := fmt.Sprintf("sim-vehicle-%03d", i+1)
 		route := routes[i%len(routes)]
+		routeID := fmt.Sprintf("sim-route-%d", i%len(routes)+1)
 		go func() {
 			defer wg.Done()
-			simulateVehicle(ctx, client, *baseURL, vehicleID, route, *interval, s)
+			simulateVehicle(ctx, client, *baseURL, vehicleID, route, routeID, *interval, s)
 		}()
 	}
 	wg.Wait()
@@ -80,7 +82,7 @@ func main() {
 	log.Printf("simulation complete: %d requests, %d ok, %d failed, avg=%dms", ok+fail, ok, fail, avgMS)
 }
 
-func simulateVehicle(ctx context.Context, client *http.Client, baseURL, vehicleID string, route []Waypoint, interval time.Duration, s *stats) {
+func simulateVehicle(ctx context.Context, client *http.Client, baseURL, vehicleID string, route []Waypoint, routeID string, interval time.Duration, s *stats) {
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 
@@ -122,6 +124,7 @@ func simulateVehicle(ctx context.Context, client *http.Client, baseURL, vehicleI
 
 			report := locationReport{
 				VehicleID: vehicleID,
+				RouteID:   routeID,
 				Latitude:  pos.Lat,
 				Longitude: pos.Lon,
 				Bearing:   brng,

cmd/simulator/main_test.go

@@ -151,6 +151,7 @@ func TestInterpolate(t *testing.T) {
 func TestLocationReportJSONRoundTrip(t *testing.T) {
 	report := locationReport{
 		VehicleID: "sim-vehicle-001",
+		RouteID:   "sim-route-1",
 		Latitude:  -1.2864,
 		Longitude: 36.8172,
 		Bearing:   327.5,
@@ -166,7 +167,7 @@ func TestLocationReportJSONRoundTrip(t *testing.T) {
 	var raw map[string]json.RawMessage
 	require.NoError(t, json.Unmarshal(data, &raw))
 
-	expectedFields := []string{"vehicle_id", "latitude", "longitude", "bearing", "speed", "accuracy", "timestamp"}
+	expectedFields := []string{"vehicle_id", "route_id", "latitude", "longitude", "bearing", "speed", "accuracy", "timestamp"}
 	for _, field := range expectedFields {
 		assert.Contains(t, raw, field, "missing JSON field %q", field)
 	}
@@ -176,6 +177,8 @@ func TestLocationReportJSONRoundTrip(t *testing.T) {
 	var decoded locationReport
 	require.NoError(t, json.Unmarshal(data, &decoded))
 	assert.Equal(t, report, decoded)
+	assert.Equal(t, "sim-route-1", decoded.RouteID)
+	assert.Contains(t, string(data), `"route_id":"sim-route-1"`)
 }
 
 func TestRouteWraparound(t *testing.T) {
@@ -293,7 +296,7 @@ func TestSimulateVehicle(t *testing.T) {
 	ctx, cancel := context.WithTimeout(context.Background(), 350*time.Millisecond)
 	defer cancel()
 
-	simulateVehicle(ctx, server.Client(), server.URL, "test-sim", route, 100*time.Millisecond, s)
+	simulateVehicle(ctx, server.Client(), server.URL, "test-sim", route, "sim-route-1", 100*time.Millisecond, s)
 
 	assert.Eventually(t, func() bool {
 		return s.succeeded.Load() >= 2

docs/development.md

@@ -367,7 +367,8 @@ curl -X POST http://localhost:8080/api/v1/locations \
   -H 'Content-Type: application/json' \
   -d '{
     "vehicle_id": "demo-vehicle-42",
-    "trip_id": "route-5-0830",
+    "trip_id": "t_5_0830",
+    "route_id": "5",
     "latitude": -1.2921,
     "longitude": 36.8219,
     "bearing": 180,