From a52482256abb9b66c13a8300e82c2869bf19e89f Mon Sep 17 00:00:00 2001
From: Andrej Mickov <andrej@ferdzo.xyz>
Date: Sat, 7 Feb 2026 11:11:31 +0100
Subject: [PATCH] Initial commit

---
 README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..45a2db7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# 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