Bikun Tracker Location Service
ETA and broadcast layer for the Bikun ecosystem. It listens to the live shuttle stream, predicts arrival time, and serves the data back as an API for the frontend.
At a Glance
| Area | Details |
|---|
| Role | ETA prediction and live-stream bridge |
| Runtime | Python 3.10 + FastAPI |
| Model | CatBoost Regressor |
| Target | Remaining Time to Arrival in seconds |
| Input stream | Backend V2 WebSocket |
| Output | REST JSON responses |
What It Does
- Consumes live coordinates from Backend V2.
- Predicts ETA using a CatBoost-based model.
- Performs chain prediction for the remaining stops.
- Exposes APIs for single-bus, multi-bus, and all-stop ETA.
- Keeps the prediction pipeline separate from the location ingest layer.
Service Split
| Component | Responsibility |
|---|
master | Polls the upstream vehicle API and publishes updates to Redis |
slave | Subscribes to Redis and broadcasts updates via WebSocket |
client | Visual dashboard used to observe live fleet state |
Data Flow
- The backend or upstream vehicle feed changes.
- The master process polls and republishes the latest state.
- The slave process picks up the update and keeps WebSocket clients in sync.
- The client dashboard renders status, coordinates, speed, and trip metrics.
Project Structure
| Path | Responsibility |
|---|
master/src/app/main.py | Polls the upstream API and publishes to Redis |
slave/src/app/main.py | Subscribes to Redis and broadcasts to clients |
client/index.html | Fleet monitoring dashboard |
client/src | Browser app code and styling |
Key Components
master/src/app/main.py: adaptive polling, Redis publishing, bearer-token access.slave/src/app/main.py: WebSocket server, connection handling, and client broadcast.client/index.html: live dashboard with connection state, fleet cards, and trip metrics.
Operational Notes
Infrastructure
| Item | Value |
|---|
| Container registry | 638207107223.dkr.ecr.ap-southeast-1.amazonaws.com |
| Image name | bikun-tracker-v2-backend |
| Production tag | stable |
| Staging tag | latest |
| Region | ap-southeast-1 |
Environment Variables
| Key | Purpose | Notes |
|---|
REDIS_HOST | Redis hostname | Master process dependency |
REDIS_PORT | Redis port | Master process dependency |
REDIS_PASSWORD | Redis password | Secret value, not committed |
MCEASY_API_TOKEN | Upstream API token | Secret value, not committed |
Notes
- The service treats ETA as a separate concern from raw tracking so the model can evolve independently.
- Redis is the transport between the polling side and the broadcast side.
- The current docs describe a split deployment, so the dashboard, broadcast layer, and polling layer can scale independently.