KidsRoute — User Manual & Operating Guide

Real-Time School Van Management & Telemetry System
Department of Computer Engineering, Faculty of Engineering, University of Peradeniya
CO2060 Software Systems Development Project — Academic Evaluation
Engineered by Team AlphaWolves

📋 Table of Contents

  1. Introduction & System Overview
  2. System Architecture & Core Concepts
  3. System Access & Technical Requirements
  4. Authentication & Account Management
  5. Parent User Guide
  6. Driver User Guide
  7. Administrator User Guide
  8. Offline Resiliency & Telemetry Fail-Safes
  9. Frequently Asked Questions & Troubleshooting
  10. Academic & Team Attribution

1. Introduction & System Overview

1.1 The Challenge

In Sri Lanka, school transportation has traditionally relied on fragmented, informal communication—phone calls, WhatsApp messaging while driving, and handwritten attendance notebooks. This leads to:

1.2 The KidsRoute Solution

KidsRoute is an integrated, web-based real-time transport management platform designed to connect Parents, School Van Drivers, and Educational Institutions into a single cohesive ecosystem.

2. System Architecture & Core Concepts

KidsRoute follows a decoupled Three-Tier Architecture engineered for resilience under volatile 3G/4G connectivity:

+-------------------------------------------------------------------------+
|                              CLIENT TIER                                |
|  Marketing Website (/)  •  Web Portal (/portal)  •  PWA Mobile Friendly |
|  [React 19, TypeScript, Tailwind CSS, Leaflet, Socket.io-client]       |
+------------------------------------+------------------------------------+
                                     |  REST APIs (HTTPS) & WebSockets (WSS)
                                     v
+-------------------------------------------------------------------------+
|                            APPLICATION TIER                             |
|  Node.js + Express 5.2 API Gateway  •  Socket.io Real-Time Event Bus     |
|  JWT Authentication  •  Role Guard Middleware  •  Zod Validation Engine |
+------------------------------------+------------------------------------+
                                     |  SQL Connection Pool
                                     v
+-------------------------------------------------------------------------+
|                               DATA TIER                                 |
|  PostgreSQL Database (Supabase / Managed PostgreSQL)                   |
|  Tables: Users, Drivers, Vehicles, Routes, Journeys, Attendance, etc.   |
+-------------------------------------------------------------------------+

2.1 Core Terminology

3. System Access & Technical Requirements

3.1 Portal URLs

| Interface | URL Path | Intended Audience | |—|—|—| | Marketing Website | / | Prospective parents, drivers, university evaluators | | Portal Home / Auto-Redirect | /portal | Automatically routes to user’s assigned dashboard | | User Sign In | /portal/login | Enrolled Parents & Approved Drivers | | User Registration | /portal/register | New Parents & New Drivers | | Driver Pending Approval | /portal/pending-approval | Drivers awaiting administrator credentials review | | Administrator Sign In | /portal/admin | Authorized System Administrators only |

3.2 System Requirements

4. Authentication & Account Management

4.1 Account Registration

  1. Navigate to /portal/register or click Sign Up on the website header.
  2. Select your account type: Parent or Driver.
  3. Complete the registration form:
    • Full Name
    • Email Address (must be unique)
    • Phone Number (Sri Lankan format: 07XXXXXXXX)
    • Password (minimum 6 characters)
  4. Submit the form:
    • Parents: Redirected immediately to the Parent Dashboard (/portal/parent).
    • Drivers: Directed to the Pending Approval Screen (/portal/pending-approval). To preserve passenger safety, driver accounts require administrative verification of driving licenses and vehicle compliance before active dispatch.
       +---------------------------------------------+
       |             Registration Form               |
       +---------------------------------------------+
                              |
              +---------------+---------------+
              |                               |
       [ Role: Parent ]               [ Role: Driver ]
              |                               |
              v                               v
     Instant Activation           Awaiting Admin Approval
              |                               |
              v                               v
    /portal/parent Dashboard       /portal/pending-approval

4.2 Logging In & Role-Based Redirection

  1. Open /portal/login.
  2. Select the appropriate role tab: Parent or Driver.
  3. Enter your registered email and password.
  4. Click Sign In. The system validates your JWT token and redirects you:
    • parent → /portal/parent
    • driver (approved) → /portal/driver
    • driver (unapproved) → /portal/pending-approval
    • admin → /portal/admin/dashboard

[!TIP] Academic Evaluation Mode: For rapid testing and grading, the Login Page provides 1-Click Quick-Fill Demo buttons (Parent Demo: parent@test.com and Driver Demo: driver@test.com). Click either pill to populate verified evaluation credentials instantly.

4.3 Administrator Authentication

The administrative back-office is partitioned from public authentication. Administrators authenticate at /portal/admin with designated privileged credentials.

4.4 Account Security & Profile Settings

Users can access their profile by clicking their avatar in the sidebar:

5. Parent User Guide

The Parent Portal is engineered to minimize stress and eliminate uncertainty about your child’s school transit.

5.1 Parent Dashboard (/portal/parent)

Upon signing in, parents are presented with the primary operations center:

5.2 Managing Children & Pickups (/portal/parent/children)

Parents can enroll one or more children into the transit system:

  1. Navigate to My Children in the sidebar.
  2. Click + Add Child.
  3. Enter the student’s information:
    • Student Full Name
    • School: Select from the approved school directory.
    • Grade / Class: e.g., Grade 7-B.
    • Emergency Contact: Secondary phone number for guardian backup.
    • Pickup / Drop-off Address: Residential address. Coordinates can be verified on the interactive pin-drop map.
  4. Select the preferred Assigned Van Route.
  5. Save the record. The student is immediately registered in the driver’s route manifest.

5.3 Live GPS Tracking & Telemetry (/portal/tracking)

Clicking Live Tracking opens the real-time Leaflet map interface:

+--------------------------------------------------------------------------+
|  [ < Back ]  Live Van Tracking - Morning Run #04             [ LIVE ● ] |
+--------------------------------------------------------------------------+
|                                                                          |
|       [ Home Pickup: 7:05 AM ] ---> ( Van 🚎 ) ---> [ Kingswood College ] |
|                                                                          |
|       =================== MAP VIEW (OpenStreetMap) ==================    |
|                                                                          |
|                  📍 [Child Pickup Spot: 120m away]                       |
|                   \                                                      |
|                    \=====> 🚎 Van WP-NC-4821 (34 km/h)                   |
|                             \                                            |
|                              \=====> 🏫 Kingswood College                |
|                                                                          |
+--------------------------------------------------------------------------+
|  Telemetry: Speed: 34 km/h | ETA: 4 mins | Status: En Route              |
+--------------------------------------------------------------------------+

5.4 Absence & Leave Reporting

If your child is sick or will not be attending school, notify the driver with one click:

  1. From the Parent Dashboard or Child Management page, click Mark Absence.
  2. Select the affected date (single day or date range).
  3. Select whether the absence applies to Morning Run, Afternoon Run, or Full Day.
  4. (Optional) Provide a brief reason (e.g., Fever, Family event).
  5. Submit the notice. The driver’s manifest will immediately show your child as Absent, preventing unwanted stops and telephone inquiries.

5.5 Journey History & Attendance Logs (/portal/parent/history)

The history dashboard offers full auditability of all past trips:

5.6 Fee Payments & Bank Slips (/portal/parent/payments)

KidsRoute eliminates paper receipts and cash handling confusion:

  1. Navigate to Payments from the sidebar.
  2. Review the monthly statement:
    • Monthly Due Amount (in LKR).
    • Billing Month & Due Date.
    • Status Badge: PAID, PENDING, or OVERDUE.
  3. If paying via bank transfer:
    • Transfer the due amount to the driver’s registered bank account displayed on the invoice card.
    • Click Upload Bank Slip.
    • Select an image or PDF of your bank deposit slip or mobile banking transfer receipt.
    • Click Submit Payment Verification.
  4. Once the driver confirms receipt, your dashboard status automatically updates to Verified & Paid.

6. Driver User Guide

The Driver Portal is optimized for high-contrast visibility, large touch targets, and minimal distraction while operating a vehicle.

[!WARNING] Safety Notice: Drivers must never interact with mobile screens while actively driving. Attendance updates and journey controls must only be operated when the vehicle is stationary at designated stops.

6.1 Driver Onboarding & Setup (/portal/driver/onboarding)

After administrative approval, drivers complete a one-time onboarding workflow:

  1. Vehicle Registration:
    • Vehicle Make & Model (e.g., Toyota HiAce 2018)
    • Official License Plate Number (e.g., WP-NB-8214)
    • Seating Capacity (e.g., 14 Passengers)
  2. Route Definition:
    • Route Name (e.g., Peradeniya - Kandy Schools Morning Route)
    • Scheduled Departure Times (Morning & Afternoon)
    • Primary Destination Schools (e.g., Kingswood, Dharmaraja, Girls’ High School)

6.2 Driver Dashboard & Journey Controls (/portal/driver)

The main dashboard gives drivers direct control over their daily trips:

6.3 Live Telemetry Broadcasting

Once a journey starts:

6.4 Passenger Attendance Manifest (/portal/driver/attendance)

The Attendance page provides a digital checklist organized by pickup sequence:

6.5 Emergency SOS & Broadcast Announcements (/portal/driver/announce)

In unpredictable traffic or emergency conditions:

6.6 Student Fee Collection & Management (/portal/driver/payments)

7. Administrator User Guide

The Administrator Back-Office is reserved for platform managers and transport coordinators.

7.1 Admin Dashboard & System KPIs (/portal/admin/dashboard)

The administrative command center provides an aggregate overview of platform health:

7.2 Driver Approvals & User Auditing (/portal/admin/users)

To maintain safety and regulatory compliance:

  1. Navigate to User Management.
  2. Filter users by Pending Drivers.
  3. Inspect driver details:
    • Driving license number and National Identity Card (NIC).
    • Vehicle registration credentials.
    • Assigned route proposal.
  4. Click Approve Driver to grant active dispatch privileges, or Reject / Suspend if documentation is incomplete.

7.3 Vehicle & Fleet Management (/portal/admin/vehicles)

7.4 School Directory Management (/portal/admin/schools)

7.5 Route Configuration & Geocoding (/portal/routes)

8. Offline Resiliency & Telemetry Fail-Safes

Road conditions in Sri Lanka present intermittent 3G/4G cellular coverage. KidsRoute integrates architectural safeguards:

  1. Graceful Degradation:
    • If the driver’s device loses mobile data, the web client stores the latest GPS coordinates in local memory.
    • Once data connectivity resumes, queued fixes are flushed to the server.
  2. WebSocket Heartbeats & Reconnection:
    • Both parent and driver clients maintain a 15-second heartbeat ping-pong with the Socket.io server.
    • If a connection drops, exponential backoff retries re-establish the socket session without requiring a page refresh.
  3. Optimistic UI Updates:
    • Attendance clicks (Boarded/Dropped Off) update the local UI instantly so drivers can continue their workflow without waiting for network acknowledgment.

9. Frequently Asked Questions & Troubleshooting

Q1: The live map is not updating the van’s position. What should I check?

Q2: How does a driver get approved after registering?

Q3: Can a parent track more than one child if they travel in different vans?

Q4: What happens if a student is marked Absent by mistake?

Q5: Can KidsRoute be used as a mobile app?

10. Academic & Team Attribution

This software platform was designed and developed as part of the CO2060 Software Systems Development Project at the Department of Computer Engineering, Faculty of Engineering, University of Peradeniya.

Engineering Team (Team AlphaWolves):

Project Repository & Resources:

KidsRoute — Keeping Sri Lankan School Journeys Tracked, Safe & Transparent.