Main Website - Documentation
🔎 Background
Overview
Bikun Tracker Frontend V2 is the client-side web interface for the Universitas Indonesia shuttle bus tracking system. It consumes data from Backend V2 via WebSocket connections for live location updates, and utilizes REST APIs for static data and authentication.
Stakeholders
- Users: UI students and staff (monitoring real-time bus locations), Bikun Administrators (accessing reporting dashboards and schedules).
- Upstream Dependencies: Bikun Tracker Backend V2 (providing REST API endpoints and /ws WebSocket), UI SSO (for authentication).
- Downstream Consumers: End-user devices (Mobile and desktop web browsers).
Scope & Boundaries
In Scope
- Real-time interactive map rendering using Leaflet.
- Maintaining continuous WebSocket connections to receive live bus GPS coordinates.
- User interface for bus schedule management and reporting.
- Client-side authentication integration utilizing UI CAS SSO.
- Local state management for bus movement interpolation.
Out of Scope
- Heavy computational processing for lane detection or lap history (strictly backend responsibility).
- Relational data storage or direct interaction with PostgreSQL.
- Ingesting raw hardware GPS data from Damri.
⚙️ Architecture & Design
System Diagram
Architecture Decisions (ADRs)
- Language/Framework: React 19 + TypeScript built with Vite
- Routing: TanStack React Router
- State Management: Zustand
- Styling & UI: Tailwind CSS v4
- Map Visualization: Leaflet
💻Technical Specifications
API Documentation
Data Model/Schema
Project Structure
bikuntracker-frontend-v2
┣ public
┃ ┣ assets
┃ ┣ favicon
┃ ┣ robots.txt
┃ ┗ service-worker.js
┣ src
┃ ┣ assets
┃ ┃ ┣ bus-stops/
┃ ┃ ┗ icons/
┃ ┣ common
┃ ┃ ┣ components/ (Reusable UI: map, modal, drawer, navbar)
┃ ┃ ┣ constants/ (Absolute static data: busSchedule, routes, map config)
┃ ┃ ┣ data/ (Bus stops and routes definitions)
┃ ┃ ┣ hooks/ (React logic hooks: useAnimatedBus, useWebsocket)
┃ ┃ ┣ schema/ (Zod type validation: auth, ws)
┃ ┃ ┗ types/ (Global TypeScript interfaces)
┃ ┣ lib
┃ ┃ ┣ store/ (Zustand global state logic: auth, global, ref)
┃ ┃ ┣ busStopUtils.ts
┃ ┃ ┗ utils.ts
┃ ┣ routes
┃ ┃ ┣ __root.tsx
┃ ┃ ┣ bus-schedule.tsx
┃ ┃ ┣ create-report.tsx
┃ ┃ ┣ index.tsx
┃ ┃ ┣ report.tsx
┃ ┃ ┗ sso-login.tsx
┃ ┣ services
┃ ┃ ┣ auth.ts
┃ ┃ ┗ util.ts
┃ ┣ index.css
┃ ┣ main.tsx
┃ ┗ routeTree.gen.ts (Auto-generated by TanStack router)
┣ .env.example
┣ eslint.config.js
┣ package.json
┣ tsconfig.json
┗ vite.config.ts
Key Components
main.go — Application Bootstrap
- Reads config from .env via Viper
- Creates pgxpool connection to PostgreSQL
- Wires all handlers, services, repositories, and middlewares
- Registers HTTP routes via utils.HandleRoute
- Starts WebSocket broadcaster at /ws
- Exposes webhook endpoint at /wh for GPS ingestion
app/bus/container.go — Runtime State Manager
- Holds in-memory maps: busCoordinates, previousHalte, activeLaps, storedBuses, currentPlates
ApplyExternalCoordinates() — the main pipeline called by webhook: updates colours, detects lanes, tracks halte visits, detects lap start/end
- DQ_SIZE = 50: rolling deque per bus for lane detection sampling
InitRuntimeState() — hydrates runtime caches from DB on startup
app/bus/halte.go — Geofence Proximity
- 22 named haltes (bus stops) with fixed coordinates
- nearestHalte(lat, lng) returns the closest halte name + distance in metres
Threshold: 45 metres — bus must be within 45m to register a halte visit
app/bus/route.go — Route Definitions
- 4 route arrays: blueNormal, blueMorning, redNormal, redMorning
- Pre-built halte-pair sets for O(1) lookup
- detectRouteColorFromPair() returns blue / red / grey
app/auth/ — Authentication
- SSO Login: validates CAS ticket with sso.ui.ac.id, auto-creates user in DB on first login
- JWT pair (access + refresh) signed with HS256; expiry is configurable via env vars
- Admin protection: API_KEY header is checked against ADMIN_API_KEY env var
☁️ Operational Playbook
Infrastructure
- Cloud Provider: AWS ECR + Pusilkom instance
- Container Registry: 638207107223.dkr.ecr.ap-southeast-1.amazonaws.com
- Image Name: bikun-tracker-v2-backend
- Production Tag: stable (deployed from main branch)
- Staging Tag: latest (deployed from staging branch)
- Region: ap-southeast-1 (Singapore)
Environment Variables
| Key | Description | Default (Dev) | Sensitive? |
|---|---|---|---|
| DAMRI_API | Damri GPS API base URL | https://api-damri.istsolutions.co.id | No |
| DAMRI_LOGIN_USERNAME | Damri API username | — | Yes |
| DAMRI_LOGIN_PASSWORD | Damri API password | — | Yes |
| WS_URL | External GPS WebSocket URL | ws://localhost:8000/status | No |
| RM_API | RM lane-detection service URL | https://eta-bikun-tracker-production.up.railway.app | No |
| PRINT_CSV_LOGS | Enable CSV log POST to port 4040 | FALSE | No |
| PORT | Port the server listens on | 8080 | No |
| DB_HOST | PostgreSQL host address | localhost | No |
| DB_NAME | Database name | bikun_tracker | No |
| DB_USER | Database username | postgres | No |
| DB_PASSWORD | Database password | — | Yes |
| DB_PORT | Database port | 5043 | No |
| WS_UPGRADE_WHITELIST | Allowed WebSocket origins (comma-separated) | localhost:5173 | No |
| JWT_EXPIRY_IN_DAYS | Access token validity in days | 1 | No |
| JWT_REFRESH_EXPIRY_IN_DAYS | Refresh token validity in days | 30 | No |
| JWT_SECRET_KEY | HMAC secret for JWT signing | — | Yes |
| ADMIN_API_KEY | API key for admin-protected endpoints | — | Yes |
🙋Questions
🗒 List of frequently asked questions or question that need to be answered that is related to this initiative ..