vigneshpy/railvazhi

Purpose and workspace

Rail Vazhi predicts railway-level-crossing closure windows along a user’s road route, then recommends whether to leave or wait. It is a pnpm monorepo with a browser client, HTTP API, and shared TypeScript contracts:

• apps/web

• apps/api

• packages/shared/src/index.ts

Entry points and request surface

The API process is initialized in apps/api/src/index.ts and exposes focused route handlers:

• Prediction orchestration: apps/api/src/routes/predict.ts

• Train-related data endpoints: apps/api/src/routes/trains.ts

• Gate endpoints: apps/api/src/routes/gates.ts

The Next.js App Router client begins at apps/web/src/app/layout.tsx and apps/web/src/app/page.tsx. The browser calls the API URL configured through NEXT_PUBLIC_API_URL.

Prediction pipeline

POST /api/predict is the central control flow. It accepts origin/destination coordinates, obtains a road route, identifies crossings near that route, and produces closure predictions plus a travel recommendation.

Core stages are implemented in:

• Road routing via OSRM: apps/api/src/services/routing.ts

• Spatial crossing lookup: apps/api/src/services/gates.ts

• Live/scheduled closure calculation: apps/api/src/services/prediction.ts

• Aggregated response endpoint: apps/api/src/routes/predict.ts

The important boundary is that the API owns all external-data, spatial, and prediction logic; the web app renders returned route/gate/recommendation data rather than computing closures itself.

Geospatial persistence

PostgreSQL 16 with PostGIS is the authoritative local dataset for stations and level crossings. Schema, migrations, and seeded corridor data reside in:

• apps/api/src/db/schema.sql

• apps/api/src/db/migrate.ts

• apps/api/src/db/seed.sql

The database client is centralized in apps/api/src/db/client.ts. Route-to-gate matching uses PostGIS spatial proximity (ST_DWithin), isolating geometry querying from HTTP handlers and routing providers.

Train-data and fallback boundary

Train timing is sourced from NTES scraping and falls back to schedule-based information when live data is unavailable. This provider behavior is isolated in:

• apps/api/src/services/ntes.ts

• apps/api/src/services/prediction.ts

Predictions convey confidence such as Live versus Scheduled. This containment allows NTES/provider changes without altering the frontend or spatial gate query layer.

Web interaction and notification model

The mobile-oriented frontend gathers locations, renders the route and predicted gates, and shows the recommendation:

• Route input/location selection: apps/web/src/components/RouteForm.tsx, apps/web/src/components/LocationPickerModal.tsx

• Map rendering: apps/web/src/components/RouteMap.tsx

• Gate and recommendation presentation: apps/web/src/components/GateCard.tsx, apps/web/src/components/RecommendationBanner.tsx

Saved routes are browser-local rather than server accounts, through apps/web/src/hooks/useFavourites.ts. Route monitoring and notifications are client-side via apps/web/src/hooks/useRouteWatcher.ts, apps/web/src/components/NotificationToggle.tsx, and the service worker at apps/web/public/sw.js.

Runtime and deployment dependencies

The API runs Node.js 20, Express, and strict TypeScript; the web runtime is Next.js 14 with Leaflet/OpenStreetMap mapping. External services are OSRM’s public routing server, Nominatim for search/reverse geocoding, and NTES for train data. Expected deployment separates PostGIS (Supabase), API hosting (Railway; apps/api/railway.toml), and web hosting (Vercel), with API CORS restricted by WEB_ORIGIN.