Orbit Edu School Transport Fleet Telemetry & Route Stoppage Manifest Governance

1. System Topology & Architectural Ingress

The Orbit Edu Transport subsystem operates as an integrated fleet and logistics management engine anchored in apps/api/src/modules/edu/services/transport.service.ts and managed through the administrative console at apps/edu/src/app/admin/transport/page.tsx. It coordinates physical vehicle profiles, route geometry sequences, student passenger seat allocations, driver fitness records, and automated accounting linkages.

+----------------------------------------------------------------------------------------------------+
|                                    ORBIT EDU FLEET CONTROL PLANE                                   |
|                                                                                                    |
|   +-----------------------+     +-----------------------+     +--------------------------------+   |
|   |   VEHICLE ASSET POOL  |     |   ROUTE TOPOLOGY HUB  |     |   STUDENT ALLOCATION ENGINE    |   |
|   |   - Bus / Coaster /   |     |   - Route Code & Name |     |   - Passenger Rosters          |   |
|   |     HiAce Van / Rick. |     |   - Morning Pickup    |     |   - Morning / Afternoon Scope  |   |
|   |   - Capacity & Fuel   |     |   - Afternoon Drop    |     |   - Seat Assignments           |   |
|   |   - GPS IMEI Stream   |     |   - Stoppage Sequence |     |   - Stop-to-Student Mapping    |   |
|   |   - Fitness Expiries  |     |   - Distance Tier Fee |     |   - Linked Fee Surcharges      |   |
|   +-----------+-----------+     +-----------+-----------+     +---------------+----------------+   |
|               |                             |                                 |                    |
|               +----------------------+      |      +--------------------------+                    |
|                                      |      |      |                                               |
|                                      v      v      v                                               |
|                      +-----------------------------------------------+                             |
|                      |        TRANSPORT LOGISTICS COORDINATOR        |                             |
|                      |  apps/api/src/modules/edu/services/           |                             |
|                      |              transport.service.ts             |                             |
|                      +-----------------------+-----------------------+                             |
|                                              |                                                     |
|                      +-----------------------+-----------------------+                             |
|                      |                                               |                             |
|                      v                                               v                             |
|   +------------------------------------+   +---------------------------------------------------+   |
|   |     MONTHLY FEE CHALLAN LINK       |   |             FLEET FUEL & TELEMETRY HUB            |   |
|   |   - Automated Route Fee Ingress    |   |   - Odometer Delta & Liters Consumed              |   |
|   |   - Line Item: Student Transit     |   |   - Liters per 100km Fuel Economy                 |   |
|   |   - Linked Bounded Invoice Token   |   |   - Driver Fitness & Regulatory Road Permits      |   |
|   +------------------------------------+   +---------------------------------------------------+   |
+----------------------------------------------------------------------------------------------------+

1.1 Relational Schema Definitions

The transport domain models vehicles, geographic route stops, active passenger allocations, and maintenance fuel logs within the relational persistence kernel:

export interface VehicleRecord {
  id: string;
  registrationNumber: string;
  vehicleType: 'BUS' | 'COASTER' | 'VAN' | 'RICKSHAW_CONTRACT';
  capacity: number;
  occupancy: number;
  gpsImei?: string | null;
  fuelType: 'DIESEL' | 'PETROL' | 'CNG';
  fitnessExpiryDate?: string | null;
  driverName?: string | null;
  driverPhone?: string | null;
  status: 'ACTIVE' | 'MAINTENANCE' | 'STANDBY' | 'RETIRED';
}

export interface RouteRecord {
  id: string;
  routeCode: string;
  name: string;
  vehicleId?: string | null;
  vehicleRegistration?: string | null;
  morningPickupTime: string;
  morningDropTime: string;
  afternoonPickupTime: string;
  afternoonDropTime: string;
  monthlyFee: number;
  stops: RouteStop[];
  assignedStudentCount: number;
}

export interface RouteStop {
  id: string;
  stopName: string;
  sequenceOrder: number;
  morningTime: string;
  afternoonTime: string;
  landmarkDescription?: string;
}

export interface StudentTransportAllocation {
  id: string;
  studentId: string;
  studentName: string;
  admissionNumber: string;
  className: string;
  guardianName: string;
  guardianPhone: string;
  routeId: string;
  routeCode: string;
  routeName: string;
  stopName: string;
  serviceType: 'BOTH' | 'MORNING_ONLY' | 'AFTERNOON_ONLY';
  seatNumber?: string | null;
  monthlyFee: number;
  effectiveMonth: string;
  isFeeLinked: boolean;
  linkedChallanInvoiceNumber?: string | null;
}

2. Interactive Operator Interface

The Fleet Management Console displays active bus allocations, passenger capacity utilization gauges, vehicle mechanical fitness dates, and route dispatch timings:

3. Route Geometry & Manifest Execution Pipeline

Every transport route enforces a deterministic stoppage sequence, timing profile, and passenger capacity quota:

3.1 Fuel Efficiency & Fleet Telematics Ledger

To identify abnormal consumption or fuel pilferage, TransportService.logFuelExpense() records odometer readings, volume dispensed, and total monetary outlays, computing fuel economy metrics:

export interface FuelLogRecord {
  id: string;
  vehicleId: string;
  vehicleRegistration: string;
  date: string;
  odometerReadingKm: number;
  litersDispensed: number;
  ratePerLiterPKR: number;
  totalCostPKR: number;
  fuelStation: string;
  loggedBy: string;
  calculatedKmPerLiter?: number;
}

The mathematical fuel efficiency formula computes consumption over sequential logs:

DistanceDeltaKm = CurrentOdometerKm - PreviousOdometerKm
FuelEconomyKmPerLiter = DistanceDeltaKm / LitersDispensed
LitersPer100Km = (LitersDispensed / DistanceDeltaKm) * 100

Where:

• DistanceDeltaKm represents the odometer advance since the last full tank refill.
• If FuelEconomyKmPerLiter falls below the threshold for the vehicle class (e.g., 4.5 km/L for 42-seater buses or 9.0 km/L for HiAce vans), the system generates an automated maintenance inspection ticket.

4. Operational Runbook: Student Allocation & Fee Integration

The transport management workflow coordinates seat assignment, route capacity enforcement, and fee challan synchronization.

Phase 1: Student Route Assignment & Capacity Check

1. Locate Student Dossier:

   • The transport officer navigates to apps/edu/src/app/admin/transport and clicks Assign Transport.
   • Select the target student by admission number (#ADM-2024-001) or name.
   • The system retrieves active enrolled data from students.service.ts.

2. Select Route & Stoppage:

   • The operator selects the designated route (e.g., RT-01 (Gulberg to Model Town)).
   • The console queries transport.service.ts:getRouteById() and displays available capacity:

     RemainingSeats = VehicleCapacity - AssignedStudentCount
     

   • If RemainingSeats <= 0, the system blocks assignment and displays a warning dialog: Vehicle Capacity Exceeded.
   • Select the passenger pick-and-drop stop from the configured stoppage list.
   • Choose the service type: Both Ways, Morning Pickup Only, or Afternoon Drop Only.

3. Seat Number Allocation:

   • Assign a designated seat number (e.g., Seat #14).
   • Click Save Allocation. The system generates a persistent StudentTransportAllocation record.

Phase 2: Automated Fee Challan Surcharge Linkage

1. Monthly Invoicing Ingress:

   • When the Bursar office executes batch monthly fee compilation via Composite Fee Challans & 1Bill Integration, the billing engine queries transport.service.ts:listAllocations({ effectiveMonth: '2026-10' }).
   • For every active allocation with isFeeLinked: false, the system appends a fee item:
     • Fee Head: School Bus Route Service (GL 4040)
     • Amount: Determined by route tariff (e.g., PKR 4,500.00).
   • Marks the allocation record:

     allocation.isFeeLinked = true;
     allocation.linkedChallanInvoiceNumber = `CHAL-202610-ADM2024001`;
     

2. Withdrawal Clearance Surcharge Gate:

   • If a student initiates institutional departure via Registrar 360 Student Dossier & Clearance Gates, the system inspects transport records.
   • Any unlinked pro-rated transport dues block clearance until settled.

5. Architectural Verification & Throughput Telemetry

The transport logistics subsystem is benchmarked under peak fleet telemetry streams:

6. Failure Modes & Recovery SOP

The following operational contingency protocols resolve edge-case transport interruptions:

7. Cross-Vertical Internal Linkages

The transport management module coordinates with other core subsystems across the academic enterprise:

• Composite Fee Challans & 1Bill Integration — Binds monthly bus transit tariffs directly into unified bank fee challans.
• Registrar 360 Student Dossier & Clearance Gates — Verifies transit clearance status before issuing Transfer Certificates.
• RFID Turnstile Gate Kiosk & Tardiness Escalation — Reconciles morning bus arrival timestamps against school gate tardiness cutoffs.
• Guardian Self-Service Portal & Turnstile Stream — Displays live bus stop departure and estimated arrival timings to parents.
• Universal Double-Entry General Ledger & Chart of Accounts — Automatically posts vehicle fuel expenses to Fleet Operational Expenses (GL 5030).