algoarchemist/public-transit

Purpose and Entry Points

SetuTrack is a real-time public-transport tracking platform for small Punjab cities. It combines passenger/driver mobile workflows, an operations dashboard, live GPS processing, route data ingestion, and ETA/crowding inference. Main runnable entry points are apps/mobile-app/lib/main.dart, apps/admin-dashboard/src/main.tsx, services/api-gateway/src/main.ts, services/stream-processor/src/consumer.ts, services/stream-processor/src/gateway.ts, and services/ml-service/app/main.py.

Client Applications

The Flutter app selects Passenger versus Driver/Conductor experiences at startup. Driver flows authenticate, select routes, transmit location, buffer pings, manage trips, and validate tickets; passenger flows expose home, live-map, ticketing, and voice-assistant views. Core paths: apps/mobile-app/lib/role_selection_screen.dart, apps/mobile-app/lib/driver/location_transmitter.dart, apps/mobile-app/lib/passenger/live_map_screen.dart.

The React/Vite admin dashboard is a separate fleet-operations client. It consumes REST and socket abstractions for live fleet state, maps, alerts, route performance, load analytics, model health, and demand/supply planning. Core paths: apps/admin-dashboard/src/App.tsx, apps/admin-dashboard/src/hooks/useFleetSocket.ts, apps/admin-dashboard/src/components/FleetMap.tsx.

API and Transaction Boundary

The NestJS API gateway owns client-facing REST domains: authentication, routes/stops, buses, and tickets. It is the fallback/query boundary for clients, distinct from the real-time stream path. Core paths: services/api-gateway/src/app.module.ts, services/api-gateway/src/buses/buses.controller.ts, services/api-gateway/src/tickets/tickets.service.ts.

Live Telemetry Processing

The Node/TypeScript stream processor is the central real-time pipeline. It consumes MQTT GPS messages, performs geographic processing, dead reckoning and map matching, persists state, requests ETA scoring, and fan-outs updates through Kafka-compatible streaming and Socket.IO. Its split consumer and gateway processes form an ingestion-to-client boundary. Core paths: services/stream-processor/src/consumer.ts, services/stream-processor/src/mapMatch.ts, services/stream-processor/src/gateway.ts.

Data, Routing, and Persistence

Postgres/PostGIS is the durable operational and geospatial store, initialized and evolved through SQL migrations; Redis supports live/cache state. Route snapshots use GTFS-like text plus GeoJSON geometry for Mohali/Tricity. Core paths: db/migrations/0001_init.sql, services/stream-processor/src/pgPersist.ts, data/snapshots/mohali-tricity/routes.geojson.

Geo-ingest builds and reconciles route/stop data from OSM/Overpass, OSRM, and optionally Google Maps before persistence. Core paths: services/geo-ingest/app/main.py, services/geo-ingest/app/reconcile.py, services/geo-ingest/app/persist.py.

Prediction and Simulation

The FastAPI ML service provides ETA and crowd inference behind dedicated routers, with baseline behavior until trained artifacts are available. Training code derives features and refreshes statistics from accumulated data. Core paths: services/ml-service/app/main.py, services/ml-service/app/routers/eta.py, services/ml-service/train/train_eta.py.

The simulator provides an end-to-end source when real vehicles are unavailable: it loads snapshots, models congestion/crowding/trips, publishes live telemetry, and can write historical backfill for training. Core paths: services/simulator/app/main.py, services/simulator/app/trip_simulator.py, services/simulator/app/live_publisher.py.

Infrastructure and Contracts

Local infrastructure in docker-compose.yml supplies Postgres/PostGIS, Redis, Redpanda (Kafka API), and EMQX (MQTT). OSRM container preparation is under infra/docker/osrm/build.sh. Type contracts shared by dashboard and stream processor live in packages/shared-types/src/gps.ts and packages/shared-types/src/ml.ts. The repository is scaffold-stage: these boundaries exist, but live UI, map matching, trained models, and payments remain incomplete.