# 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.

## Requirements

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

## Quick Start

```bash
bun install
bun run typecheck
```

Run single stop/route terminal tracker:

```bash
bun run tracker
```

Run with custom stop and route IDs:

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

Run background collection pipeline:

```bash
bun run track
```

## 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`: alias for the terminal tracker.
- `bun run tracker`: terminal tracker.
- `bun run track`: background collector.
- `bun run typecheck`: TypeScript no-emit check.

## Notes

- 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.