SafePass Intelligent Student Transit Platform – Phase II Report

Crew Sirius

Bekir Emre Sarıpınar, Mehmet Efe Hırkalı, Ahmet Burak Durukanoğlu, Ömer Nacar, Bekir Göktepe, Edip Zahit Güney

CSE343 – Software Engineering, Gebze Technical University

---

Abstract

SafePass is a production-ready SaaS platform for student transportation management, featuring real-time GPS tracking, digital attendance recording, dynamic route optimization, and unified notification systems. Built with NestJS backend, Next.js admin portal, and Flutter mobile apps, the system is deployed to Supabase PostgreSQL, Render, and Netlify with zero monthly operational costs. This report documents the completed implementation through user stories, product backlog, UML system models, and working interface demonstrations.

Keywords: student transportation, real-time tracking, digital attendance, WebSocket, production deployment

---

I. INTRODUCTION

Student transportation systems face persistent coordination challenges: parents lack visibility into bus locations, schools struggle with real-time attendance records, and communication relies on fragmented channels. SafePass addresses these inefficiencies through a unified digital platform providing role-specific interfaces (drivers, parents, school/company administrators) while maintaining a single source of truth for operations.

A. Technical Implementation

The backend (NestJS + PostgreSQL via TypeORM) manages 38 database migrations, authentication via Firebase with four roles, and a WebSocket gateway for real-time event streaming. The web portal (Next.js 15 + TailwindCSS) provides administrative dashboards for routes, assignments, and live fleet tracking. Mobile apps (Flutter + Riverpod) deliver driver trip execution and parent tracking interfaces with background GPS support. Integration with Google Maps API handles geocoding, distance matrices, and dynamic route optimization.

B. Deployment Infrastructure

The system is deployed on Supabase (PostgreSQL with connection pooling, just used for deploy not used as BAAS), Render (backend with WebSocket support), and Netlify (frontend delivery), achieving zero monthly operational costs while maintaining production-grade reliability.

C. Report Structure

Section II: User stories and scenarios. Section III: Product backlog with sprint completion status. Section IV: UML models (context, process, use-case, sequence diagrams). Section V: Working interface demonstrations.

---

II. USER STORY AND SCENARIOS

User Story: A Calm Morning for Every Stakeholder

Ahmet Bey has been driving school buses for TransEdu Transportation Company in Gebze for eight years. Every morning, he arrives at the company garage at 6:45 AM, picks up his assigned vehicle, and checks his printed route sheet showing 12 stops across three neighborhoods. His phone rings constantly during the route—parents asking “where is the bus?”, the school secretary calling about absent students, and his manager checking if everything is on schedule.

This morning is different. Ahmet Bey opens the SafePass mobile app on his company-provided tablet. The app shows his route on a map with all stops numbered, student names listed at each location, and scheduled times. He taps “Start Trip” at 7:15 AM, and immediately, parents waiting at home receive notifications on their phones: “School bus has departed. Track in real-time.” Fatma Hanım, a parent waiting with her daughter Zeynep at the third stop, opens her SafePass app and sees the bus moving on the map, just leaving the second stop. The app estimates arrival in 4 minutes.

When Ahmet Bey arrives at the stop, Zeynep boards the bus. He taps her name on the attendance screen—a single touch confirms boarding. Fatma Hanım’s phone vibrates: “Zeynep boarded the bus at 7:28 AM.” She heads back inside, relieved. Meanwhile, at the school, Principal Ayşe Hanım opens the SafePass web dashboard on her office computer. The live map shows Ahmet Bey’s bus approaching the school with 11 of 12 students onboard—one student was marked absent at stop 5 because the parent had reported illness through the app earlier that morning.

At 8:05 AM, Ahmet Bey taps “End Trip” as the last student walks into the school building. The system automatically logs trip duration (50 minutes), total distance (18.3 km), and generates an attendance summary. Parents receive final notifications: “Your child arrived safely at school at 8:05 AM.” No phone calls were made during the entire route. The company operations manager reviews the morning dashboard showing 15 completed trips across the fleet, 287 students transported, and 94% on-time performance.

That afternoon, when a parent cannot reach the stop on time and reports via the app that their child will take alternate transportation, the system immediately alerts Ahmet Bey. His return route is automatically updated, removing that stop from the sequence—saving 12 minutes and reducing fuel costs. The school is notified, and the student’s status shows “alternative transport arranged” in the attendance records.

---

Scenario 1: Recording Digital Attendance During Morning Trip

Initial assumption: The driver has logged into SafePass mobile app with valid credentials and has successfully started a morning school trip. The driver is at a designated stop where one or more students are expected to board. The students’ parents have the SafePass mobile app installed and are logged in with accounts linked to their children. Network connectivity is available.

Normal: The driver parks at the stop and opens the attendance screen showing the list of expected students for this location. For each student who boards the bus, the driver taps the student’s name and selects “Mark as Boarded.” The system immediately creates a timestamped attendance record including the student ID, current GPS location, and driver ID. An automated push notification is sent to the student’s linked parents: “Your child has boarded the bus at [stop address] at [time].” The parent’s mobile app updates the student status from “waiting” to “onboard” with the boarding timestamp displayed. The school administrator’s web dashboard simultaneously reflects the boarding event, incrementing the “students onboard” counter for this trip. The driver proceeds to the next stop after all expected students have boarded.

What can go wrong: If a student is expected but not present at the stop, the driver taps “Mark as Absent” instead. The system sends a notification to the parents: “Your child was not at the stop at [address] at [time]. Please contact the school if this is unexpected.” The school dashboard marks the student as absent with timestamp.

If network connectivity is lost, the mobile app queues the attendance event in local storage and displays an offline indicator. When connectivity returns, queued events are automatically synchronized to the server in chronological order. Parents receive delayed notifications once synchronization completes.

If the driver accidentally taps the wrong student name, they can tap “Undo” within 30 seconds to reverse the action before it becomes permanent in the attendance log.

Other activities: While the driver is recording attendance, parents may be viewing the live map tracking the bus approaching their stop. School administrators may be monitoring multiple active trips simultaneously on the fleet overview dashboard. The company operations center may be collecting aggregated statistics on boarding times across all routes for performance analysis.

System state on completion: The driver has recorded attendance for all expected students at the current stop (either boarded or absent). Attendance records are persisted in the database with timestamps and GPS coordinates. Parents have received boarding notifications and see updated status in their apps. The school dashboard shows current boarding progress. The driver proceeds to the next stop in the route sequence.

---

Scenario 2: Parent Tracking Bus Location in Real Time

Initial assumption: A parent has logged into the SafePass mobile app and is viewing the “Today’s Trips” screen. The morning school trip for their child has been started by the driver and is currently in progress. The child has not yet boarded the bus. The parent’s device has location permissions enabled. Network connectivity is available.

Normal: The parent taps on the active trip to open the live tracking screen. The app displays a map showing the current bus location as a moving marker, the full route path as a colored line, and all stops numbered along the route. The parent’s child’s designated stop is highlighted with a distinct icon. The app continuously receives location updates via WebSocket connection and smoothly animates the bus marker as it moves. An estimated time of arrival (ETA) is displayed: “Arriving at your stop in approximately 6 minutes.” As the bus approaches within 2 minutes of the stop, the parent receives a proximity notification: “The bus is approaching your stop. Please be ready.” The parent prepares their child based on this timely alert.

What can go wrong: If the parent’s internet connection is unstable, the app displays a “Reconnecting…” indicator and attempts to re-establish the WebSocket connection. The bus marker may freeze temporarily but resumes updating once connectivity returns.

If the driver’s device has lost GPS signal (e.g., in a tunnel), the bus marker remains at the last known position. The app displays “Last updated: 2 minutes ago” to inform the parent of stale data.

If the trip experiences traffic delays and the driver has declared a delay through the app, the parent receives an updated notification: “The bus is delayed by approximately 10 minutes due to traffic. New estimated arrival: [updated time].”

Other activities: The driver is simultaneously navigating the route and recording attendance at each stop. Other parents whose children are at different stops are also tracking the same bus on their own devices. School administrators are monitoring this trip along with all other active trips on the web dashboard.

System state on completion: The parent has visibility into real-time bus location and arrival estimates throughout the trip. When the child boards, the parent receives a confirmation notification and the live tracking view transitions to show “Your child is onboard” status. The parent can continue tracking the bus until it arrives at school and the trip completes.

---

Scenario 3: Handling Emergency Panic Alert

Initial assumption: The driver is executing an active trip with multiple students onboard. An emergency situation occurs (vehicle breakdown, medical emergency, or security threat). The driver has the SafePass mobile app running with the panic button feature enabled. The device has network connectivity.

Normal: The driver locates the panic button prominently displayed in the app interface and presses and holds it for three seconds to prevent accidental activation. The app displays a confirmation: “Emergency alert will be sent. Continue?” The driver releases after three seconds to confirm. The system immediately captures the current GPS location, timestamp, vehicle ID, and route ID. A high-priority emergency alert is created and stored in the database with status “active.” Push notifications are instantly dispatched to all company administrators with the message: “EMERGENCY ALERT: Driver [name] on route [name] has triggered panic button. Location: [address]. View details.” School administrators linked to the affected school receive similar notifications. The company operations dashboard displays a flashing alert modal showing the emergency location on a map with driver contact information. Parents whose children are onboard receive a reassurance message: “An alert has been issued for your child’s bus. Our team is responding. We will keep you updated.” Company administrators can immediately contact the driver via phone or dispatch emergency support.

What can go wrong: If network connectivity is unavailable when the driver triggers the panic button, the mobile app stores the alert locally and displays “Alert will be sent when connection is restored. Emergency services: call 112.” Once connectivity returns, the alert is immediately transmitted.

If no company administrators are currently logged in, the system falls back to sending SMS messages to pre-configured emergency contact phone numbers in addition to push notifications.

Other activities: While the alert is active, the driver’s location continues streaming to provide real-time position updates. Parents may be attempting to contact the company or school for more information. Company operations staff are logging response actions in the system.

System state on completion: Once the situation is resolved, a company administrator marks the alert as “resolved” through the dashboard. The system updates the alert status to “resolved” with resolution timestamp and notes. Follow-up notifications are sent to parents: “The situation has been resolved. Your child’s bus will continue shortly.” A complete audit trail of the incident is stored, including trigger time, location, all notifications sent, response actions taken, and resolution details for reporting and insurance purposes.

---

III. PROJECT BACKLOG (Epic-Level Summary)

---

Epic 1 – Project Infrastructure & DevOps Setup

Goal: Establish the monorepo structure, CI/CD tooling, backend skeleton with NestJS and PostgreSQL, frontend foundation with Next.js, and mobile workspace with Flutter to enable parallel development across all platform teams.

Stories:

1. Story 1.1 – Repository and development environment bootstrap with GitHub workflow and branch protection
2. Story 1.2 – NestJS + PostgreSQL foundation with TypeORM migrations and environment configuration
3. Story 1.3 – Next.js admin portal skeleton with App Router structure and TailwindCSS styling
4. Story 1.4 – Flutter mobile workspace with Riverpod state management, GoRouter navigation, and Dio HTTP client

Priority & Rationale: High – foundational requirement enabling all downstream feature development and ensuring reliable build/test automation across monorepo.

Status: Completed in Sprint 1 (Weeks 1-2)

Epic 2 – Authentication System

Goal: Provide secure role-based authentication flows across web and mobile platforms using Firebase Authentication with custom claims supporting four distinct roles (company admin, school admin, driver, parent).

Stories:

1. Story 2.1 – Firebase Authentication integration including Admin SDK backend setup and JWT token validation middleware
2. Story 2.2 – Parent mobile login experience with email/password authentication and error handling
3. Story 2.3 – Driver mobile login experience with role-specific navigation to driver dashboard
4. Story 2.4 – Web admin login with role-aware redirects to company or school dashboards
5. Story 2.5 – Profile synchronization API connecting Firebase UID to PostgreSQL user records and managing custom claims

Priority & Rationale: High – security prerequisite for all protected features; without authentication, downstream modules cannot enforce access controls or personalize user experiences.

Status: Completed in Sprint 1 (Weeks 1-2)

Epic 3 – Real-Time Tracking (MVP)

Goal: Deliver live bus tracking capability using WebSocket architecture enabling drivers to broadcast GPS coordinates while parents and administrators subscribe to assignment-specific rooms for real-time location updates.

Stories:

1. Story 3.1 – WebSocket gateway (/location namespace) with room management, authentication guards, and connection lifecycle handling
2. Story 3.2 – Driver-side GPS streaming pipeline including location permissions, background tracking service, and reconnection logic
3. Story 3.3 – Parent mobile live map powered by Socket.IO client rendering bus position with route polyline overlay
4. Story 3.4 – Admin live-tracking console aggregating all active routes on fleet overview map with status indicators

Priority & Rationale: High – core differentiating capability of SafePass platform; real-time visibility eliminates primary pain point of parent uncertainty during trips.

Status: Completed in Sprint 1 (Weeks 1-2)

Epic 4 – Route Management System

Goal: Enable transportation companies to plan routes with geocoded stops, assign drivers and vehicles to daily trips, and provide drivers with navigable route interfaces showing ordered stops and student rosters.

Stories:

1. Story 4.1 – Route creation and editing via web admin panel with map-based stop placement, CRUD endpoints, and route listing with pagination
2. Story 4.2 – Driver route visualization on mobile app displaying ordered stops, student lists per stop, and offline route data caching
3. Story 4.3 – Operational daily reporting including trip completion metrics, delay statistics, and performance summaries

Priority & Rationale: High – foundational data structure enabling attendance, tracking, and safety features; routes define operational context for all trip execution workflows.

Status: Completed in Sprint 2 (Weeks 3-4)

Epic 5 – Student & Parent Management

Goal: Maintain accurate student rosters with parent-child relationships, enabling school administrators to manage student data and parents to view their children’s transportation information.

Stories:

1. Story 5.1 – Student management including entity design, CRUD APIs, and admin UI for student creation with parent linkage
2. Story 5.2 – Parent-facing children list showing enrolled students with school information and child selection workflows

Priority & Rationale: High – prerequisite for attendance tracking, notifications, and compliance reporting; establishes data relationships between users, students, and schools.

Status: Completed in Sprint 2 (Weeks 3-4)

Epic 6 – WebSocket Optimization & Monitoring

Goal: Enhance WebSocket infrastructure scalability through connection pooling, memory leak elimination, load testing validation, and observability dashboards showing real-time connection metrics.

Stories:

1. Story 6.1 – Performance hardening including connection pooling optimization, memory profiling, leak detection, and load testing with 100+ concurrent connections
2. Story 6.2 – Metrics and logging collection with Prometheus integration and monitoring dashboard for active connections, message throughput, and error rates

Priority & Rationale: Medium – critical for production stability and long-term scalability; ensures WebSocket infrastructure can support growing fleet operations without performance degradation.

Status: Completed in Sprint 2 (Weeks 3-4)

Epic 7 – Digital Attendance, Notifications & Absence Management

Goal: Implement comprehensive attendance workflows including driver-initiated digital attendance with offline support, FCM push notification infrastructure, parent absence reporting with dynamic route optimization, and emergency panic button functionality.

Stories:

1. Story 7.1 – Driver student list and attendance interface with tap-to-record boarding/alighting, visual feedback, and offline queue synchronization
2. Story 7.2 – Parent attendance notifications via Firebase Cloud Messaging delivering real-time alerts for boarding/alighting events
3. Story 7.3 – FCM backend service with topic-based messaging, event-driven notification dispatch, and mobile client token management
4. Story 7.4 – Notification preferences allowing parents to customize event types and delivery settings
5. Story 7.5 – Parent absence notification form with date range selection triggering automatic roster updates and driver/school notifications
6. Story 7.6 – Driver absence visualization showing absent students with distinct styling and route optimization suggestions
7. Story 7.7 – Emergency panic alert workflow with 3-second hold activation, high-priority notification dispatch, and incident logging
8. Story 7.8 – Administrator emergency dashboard displaying active alerts with driver location and incident resolution workflows

Priority & Rationale: High – core operational features replacing manual processes; digital attendance provides compliance records, FCM enables reliable communication, absence management demonstrates system intelligence, and panic button addresses safety requirements.

Status: Completed in Sprint 3 (Weeks 5-6)

Epic 8 – Trip Lifecycle, Dynamic Routing & In-App Notifications

Goal: Complete trip execution workflows with status transitions (pending → in_progress → completed), implement dynamic route optimization responding to absences, deploy in-app notification system replacing external channels, and provide comprehensive trip history with student-level data.

Stories:

1. Story 8.1 – Trip state management recording start/end timestamps, status transitions, and calculated metrics (duration, distance, speed, punctuality)
2. Story 8.2 – Dynamic route optimization service removing empty stops, recalculating ETAs via Google Maps API, and broadcasting route updates
3. Story 8.3 – Trip history with student boarding/alighting timestamps accessible to parents, schools, and company administrators
4. Story 8.4 – Backend notification event generation for trip lifecycle, attendance actions, delays, and panic alerts with role-based targeting
5. Story 8.5 – Web notification display using toast messages and notification panel for administrators and school staff
6. Story 8.6 – Mobile notification banners and notification history screen for parents showing chronological event timeline

Priority & Rationale: High – completes operational cycle from planning through execution to analysis; dynamic routing demonstrates cost savings, in-app notifications consolidate communication, and trip history supports auditing.

Status: Completed in Sprint 4 (Weeks 7-8)

Epic 9 – Testing, Performance & Observability

Goal: Validate system functionality through integration and end-to-end testing, optimize performance bottlenecks in location streaming and database queries, and deploy monitoring infrastructure for operational visibility.

Stories:

1. Story 9.1 – Integration tests covering trip lifecycle, attendance workflows, route optimization, and notification dispatch with ≥70% backend code coverage
2. Story 9.2 – End-to-end web tests validating login → trip monitoring → notification receipt → history review workflows
3. Story 9.3 – Mobile demo validation running complete trip scenario on physical devices with smoke test checklist
4. Story 9.4 – Performance optimization including location update throttling, query index tuning, and N+1 problem elimination
5. Story 9.5 – Monitoring dashboard displaying active trip count, WebSocket connection metrics, and system health indicators

Priority & Rationale: Medium-High – ensures production readiness through validation, improves user experience via performance optimization, and enables proactive issue detection.

Status: In Progress – Sprint 5 (Weeks 9-10)

Epic 10 – Documentation & Demo Preparation

Goal: Create comprehensive documentation for API testing procedures, demo walkthrough scripts, and QA checklists to support final presentation and stakeholder demonstrations.

Stories:

1. Story 10.1 – API and UI testing documentation with step-by-step workflow instructions
2. Story 10.2 – Demo scenario preparation including seed data scripts, simulation workflows, and presentation narrative
3. Story 10.3 – QA acceptance checklist verifying all user stories meet defined acceptance criteria

Priority & Rationale: Medium – supports knowledge transfer, enables repeatable demonstrations, and provides validation framework for acceptance testing.

Status: In Progress – Sprint 5 (Weeks 9-10)

Epics 11+ (Future Roadmap) – Not Started

Goal: Post-MVP enhancements including advanced analytics dashboards, billing and invoicing modules, fleet maintenance tracking, third-party integrations via webhooks, mobile UX refinements, and regulatory compliance features.

Status: Planned for future sprints pending pilot deployment feedback and stakeholder prioritization.

---

IV. UML DIAGRAMS

A.System Context Diagram

This diagram shows the SafePass system and other systems in its operational environment, following Sommerville’s context modeling approach.

B.Process Diagrams

1. Morning Trip Execution Process

This process shows the complete workflow for a school bus trip from initiation through completion, including student pickup and delivery.

2. Digital Attendance Recording with Absence Handling

This process shows how student attendance is recorded and how absence is managed with parent notification and dynamic route updates.

3. Emergency Panic Alert Handling

This process shows the critical workflow when a driver triggers an emergency panic alert and how the system manages immediate escalation notifications to all stakeholders.

C.Use-Case Diagrams

1. Driver Use Cases

This diagram shows all use cases involving the Driver actor—the primary user who executes trips and manages student attendance.

Use Case 1: Start Trip

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Start Trip
Actors	Driver, Backend System, FCM Notification Service
Data	Assignment ID, trip date, route data, student roster, driver location (GPS)
Stimulus	Driver taps ‘Start Trip’ button in mobile app after authentication and loading assignment
Response	System validates assignment exists, records trip start timestamp, broadcasts ‘Trip Started’ notification to all parents, begins GPS location streaming at 3-second intervals, updates dashboard status to ‘in_progress’
Comments	This is the critical initiating action for any transportation journey. The system must ensure the driver is authenticated and assigned before allowing trip initiation. Real-time notifications must reach all parents within 2 seconds of trip start. GPS streaming must start immediately and continue until trip end.

Use Case 2: Record Student Attendance

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Record Student Attendance
Actors	Driver, Backend System, FCM Notification Service, School Administrator
Data	Student ID, boarding status (boarded/absent), timestamp, GPS coordinates, stop location, trip ID
Stimulus	Driver arrives at a pickup stop and marks each student as either boarded or absent using the mobile interface
Response	System creates an attendance record with precise timestamp and GPS coordinates. System sends boarding confirmation or absence alert to student’s parent via FCM. System updates school administrator’s live dashboard counter. If student is absent, system optionally triggers dynamic route re-optimization and notifies school admin of the absence.
Comments	Attendance recording is the core business function. Each record must be immutable and timestamped. GPS accuracy must be ±10 meters. Parent notifications must be sent within 1 second of marking. Absence notifications must escalate to school admin within 3 seconds. Driver must be able to continue to next stop only after all students at current stop are processed or explicitly marked.

Use Case 3: View Trip Route

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Trip Route
Actors	Driver, Google Maps API, Backend System
Data	Route waypoints, stop addresses, student assignments per stop, turn-by-turn directions, estimated travel times, current GPS position
Stimulus	Driver requests route visualization before or during trip execution via mobile app map interface
Response	System displays interactive map showing: current driver location, remaining stops in sequence with color coding (completed in green, current in blue, upcoming in gray), addresses and GPS coordinates for each stop, turn-by-turn navigation directions from Google Maps API, updated ETA to next stop and to school, student count per stop
Comments	Route visualization must update in real-time as driver progresses. Map must show next 3-5 stops clearly. Driver must be able to mark stops as skipped (due to absence) and system must recalculate remaining route. Navigation instructions must be readable on small mobile screens. Integration with Google Maps API must handle offline scenarios (cache previous route).

Use Case 4: Trigger Panic Alert

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Trigger Panic Alert
Actors	Driver, Backend System, FCM Notification Service, Company Administrator, School Administrator, Parents
Data	Alert timestamp, driver GPS location (coordinates), trip ID, route ID, driver name, current stop location
Stimulus	Driver presses the panic button in the mobile app during an emergency or security incident
Response	System immediately captures driver’s current GPS coordinates and creates alert record. System sends high-priority FCM notifications to: company administrators, school administrators, and all parents on the trip. System displays alert on administrator dashboards with real-time bus location on emergency map. Administrators can review alert and take action (contact police, etc.). System logs alert for audit and compliance purposes.
Comments	This is a critical safety feature. Panic button must be easily accessible and trigger within 500ms. Alerts must reach all stakeholders within 1 second. Alert must display exact GPS coordinates for emergency responders. System must maintain alert history for incident investigation. All stakeholders must receive resolution notification when alert is marked resolved.

Use Case 5: End Trip

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	End Trip
Actors	Driver, Backend System, FCM Notification Service
Data	Trip end timestamp, total trip duration, distance traveled, average speed, students boarded count, students absent count, attendance completion status
Stimulus	Driver arrives at school destination and taps ‘End Trip’ button in mobile app
Response	System validates that all assigned students have been processed (marked as boarded or absent). If incomplete, system displays warning and allows driver to return to attendance recording or force completion. Upon validation, system: records precise trip end timestamp, calculates trip metrics (duration, distance, average speed), sends ‘Trip Completed’ notification to all parents, updates school dashboard with final attendance summary, stops GPS streaming, closes WebSocket room for real-time communication, archives trip record
Comments	Trip completion must be atomic—either fully committed or rejected. Incomplete trips require explicit driver confirmation before forcing completion. Trip metrics must be calculated in real-time. Completion notifications must be sent within 2 seconds. WebSocket room closure must be graceful to avoid orphaned connections. All trip data must be immutable after trip end.

Use Case 6: View Expected Students

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Expected Students
Actors	Driver, Backend System
Data	Student name, student ID, parent phone/email, pickup stop address, expected pickup time, student status (expected/arrived/boarded/absent)
Stimulus	Driver navigates to a pickup stop and requests list of students expected at that stop
Response	System displays all students assigned to the current stop in a scrollable list with: student name and ID, parent contact information, any special notes or remarks (allergies, care instructions, special requests), real-time status indicator for each student (✓ boarded, ✗ absent, ? not yet arrived), count of remaining students to process at current stop
Comments	Student list must load within 1 second even with 100+ stops. Student names must be clearly visible on small screens. Special notes must be prominently displayed to ensure driver awareness of any requirements. System must allow driver to quickly mark each student without switching views. List must support filtering (show only pending, show all) for large routes.

---

2. Parent Use Cases

This diagram shows all use cases involving the Parent actor—who receives notifications and tracks their child’s transportation.

Use Case 1: Track Bus Location

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Track Bus Location
Actors	Parent, Driver Mobile App (GPS streaming), WebSocket Gateway, Backend System
Data	Bus GPS coordinates (latitude/longitude), timestamp, current stop location, next stop address, ETA to school, remaining stops count, route polyline
Stimulus	Parent opens the SafePass mobile app and navigates to ‘Live Tracking’ view during an active trip
Response	System displays interactive map centered on current bus location with: real-time GPS position updated every 3 seconds, route path shown as polyline from pickup to school, current stop highlighted with address, upcoming stops marked with sequential numbers, ETA to next stop and to school, indication of how many stops remain, student boarding progress (X of Y students boarded)
Comments	Location updates must stream in real-time via WebSocket with <500ms latency. Map must work on slow 3G/4G connections with graceful degradation (cache previous locations, reduce update frequency if needed). Zoom level must auto-fit to show current stop and next 2 stops. Parent must be able to see if bus is running late (ETA vs scheduled time). Location accuracy should be ±10 meters.

Use Case 2: View Boarding Status

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Boarding Status
Actors	Parent, Backend System, Driver Mobile App
Data	Student name, boarding timestamp, pickup stop address, bus current location, remaining stops, ETA to school, any special notes from driver
Stimulus	Parent receives boarding notification or proactively checks app to confirm child has boarded the bus
Response	System displays confirmation showing: ✓ Student successfully boarded with timestamp, bus current location and ETA to school, list of remaining stops before destination, driver name and vehicle information if enabled, any messages from driver or school admin. If student has not yet boarded, system shows: ⏳ Student expected at current stop (if stop is active) or upcoming stop (with wait time estimate)
Comments	Boarding confirmation must be sent via push notification within 1 second of driver marking student as boarded. Notification must include ETA so parent knows when child will arrive at school. System must distinguish between ‘awaiting at stop’, ‘on bus’, ‘delivered’ states. If boarding does not occur by expected time, system should prompt parent to confirm student’s status.

Use Case 3: Report Student Absence

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Report Student Absence
Actors	Parent, Backend System, School Administrator, Driver Mobile App
Data	Student ID, trip ID, absence reason (student sick, parent absent, traffic, other), parent comment, timestamp
Stimulus	Parent receives absence notification from driver or parent manually reports student was not picked up as expected
Response	System records absence report with timestamp and reason. System notifies school administrator immediately with: student name, absence reason, reported by (driver or parent), timestamp. System optionally triggers dynamic route re-optimization to remove student’s stop from remaining route (reducing ETA for other students). System creates incident record for school administrative review. System may trigger follow-up communication rules (e.g., automated call to student’s alternative contact).
Comments	Parents must be able to submit absence reports during or after the trip. Absence reports should include reason category (sick, parental request, no-show, other) plus free-text comment. School admin must be notified within 30 seconds. Route optimization should be automatic but reversible (if student is found/added back). Absence report must be immutable once submitted (audit trail).

Use Case 4: View Trip Notifications

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Trip Notifications
Actors	Parent, FCM Notification Service, Backend System
Data	Notification type (trip started, boarding, arrival, completion, alert, delay), timestamp, message content, action link (open map, view details)
Stimulus	Parent opens the SafePass app and views notification center or receives push notification on device
Response	System displays notification history for the current day showing: chronological list of all notifications received (trip started, boarding confirmations, arrival notification, trip completed, any alerts), expandable details for each notification, quick actions (view map, confirm receipt, report issue). Parent can mark notifications as read or archive them. System also shows unread count badge.
Comments	Notifications must persist in app notification center for at least 7 days. Unread notifications must show visual indicator. Parent must be able to search/filter notifications (e.g., show only alerts, show only today). Critical notifications (panic alerts) must show different styling/sound than routine notifications.

Use Case 5: View Trip History

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Trip History
Actors	Parent, Backend System
Data	Trip date, route name, driver name, trip duration, students boarded count, on-time status, any incidents or alerts, attendance summary
Stimulus	Parent navigates to ‘Trip History’ section in the app to review past transportation
Response	System displays filterable list of previous trips with: trip date and route, driver assigned, on-time indicator (✓ on time / ⚠ delayed), number of students boarded vs assigned, any incidents flagged, option to expand and view full details (boarding timestamps, stops visited, route map). Parent can filter by date range, route, or status. System displays up to 90 days of history.
Comments	Trip history should be searchable and filterable for parents with multiple children or routes. Pagination required for parents with extensive history. Detailed view should show: full boarding timeline, GPS route playback option (if enabled), attendance breakdown. Incidents should be clearly flagged with escalation status. System should provide summary statistics (on-time percentage, average delay).

---

3. Administrator (School & Company) Use Cases

This diagram shows use cases for School Administrators and Company Administrators who manage operational aspects.

Use Case 1: Monitor Live Attendance

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Monitor Live Attendance
Actors	School Administrator, Backend System, Driver Mobile App
Data	Active trips list, per-trip attendance progress (X of Y students boarded), student names, pickup stops, current route status, any absences reported
Stimulus	School administrator opens the SafePass dashboard during school morning (typical 7:00 AM - 9:00 AM window) to monitor student arrivals
Response	System displays real-time dashboard showing: list of active trips for the school with on-time status indicators, per-trip attendance progress bar (visual indication of % students boarded), detailed expandable view showing: students boarded (with boarding time), students still expected, students marked absent, current route progress (current stop, stops remaining), option to drill-down into any trip to see live map and individual student status, alert indicator if any absences or incidents reported
Comments	Dashboard must update in real-time (<2s latency) as driver marks students. Color coding should be clear: green for on-time, orange for delayed, red for incidents. School admin should be able to quickly identify which students are not yet boarded by clicking a student name. System should highlight absence patterns (if multiple students from same stop absent) for quick investigation.

Use Case 2: Generate and View Reports

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Generate and View Reports
Actors	School Administrator, Company Administrator, Backend System
Data	Report type (attendance, punctuality, incidents), date range filter, route filter, trip ID, student names, boarding timestamps, absence reasons, incident logs
Stimulus	Administrator navigates to Reports section and selects report type, date range, and filters (by route, by school, by driver)
Response	System generates report showing: for attendance reports - daily breakdown of student arrivals, absences by reason (sick, no-show, parental request, other), trends over time. For punctuality reports - on-time vs late arrivals, average delay per route, drivers with best/worst punctuality. For incident reports - all recorded incidents (panic alerts, route issues, communication failures), severity level, resolution status. Reports can be exported as CSV/PDF. System also shows summary statistics and charts.
Comments	Reports should be generated in seconds for standard date ranges (7-30 days). Schools require daily attendance reports for compliance. Company admin needs weekly punctuality and incident reports. Reports must be audit-logged (who generated, when). System should support scheduled report delivery via email. Graphs should show trends (is attendance improving/degrading over time?).

Use Case 3: Create and Edit Routes

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Create/Edit Routes
Actors	Company Administrator, Google Maps API, Backend System
Data	Route name, pickup stops (addresses, GPS coordinates, sequence), dropoff location (school), student assignments per stop, start time, expected duration, vehicle requirement (capacity, wheelchair accessible), driver assignment
Stimulus	Company administrator creates a new transportation route or edits an existing route in the management portal
Response	System allows administrator to: enter list of pickup stop addresses (system geocodes via Google Maps API to get coordinates), drag-and-drop stops to reorder pickup sequence, assign students to each stop, view calculated route distance, duration, and cost via Google Maps. System shows: map preview of route with stops marked sequentially, estimated travel time, vehicle capacity requirements, conflicts with other routes (if stops overlap). Upon save, system validates: no duplicate stops, minimum 2 stops, all students assigned have valid addresses, no student assigned to multiple routes for same time slot. System calculates optimal stop sequence using Google Maps distance matrix and allows manual reordering.
Comments	Route creation requires integration with Google Maps API for geocoding and distance matrix. System should suggest optimal stop sequence based on distance matrix (minimize total distance). Company admin must be able to assign vehicles to routes and verify capacity. Routes should be versioned (audit trail of changes). Route can be marked as template for recurring routes (weekly/daily). Route optimization should consider time windows if students have specific pickup time requirements.

Use Case 4: Assign Drivers to Routes

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Assign Drivers to Routes
Actors	Company Administrator, Backend System
Data	Driver ID, driver name, vehicle ID, route ID, assignment date(s) (recurring or one-time), start time, end time
Stimulus	Company administrator assigns an available driver to a route for specific date(s) in the management portal
Response	System creates driver assignment record linking: driver to route to specific date(s). System validates: driver has no conflicting assignments (cannot be assigned to two routes at overlapping times), vehicle assigned to driver is available, driver has required certifications/documents if enabled. System notifies driver via app that assignment is available/confirmed. System blocks driver from starting any other trip on the same date/time. Upon assignment, driver can load route data and begin trip preparation. System enables route-specific features (navigation, student roster) for the assigned driver.
Comments	Assignments can be recurring (every Monday-Friday) or one-time. System should show available drivers with current load (how many routes assigned that day). Admin should be able to bulk-assign drivers for a week. System must prevent double-booking. Assignments should be immutable after trip starts (audit trail). Driver must be notified of assignment immediately.

Use Case 5: Handle Emergency Alerts

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	Handle Emergency Alerts
Actors	School Administrator, Company Administrator, Backend System, Driver Mobile App
Data	Alert ID, alert type (panic button, system outage, etc.), timestamp, driver GPS location, route ID, trip ID, parents/students affected, alert status (pending/resolved)
Stimulus	Administrator receives alert notification on dashboard (high-priority flag) when driver triggers panic button or system detects critical event
Response	System displays alert in dedicated emergency panel showing: alert severity (critical/high/medium), exact GPS coordinates of bus, route and trip details, driver name and phone number, list of all parents/students on affected trip. System provides action options: mark alert reviewed, contact emergency services (with pre-filled coordinates/info), send custom message to parents, end trip early. Once alert is marked resolved, system sends resolution notification to all stakeholders. System archives alert record for incident investigation.
Comments	Alerts must appear with high visual prominence (red banner, sound). Admin must be able to contact police with one-click (copy coordinates feature). All alert actions must be logged (audit trail). System should allow pre-configured alert responses (e.g., “Alert resolved, no action needed” template). Alert history must be searchable and retained for compliance.

Use Case 6: View Fleet Metrics

Attribute	Description
System	SafePass Student Transportation Management System
Use Case	View Fleet Metrics
Actors	Company Administrator, Backend System
Data	Active assignments count, trips completed today, on-time trips vs delayed, total distance traveled, total students transported, fuel efficiency metrics, system uptime/health, WebSocket connection count, average API response time
Stimulus	Company administrator opens Fleet Dashboard to monitor operational performance and system health
Response	System displays operational metrics dashboard showing: daily KPIs (trips scheduled, trips completed, on-time %, students transported, total distance), real-time system health (backend uptime, database connections, API response times ), active trip count, active driver count, vehicle utilization (% of assigned vehicles in use). System shows trends over time (7-day, 30-day rolling average). Administrator can drill-down to specific driver or route metrics. System alerts if key metrics exceed thresholds (e.g., API latency >2s, system uptime <99.9%).
Comments	Dashboard must load within 2 seconds. Metrics should update every 30 seconds. KPIs should include target benchmarks (on-time % target: 95%, system uptime target: 99.9%). Administrator should be able to export metrics for reporting to stakeholders. System health metrics are critical for SLA monitoring.

---

D.Sequence Diagrams

1. Start Trip Sequence

This sequence diagram models the interactions when a driver initiates a school trip, showing how the system coordinates between the driver app, backend services, and notification system.

2. Record Student Attendance Sequence

This sequence diagram models the core business workflow when a driver records student attendance at a pickup stop, including validation, notification, and dashboard updates.

3. Handle Emergency Panic Alert Sequence

This sequence diagram models the critical emergency workflow when a driver triggers a panic button, showing how the system escalates to all stakeholders.

4. Track Bus Location in Real-Time Sequence

This sequence diagram models the real-time location tracking feature used by parents, showing continuous WebSocket streaming and map updates.

V. Working Graphical Interface

Youtube Link: https://www.youtube.com/@bemresaripinar/videos