Bikun Tracker Frontend V2
Client-facing web app for the Bikun shuttle system. It consumes live state from the backend, renders the map and bus status, and keeps the user experience fast enough for real-time tracking.
At a Glance
| Area | Details |
|---|
| Role | Live map, schedules, reporting, and auth entrypoint |
| Runtime | React 19 + TypeScript + Vite |
| Routing | TanStack React Router |
| State | Zustand |
| Styling | Tailwind CSS v4 |
| Map layer | Leaflet |
| Main consumers | Students, staff, and Bikun administrators |
What It Does
- Shows live bus positions on an interactive map.
- Keeps a persistent connection to backend real-time updates.
- Handles authentication through UI CAS.
- Presents schedules and bus operational information.
- Uses local interpolation so bus movement feels smooth between updates.
User Flow
- The user opens the dashboard and authenticates through UI SSO.
- The app fetches the static route and account data it needs.
- The browser subscribes to live updates from the backend WebSocket.
- Map markers and status cards update as new coordinates arrive.
- Reporting and schedule screens reuse the same authenticated session.
Backend Dependencies
| Dependency | Used For |
|---|
| Backend V2 REST API | Buses, auth, and schedule data |
| Backend V2 WebSocket | Live location updates |
| UI CAS | Sign-in and session bootstrap |
Project Structure
| Path | Responsibility |
|---|
src/routes | Route entrypoints and page composition |
src/common/components | Shared map, modal, drawer, and navbar pieces |
src/common/constants | Static route and map configuration |
src/common/data | Bus stop and route definitions |
src/common/hooks | WebSocket, animation, and UI logic hooks |
src/common/schema | Zod validation for auth and socket payloads |
src/lib/store | Zustand stores for auth and global app state |
src/services | API and utility wrappers |
Key Components
main.tsx: app bootstrap.__root.tsx: top-level route shell.index.tsx: dashboard entry page.bus-schedule.tsx: schedule browsing.report.tsx and create-report.tsx: reporting flows.sso-login.tsx: login entry and redirect handling.
Operational Notes
Environment Variables
| Key | Purpose | Notes |
|---|
DAMRI_API | Damri GPS API base URL | Shared backend dependency in docs |
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 for live connection testing |
RM_API | Lane detection service URL | Shared backend dependency |
PRINT_CSV_LOGS | Enable CSV logging | Debug only |
PORT | Local dev port | Default app port |
DB_HOST | Database host | Dev environment only |
DB_NAME | Database name | Dev environment only |
DB_USER | Database username | Dev environment only |
DB_PASSWORD | Database password | Secret value, not committed |
Notes
- The frontend is a consumer of the backend, so it does not own the authoritative bus state.
- Live behavior should always be validated against the backend and WebSocket contract.
- The map experience should stay minimal and readable, because this page is used in motion-heavy contexts.