# School Transport GPS Platform

> A multi-tenant Laravel and Flutter platform for live school bus tracking, offline-first GPS sync, and subscription entitlements.

Author: Nirdesh Pokharel

Canonical URL: https://nirdeshpokhrel.com.np/work/school-transport-gps

## Architecture

Flutter driver app → Local SQLite queue → Batched GPS upload → Laravel API → PostgreSQL; Reverb websockets → School dashboard / parent app

## Problem

Schools in Nepal run buses and vans without a reliable way for staff and parents to see where a vehicle is. The platform lets drivers share location from a phone during a trip, schools watch their fleet live, and parents follow their child's bus. An operator sells it to schools as a monthly or yearly subscription.

## Users and applications

One Flutter app serves drivers and parents. A web dashboard serves school administrators and transport managers, and a platform console serves the operator. Each school is a separate tenant, and one account can belong to several schools with a different role in each.

## Offline-first tracking

The driver app saves GPS points to a local SQLite database and uploads them in batches with retry and backoff. Points are deleted only after the server confirms them, so a trip ended without signal completes once its saved points upload. Sampling adapts to speed and never exceeds the update frequency allowed by the school's plan.

## Realtime delivery

Laravel Reverb pushes vehicle positions to the school dashboard and parent app over websockets when the plan includes realtime updates. Otherwise clients poll over HTTP. Road-aware arrival estimates are cached per trip and stop, refreshed on a timer or after significant movement, and fall back to a straight-line estimate.

## Plans, add-ons, and billing

Four subscription tiers set limits on vehicles, drivers, routes, students, GPS history, and update frequency. A feature is enabled by a platform override, the school's plan, or an active add-on, and add-on quantities stack onto plan limits only while the add-on is within its dates. Invoices can be paid through Khalti or eSewa, or recorded as offline payments.

## Tenant isolation

A dedicated test suite checks every school-facing endpoint for each pair of schools and expects one school to receive a not-found response or an empty list for another school's resources. Platform administrators can enter a school's dashboard, but each entry shows a visible banner, uses a time-limited token, and is audited.

## Evidence and limitations

This note follows the project's feature documentation and source. It does not claim production school counts, tracking accuracy, or battery measurements. Push notifications are wired through Firebase but depend on credentials being configured.