System Requirements Document for nursery-school-monitoring

1. Introduction

This document specifies nursery-school-monitoring, an AI-assisted safety and wellbeing monitoring system for nursery and preschool children. It is written for the school administrators and authorized staff who will operate it, the teachers and caregivers who will feed it daily records, and the parents and guardians who receive approved notifications from it.

The product intent is to help school administrators and authorized staff monitor student attendance, meal status, potential health concerns, and classroom safety using CCTV cameras, a web dashboard, and teacher-assisted reporting. The system must be practical, affordable, privacy-focused, and achievable within 15–20 days as a working MVP. It prioritizes a functional, demonstrable MVP over unsupported claims of fully automatic monitoring, and it clearly labels features that require further model training or real-world validation.

The system is built as working modules, each tested, with a documented fallback for the AI/video-processing module if real-time action recognition is unavailable. It is delivered with complete project architecture, frontend and backend source code, database schema and sample records, REST API documentation, admin and teacher dashboards, testing instructions and sample test data, local installation and deployment instructions, a project report, workflow diagram, final presentation, itemized budget, hardware requirements, API requirements, and a 15–20-day development schedule.

2. System Overview

nursery-school-monitoring is a web application with a React frontend, a shared Python FastAPI backend, and PostgreSQL for application-owned persistent data (student information, attendance, incidents, and reports). CCTV footage is stored separately from the database; large video files are never placed directly in the database.

The system serves three active human personas: the School Administrator, the Teacher / Caregiver, and the Parent / Guardian. Administrators register students, staff, classrooms, and authorized users; review AI-flagged safety events and their permitted evidence; confirm, dismiss, or escalate alerts; and manage settings, audit logs, privacy controls, and user management. Teachers and caregivers record daily attendance status, mark student-wise meal checklists, and record symptoms and wellbeing observations. Parents and guardians receive only approved, relevant notifications about their child's attendance and wellbeing, subject to consent and school policy.

CCTV cameras (existing cameras or an authorized test video source) provide an authorized video stream. A video-processing service samples frames or short clips, and an AI service processes supported visual events. The backend creates a timestamped alert when a configured event is detected. Attendance and meal records are updated by the camera system only where reliable; otherwise, staff enter the information. The dashboard generates daily and monthly reports.

The system is privacy-focused: it avoids facial recognition and biometric identification in the MVP, processes video locally where possible, does not continuously upload classroom footage to external AI services, uses restricted and encrypted incident storage with a defined deletion schedule, and does not use automated AI results to discipline teachers or children. It provides an emergency escalation process for credible safety concerns and uses synthetic or consented test footage during development.

Provisioned infrastructure (authoritative inventory): a shared FastAPI backend process for application APIs and domain modules; a database service (MariaDB) for application-owned persistent data; a React frontend application UI; a litellm gateway for the backend's model-provider calls; and a postgres service supporting LiteLLM, separate from application-owned storage. The shared backend is reused for feature APIs. These services do not add product requirements or change access decisions.

Removed from scope

• None. No concepts were removed from the authoritative requirement thread.

2a. Product Interpretation and Delivery Boundary

The product is a first-party web application owned by the school. All operational surfaces — the dashboard, student records, attendance, meals, camera status, AI event review, health and wellbeing reports, parent notification history, and settings — are delivered by the application itself. The application owns identity: administrators provision staff and authorized users before their first sign-in, and returning users verify through the secure login surface. Role-based access governs which surfaces and actions each role may use.

CCTV cameras and any authorized test video source are external providers of video streams; the application consumes their streams and reports camera status but does not own the cameras. The AI/video-processing module runs as part of the backend's processing capability, with a documented fallback when real-time action recognition is unavailable. A vision-language API may be used only if it is necessary and permitted for the selected workflow; it is not a current requirement. Parent notifications are delivered to parents and guardians as external recipients; the application records notification history and enforces consent and school policy before sending.

Everything described in this document is current scope. No future-horizon features are specified beyond the MVP; features requiring further model training or real-world validation are labeled as such within current scope rather than deferred.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous public entry explaining the AI-based nursery safety and wellbeing monitoring system, its audiences (administrators, teachers/caregivers, parents/guardians), and its privacy-focused scope before any sign-in. States: default, loading (minimal), error (static content fallback).
• Primary actions: Navigate to secure login. Supporting actions: Read scope and privacy summary.
• Domain entities: None persisted; presentation of product scope.
• Component responsibilities: Hero heading, scope summary, privacy summary, sign-in call-to-action.
• States: Empty/loading not applicable beyond static render; success = page renders; error = static fallback message; recovery = retry navigation to login.

Secure login and role-based access

• Information/state: Credential entry for provisioned users; role-based access determines available surfaces after sign-in. States: anonymous (pre-identity), authenticating, authenticated, failed authentication, locked/error.
• Primary actions: Sign in with provisioned credentials. Supporting actions: View access-denied message; sign out.
• Domain entities: User account (provisioned by administrator), role.
• Component responsibilities: Credential form, validation messages, role resolution, session establishment.
• States: Loading during authentication; empty not applicable; success = session established and role-appropriate surfaces available; error = invalid credentials or unauthorized role with clear message; recovery = retry sign-in.

Dashboard

• Information/state: Total students, present students, absent students, meal concerns, and open safety incidents. Labels for features needing further validation. States: loading, populated, empty (no data for day), error.
• Primary actions: Review daily counts and open safety incidents. Supporting actions: Navigate to attendance, meals, event alerts, cameras.
• Domain entities: Student, attendance record, meal record, incident.
• Component responsibilities: Metric summaries, charts (Recharts), alert indicators, validation labels.
• States: Loading skeletons; empty state with guidance; success = metrics and charts render; error = retry with message; recovery = refresh.

Student registration and profiles

• Information/state: Student records with name, class, age, parent contact, and authorized pickup details. States: list, detail, create/edit form, validation errors.
• Primary actions: Register a student. Supporting actions: View and edit profiles; search/filter.
• Domain entities: Student, class, parent contact, authorized pickup details.
• Component responsibilities: Registration form, profile view, validation, list/table.
• States: Loading; empty (no students); success = record saved and visible; error = validation or save failure with recovery; recovery = correct and resubmit.

Attendance calendar and reports

• Information/state: Daily present, absent, late, and early departure status per student; daily attendance percentage; monthly reports. States: calendar view, daily view, monthly report, loading, empty, error.
• Primary actions: Record daily attendance status (teacher-assisted entry, QR codes, or approved camera-based presence where reliable). Supporting actions: View daily percentage and monthly reports; trigger attendance notifications subject to consent and school policy.
• Domain entities: Attendance record, student, class, notification.
• Component responsibilities: Calendar, status entry controls, percentage display, monthly report charts, notification trigger.
• States: Loading; empty (no records for date); success = records saved and reports render; error = save/report failure with recovery; recovery = retry or staff re-entry.

Meal tracking and daily meal reports

• Information/state: Student-wise meal checklist for breakfast, lunch, snacks, and water intake with statuses ate well, ate partially, refused food, or meal not recorded; daily meal reports; concern flags. Optional camera-based observation may flag a possible meal-time concern where technically feasible, without claiming quantity eaten from ordinary CCTV. States: checklist, daily report, loading, empty, error.
• Primary actions: Mark meal status per student per meal. Supporting actions: View daily meal reports; notify authorized staff when a child repeatedly refuses meals or has a recorded concern.
• Domain entities: Meal record, student, concern notification.
• Component responsibilities: Checklist grid, status controls, report view, concern indicator.
• States: Loading; empty (no meals recorded); success = statuses saved and report renders; error = save failure with recovery; recovery = retry.

CCTV camera status and live feed

• Information/state: Camera status and live feed where supported by the camera. States: connected, disconnected, unsupported (no live feed), loading, error.
• Primary actions: View camera status and live feed where supported. Supporting actions: Refresh status.
• Domain entities: Camera, camera status.
• Component responsibilities: Status indicators, live feed player where supported, fallback message when unsupported.
• States: Loading; empty (no cameras configured); success = status and feed render; error = connection failure with recovery; recovery = retry.

AI-generated event alerts

• Information/state: AI-generated safety events with timestamps and review status; secure incident-review panel with statuses new, under review, verified, or dismissed; permitted evidence (short incident clip or timestamped event reference where legally permitted); urgent incident workflow for suspected injury or immediate danger. States: list, detail/review, loading, empty, error.
• Primary actions: Review an event and its permitted evidence; confirm, dismiss, or escalate the alert; move status through new → under review → verified/dismissed; initiate urgent incident workflow. Supporting actions: Filter by status; view timestamps.
• Domain entities: Incident, evidence reference, review status, escalation.
• Component responsibilities: Event list, review panel, status controls, evidence display, escalation action, urgent workflow entry.
• States: Loading; empty (no events); success = review action saved and status updated; error = save failure with recovery; recovery = retry. AI predictions never automatically declare abuse.

Health and wellbeing reports

• Information/state: Staff-recorded symptoms (fever, vomiting, unusual tiredness, injury, discomfort); visible events such as a child falling or remaining unusually inactive for an extended period where feasible; staff verification before generating a health alert; health and wellbeing reports. States: record entry, verification pending, alert generated, report view, loading, empty, error.
• Primary actions: Record symptoms and wellbeing observations; verify before health alert generation. Supporting actions: View health and wellbeing reports.
• Domain entities: Wellbeing record, symptom, verification, health alert.
• Component responsibilities: Symptom entry form, verification control, report view, alert indicator.
• States: Loading; empty (no records); success = record saved and alert generated only after verification; error = save failure with recovery; recovery = retry. CCTV never diagnoses disease.

Parent notification history

• Information/state: Approved, relevant parent notifications subject to consent and school policy; notification history. States: list, detail, loading, empty, error.
• Primary actions: Send approved notification to parents. Supporting actions: Review notification history; confirm consent and policy before sending.
• Domain entities: Notification, consent status, parent contact.
• Component responsibilities: Notification composer, consent/policy check, history list.
• States: Loading; empty (no notifications); success = notification sent and recorded; error = send failure or consent block with recovery; recovery = retry or resolve consent.

Settings, audit logs, privacy controls, and user management

• Information/state: Settings; audit logs; privacy controls; user management including staff, classrooms, and authorized users. States: list, edit, loading, empty, error.
• Primary actions: Manage staff, classrooms, and authorized users; configure settings and privacy controls; review audit logs. Supporting actions: Provision user accounts before first sign-in.
• Domain entities: User, staff, classroom, audit log entry, privacy setting.
• Component responsibilities: User management forms, classroom management, settings controls, audit log viewer, privacy controls.
• States: Loading; empty (no users/logs); success = changes saved and logged; error = save failure with recovery; recovery = retry.

3. Functional Requirements

FR-1 (explicit): As a School Administrator, I should register students with their name, class, age, parent contact, and authorized pickup details, so that student records are complete for attendance, meals, and safety monitoring. Lifecycle: Trigger = administrator opens student registration; Input = name, class, age, parent contact, authorized pickup details; Result = student record persisted and visible in profiles; Access = role-restricted; Failure/recovery = validation errors shown, correct and resubmit; Continuation = student available for attendance and meal records.

FR-2 (explicit): As a Teacher / Caregiver, I should record daily present, absent, late, and early departure attendance status via teacher-assisted entry, QR codes, or an approved camera-based presence system, so that daily attendance is accurate. Lifecycle: Trigger = daily attendance session; Input = per-student status; Result = attendance record saved; Access = role-restricted; Failure/recovery = save failure retried or staff re-entry; Continuation = daily percentage and monthly reports update.

FR-3 (explicit): As a School Administrator, I should view daily attendance percentage and monthly attendance reports, so that I can monitor attendance trends. Lifecycle: Trigger = open attendance reports; Result = daily percentage and monthly report rendered; Access = role-restricted; Failure/recovery = retry report load; Continuation = use reports for daily/monthly reporting.

FR-4 (explicit): As a School Administrator, I should send attendance notifications to parents subject to consent and school policies, so that parents are informed appropriately. Lifecycle: Trigger = attendance event or administrator action; Input = notification content; Result = notification sent and recorded in history; Access = role-restricted; Failure/recovery = consent/policy block or send failure with recovery; Continuation = notification appears in parent notification history.

FR-5 (explicit): As a Teacher / Caregiver, I should maintain a student-wise meal checklist for breakfast, lunch, snacks, and water intake with statuses ate well, ate partially, refused food, or meal not recorded, so that meal status is tracked per student. Lifecycle: Trigger = meal time; Input = status per student per meal; Result = meal record saved; Access = role-restricted; Failure/recovery = save failure retried; Continuation = daily meal reports update.

FR-6 (explicit): As a Teacher / Caregiver, I should optionally flag a possible meal-time concern from camera observation where technically feasible, without claiming quantity eaten from ordinary CCTV, so that concerns are surfaced without false quantity claims. Lifecycle: Trigger = camera observation where feasible; Result = possible concern flagged; Access = role-restricted; Failure/recovery = fallback to staff entry when not feasible; Continuation = concern visible in meal reports. Constraint: never claim a specific quantity eaten based solely on ordinary CCTV.

FR-7 (explicit): As a School Administrator, I should be notified when a child repeatedly refuses meals or has a recorded concern, so that I can respond. Lifecycle: Trigger = repeated refusal or recorded concern; Result = authorized staff notified; Access = role-restricted; Failure/recovery = retry notification; Continuation = concern tracked in meal reports.

FR-8 (explicit): As a School Administrator, I should use classroom CCTV with action-recognition models to flag potentially unsafe physical actions such as hitting, pushing, or rough handling for human review, so that suspicious events are reviewed by humans. Lifecycle: Trigger = CCTV stream processed; Result = event flagged for human review; Access = role-restricted; Failure/recovery = documented fallback when real-time action recognition unavailable; Continuation = event appears in AI-generated event alerts. Constraint: never automatically declare abuse based on AI prediction.

FR-9 (explicit): As a School Administrator, I should save a short incident clip or timestamped event reference where legally permitted, so that permitted evidence is available for review. Lifecycle: Trigger = flagged event; Result = clip or timestamped reference saved where legally permitted; Access = role-restricted; Failure/recovery = timestamped reference fallback when clip not permitted; Continuation = evidence available in review panel.

FR-10 (explicit): As a School Administrator, I should use a secure incident-review panel with statuses new, under review, verified, or dismissed, so that incidents are reviewed with human accountability. Lifecycle: Trigger = open review panel; Input = review decision; Result = status updated; Access = role-restricted; Failure/recovery = save failure retried; Continuation = status reflected in event list.

FR-11 (explicit): As a Teacher / Caregiver, I should record symptoms such as fever, vomiting, unusual tiredness, injury, or discomfort, so that wellbeing concerns are documented. Lifecycle: Trigger = observed symptom; Input = symptom details; Result = wellbeing record saved; Access = role-restricted; Failure/recovery = save failure retried; Continuation = record available for verification and reports.

FR-12 (explicit): As a School Administrator, I should have visible events such as a child falling or remaining unusually inactive for an extended period flagged where feasible, so that potential wellbeing concerns are surfaced. Lifecycle: Trigger = camera observation where feasible; Result = event flagged; Access = role-restricted; Failure/recovery = fallback to staff observation; Continuation = event available for staff verification.

FR-13 (explicit): As a Teacher / Caregiver, I should verify before a health alert is generated, so that health alerts require staff verification. Lifecycle: Trigger = recorded symptom or flagged event; Input = staff verification; Result = health alert generated only after verification; Access = role-restricted; Failure/recovery = alert withheld until verified; Continuation = verified alert appears in health reports. Constraint: never diagnose disease using CCTV.

FR-14 (explicit): As a School Administrator, I should have an urgent incident workflow for suspected injury or immediate danger, so that credible safety concerns are escalated promptly. Lifecycle: Trigger = suspected injury or immediate danger; Input = urgent incident details; Result = urgent incident recorded and escalated; Access = role-restricted; Failure/recovery = retry escalation; Continuation = escalation tracked in incident review.

FR-15 (explicit): As a School Administrator, I should see a dashboard showing total students, present students, absent students, meal concerns, and open safety incidents, so that I have an at-a-glance operational view. Lifecycle: Trigger = open dashboard; Result = metrics and charts rendered; Access = role-restricted; Failure/recovery = retry load; Continuation = navigate to detail pages.

FR-16 (explicit): As a School Administrator, I should view CCTV camera status and live feed where supported by the camera, so that I can confirm camera health. Lifecycle: Trigger = open camera page; Result = status and live feed where supported; Access = role-restricted; Failure/recovery = unsupported message or retry; Continuation = monitor camera health.

FR-17 (explicit): As a School Administrator, I should see AI-generated event alerts with timestamps and review status, so that I can track review progress. Lifecycle: Trigger = open event alerts; Result = alerts with timestamps and status rendered; Access = role-restricted; Failure/recovery = retry load; Continuation = open review panel.

FR-18 (explicit): As a School Administrator, I should view health and wellbeing reports, so that I can monitor wellbeing trends. Lifecycle: Trigger = open health reports; Result = reports rendered; Access = role-restricted; Failure/recovery = retry load; Continuation = use reports for daily/monthly reporting.

FR-19 (explicit): As a School Administrator, I should view parent notification history, so that I can confirm approved notifications were sent. Lifecycle: Trigger = open notification history; Result = history rendered; Access = role-restricted; Failure/recovery = retry load; Continuation = review and resend if needed.

FR-20 (explicit): As a School Administrator, I should manage settings, audit logs, privacy controls, and user management, so that the system is governed and auditable. Lifecycle: Trigger = open settings; Input = configuration changes; Result = changes saved and logged; Access = role-restricted; Failure/recovery = save failure retried; Continuation = audit log records change.

FR-21 (explicit): As a School Administrator, I should have secure login with role-based access, so that only authorized users reach protected surfaces. Lifecycle: Trigger = sign-in attempt; Input = credentials; Result = session established with role; Access = anonymous entry then role-restricted; Failure/recovery = invalid credentials message and retry; Continuation = role-appropriate surfaces available.

FR-22 (explicit): As a School Administrator, I should register staff, classrooms, and authorized users, so that the school's operational structure is configured. Lifecycle: Trigger = open user management; Input = staff, classroom, user details; Result = records saved; Access = role-restricted; Failure/recovery = validation errors and retry; Continuation = provisioned users can sign in.

FR-23 (explicit): As a School Administrator, I should generate daily and monthly reports, so that operational reporting is available. Lifecycle: Trigger = open reports; Result = daily and monthly reports rendered; Access = role-restricted; Failure/recovery = retry; Continuation = use for school reporting.

FR-24 (explicit): As a School Administrator, I should have authentication, role-based permissions, request validation, error handling, and audit logging implemented, so that the system is secure and auditable. Lifecycle: Trigger = any API request; Result = validated, authorized, logged; Access = role-restricted; Failure/recovery = error response with recovery; Continuation = audit log records action.

FR-25 (explicit): As a School Administrator, I should have REST endpoints for students, attendance, meals, incidents, camera status, notifications, and reports summary, so that the frontend and integrations can operate. Lifecycle: Trigger = API call; Result = endpoint responds per contract; Access = role-restricted; Failure/recovery = validation/error response; Continuation = client retries or corrects.

FR-26 (explicit): As a School Administrator, I should have CCTV footage stored separately from the database, so that large video files are not placed directly in the database. Lifecycle: Trigger = footage capture; Result = footage stored separately; Access = role-restricted; Failure/recovery = storage failure logged; Continuation = reference retained in database.

FR-27 (explicit): As a School Administrator, I should have attendance identification kept separate from incident detection, so that the two workflows do not interfere. Lifecycle: Trigger = processing; Result = separate pipelines; Access = role-restricted; Failure/recovery = isolated failure; Continuation = each workflow continues independently.

FR-28 (explicit): As a School Administrator, I should have a documented fallback for the AI/video-processing module if real-time action recognition is unavailable, so that the system remains demonstrable. Lifecycle: Trigger = action recognition unavailable; Result = fallback documented and active; Access = role-restricted; Failure/recovery = fallback engaged; Continuation = staff-assisted review continues.

FR-29 (explicit): As a School Administrator, I should receive frontend and backend source code, database schema with sample records, REST API documentation, testing instructions with sample test data, and local installation and deployment instructions, so that the system can be built and operated. Lifecycle: Trigger = delivery; Result = deliverables provided; Access = not applicable; Failure/recovery = not applicable; Continuation = installation and testing.

FR-30 (explicit): As a School Administrator, I should receive project architecture, project report, workflow diagram, final presentation, itemized budget, hardware requirements, API requirements, and a 15–20-day development schedule, so that the project is documented. Lifecycle: Trigger = delivery; Result = documentation provided; Access = not applicable; Failure/recovery = not applicable; Continuation = project review.

FR-31 (explicit): As a School Administrator, I should see features that require further model training or real-world validation clearly labeled, so that limitations are transparent. Lifecycle: Trigger = viewing features; Result = labels visible; Access = role-restricted; Failure/recovery = not applicable; Continuation = informed use.

FR-32 (required_inference): As a School Administrator, I should provision staff and authorized user accounts before their first sign-in, so that accepted users can access the system. Lifecycle: Trigger = new staff/user; Input = account details and role; Result = account provisioned; Access = role-restricted; Failure/recovery = validation errors and retry; Continuation = user signs in via secure login.

FR-33 (required_inference): As a School Administrator, I should confirm school authorization and informed parent/guardian consent are obtained before processing children's video, so that video processing is lawful. Lifecycle: Trigger = enabling video processing; Input = authorization and consent confirmation; Result = processing permitted; Access = role-restricted; Failure/recovery = processing blocked until confirmed; Continuation = video processing proceeds.

FR-34 (required_inference): As a School Administrator, I should assess applicable Indian child-protection, privacy, and data-protection requirements before deployment, so that deployment is compliant. Lifecycle: Trigger = pre-deployment; Result = assessment recorded; Access = role-restricted; Failure/recovery = deployment blocked until assessed; Continuation = deployment proceeds.

FR-35 (required_inference): As a School Administrator, I should ensure synthetic or consented test footage is available for development, so that development uses lawful footage. Lifecycle: Trigger = development setup; Result = test footage available; Access = role-restricted; Failure/recovery = development blocked without footage; Continuation = development proceeds.

FR-36 (required_inference): As a School Administrator, I should connect CCTV cameras or an authorized test video source for camera status and event detection, so that monitoring operates. Lifecycle: Trigger = setup; Result = source connected; Access = role-restricted; Failure/recovery = connection failure with retry; Continuation = status and events flow.

FR-37 (required_inference): As a School Administrator, I should configure encrypted incident storage with a defined deletion schedule, so that incident evidence is protected and retained per policy. Lifecycle: Trigger = setup; Input = storage and schedule configuration; Result = storage encrypted and schedule active; Access = role-restricted; Failure/recovery = configuration error with retry; Continuation = evidence stored and deleted per schedule.

FR-38 (required_inference): As a School Administrator, I should have a documented fallback configured for when real-time action recognition is unavailable, so that the system degrades gracefully. Lifecycle: Trigger = action recognition unavailable; Result = fallback active; Access = role-restricted; Failure/recovery = fallback engaged; Continuation = staff-assisted review continues.

4. User Personas

School Administrator

The School Administrator is the operational owner of the school's monitoring system. They register students, staff, classrooms, and authorized users; review AI-flagged safety events and their permitted evidence; confirm, dismiss, or escalate alerts; and manage settings, audit logs, privacy controls, and user management. They are the primary decision-maker for incident review and the guardian of privacy controls. Their primary goal is to keep every child accounted for and every safety concern resolved with human verification, while ensuring daily and monthly reports are available. They interact with teachers and caregivers (who supply attendance, meal, and symptom records) and with parents and guardians (who receive approved notifications). They succeed when incidents are resolved with human verification and daily/monthly reports are available.

Teacher / Caregiver

The Teacher / Caregiver is the daily frontline recorder. They record daily attendance status, mark student-wise meal checklists (ate well, partially, refused, not recorded), and record symptoms such as fever, vomiting, tiredness, injury, or discomfort. They are the human verifier for health alerts: a health alert is generated only after staff verification. Their primary goal is accurate staff-entered records and verified health alerts. They interact with the School Administrator (who reviews incidents and manages users) and indirectly with parents and guardians through approved notifications. They succeed when staff-entered records are accurate and health alerts are generated only after staff verification.

Parent / Guardian

The Parent / Guardian is the external recipient of approved, relevant notifications about their child's attendance and wellbeing, subject to consent and school policy. They do not operate the dashboard; they receive notifications and are informed of relevant, approved events without exposure to unverified AI results. Their primary goal is to be informed of relevant, approved events. They interact with the School Administrator (who sends approved notifications) and the Teacher / Caregiver (whose records inform notifications). They succeed when they are informed of relevant, approved events without exposure to unverified AI results.

5. Core User Flows

Flow 1: Administrator registers a student

1. School Administrator signs in via Secure login and role-based access.
2. Administrator opens Student registration and profiles.
3. Administrator enters name, class, age, parent contact, and authorized pickup details.
4. System validates and saves the student record; the profile appears in the list.
5. If validation fails, the administrator corrects fields and resubmits.
6. The student is now available for attendance and meal records.

Flow 2: Teacher records daily attendance

1. Teacher / Caregiver signs in via Secure login and role-based access.
2. Teacher opens Attendance calendar and reports.
3. Teacher records present, absent, late, or early departure status per student via teacher-assisted entry, QR codes, or approved camera-based presence where reliable.
4. System saves records; daily attendance percentage and monthly reports update.
5. If save fails, teacher retries or re-enters.
6. Administrator views daily percentage and monthly reports on the same page.

Flow 3: Administrator sends attendance notification to parents

1. Administrator opens Parent notification history.
2. Administrator composes an attendance notification.
3. System checks consent and school policy before sending.
4. Notification is sent to parents and recorded in history.
5. If consent/policy blocks or send fails, administrator resolves and retries.
6. Parent / Guardian receives the approved notification.

Flow 4: Teacher marks meal checklist

1. Teacher opens Meal tracking and daily meal reports.
2. Teacher marks each student's breakfast, lunch, snacks, and water intake as ate well, ate partially, refused food, or meal not recorded.
3. Optional camera-based observation may flag a possible meal-time concern where technically feasible, without claiming quantity eaten from ordinary CCTV.
4. System saves records; daily meal reports update.
5. If a child repeatedly refuses meals or has a recorded concern, authorized staff are notified.
6. Administrator reviews daily meal reports.

Flow 5: AI flags a safety event and administrator reviews

1. CCTV cameras provide an authorized video stream; the video-processing service samples frames or short clips; the AI service processes supported visual events.
2. Backend creates a timestamped alert when a configured event is detected; a short incident clip or timestamped event reference is saved where legally permitted.
3. Administrator opens AI-generated event alerts and sees the event with timestamp and review status.
4. Administrator opens the secure incident-review panel and reviews permitted evidence.
5. Administrator confirms, dismisses, or escalates; status moves through new → under review → verified/dismissed.
6. If real-time action recognition is unavailable, the documented fallback engages and staff-assisted review continues.
7. AI predictions never automatically declare abuse.

Flow 6: Teacher records symptoms and verifies health alert

1. Teacher opens Health and wellbeing reports.
2. Teacher records symptoms such as fever, vomiting, unusual tiredness, injury, or discomfort.
3. Where feasible, visible events such as a child falling or remaining unusually inactive for an extended period are flagged.
4. Teacher verifies before a health alert is generated.
5. System generates the health alert only after staff verification; CCTV never diagnoses disease.
6. Administrator views health and wellbeing reports.

Flow 7: Administrator handles urgent incident

1. Administrator identifies suspected injury or immediate danger.
2. Administrator initiates the urgent incident workflow from AI-generated event alerts.
3. System records and escalates the urgent incident.
4. Administrator tracks escalation in incident review.
5. If escalation fails, administrator retries.

Flow 8: Administrator manages users and settings

1. Administrator opens Settings, audit logs, privacy controls, and user management.
2. Administrator registers staff, classrooms, and authorized users; provisions accounts before first sign-in.
3. Administrator configures settings and privacy controls; reviews audit logs.
4. System saves changes and records them in audit logs.
5. If save fails, administrator retries.
6. Provisioned users can sign in via Secure login and role-based access.

Flow 9: Administrator monitors camera health

1. Administrator opens CCTV camera status and live feed.
2. System shows camera status and live feed where supported by the camera.
3. If a camera is unsupported or disconnected, the administrator sees a clear message and retries.
4. Administrator confirms camera health.

Flow 10: Administrator reviews dashboard and reports

1. Administrator opens Dashboard and sees total students, present students, absent students, meal concerns, and open safety incidents, with labels for features needing further validation.
2. Administrator navigates to attendance, meals, event alerts, or cameras for detail.
3. Administrator generates daily and monthly reports.
4. If data is empty or load fails, administrator refreshes or retries.

6. Visuals Colors and Theme

The creative direction is authoritative: Functional clarity for care-critical school operations, muse Dieter Rams. The interface must feel child-aware without becoming childish, and safety-focused without becoming alarming.

Colour tokens (light mode):

• Background (dominant canvas, ~60%): #F4F1EB warm paper.
• Surface (elevated working surfaces and tables, ~30%): #FFFDF8.
• Text (body and rules): #252624 charcoal.
• Primary (urgent attention, unresolved safety review, primary actions only; never to state an allegation as fact): #D96B22 Braun-like orange.
• Accent (verified completion, healthy camera connection, recorded attendance): #2E7D62 forest green.
• Muted (metadata, timestamps, inactive states): #7A766E.
• Pale tints derived from these colours for status fills, keeping text contrast readable.

Typography:

• Headings: Barlow Condensed 600–700 for compact operational headings and large numeric summaries.
• Body: Fira Sans 400–600 for humanist, highly legible labels and body copy.
• Sentence case for page names; uppercase with 0.1em tracking only for compact system labels such as CAMERA 03 or REVIEW QUEUE.
• Scale (1.25): display clamp(42px, 7vw, 84px); page title 32/40px; section title 24/30px; metric 28/34px; body 16/24px; compact table text 14/20px; micro-label 12/16px. Display starts at 42px on mobile and wraps rather than clips.

Shape language: Purposeful rounded rectangles with 8px radii for controls and 12px for panels; 1px charcoal-tinted rules; squared data grids; circular status lamps; clear physical toggle affordances. Avoid bubbly cards, decorative blobs, and overly soft pill-heavy UI. A single orange safety tab projects from an incident panel edge as a recognizable operational marker.

Layout: Strict 12-column desktop grid, 8-column tablet grid, 4-column mobile grid. Desktop uses a persistent 232px left rail with numbered operational sections; mobile collapses it into a bottom-safe navigation sheet with the current section and urgent-review shortcut always visible. Dashboard content is composed from unequal functional modules: a wide attendance register, a narrow safety queue, a camera-health strip, and a full-width review timeline. At 375px all data modules become stacked rows with label/value pairs and horizontally scrollable tables where needed.

Imagery: The interface itself is the principal imagery: privacy-safe camera placeholders, simplified classroom floor-plan diagrams, CCTV framing guides, timeline markers, and diagrammatic child-safety workflow symbols. Where footage is permitted, show a tightly controlled still-frame or clip thumbnail with timestamp, retention badge, camera name, and access label; never use stock children photography, expressive-face analysis, or sensational incident imagery.

7. Signature Design Concept

The first dashboard screen opens as an operations board, not a marketing SaaS hero. A full-width warm-paper field (#F4F1EB) carries a left-aligned oversized Barlow Condensed heading, "Today, every child accounted for," at clamp(42px, 7vw, 84px). Beneath it, a black ruled attendance ledger spans eight columns with large present/absent figures and an orange vertical review marker. The remaining four columns contain a tall ivory (#FFFDF8) "Human review queue" panel whose top edge carries the orange safety tab, showing one timestamped possible event and explicit "AI flag — verification required" language. A thin green (#2E7D62) camera-status rail runs along the bottom of the composition. On mobile, the heading sits above the ledger; the review queue follows as a full-width panel, preserving all readable controls and labels.

Signature moves: a numbered left navigation rail treats Attendance, Meals, Review, Cameras, Wellbeing, and Privacy as operational stations, with the active station marked by a 4px orange rule and a large two-digit index; the dashboard's central attendance module is a ruled register board with oversized present and absent numerals aligned to small-caps labels, with late and early-departure figures in a narrow right-hand column rather than separate cards; every AI-originated item carries a fixed evidence strip with source, timestamp, confidence context, retention status, and the immutable phrase "Requires human review"; the incident-review panel uses a horizontal four-stage mechanical track — New, Under review, Verified, Dismissed — where the current status is a solid marker and no state implies guilt or diagnosis; camera status is rendered as a continuous bottom rail of labeled circular lamps and uptime values, allowing staff to scan all classrooms as a single instrument panel rather than opening a card grid.

8. Interaction Model & Motion Direction

Interaction Model: Animated Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief: Focal subject is the operations board composition — the oversized "Today, every child accounted for" heading, the ruled attendance ledger, the ivory Human review queue panel with its orange safety tab, and the green camera-status rail. Input→transformation→outcome thesis: on load, the ledger's present/absent numerals settle into place and the review queue's single timestamped event reveals with a single-line scan; the camera-status rail lamps illuminate in sequence to show connection health. Motion vocabulary is restrained and mechanical: 140–180ms state transitions, status-lamp changes, and a single-line scan reveal when a review item opens; incident status changes visibly move the item along its review path without bounce, confetti, or decorative floating effects. Composed first frame: warm-paper field, left-aligned oversized heading, eight-column ledger with orange review marker, four-column ivory review panel with orange safety tab, green camera rail along the bottom. Reduced-motion state: instant state changes and static progress markers replace all movement; the ledger, review panel, and camera rail render fully without animation.

9. Non-Functional Requirements

• NFR-1 (explicit): Obtain appropriate school authorization and informed parent/guardian consent before processing children's video. Rationale: privacy and lawful processing.
• NFR-2 (explicit): Assess applicable Indian child-protection, privacy, and data-protection requirements before deployment. Rationale: regulatory compliance.
• NFR-3 (explicit): Avoid facial recognition and biometric identification in the MVP. Rationale: privacy constraint.
• NFR-4 (explicit): Process video locally where possible. Rationale: privacy and data minimization.
• NFR-5 (explicit): Do not continuously upload classroom footage to external AI services. Rationale: privacy constraint.
• NFR-6 (explicit): Use restricted, encrypted incident storage and a defined deletion schedule. Rationale: evidence protection and retention control.
• NFR-7 (explicit): Do not use automated AI results to discipline teachers or children. Rationale: human accountability.
• NFR-8 (explicit): Provide an emergency escalation process for credible safety concerns. Rationale: safeguarding.
• NFR-9 (explicit): Use synthetic or consented test footage during development. Rationale: lawful development.
• NFR-10 (explicit): Store CCTV footage separately; do not put large video files directly in the database. Rationale: storage architecture.
• NFR-11 (explicit): Keep attendance identification separate from incident detection. Rationale: workflow isolation.
• NFR-12 (explicit): Use a vision-language API only if necessary and permitted for the selected workflow. Rationale: privacy and cost control.
• NFR-13 (explicit): Parents receive only approved, relevant notifications. Rationale: consent and policy.

• NFR-14 (explicit): Send attendance notifications to parents subject to consent and school policies. Rationale: consent and policy.
• NFR-15 (explicit): Save incident clips or timestamped event references only where legally permitted. Rationale: legal constraint.
• NFR-16 (explicit): Prioritize a functional, demonstrable MVP over unsupported claims of fully automatic monitoring. Rationale: delivery realism.
• NFR-17 (explicit): Clearly label features that require further model training or real-world validation. Rationale: transparency.
• NFR-18 (explicit): Achievable within 15–20 days as a working MVP. Rationale: delivery constraint.
• NFR-19 (explicit): Never claim that a child ate a specific quantity based solely on an ordinary CCTV recording. Rationale: accuracy constraint.
• NFR-20 (explicit): Do not automatically declare that a teacher committed abuse based on an AI prediction. Rationale: human accountability.
• NFR-21 (explicit): Do not use facial emotion recognition to determine guilt, fear, or intent. Rationale: privacy and fairness.
• NFR-22 (explicit): Never diagnose a disease using CCTV. Rationale: medical accuracy.
• NFR-23 (explicit): Require staff verification before generating a health alert. Rationale: human verification.
• NFR-24 (explicit): Implement authentication, role-based permissions, request validation, error handling, and audit logging. Rationale: security and auditability.
• NFR-25 (explicit): Use a clean, professional, child-friendly interface with a light background, readable charts, clear alert indicators, and responsive layouts. Rationale: usability.
• NFR-26 (explicit): Encrypted storage, access controls, backups, and audit logs. Rationale: infrastructure security.

10. Tech Stack

• Frontend: React.js with Tailwind CSS; Recharts for dashboard charts.
• Backend: Python FastAPI; REST APIs for attendance, students, incidents, meals, and notifications. Shared backend process for application APIs and domain modules.
• Database: PostgreSQL for student information, attendance, incidents, and reports. Provisioned database service (MariaDB) for application-owned persistent data; postgres service supports LiteLLM, separate from application-owned storage.
• AI and Computer Vision: Python, OpenCV, and Ultralytics YOLO for suitable object-detection tasks; evaluate an action-recognition model for possible unsafe physical interactions; use a vision-language API only if necessary and permitted for the selected workflow; keep attendance identification separate from incident detection.
• Infrastructure: Existing CCTV cameras or an authorized test video source; local processing computer or an appropriately secured cloud server; encrypted storage, access controls, backups, and audit logs. Provisioned litellm gateway for the backend's model-provider calls; frontend React application UI.
• Storage: CCTV footage stored separately from the database; large video files never placed directly in the database.

11. Assumptions and Constraints

• A-1 (explicit): The MVP must be achievable within 15–20 days.
• A-2 (explicit): CCTV cameras or an authorized test video source are available.
• A-3 (explicit): Synthetic or consented test footage is available during development.
• A-4 (required_inference): School authorization and informed parent/guardian consent are obtained before processing children's video.
• A-5 (required_inference): Applicable Indian child-protection, privacy, and data-protection requirements are assessed before deployment.
• A-6 (required_inference): Administrators provision staff and authorized user accounts before first sign-in.
• A-7 (required_inference): Encrypted incident storage with a defined deletion schedule is configured.
• A-8 (required_inference): A documented fallback is configured for when real-time action recognition is unavailable.
• A-9 (explicit): Features requiring further model training or real-world validation are clearly labeled.
• A-10 (explicit): The system prioritizes a functional, demonstrable MVP over unsupported claims of fully automatic monitoring.

12. Glossary

• AI-generated event alert: A timestamped safety event flagged by the AI/video-processing module for human review.
• Action recognition: A model capability to detect potentially unsafe physical actions such as hitting, pushing, or rough handling.
• Attendance status: Daily present, absent, late, or early departure state per student.
• Authorized pickup details: The persons authorized to collect a student.
• Camera status: The connection and health state of a CCTV camera.
• Consent: Parent/guardian permission required before processing children's video and before sending notifications.
• Deletion schedule: The defined retention period after which incident evidence is deleted.
• Fallback: The documented alternative behavior when real-time action recognition is unavailable.
• Health alert: A wellbeing alert generated only after staff verification.
• Incident review panel: The secure surface for authorized administrators to review events and set status.
• Incident status: New, under review, verified, or dismissed.
• Meal checklist: Student-wise record of breakfast, lunch, snacks, and water intake with statuses ate well, ate partially, refused food, or meal not recorded.
• MVP: Minimum viable product achievable within 15–20 days.
• Notification history: The record of approved parent notifications sent.
• Role-based access: Access control by user role (School Administrator, Teacher / Caregiver).

• Urgent incident workflow: The escalation path for suspected injury or immediate danger.
• Vision-language API: An external model API used only if necessary and permitted for the selected workflow.
• Wellbeing record: Staff-recorded symptoms and observations.