RouteScholar

Operations

Original Idea

School Bus Route Planner A web app that optimizes routes and sends parent SMS alerts for delays.

Product Requirements Document (PRD): RouteScholar

Project Name: RouteScholar
Version: 1.0.0 (2026 Compliance Standard)
Status: Draft
Owner: Senior Product Manager

1. Executive Summary

RouteScholar is a next-generation school transportation management platform designed to eliminate the inefficiencies of manual routing and the anxiety of parent-school communication. By leveraging real-time GPS tracking, automated VRP (Vehicle Routing Problem) optimization, and proactive SMS alerting, RouteScholar ensures student safety while reducing operational costs for school districts by up to 20%.

2. Problem Statement

School districts currently struggle with:

  • High Fuel & Labor Costs: Manual routing leads to overlapping paths and underutilized bus capacity.
  • Communication Breakdown: Parents are left in the dark during traffic delays or mechanical breakdowns.
  • Student Safety Risks: Lack of real-time manifest tracking makes it difficult to verify if a student boarded the correct bus.
  • Regulatory Pressure: Stricter 2026 COPPA and GDPR updates demand higher data privacy standards for student geolocation.

3. Goals & Success Metrics

  • Efficiency: Reduce total fleet mileage by 15% through automated route optimization.
  • Communication: Achieve a 90% reduction in "Where is the bus?" phone calls to dispatch.
  • Safety: 100% accurate student boarding logs via RFID/NFC integration.
  • Compliance: Zero data breaches and full adherence to the April 2026 COPPA Rule amendments.

4. User Personas

| Persona | Goals | Pain Points | | :--- | :--- | :--- | | Admin (District) | Cost reduction, fleet oversight, reporting. | Budget cuts, manual data entry. | | Dispatcher | Real-time monitoring, handling emergencies. | Radio congestion, unpredictable traffic. | | Bus Driver | Safe driving, clear navigation, manifest check. | Distractions, complex manual stop lists. | | Parent/Guardian | Knowing where their child is, receiving delay alerts. | Waiting in rain/cold for late buses. |

5. User Stories

  • As an Admin, I want to upload a CSV of student addresses so that the system can generate the most fuel-efficient routes for my 50-bus fleet.
  • As a Driver, I want a high-contrast, voice-guided navigation interface so that I can focus on the road while following the optimized path.
  • As a Parent, I want a secure, one-time tracking link via SMS so that I can see the bus's live location when it's more than 5 minutes late.
  • As a Student, I want to tap my school ID card when boarding so that my parents and the school know I am safely on the bus.

6. Functional Requirements

6.1 Route Optimization (TSP/VRP)

  • The system shall solve the Vehicle Routing Problem with Time Windows (VRPTW) using hybrid GA-LLM logic.
  • Supports "soft constraints" like driver preferences and specialized student needs (e.g., wheelchair access).

6.2 Real-Time Tracking & Geofencing

  • GPS ingestion at 1Hz frequency via WebSockets.
  • Automatic "Arrival" triggers when a bus enters a 30-meter radius of a BusStop.
  • Automatic "Departure" triggers when a bus leaves the geofence and remains outside for >10 seconds.

6.3 Smart SMS Alerting

  • Trigger SMS via Twilio when Current_ETA - Scheduled_Time > 5 minutes.
  • Implementation of the "Stateful Delta" pattern to prevent notification spam (no re-alerts unless delay increases by an additional 5 minutes).

6.4 Secure Parent View

  • A "Zero-Trust" web view accessible via a Clerk-authenticated short-lived token (1-hour expiry).
  • Live map rendering using MapLibre GL JS with restricted scoped credentials.

7. Technical Requirements

7.1 Tech Stack (2026 Verified)

  • Frontend: React v19.2.3 (utilizing React Compiler and RSC for performance).
  • Mobile/Driver UI: React-based PWA with react-screen-wake-lock and react-speech-recognition.
  • Backend: NestJS v11.1.12 on Node.js v22 (LTS).
  • Real-Time: Socket.io with Redis Pub/Sub adapter and Redis Geospatial indexing (GEOSEARCH).
  • Database: PostgreSQL 17 with PostGIS 3.5 (using ST_DWithin and GIST indexing).
  • Mapping: Mapbox GL JS v3.18.0 (Standard 3D styles) and Amazon Location Service v2.
  • Authentication: Clerk (with Sign-in Token logic for parents).

7.2 Integrations

  • Telematics: Samsara API (Stats Feed) and Geotab API (GetFeed).
  • Communications: Twilio Programmable Messaging.
  • Infrastructure: AWS (Lambda for logic, RDS for persistence, ElastiCache for real-time).

8. Data Model

8.1 Core Entities

  • Route: id (UUID), driver_id, path (Geometry), optimization_score, last_updated.
  • BusStop: id, location (Point), geofence_radius (int), arrival_window (TSRange).
  • Student: id, ephemeral_id (for GDPR), parent_contact_hash, assigned_stop_id.
  • VehicleState: vehicle_id, current_location (Point/Geohash), speed, occupancy, heading.
  • DelayLog: id, route_id, delay_seconds, timestamp, notified (boolean).

9. API Specification

9.1 Key Endpoints

  • POST /v1/routes/optimize: Accepts stop list and fleet constraints; returns optimized waypoints.
  • GET /v1/tracking/live/:busId: WebSocket upgrade for real-time coordinate stream.
  • POST /v1/notifications/trigger: Logic-gate endpoint for Twilio SMS execution.
  • GET /v1/parent/secure-link/:studentId: Generates a Clerk-scoped temporary JWT link.

10. UI/UX Requirements

  • Driver Dashboard: High-contrast (minimum 7:1 ratio), 48dp minimum touch targets, automatic Night Mode switching.
  • Admin Map: Clustering for fleet overview; "Pulse" animation for active delays.
  • Parent View: "Glanceable" ETA, "Bus is X stops away" text, and live-moving bus icon.

11. Non-Functional Requirements

  • Performance: GPS update-to-UI latency < 500ms.
  • Scalability: Support 10,000 concurrent WebSocket connections per cluster.
  • Security: End-to-end encryption for Student PII; data "Blurred" (1,750ft radius) for non-authorized users.
  • Compliance: Automated 72-hour GDPR breach notification system; written data retention policies in place.

12. Out of Scope

  • In-app payment processing for school fees.
  • Driver payroll management.
  • Full parent-to-teacher instant messaging (SMS only).

13. Risks & Mitigations

  • Risk: GPS drift in urban canyons causing false geofence triggers.
    • Mitigation: Implement a 10-second "settling time" before logging stop arrivals.
  • Risk: SMS delivery failures in low-signal areas.
    • Mitigation: Implement Twilio fallback to Push Notifications via PWA.
  • Risk: Legal liability regarding minor location data.
    • Mitigation: Use ephemeral IDs and "Privacy-by-Design" principles; auto-purge location history every 24 hours.

14. Implementation Tasks

Phase 1: Infrastructure & Security

  • [ ] Initialize NestJS v11.1.12 backend with TypeScript.
  • [ ] Set up PostgreSQL with PostGIS and Redis Stack for spatial caching.
  • [ ] Configure Clerk Role-Based Access Control (RBAC).
  • [ ] Implement 2026 COPPA-compliant data encryption at rest (AES-256-GCM).

Phase 2: Routing & Optimization

  • [ ] Integrate node-or-tools for VRP optimization logic.
  • [ ] Build CSV upload parser for student/stop data.
  • [ ] Implement route generation with Mapbox Directions API.
  • [ ] Create ST_Subdivide optimized GIST indexes for stop geofences.

Phase 3: Driver Experience

  • [ ] Build React v19.2.3 PWA shell.
  • [ ] Implement react-screen-wake-lock for the navigation view.
  • [ ] Integrate Mapbox GL JS v3.18.0 with 3D lane rendering.
  • [ ] Build WebHID/WebUSB bridge for NFC/RFID reader integration.

Phase 4: Tracking & Parent Notifications

  • [ ] Set up Socket.io with Redis Pub/Sub for fleet-wide GPS streaming.
  • [ ] Develop "Stateful Delta" logic for Twilio SMS triggers.
  • [ ] Build the "Zero-Trust" Parent tracking page with Clerk Sign-in Tokens.
  • [ ] Implement Amazon Location Service scoped API key vending machine via Lambda.

Phase 5: Compliance & Launch

  • [ ] Conduct automated demographic bias audit on routing algorithms.
  • [ ] Implement 2026 "Privacy Shield" opt-in splash page for parents.
  • [ ] Perform load testing for 10k concurrent GPS updates.
  • [ ] Deploy to AWS Elastic Beanstalk (Node 22 runtime).