# Skopje Bus Tracker

Real-time bus tracking for Skopje public transport. Modular system supporting any stop and route.

## Quick Start

```bash
npm install
npm run setup-gtfs  # Download latest GTFS data
npm run web
```

Open **http://localhost:3000**

## Features

- **Fully Modular Web Interface**: Select any stop and route via UI controls or URL parameters
- **Dynamic Tracking**: Change stops/routes without restarting the server
- Interactive map with live vehicle positions
- Real-time arrivals with delays
- 5-second auto-refresh (web), 10-second (terminal)
- CLI arguments for terminal tracker
- Configurable defaults via [config.ts](config.ts)
- Shareable URLs with stop/route parameters

## Commands

```bash
npm run setup-gtfs         # Download GTFS data
npm run find -- --stop "american"  # Find stop IDs by name
npm run find -- --route "7"        # Find route IDs by number/name
npm run web                # Web interface at http://localhost:3000
npm run tracker            # Terminal interface (default)
npm run tracker -- --stop 1571 --route 125  # Custom stop/route
npm start                  # Same as web
```

### Finding Stop and Route IDs

Not sure which Stop ID or Route ID to use? Use the find command:

```bash
# Find stops by name (case-insensitive)
npm run find -- --stop "american"
npm run find -- --stop "центар"

# Find routes by number or name
npm run find -- --route "7"
npm run find -- --route "линија"
```

### Web Interface Usage

1. **Default tracking**: Open `http://localhost:3000` (loads default stop/route, can be changed in UI)
2. **Direct URL**: `http://localhost:3000?stopId=1571&routeId=125` (bookmarkable)
3. **Change tracking**: Use the controls at the top to enter different Stop ID and Route ID
4. **Share**: Copy URL after selecting a stop/route to share with others

### CLI Arguments

Terminal tracker supports custom stop and route:

```bash
npm run tracker -- --stop <stopId> --route <routeId>
npm run tracker -- --help
```

### API Endpoints

Query parameters for custom tracking:

```
GET /api/config?stopId=1571&routeId=125
GET /api/arrivals?stopId=1571&routeId=125
GET /api/vehicles?routeId=125
```

## Configuration

Edit [config.ts](config.ts) to set defaults:

```typescript
export const config: AppConfig = {
  defaultStop: {
    stopId: '1571',
    name: 'АМЕРИКАН КОЛЕЏ-КОН ЦЕНТАР',
    lat: 41.98057556152344,
    lon: 21.457794189453125,
  },
  defaultRoute: {
    routeId: '125',
    shortName: '7',
    name: 'ЛИНИЈА 7',
  },
  server: {
    port: 3000,
  },
  tracking: {
    refreshInterval: {
      web: 5000,     // 5 seconds
      terminal: 10000, // 10 seconds
    },
    minutesAhead: 90,
  },
};
```

## Structure

```
bus/
├── config.ts              # Configuration (stops, routes, timing)
├── setup-gtfs.ts         # GTFS data downloader
├── find-stops-routes.ts  # Helper to find Stop/Route IDs
├── server.ts             # Web server (modular API)
├── bus-tracker-json.ts   # Terminal tracker (CLI args)
├── lib/gtfs.ts          # GTFS loader
├── public/index.html    # Frontend (modular UI)
└── gtfs/                # Static data (auto-downloaded)
```

## Stack

- Node.js + Express + TypeScript
- Leaflet.js + OpenStreetMap
- GTFS + GTFS-RT Protocol Buffers

## License

MIT