Bikun Tracker Backend V2

Real-time backend for the Bikun shuttle system. It receives live GPS webhooks, keeps the bus state in sync, detects halte transitions and lap history, and serves both the public dashboard and internal admin workflows.

At a Glance

Area	Details
Role	Ingestion, state management, real-time broadcast, and admin APIs
Runtime	Go 1.23 with net/http
Database	PostgreSQL 16 via pgxpool
Auth	UI CAS JWT + API key for admin writes
Real-time channel	POST /wh and WS /ws
Deployment	AWS ECR + Pusilkom
Main consumers	Frontend dashboard, admin tools, ETA service

What It Does

• Accepts Damri GPS updates through a webhook.
• Normalizes bus coordinates and updates runtime state.
• Detects halte visits, route color, and lap history.
• Broadcasts live state to connected clients over WebSocket.
• Exposes protected CRUD and history endpoints for admins.

Request Flow

1. The GPS provider posts a location event to POST /wh.
2. The backend resolves the bus, updates coordinates, and applies halte logic.
3. Runtime caches are refreshed so the next WebSocket tick has current state.
4. Connected dashboards receive the latest snapshot from WS /ws.
5. Admin tools use REST endpoints for bus management and history review.

API Surface

Method	Endpoint	Auth	Purpose
POST	/auth/sso/login	Public	Login with UI CAS ticket
POST	/auth/refresh	Public	Refresh access token
GET	/auth/me	Bearer JWT	Get current user profile
GET	/bus	Public	List buses
POST	/bus	API key	Create a bus
PUT	/bus/:id	API key	Update a bus
DELETE	/bus/:id	API key	Delete a bus
GET	/bus/lap-history	API key	Filter lap history
GET	/bus/:imei/lap-history	Public	Lap history by bus
GET	/bus/:imei/active-lap	Public	Current active lap
WS	/ws	Public	Live coordinate broadcast
POST	/wh	Public	Receive GPS updates
POST	/bus/test-lap-data	Public	Seed debug lap data
GET	/bus/check-table	Public	Debug table existence check

Core Modules

• main.go: bootstrap, config loading, database pool, route wiring, and server startup.
• app/auth: CAS login, token issuance, refresh flow, and auth helpers.
• app/bus: bus state, halte detection, route logic, lap tracking, and WebSocket handling.
• app/damri: provider integration and payload normalization.
• app/rm: lane detection model integration.
• db/migrations: schema evolution and historical data changes.
• utils/middleware: CORS, JWT, logging, route parsing, and access control.

Data Model

Entity	Purpose
bus	Registered fleet data
bus_stop	Halte definitions and fixed coordinates
bus_lap_history	Lap transitions and visit history
user	Authenticated users and admin roles

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
DAMRI_API	Damri GPS API base URL	External provider endpoint
DAMRI_LOGIN_USERNAME	Damri username	Secret value, not committed
DAMRI_LOGIN_PASSWORD	Damri password	Secret value, not committed
WS_URL	External GPS WebSocket URL	Used by the live feed
RM_API	Lane detection service URL	ML service dependency
PRINT_CSV_LOGS	Enable CSV log forwarding	Optional debug mode
PORT	HTTP port	Default server port
DB_HOST	PostgreSQL host	Database connection
DB_NAME	PostgreSQL database name	Database connection
DB_USER	PostgreSQL username	Database connection
DB_PASSWORD	PostgreSQL password	Secret value, not committed
DB_PORT	PostgreSQL port	Database connection
WS_UPGRADE_WHITELIST	Allowed WebSocket origins	Comma-separated list
JWT_EXPIRY_IN_DAYS	Access token lifetime	Token policy
JWT_REFRESH_EXPIRY_IN_DAYS	Refresh token lifetime	Token policy
JWT_SECRET_KEY	JWT signing secret	Secret value, not committed
ADMIN_API_KEY	Admin endpoint key	Secret value, not committed

Next Sections

• Frontend V2
• ETA Service
• Location Service
• Admin