Student Attendance Management System

Product Requirements Document — Full Feature Specification

Field	Value
Document Version	v1.0
Audience	Engineering, Product, Design, QA

---

Part I — Overview

1. Product Overview

The Smartsapp Attendance Management System tracks student check-ins and check-outs, manages designated pickup persons, and provides real-time dashboards and reports on attendance across the school. It is used by school administrators and staff through the Admin Portal and by parents through the Parent App.

1.1 Document Structure

This PRD is organised into three parts:

Part	Scope	Sections
Part I — Overview	Product context, goals, and core concepts	1
Part II — Admin Portal	Dashboard, attendance register, check-in/check-out, pickup person management, settings, and reports	2–7
Part III — Parent App	Pickup person management, self-check-in/out, attendance history, and notifications	8–11

1.2 Strategic Goals

• Provide real-time visibility into which students are present, absent, or late across the school
• Track who dropped off and picked up each student, with full audit trail
• Give parents control over designated pickup persons with flexible scheduling
• Support multiple check-in modes: staff scan, manual entry, and parent self-check-in
• Enable compliance with safeguarding requirements through pickup person verification

1.3 System Boundaries

The system spans two client applications:

Admin Portal (Part II) — used by school administrators and staff:

• Real-time attendance dashboard with campus, section, and class breakdowns
• Daily attendance register with check-in/check-out tracking
• Mass check-in for entire classes
• Pickup person management and verification
• Attendance schedule configuration per section
• Attendance reporting and export

Parent App (Part III) — used by parents:

• Add and manage designated pickup persons with day-specific scheduling
• Self-check-in/check-out their children (if enabled by the school)
• View attendance history for their children
• Receive notifications on check-in, check-out, late arrival, and pickup events

1.4 Core Concepts

Concept	Definition
Attendance Record	A daily record for a student capturing check-in time, check-out time, who performed each action, and the resulting status. One record per student per school day.
Check-In (Drop-off)	The act of recording a student's arrival at school. Records the time, who dropped off the student, and classifies the arrival as Early, On Time, or Late relative to the section's start time.
Check-Out (Pick-up)	The act of recording a student's departure from school. Records the time, who picked up the student, and classifies the departure as Early, On Time, or Late relative to the section's end time.
Pickup Person	A designated adult authorised by a parent to drop off or pick up a student. Identified by phone number (deduplicated across the system). Each student–pickup-person link has its own authorisation mode, permission type, and day schedule.
Unaccompanied Student	A student flagged as permitted to check in or check out without an accompanying adult (e.g., older students). Staff can see this flag during check-in/check-out.

---

Part II — Admin Portal

2. Dashboard

Status: Pending — none of Section 2 is implemented yet. The dashboard path constant exists on the backend but no controller, service, or metric queries are wired up; the admin portal has no dashboard view. All metrics, filters, breakdowns, and actions below describe the target behaviour.

The Dashboard provides a real-time snapshot of attendance across the school for the current or selected date.

2.1 Key Metric Cards

Metric	Description & Logic
Total Present	Count of students with a check-in record for the selected date.
Total Absent	School population minus Total Present. Students with no check-in record for the day.
School Population	Total enrolled active students across the filtered scope (campus, section, class).
Total Late (Drop-off)	Count of students checked in after the section's late threshold.
Total Late (Pick-up)	Count of students checked out after the section's end time plus late threshold.
Total Early Departures	Count of students checked out before the section's early departure threshold.

2.2 Dashboard Filters

All dashboard metrics must be filterable by the following dimensions simultaneously:

• Date (defaults to today; supports past dates)
• Campus
• Section (e.g., Nursery, Primary, JHS)
• Class / Grade

2.3 Summary Breakdowns

The dashboard provides attendance summaries grouped by:

• By Class — present, absent, and late counts per class
• By Campus — aggregated attendance per campus
• By Section — aggregated attendance per section within a campus

2.4 Dashboard Actions

• Export attendance summary for the selected date and filters as Excel (.xlsx)
• Quick-navigate to Attendance Register filtered by selected metrics

---

3. Attendance Register

The Attendance Register is the daily attendance view showing all students and their check-in/check-out status.

3.1 Register View

Displayed Columns:

• Student Name
• Student ID
• Class / Grade
• Status (Present / Absent / Late / Excused)
• Check-In Time
• Checked-In By (staff name, parent name, or "Self")
• Drop-off Classification (Early / On Time / Late)
• Check-Out Time
• Checked-Out By (staff name, parent name, pickup person name, or "Self")
• Pick-up Classification (Early / On Time / Late)
• Pickup Person (name of the person who collected the student)
• Unaccompanied Flag (indicates if student is permitted to be unaccompanied)

3.2 Filter Panel

Filter	Options / Behaviour
Date	Date picker; defaults to today
Campus	Dropdown; multi-select
Section	Dropdown; multi-select; depends on campus selection
Class / Grade	Dropdown; multi-select; depends on section selection
Status	Present, Absent, Late, Excused (multi-select)
Check-In Status	Checked In, Not Checked In
Check-Out Status	Checked Out, Not Checked Out
Drop-off Classification	Early, On Time, Late

3.3 Register Actions

Mass Check-In

• Admin selects a class and marks all students as checked in with a single action
• System records the current time as the check-in time for all students
• System records the admin who performed the mass check-in
• Students already checked in are skipped (no duplicate records)
• Drop-off classification (Early / On Time / Late) is calculated per student based on the section's schedule

Individual Check-In / Check-Out

• Admin can check in or check out an individual student
• System records the staff member who performed the action and the timestamp
• For check-out: admin can select the pickup person from the student's authorised list, or record an unrecognised person (flagged for review)

Mark as Excused

• Admin can mark an absent student as "Excused" with an optional reason
• Excused students are counted separately from absent in reports

Export

Status: Pending — no xlsx export endpoint exists for the register yet.

• Export the currently filtered register as Excel (.xlsx)
• Export respects all active filters

---

4. Check-In / Check-Out

Check-in and check-out are the core operations of the attendance system. Every check-in/check-out event creates an auditable record.

4.1 Check-In (Drop-off)

Recorded Data:

Field	Description
Student	The student being checked in
Time	Exact timestamp of check-in
Performed By	The staff member, parent, or pickup person who checked the student in
Method	Scan (QR / ID card) or Manual
Drop-off Person	The adult who accompanied the student (selected from authorised pickup persons, or manually entered)
Classification	Early, On Time, or Late — calculated automatically based on the section's start time and late threshold

4.2 Check-Out (Pick-up)

Recorded Data:

Field	Description
Student	The student being checked out
Time	Exact timestamp of check-out
Performed By	The staff member, parent, or pickup person who checked the student out
Method	Scan (QR / ID card) or Manual
Pickup Person	The adult who collected the student. Must be verified against the student's authorised pickup person list (see 4.4).
Classification	Early, On Time, or Late — calculated automatically based on the section's end time and late threshold

4.3 Unaccompanied Students

Some students are permitted to check in or check out without an accompanying adult.

• Unaccompanied flag is captured per check-in/check-out event on the AttendanceRecord (isUnaccompanied boolean), set by the staff member performing the action when no accompanying adult is required. A persistent per-student "permitted to be unaccompanied" setting is not modelled today — this is a day-by-day attribute on each record.
• When a staff member processes an unaccompanied student, the system clearly indicates that no accompanying adult is required
• Staff can see at a glance which students in a class are permitted to be unaccompanied (Status: Pending — depends on a persistent per-student flag, which is not modelled today)
• Check-in/check-out for unaccompanied students does not require selecting a drop-off/pickup person

4.4 Pickup Person Verification

When a student is being checked out, the system verifies the pickup person:

1. Staff selects the pickup person from the student's authorised list
2. System checks that the person is authorised for today (based on their schedule — general or day-specific)
3. System checks that the person has pick-up permission (not drop-off only)
4. If the person is not on the authorised list, the system flags the attempt and requires admin override
5. Unauthorised pickup attempts trigger a notification to the parent (see section 11)

4.5 Parent Self-Check-In / Check-Out

When enabled in Settings (see section 6), parents can check their children in or out via the Parent App.

• Requires explicit confirmation (e.g., "Confirm that [Child Name] has arrived at school")
• Records the parent as the person who performed the check-in/check-out
• Subject to the same time-based classification rules (Early / On Time / Late)
• Available only during configurable hours (e.g., not allowed outside school hours)

4.6 Business Rules — Check-In / Check-Out

A student can only be checked in once per day. Duplicate check-in attempts are rejected.

A student must be checked in before they can be checked out.

Mass check-in records the admin who performed it. Each student's record references the same admin but has its own timestamp and classification.

Check-in/check-out times cannot be backdated by staff. Only the current time is recorded. Admins can edit times after the fact with a reason logged in the audit trail. Status: Pending — no time-edit endpoint or audit-reason field exists yet; only current-time capture ships today.

If a student is checked out by someone not on the authorised pickup person list, the system requires admin confirmation and records the event as an unauthorised pickup for audit purposes. Status: Pending — CheckOutRequest has no override/admin-confirmation field and AttendanceService.checkOut() does not flag unauthorised pickups today.

---

5. Pickup Person Management (Admin View)

Pickup persons are primarily managed by parents through the Parent App. The admin view provides oversight and the ability to override or supplement parent-managed data.

5.1 Pickup Person List

Admins can view all designated pickup persons for any student, including:

• Person name, phone number, relationship, and photo
• Authorisation mode: General (any day) or Day-specific (restricted days)
• Permission type: Drop-off only, Pick-up only, or Both
• Day schedule (if day-specific): which days of the week

5.2 Admin Actions

• Add a pickup person to any student — system checks by phone number if the person already exists and links the existing record rather than creating a duplicate
• Remove a pickup person from a student — removes the link, not the person record (the person may still be linked to other students)
• Edit authorisation settings — change the authorisation mode, permission type, or day schedule for any student–pickup-person link
• Reverse lookup — view all students a given pickup person is authorised for, across families

5.3 Business Rules — Pickup Persons

A pickup person is uniquely identified by phone number across the entire system. Adding a person with an existing phone number links the existing record.

The same pickup person can be assigned to multiple students under the same parent or across different parents/families.

Each student–pickup-person link has its own authorisation mode, permission type, and day schedule. For example, a grandmother may be authorised to pick up Child A every day but only Monday and Wednesday for Child B.

Removing a pickup person from a student does not delete the person record — it only removes the link. The person may still be linked to other students.

A student must have at least one authorised pickup person unless the student is flagged as unaccompanied. Status: Pending — StudentPickupPersonService.remove() does not validate this today; the last pickup person can be removed unconditionally.

---

6. Settings

6.1 Section Schedule

Attendance schedules are configured per section (e.g., Nursery, Primary, JHS). Each section within a campus can have its own schedule.

Setting	Description
Start Time	The official start time for the section (e.g., 7:30 AM for Nursery, 8:00 AM for Primary). Used to calculate drop-off classification.
End Time	The official end time for the section (e.g., 2:00 PM for Nursery, 3:30 PM for Primary). Used to calculate pick-up classification.
Late Threshold (Drop-off)	Number of minutes after the start time before a student is classified as Late. Example: 15 minutes → arriving at 8:16 AM is Late if start time is 8:00 AM.
Late Threshold (Pick-up)	Number of minutes after the end time before a pick-up is classified as Late.
Early Departure Threshold	Number of minutes before the end time that classifies a check-out as an Early Departure.

6.2 General Settings

Setting	Description
Parent Self-Check-In	Toggle (enabled / disabled). When enabled, parents can check their children in or out via the Parent App.
Attendance Mode	Scan (QR code or ID card only), Manual (staff enters manually), or Both (either method accepted).
Self-Check-In Hours	Start and end time during which parent self-check-in is permitted. Only applicable when parent self-check-in is enabled.

---

7. Reports

Status: Pending — none of Section 7 is implemented yet. The reports path constant exists on the backend but no ReportsController / ReportsService / aggregation queries exist; the admin portal has no reports view. All four reports (7.1–7.4) and export (7.5) below describe the target behaviour.

The Reports module provides historical and analytical views of attendance data. All reports support date range filtering and export.

7.1 Attendance Summary Report

Filters:

• Date range
• Campus
• Section
• Class / Grade

Metrics:

• Total school days in the period
• Average daily attendance rate (present / population × 100%)
• Total present, absent, late, and excused counts
• Attendance rate trend chart over the selected period
• Breakdown by class, section, or campus (selectable grouping)

7.2 Individual Student Attendance Report

• Full attendance history for a specific student
• Each day shows: status, check-in time, check-out time, who checked in/out, classification
• Summary: total days present, absent, late, excused, and overall attendance percentage
• Exportable as Excel or PDF

7.3 Late Arrivals Report

Filters:

• Date range
• Campus, Section, Class

Content:

• List of all late check-ins within the period
• Columns: student name, class, date, check-in time, minutes late, section start time
• Sortable by frequency (students who are late most often appear first)

7.4 Absentee Report

Filters:

• Date range
• Campus, Section, Class
• Consecutive absences threshold (e.g., show students absent 3+ consecutive days)

Content:

• List of all absences within the period
• Columns: student name, class, date, excused (yes/no), reason (if excused)
• Consecutive absence flag for students with extended absences

7.5 Export

All reports support export as Excel (.xlsx). Exports respect all active filters.

---

Part III — Parent App

Status: Pending — all of Part III (sections 8–11) is unbuilt. The backend controllers/parentapp/ package is empty (.gitkeep only); no pickup-person parent endpoints, self-check-in flows, history view, or notification pipeline exist yet. Everything below describes target behaviour.

8. Pickup Person Management

Parents manage designated pickup persons for their children through the Parent App. The system deduplicates pickup persons by phone number to avoid duplicate records.

8.1 Pickup Person Fields

Field	Required	Description
Full Name	Yes	Display name of the pickup person
Phone Number	Yes	Unique identifier. If a person with this phone number already exists in the system, the existing record is linked rather than creating a duplicate.
Relationship	Yes	Relationship to the student (e.g., Grandmother, Uncle, Nanny, Driver, Family Friend)
Photo	Optional	Photo of the pickup person for visual verification by staff

8.2 Authorisation Settings

Each student–pickup-person link has its own authorisation configuration:

Setting	Options	Description
Authorisation Mode	General, Day-specific	General — the person is authorised any school day. Day-specific — the person is authorised only on selected days of the week.
Permission Type	Drop-off only, Pick-up only, Both	Controls whether the person can drop off, pick up, or both.
Day Schedule	Mon, Tue, Wed, Thu, Fri (multi-select)	Only applicable when authorisation mode is Day-specific. Defines which days of the week this person is authorised.

8.3 Multi-Child Assignment

• A parent can assign the same pickup person to multiple children
• Each child–pickup-person link has independent authorisation settings
• Example: Grandmother is authorised for Child A every day (General, Both) but only Monday and Wednesday for Child B (Day-specific, Pick-up only)

8.4 Business Rules — Pickup Persons (Parent App)

When a parent enters a phone number that matches an existing pickup person, the system links the existing record. The parent does not need to re-enter name, relationship, or photo — these are pre-filled from the existing record.

A parent can update the name, relationship, and photo of a pickup person they have added. Changes are visible to all families the person is linked to.

Removing a pickup person from a child only removes the link for that child. The person may still be linked to other children (same parent or different parents).

---

9. Self-Check-In / Check-Out

When enabled by the school (see Settings section 6.2), parents can check their children in or out through the Parent App.

9.1 Check-In Flow

1. Parent opens the attendance section for their child
2. Parent taps "Check In [Child Name]"
3. System displays a confirmation: "Confirm that [Child Name] has arrived at school"
4. On confirmation, the system records the check-in with the parent as the performing user
5. Drop-off classification (Early / On Time / Late) is calculated based on the section's schedule

9.2 Check-Out Flow

1. Parent opens the attendance section for their child
2. Parent taps "Check Out [Child Name]"
3. System displays a confirmation: "Confirm that [Child Name] is leaving school"
4. On confirmation, the system records the check-out with the parent as the performing user
5. Pick-up classification (Early / On Time / Late) is calculated based on the section's schedule

9.3 Business Rules — Self-Check-In/Out

Self-check-in/out is only available when enabled in school settings.

Self-check-in/out is only permitted during the configured self-check-in hours.

A parent can only check in/out their own children.

Self-check-in/out follows the same rules as staff-performed check-in/out: no duplicate check-ins, must check in before check-out.

---

10. Attendance History

Parents can view their child's attendance history in the Parent App.

10.1 History View

Displayed per day:

• Date
• Status (Present / Absent / Late / Excused)
• Check-in time and who performed it
• Check-out time and who performed it
• Drop-off / pick-up classification
• Pickup person name (if applicable)

10.2 Summary

• Total days present, absent, late, and excused for the current term
• Overall attendance percentage

---

11. Notifications

Attendance notifications keep parents informed of their child's daily attendance events and alert them to potential safety concerns.

11.1 Notification Events

Event	Trigger	Recipients
Check-In	Student is checked in (by staff, parent, or self)	Parent / Guardian
Check-Out	Student is checked out (by staff, parent, pickup person, or self)	Parent / Guardian
Late Arrival	Student is checked in after the section's late threshold	Parent / Guardian
Early Departure	Student is checked out before the early departure threshold	Parent / Guardian
Pickup Completed	Student is picked up — includes the name of the pickup person	Parent / Guardian
Unauthorised Pickup Attempt	Someone not on the student's authorised pickup person list attempts to pick up the student	Parent / Guardian, School Admin

11.2 Notification Content

Each notification includes:

• Student name
• Event type
• Timestamp
• Who performed the action (staff name, parent name, or pickup person name)
• School / campus name

11.3 Business Rules — Notifications

Unauthorised pickup attempt notifications are sent immediately and to both the parent and the school admin.

Parents can configure notification preferences (e.g., disable check-in notifications but keep late arrival alerts) — subject to the school's notification policy.

Notifications are delivered via the channels configured in the school's notification settings (push notification, SMS, or both).

---

Revision History

Version	Date	Author	Changes
v1.0	2026-03-21	—	Initial PRD: attendance dashboard, register, check-in/check-out with drop-off/pickup tracking, pickup person management, parent self-check-in, settings, reports, and notifications
v1.1	2026-04-19	—	Sync pass against implementation: marked Section 2 (Dashboard), Section 7 (Reports), and Part III (Parent App, sections 8–11) as Pending — not yet implemented. Inline Pending notes added to register export (3.3), time-edit rule (4.6), unauthorised-pickup rule (4.6), and pickup-person minimum rule (5.3). Reconciled Unaccompanied flag (4.3) to describe current per-record storage on AttendanceRecord.isUnaccompanied rather than a per-student attribute. No product scope changed.