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.
• index.ts: continuous collector for multiple routes/stops.
• lib/storage.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.

Requirements

• Bun 1.x+
• Network access to the configured GTFS/JSON upstream APIs

Quick Start

bun install
bun run typecheck

Run single stop/route terminal tracker:

bun run bus-tracker-json.ts

Run with custom stop and route IDs:

bun run bus-tracker-json.ts --stop 1571 --route 125

Run background collection pipeline:

bun run start

Environment

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.

Scripts

• bun run start: collector entrypoint (index.ts).
• bun run typecheck: TypeScript no-emit check.

Notes

• Generated parquet files are intentionally ignored by git (data/**/*.parquet).
• The collector 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.