Skip to content

README.md

Latest commit

 

History

History
131 lines (106 loc) · 5.74 KB

README.md

File metadata and controls

131 lines (106 loc) · 5.74 KB
Raw

CityBus Tracker

Real-time city bus tracking platform for Aurangabad — live GPS tracking over WebSockets, measured-speed ETAs, proximity alerts, and a full fleet-management CRUD console, built on Spring Boot 3.

Architecture, trade-offs and the scaling story are documented in SYSTEM_DESIGN.md — read that first if you're evaluating the design.

What it does

Surface URL Who
Rider app / Public — live map, journey planner, live line diagram, crowding info, ETA panel, service alerts
Driver dashboard /driver Drivers — stream GPS, one-tap crowding report, visibility toggle
Admin console /admin Admins — CRUD for routes, fleet & service alerts, live operations view
API docs /swagger-ui.html OpenAPI 3 with JWT authorize button
Health / metrics /actuator/health Ops (custom citybus.* metrics under /actuator/metrics)

Headline features

  • Door-to-door journey planner — Dijkstra over a graph compiled from the route network: walking access/egress, rides along real route geometry, and walking transfers between nearby stops of different routes, with expected waits from each route's headway. Rebuilt automatically when an admin edits a route (Spring event → graph invalidation).
  • Live line diagram — select a route and see a metro-style stop ladder with the bus bead moving between stops in real time.
  • Crowding reports — drivers tap Seats free / Filling up / Full; riders see the badge on bus cards and the ETA panel instantly over WebSocket.
  • Service alerts — admins publish network-wide or per-route notices with severity and expiry; riders get dismissible banners within seconds.
  • Measured-speed ETAs — a ring buffer of GPS fixes per bus yields a real rolling speed; the ETA panel says whether it used live speed or an estimate.
  • Route-aware WebSocket fan-out — riders subscribe to the route they are viewing, cutting per-ping broadcast volume by roughly the number of routes.

Admin edits propagate end-to-end: create or edit a route in the console and the rider map, routes table, schedule page and journey planner all reflect it — no hardcoded data anywhere in the frontend.

Tech stack

  • Backend: Java 17, Spring Boot 3.3 (Web, Data JPA, Security, WebSocket, Validation, Actuator, Cache), H2 file database (PostgreSQL-ready), JJWT, Caffeine, springdoc-openapi
  • Frontend: vanilla JS + Leaflet maps, design-token CSS system with dark mode, service worker (network-first)
  • Tests: 50 JUnit 5 tests — unit, @DataJpaTest slices, and @SpringBootTest + MockMvc integration through the real security filter chain
  • Concurrency: virtual threads (Java 21) for request handling; a zero-dependency load test (tools/loadtest/LoadTest.java) simulates hundreds of WebSocket riders + REST traffic and reports latency percentiles

Architecture in one paragraph

Slow-changing data (routes, stops, buses, users) lives in a relational store behind a layered REST API (controller → service → repository) with DTO validation, a uniform error contract, optimistic locking and Caffeine caching. Fast-changing data (GPS pings, sessions, rolling speeds) lives in an in-memory registry that never touches the database — the WebSocket layer is a thin, JWT-authenticated transport over it. Security is stateless JWT with role-based rules enforced centrally, plus login rate limiting.

Run it

Prerequisites: JDK 17+ and Maven.

mvn spring-boot:run
# → http://localhost:8081

Run the tests:

mvn test

Demo accounts (seeded on first boot)

Role Username Password
Admin admin admin123
Drivers driver1 … driver5 password123

Production configuration

Variable Purpose
JWT_SECRET HMAC signing key (≥ 32 bytes; startup fails on weak keys)
app.cors.allowed-origins Lock CORS down from the * dev default
spring.datasource.url Point at PostgreSQL instead of H2

API at a glance

POST   /api/v1/auth/login              credentials → JWT (rate-limited)
GET    /api/v1/auth/me                 current account
GET    /api/v1/routes                  route network (public, cached)
POST/PUT/DELETE /api/v1/routes...      route CRUD              [ADMIN]
GET    /api/v1/buses?page=&size=       fleet, paginated, live state merged
GET    /api/v1/buses/live              buses broadcasting now
GET    /api/v1/buses/code/{c}/history  recent GPS trace
POST/PUT/DELETE /api/v1/buses...       fleet CRUD              [ADMIN]
GET    /api/v1/journeys?fromLat=..     fastest door-to-door plan (Dijkstra)
GET    /api/v1/alerts                  live service alerts (public, 30s cache)
GET    /api/v1/alerts/all              every alert              [ADMIN]
POST/PUT/DELETE /api/v1/alerts...      alert CRUD               [ADMIN]

Errors always come back in one shape (status, error, message, path, optional fieldErrors[]).

Project layout

src/main/java/com/citybus/
├── config/        Security, WebSocket, OpenAPI, data seeding
├── controller/    REST endpoints (/api/v1)
├── domain/        JPA entities (Route, Stop, Bus, UserAccount)
├── dto/           Request/response records + validation
├── exception/     Typed exceptions + global handler (ApiError contract)
├── repository/    Spring Data repositories
├── security/      JwtService, auth filter, login rate limiter
├── service/       Business logic + LiveTrackingService (in-memory hot path)
└── websocket/     Thin WS transport over LiveTrackingService
src/main/resources/static/   rider, driver and admin single-page frontends
src/test/java/               unit + slice + integration tests