Feat/realtime reproducible fixtures regeneration mbta tests subissue 17

README.md

@@ -225,4 +225,53 @@ Developed by [Simovi Lab](https://github.com/simovilab) for processing and manag
 
 ---
 
-For more information about GTFS, visit the [General Transit Feed Specification](https://gtfs.org/) website.
+For more information about GTFS, visit the [General Transit Feed Specification](https://gtfs.org/) website.
+
+
+
+---
+
+## Reproducible Sample Data
+
+This module includes **small, deterministic GTFS-Realtime fixtures** for testing and documentation purposes.  
+They allow developers to run the system and its unit tests without relying on live MBTA feeds or external network calls.
+
+These fixtures capture a **minimal snapshot of TripUpdate, VehiclePosition, and Alert entities**, and can be regenerated at any time from the local database.
+
+---
+
+### Fixture Location
+
+The reproducible sample data is stored under:
+
+gtfs/fixtures/
+
+├── trip_update_fixture.json
+
+├── vehicle_position_fixture.json
+
+└── alert_fixture.json
+
+
+Each file contains a few representative rows from the respective realtime tables, exported as JSON.
+
+---
+
+###  Regeneration Script
+
+Fixtures can be rebuilt at any time using the script:
+
+```bash
+python -m gtfs.scripts.regenerate_fixtures
+```
+---
+
+##  Running the Realtime Streamer (MBTA)
+
+After installation, no additional database configuration is required — the project uses **SQLite** by default for testing and development.  
+Once dependencies are installed and migrations have run, you can start streaming live data directly from the MBTA GTFS-Realtime feeds.
+
+Run the following command from the project root:
+
+```bash
+python -m gtfs.scripts.stream_mbta_feeds

feed/files/trip_updates_bytewax.json

@@ -0,0 +1,48 @@
+{
+  "header": {
+    "gtfs_realtime_version": "2.0",
+    "incrementality": "FULL_DATASET",
+    "timestamp": 1762132640
+  },
+  "entity": [
+    {
+      "id": "trip_FAKE_TRIP_001",
+      "trip_update": {
+        "timestamp": 1762132640,
+        "trip": {
+          "trip_id": "FAKE_TRIP_001",
+          "route_id": "FAKE_ROUTE_1",
+          "direction_id": 0,
+          "start_time": "01:17:20",
+          "start_date": "20251103",
+          "schedule_relationship": "SCHEDULED"
+        },
+        "vehicle": {
+          "id": "V001",
+          "label": "Test Vehicle",
+          "license_plate": "TEST123"
+        },
+        "stop_time_update": [
+          {
+            "stop_id": "STOP_A",
+            "arrival": {
+              "time": 1762132702
+            }
+          },
+          {
+            "stop_id": "STOP_B",
+            "arrival": {
+              "time": 1762132749
+            }
+          },
+          {
+            "stop_id": "STOP_C",
+            "arrival": {
+              "time": 1762132867
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

gtfs/fixtures/realtime_schema.json

@@ -0,0 +1,86 @@
+{
+  "entities": {
+    "feed_message": {
+      "primary_key": "id",
+      "fields": {
+        "id": "string",
+        "header": "feed_header",
+        "entity": "array<feed_entity>"
+      }
+    },
+    "feed_header": {
+      "primary_key": "header_id",
+      "fields": {
+        "header_id": "string",
+        "gtfs_realtime_version": "string",
+        "incrementality": "string",
+        "timestamp": "integer"
+      }
+    },
+    "feed_entity": {
+      "primary_key": "entity_id",
+      "fields": {
+        "entity_id": "string",
+        "is_deleted": "boolean",
+        "vehicle": "vehicle_position",
+        "trip_update": "trip_update",
+        "alert": "alert"
+      }
+    },
+    "vehicle_position": {
+      "primary_key": "id",
+      "fields": {
+        "id": "string",
+        "trip_id": "string",
+        "vehicle_id": "string",
+        "vehicle_label": "string",
+        "vehicle_license": "string",
+        "position_lat": "float",
+        "position_lon": "float",
+        "position_bearing": "float",
+        "timestamp": "integer",
+        "stop_id": "string"
+      },
+      "foreign_keys": {
+        "trip_id": "trip_update.trip_id"
+      }
+    },
+    "trip_update": {
+      "primary_key": "trip_update_id",
+      "fields": {
+        "trip_update_id": "string",
+        "trip_id": "string",
+        "vehicle_id": "string",
+        "stop_time_updates": "array<stop_time_update>",
+        "timestamp": "integer",
+        "delay": "integer"
+      }
+    },
+    "stop_time_update": {
+      "primary_key": "stop_time_update_id",
+      "fields": {
+        "stop_time_update_id": "string",
+        "stop_sequence": "integer",
+        "stop_id": "string",
+        "arrival_time": "integer",
+        "departure_time": "integer",
+        "schedule_relationship": "string"
+      }
+    },
+    "alert": {
+      "primary_key": "alert_id",
+      "fields": {
+        "alert_id": "string",
+        "active_period": "array<period>",
+        "informed_entity": "array<entity_selector>",
+        "cause": "string",
+        "effect": "string",
+        "url": "string",
+        "header_text": "string",
+        "description_text": "string"
+      }
+    }
+  },
+  "version": "1.0.0",
+  "spec": "GTFS Realtime v2.0"
+}

gtfs/fixtures/sample_alerts.json

@@ -0,0 +1,10 @@
+[
+  {
+    "alert_id": "A001",
+    "route_id": "R01",
+    "header_text": "Service interruption on R01",
+    "description_text": "Maintenance from 14:00 to 18:00",
+    "severity": "moderate",
+    "timestamp": 1762132640
+  }
+]

gtfs/fixtures/sample_trip_updates.json

@@ -0,0 +1,48 @@
+{
+  "header": {
+    "gtfs_realtime_version": "2.0",
+    "incrementality": "FULL_DATASET",
+    "timestamp": 1762132640
+  },
+  "entity": [
+    {
+      "id": "trip_FAKE_TRIP_001",
+      "trip_update": {
+        "timestamp": 1762132640,
+        "trip": {
+          "trip_id": "FAKE_TRIP_001",
+          "route_id": "FAKE_ROUTE_1",
+          "direction_id": 0,
+          "start_time": "01:17:20",
+          "start_date": "20251103",
+          "schedule_relationship": "SCHEDULED"
+        },
+        "vehicle": {
+          "id": "V001",
+          "label": "Test Vehicle",
+          "license_plate": "TEST123"
+        },
+        "stop_time_update": [
+          {
+            "stop_id": "STOP_A",
+            "arrival": {
+              "time": 1762132702
+            }
+          },
+          {
+            "stop_id": "STOP_B",
+            "arrival": {
+              "time": 1762132749
+            }
+          },
+          {
+            "stop_id": "STOP_C",
+            "arrival": {
+              "time": 1762132867
+            }
+          }
+        ]
+      }
+    }
+  ]
+}

gtfs/fixtures/sample_vehicle_positions.json

@@ -0,0 +1,10 @@
+[
+  {
+    "vehicle_id": "V001",
+    "trip_id": "FAKE_TRIP_001",
+    "latitude": 9.93,
+    "longitude": -84.08,
+    "speed": 15,
+    "timestamp": 1762132640
+  }
+]