OpenJSP Bus Tracker

Real-time Skopje public transport tracking with Bun, GTFS/GTFS-RT ingestion, parquet persistence, and optional S3-compatible segment upload.

What Is In This Repo

bus-tracker-json.ts: terminal tracker for one stop + one route.
background-tracker.ts: continuous collector for multiple routes/stops.
lib/database.ts: parquet write layer with rolling segments and optional S3 upload.
lib/gtfs.ts: GTFS CSV loading helpers.
config.ts: API base URL, defaults, and tracker timing.

bun install
bun run typecheck

Run single stop/route terminal tracker:

bun run tracker

Run with custom stop and route IDs:

bun run tracker -- --stop 1571 --route 125

Run background collection pipeline:

bun run track

Copy .env.example to .env and adjust values as needed.

Key variables:

PARQUET_DIR: local output directory for parquet files.
PARQUET_ROLL_MINUTES: segment rotation interval.
SAVE_ALL_VEHICLE_SNAPSHOTS: save full raw vehicle feed snapshots.
SAVE_ALL_VEHICLE_POSITIONS: persist all vehicle positions (not only route-matched).
S3_ENABLED: enable object storage upload.
S3_BUCKET, S3_REGION, S3_ENDPOINT, S3_PREFIX: object storage target.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY: object storage credentials.
S3_DELETE_LOCAL_AFTER_UPLOAD: delete local parquet after successful upload.
S3_UPLOAD_RETRIES, S3_UPLOAD_RETRY_BASE_MS: upload retry behavior.

Generated parquet files are intentionally ignored by git (data/*.parquet).
The background tracker rotates segments and uploads each closed segment when S3 is enabled.
On process shutdown (SIGINT/SIGTERM), writers are flushed so the current segment is finalized.