ClassroomBehaviorLog

Education

Original Idea

Classroom Behavior Log A web app for quick behavior notes with tags, patterns, and parent-ready summaries.

Product Requirements Document (PRD): ClassroomBehaviorLog

1. Executive Summary

ClassroomBehaviorLog is a "Local-First" mobile-responsive web application designed for K-12 educators to document student behavior in real-time without disrupting instruction. By utilizing a "log-and-go" interface, automated AI-driven professionalization of notes, and deep integration with school ecosystems (Google Classroom/Clever), the platform transforms raw incident data into actionable insights and parent-ready progress reports. The system is built with a 2026-standard "Privacy by Design" architecture, ensuring full FERPA and COPPA compliance.

2. Problem Statement

Teachers currently struggle with "anecdotal drift"—the loss of objective detail when behavior is recorded hours after an incident. Existing School Information Systems (SIS) are often cumbersome, requiring multiple clicks and slow page loads, which discourages frequent, objective logging. This results in incomplete data for IEP meetings, parent conferences, and administrative interventions, ultimately harming student support outcomes.

3. Goals & Success Metrics

  • Logging Speed: Reduce the average time to log a behavior incident to under 10 seconds.
  • Data Accuracy: Increase the volume of "positive" behavior logs by 40% through low-friction UI.
  • Administrative Efficiency: Reduce teacher time spent drafting parent emails/summaries by 70% using AI sanitization.
  • Compliance: Maintain 100% audit readiness for FERPA 45-day access requests.
  • Reliability: 99.9% uptime with functional offline logging in low-connectivity areas (e.g., gym, playground).

4. User Personas

  • Sarah (K-5 Teacher): Needs to log "on-the-fly" incidents during lessons. Values speed and "one-handed" mobile use.
  • Marcus (School Administrator): Needs to see high-level trends (e.g., "Are incidents spiking on Friday afternoons?") to allocate support staff.
  • Elena (Special Education Coordinator): Needs detailed, objective, time-stamped logs to track progress against IEP behavior goals.

5. User Stories

  • As a Teacher, I want to tap a student’s tile and select a tag so I can log a behavior in under 5 seconds without stopping my lecture.
  • As a Teacher, I want my messy, shorthand notes to be rewritten into professional, empathetic summaries so I can send them to parents immediately.
  • As an Admin, I want to see a heatmap of behavior incidents by time of day so I can identify patterns across the whole school.
  • As a Teacher, I want to log data on the playground where there is no Wi-Fi and have it sync automatically when I return to the classroom.

6. Functional Requirements

6.1 Core Logging Engine

  • Student Grid: A high-performance, filterable grid of student cards.
  • Quick-Tags: Predefined and custom tags (e.g., "On Task," "Disruptive," "Leadership").
  • Radial Entry Menu: Tap-and-hold interaction to select behavior intensity or type without multiple screens.
  • Haptic Confirmation: Non-visual vibration feedback for successful logs.

6.2 AI Summary Generator

  • Sanitization: Automatic redaction of PII before sending to LLM.
  • Professionalization: Conversion of shorthand (e.g., "J. out of seat again, yelled") to professional prose (e.g., "Jordan struggled to remain seated during the lesson and expressed frustration vocally").
  • Parent-Ready PDF: Generation of branded, accessible PDFs for email attachments.

6.3 Reporting & Analytics

  • Trend Visualization: Line charts showing behavior frequency over time.
  • Temporal Heatmaps: Visualizing "hot zones" during the school day/week.
  • Comparative Analysis: Grouping by class, grade, or custom student cohorts.

7. Technical Requirements

7.1 Tech Stack (2026 Standards)

  • Frontend: Next.js v16.1.3 (App Router, Turbopack, Partial Pre-rendering).
  • Backend: NestJS v11.1.12 (Express v5 engine).
  • Database: PostgreSQL (Supabase v2.90+) with pgAudit for FERPA compliance.
  • Sync Engine: PowerSync (Local-first SQLite with Supabase replication).
  • Authentication: Clerk (Organization-based RBAC with Asymmetric RSA JWTs).
  • AI: Vercel AI SDK 6 with Claude 4.5 Sonnet (via LangChain.js piiRedactionMiddleware).
  • PDF Generation: @react-pdf/renderer v3.0+ with Route Handlers.

7.2 Integrations

  • Google Classroom API: Roster sync via Google Cloud Pub/Sub.
  • Clever SSO: OIDC-based identity and nightly roster reconciliation.
  • Notification: Microsoft Teams/Slack webhooks for high-priority incident alerts.

8. Data Model

8.1 Organizations (Schools)

  • id: UUID (PK)
  • name: String
  • settings: JSONB (Custom tags, branding)

8.2 Users (Staff)

  • id: UUID (PK)
  • clerkId: String (Unique)
  • role: Enum (ADMIN, TEACHER, COUNSELOR)
  • orgId: UUID (FK)

8.3 Students

  • id: UUID (PK)
  • orgId: UUID (FK)
  • externalId: String (Clever/Google ID)
  • fullName: String
  • metadata: JSONB (Class IDs, IEP status)

8.4 BehaviorLogs

  • id: UUID (PK)
  • studentId: UUID (FK)
  • teacherId: UUID (FK)
  • timestamp: TIMESTAMPTZ (Indexed)
  • tagId: UUID (FK)
  • rawNotes: Text (Encrypted at rest)
  • aiSummary: Text
  • isPriority: Boolean

9. API Specification (Selected)

  • POST /api/v1/logs: Creates a new behavior log.
    • Request: { studentId, tagId, notes, timestamp }
    • Optimistic Response: { status: 'queued_local' }
  • GET /api/v1/reports/summary/{studentId}: Generates AI-sanitized summary.
    • Query Params: startDate, endDate.
    • Response: { pdfUrl, sanitizedText }

10. UI/UX Requirements

  • Thumb-Zone Optimization: All logging triggers located in the bottom 40% of the screen.
  • Contrast Modes: High-contrast "Outdoor Mode" for playground use.
  • Component Library: Radix UI primitives with Tailwind CSS v4.
  • Visual Feedback: Skeuomorphic "pulse" on student cards when a log is active.

11. Non-Functional Requirements

  • Performance: <100ms UI response time using useOptimistic and useTransition.
  • Security: AES-256 encryption for rawNotes using Supabase Vault.
  • Compliance: Automated data purging (Retention Clock) 60 days after a student leaves the district.
  • Accessibility: WCAG 2.1 Level AA compliance, specifically for PDF reports (Tagged PDF/UA).

12. Out of Scope

  • Academic grading or gradebook functionality.
  • Parent-teacher direct chat (handled via external email/SIS).
  • Financial/Tuition management.

13. Risks & Mitigations

  • Risk: AI hallucinations in parent summaries.
    • Mitigation: Human-in-the-loop review; teachers must approve AI summaries before sending.
  • Risk: Data leakage in multi-tenant environments.
    • Mitigation: Strict Row-Level Security (RLS) based on Clerk Organization IDs.
  • Risk: Connectivity loss during field trips.
    • Mitigation: PowerSync for local SQLite persistence with background delta-sync.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Next.js 16.1.3 project with Turbopack and Tailwind v4
  • [ ] Set up NestJS 11.1.12 backend with Express v5
  • [ ] Configure Clerk with "Education Role Sets" (Admin/Teacher/Counselor)
  • [ ] Initialize Supabase project and enable pgAudit and pg_crypto extensions

Phase 2: Local-First Foundation

  • [ ] Integrate PowerSync with Next.js client-side SQLite
  • [ ] Define PostgreSQL schema with RLS policies for multi-tenancy
  • [ ] Implement pg_cron for automated 45-day data retention cleanup
  • [ ] Build offline-sync status indicator UI component

Phase 3: Core Logging & UI

  • [ ] Create Student Grid with useOptimistic for instant card updates
  • [ ] Implement Radial Menu for "Tap-and-Hold" behavior logging
  • [ ] Add Web Haptics API integration for log confirmation
  • [ ] Build "Outdoor Mode" high-contrast theme toggle

Phase 4: AI & Reporting

  • [ ] Implement Vercel AI SDK 6 with LangChain PII redaction middleware
  • [ ] Create Route Handler for PDF generation using @react-pdf/renderer
  • [ ] Build "Trend Dashboard" using Shadcn UI Charts (Recharts v3)
  • [ ] Implement AI "Tone Adjustment" slider (Empathetic to Formal)

Phase 5: Integrations & Compliance

  • [ ] Setup Clever SSO OIDC strategy in NestJS
  • [ ] Implement Google Classroom roster sync via BullMQ background jobs
  • [ ] Build FERPA "Export All Data" request workflow (45-day timer)
  • [ ] Conduct final security audit for COPPA 2026 data minimization compliance