Changelog

Auth Import Migration: auth-session to convex-auth

Migrated all 148 API route files from the legacy @/lib/auth-session module to the new @/lib/convex-auth module. This completes the transition from JWT/cookie-based authentication to Clerk + Convex-backed auth across the entire codebase. Dead auth code (forgot-password flow, old auth actions) was also cleaned up.

• All 148 API routes now import { getSession, isAdminRole } from @/lib/convex-auth
• Deleted dead auth code: app/actions/auth.ts and app/api/auth/forgot-password/ route
• Migrated billing routes (webhooks, plans, student-plans, sync-payment-method) to Convex
• Migrated Stripe Connect, subscription invoices, forms, push notifications, and platform-fee routes to Convex
• convex-auth.ts provides backward-compatible SessionData interface with Clerk + Convex user lookups

Fix: Email Queue Sends Directly via Resend

Eliminated the Convex -> Next.js -> Resend round-trip that was causing the email queue to fail. The Convex `processNext` action now calls the Resend REST API directly, removing the dependency on APP_URL and the internal API secret. Only RESEND_API_KEY needs to be set in the Convex dashboard.

• Convex action now calls https://api.resend.com/emails directly instead of routing through /api/email/send
• Email HTML template and wrapper are built inline within the Convex action
• Sent emails are still logged to the emailLogs table via a new internal mutation
• Only requires RESEND_API_KEY in Convex env vars; FROM_EMAIL and APP_URL are optional

Fix: Email Queue Not Delivering

Fixed a critical bug where the Convex email queue processor could not reach the Next.js email send API. The URL resolution had an operator precedence issue and relied on environment variables not available in the Convex runtime. The processor now reads a dedicated APP_URL variable and throws a clear error if it is missing.

• Fixed JS ternary operator precedence bug in base URL construction
• Added APP_URL as the primary env var (must be set in Convex dashboard)
• Added explicit error message when no app URL is configured, preventing silent failures

Email Templates: Light Mode Conversion

Converted all email templates from a dark theme to a light theme to fix readability issues when emails are opened on devices with dark mode enabled. Gmail and other email clients will now auto-generate clean dark versions instead of conflicting with an already-dark design.

• Converted shared email wrapper to light theme: white card on light gray background with dark text
• Updated color-scheme meta tags from dark to light for proper email client handling
• Fixed all inline style overrides across 11 email templates (invoices, invites, alerts, contact, careers, etc.)
• Added !important declarations on key colors to prevent email client dark mode from overriding styles

Cleanup: Remove Migrations Tab

Removed the temporary Database Migrations page and its sidebar navigation entry from the super admin dashboard. The migration tooling was only needed during the messaging system refactor and is no longer required.

• Removed /admin/migrations page and its associated sidebar link
• Cleaned up unused Database icon import from the admin sidebar

Rate-Limited Email Queue

All signup notification emails now flow through a Convex-backed queue system that respects Resend rate limits. Even if 20 schools sign up simultaneously, every notification is queued instantly and processed one at a time with 1.2-second delays between sends. Failed emails are automatically retried up to 3 times.

• New emailQueue table in Convex with pending/processing/sent/failed status tracking
• Self-scheduling Convex internal action processes jobs sequentially with rate-limit-safe delays
• Automatic retry (up to 3 attempts) for any email that fails to send
• Both live signup and retroactive notifications now enqueue instead of sending directly

Retroactive Signup Notifications

Super admins can now send signup notification emails retroactively for schools that signed up before the notification system was configured. A new card on the Platform Settings page lets you select the last 3 to 20 signups, preview the list, and fire off the notifications in one click.

• New Convex query fetches the most recent school signups with admin details
• Scrollable preview list shows school name, admin, and signup date before sending
• Uses the same beautifully designed email template as live signup notifications

Visual Consistency & Signup Notification Emails

Maintenance Mode -- Fully Implemented

The maintenance mode toggle in Super Admin Settings now fully enforces platform downtime. When enabled, all non-super-admin users are redirected to a dedicated maintenance page, and external API calls receive a 503 response.

• Dedicated /maintenance page with custom message display, auto-refresh every 30 seconds, and automatic redirect back to the dashboard when maintenance ends
• Dashboard layout checks maintenance status in real-time and redirects non-super-admin users -- super admins are never locked out and retain full access to both /admin and /dashboard
• External API routes (mobile app, SDKs) return 503 Service Unavailable with a Retry-After header during maintenance via the withApiKeyAuth middleware
• All public marketing pages, sign-in, and admin dashboard remain accessible during maintenance

Intervo.ai Chat Widget & Provider Toggle

Added Intervo.ai as a backup AI chat widget alongside Chatbase. Super admins can now switch between providers instantly from the Platform Settings page without any downtime.

• Intervo.ai widget integrated -- loads dynamically via script injection and cleans up when switching back to Chatbase
• Chat Widget card added to Admin Settings with a two-option selector -- clicking a provider saves and activates it instantly
• Provider preference stored in Convex platformSettings and served via a new public query so the front-end widget loads the correct provider on every page

Official JavaScript & Python SDKs

Released official single-file SDK libraries for JavaScript/Node.js and Python, with full documentation on the developer portal including installation guides, usage examples for every resource, and error handling patterns.

• JavaScript/Node.js SDK (centrecareos.js) -- zero-dependency, works in Node.js 18+ and modern browsers using native fetch
• Python SDK (centrecareos.py) -- Python 3.7+ compatible with the requests library, supports context manager pattern
• Both SDKs cover all API resources: students, attendance, billing, rooms, staff, and messages with full JSDoc/docstring annotations
• Developer portal updated with download links, code examples for every resource, error handling guides, and rate limit tracking

Super Admin Invite Emails + Email Logs Dashboard

Fixed a bug where super admin invite emails were never sent after creating a new user. Added a comprehensive Email Logs dashboard in the super admin panel that tracks and previews every email sent from the platform with category filtering.

• Super admin invite now generates a password reset token and sends a branded invitation email with account setup link
• New Email Logs page at /admin/email-logs with full email preview, status tracking, and category filtering
• All 15+ email types now logged automatically: staff invites, parent invites, password resets, invoices, daily reports, incident alerts, and more
• Email preview dialog renders the exact HTML that was sent, with metadata including recipient, subject, category, and sent/failed status

Unified AI + Live Support Chat Widget

The public-facing chat widget now combines an AI Assistant (powered by Chatbase) and Live Support in a single unified interface. Users can switch between AI help for common questions and live human support when needed, all from one floating widget.

• Tabbed interface with "AI Assistant" and "Live Support" tabs inside the chat widget header
• AI Assistant tab embeds Chatbase chatbot for instant answers about CentreCareOS features, pricing, and common questions
• Live Support tab retains all existing functionality including real-time messaging, file attachments, typing indicators, and read receipts
• Unread message badge appears on the Live Support tab when new agent messages arrive while viewing the AI tab

Automatic Room Group Chats

Every room can now have its own group chat that automatically includes all assigned staff, parents of enrolled students, and school administrators. Room chats sync participants when staff or students are added or removed from rooms. Super admins can join any room chat and see the full message history.

• New "Room" tab in New Conversation dialog to create or join room chats
• Auto-populated participants from room staff assignments, student-parent links, and school admins
• Automatic participant sync when room assignments change (staff added/removed, students enrolled/transferred)
• Distinct room chat icon and "Room" badge in conversation list for easy identification
• "Room Chat" label and member count shown in the message thread header

Remove Duplicate Help Center Route

Removed the redundant /help-center page and consolidated all help documentation under the /help route. Updated all references across the footer, sitemap, email templates, billing page, and developers page to point to /help.

Documentation Accuracy & Sync

Complete rewrite of both the in-dashboard and public-facing help documentation based on a thorough audit of every feature in the codebase. Both help pages now contain identical article content, ensuring no conflicting information between the dashboard and public help center.

• Full Content Audit -- Rewrote all 21 help articles across 20 categories based on actual codebase features including schema fields, page flows, form fields, statuses, and role permissions
• Content Sync -- Dashboard and public help pages now share identical article data, categories, descriptions, and role assignments, eliminating all content drift
• New Articles -- Added dedicated articles for Waitlist Management, Menu Planning, and Parent Billing that were previously missing or incomplete
• Accurate Feature Coverage -- Updated documentation for billing plans, auto-invoicing, Stripe/Paystack integration, staff time tracking, training records, admissions pipeline, paperwork form builder, lesson plan frameworks, calendar event types, and all report categories

Role Corrections & Public Documentation Redesign

Fixed incorrect role tags across the entire platform to match the actual four-role system (Super Admin, School Admin, Staff, Parent). Completely rebuilt the public /help page into the same three-pane SaaS-style documentation layout used in the dashboard: left sidebar with collapsible category navigation and search, center content area with breadcrumbs and article rendering, and right-side "On this page" table of contents with scroll-tracked heading highlighting. Also fixed a crash caused by unsupported Convex useQuery calls in the chat widget and admin support pages.

• Role System Fix - Removed incorrect "Admin" and "Teacher" roles from sidebar navigation, dashboard help docs, and public help docs. The platform uses only four roles: Super Admin, School Admin, Staff, and Parent
• Public Docs Redesign - Rebuilt the public-facing /help page with the same SaaS-style documentation design as the dashboard version, including sidebar navigation, search, table of contents, and comprehensive articles
• Dark/Light Mode - Public help pages now fully support dark and light mode using semantic design tokens throughout
• Documentation Accuracy - Updated all article content in both dashboard and public documentation to accurately reflect current features, correct role access levels, and detailed usage instructions

SaaS Documentation Redesign

Completely redesigned the in-dashboard help pages into a professional SaaS-style documentation system with sidebar navigation, search, table of contents, and comprehensive articles covering every feature.

• Docs-style Layout - Three-column layout with collapsible sidebar navigation, main content area, and "On this page" table of contents
• Comprehensive Content - 14 documentation categories with 25+ detailed articles covering getting started, attendance, daily reports, messaging, billing, students, parents, rooms, staff, admissions, settings, and more
• Global Search - Full-text search across all documentation articles with instant results dropdown
• Role Tags and Related Articles - Each article shows role-based access badges and links to related documentation

Support Chat: Typing Indicators, Read Receipts & Presence

Added real-time typing indicators, read receipts with double-check marks, and online presence tracking to the support chat system between visitors and admins.

• Typing Indicators - Animated bouncing dots in real-time when visitors or agents are typing, with automatic 3-second timeout
• Read Receipts - Single check for sent, double check for delivered, blue double check when read by the other party
• Presence Tracking - Green pulse dot for online visitors, "last seen" timestamps for offline users, shown in header and sidebar
• Schema Updates - New fields for typing state, read timestamps, delivery tracking, and presence heartbeats on both supportThreads and supportMessages tables

Mobile App Authentication Endpoint

Added server-side support for the React Native companion app to authenticate via Clerk and receive a session JWT for all subsequent API calls.

• Mobile Session Endpoint - New POST /api/auth/mobile-session route that accepts a Clerk session token via Authorization header, verifies it with the Clerk Backend API, resolves the user in Convex, and returns a signed JWT for the mobile app to store
• Token Refresh - PUT /api/auth/mobile-session allows mobile apps to refresh an expiring JWT by presenting the current token, re-fetching user data from Convex, and issuing a fresh 7-day JWT
• Middleware Bearer Pass-through - Protected API routes now allow requests with a Bearer token through the Clerk middleware layer, deferring auth verification to the route handler via getSession() so mobile apps can access all existing API routes

Full Paystack Payment Flows, Currency Support & Admin Stability

African schools can now pay platform subscriptions and receive parent fee payments via Paystack, with automatic currency handling and webhook-driven status updates. Admin dashboard crashes on reload and sign-out have also been resolved.

• Paystack Subscription Checkout - Schools in Paystack regions can now subscribe to platform plans via Paystack-hosted checkout, with automatic subscription activation on payment verification
• Parent Invoice Payments via Paystack - Parents at African schools can pay invoices through Paystack with subaccount split payments, so schools receive funds directly with the platform fee deducted automatically
• Paystack Webhook Processing - Full webhook handler for charge.success, subscription.create, subscription.disable, and transfer events with automatic invoice status updates and authorization storage
• Per-School Currency - Currency auto-detected from country (NGN, GHS, KES, ZAR, USD, GBP, etc.) and used across all billing UIs, invoice amounts, and payment displays
• Country Field on Settings - School admins can now set their country in school settings, and super admins can set it on the admin schools page; payment provider and currency auto-update when country changes
• Admin Dashboard Stability - Fixed crashes on page reload, sign-out, and session expiry across all admin queries (getAllSchools, getAllUsers, getAllPlans, getPlatformSettings, getAuditLogs, getAllApiKeys, getAllAnnouncements) by replacing throwing auth checks with graceful empty returns

Paystack Payment Integration for African Schools

Schools in Nigeria, Ghana, Kenya, and South Africa can now accept parent payments via Paystack with automatic bank settlements, alongside the existing Stripe integration for other regions.

• Paystack Subaccount Setup - Schools in Paystack-supported countries see a dedicated bank account linking form in billing settings with real-time account verification via Paystack's Resolve API
• Automatic Provider Detection - The billing settings page auto-detects whether to show Stripe Connect or Paystack setup based on the school's country, with region-specific fee breakdowns
• Bank Search and Verification - Searchable dropdown of banks per country with instant account name resolution before subaccount creation
• Admin Paystack Dashboard - New super admin page to view all Paystack-linked schools, subaccount status, bank details, and settlement schedules
• Expanded Country List - School registration now supports 30+ countries across Africa, Americas, Europe, Asia, and Oceania with proper country codes
• Webhook and Transaction APIs - Full Paystack webhook handler for charge.success, transfer events, plus transaction initialization and verification endpoints

Enhanced Admin Platform Dashboard

Completely rebuilt the super admin platform dashboard to show live, actionable data across all schools with better space efficiency and real-time alerts.

• 8 Live Stat Cards - Schools, users, enrolled students, MRR, open support tickets, unread messages, today's attendance, and pending invoices with clickable links to detail pages
• Alert Banners - Prominent banners for past due subscriptions, overdue invoices, and trials expiring this week
• Subscription Breakdown - Visual breakdown by status (active, trialing, past due, canceled) and by plan with progress bars
• Top Schools - Leaderboard of schools ranked by enrolled students showing staff count and plan tier
• Expiring Trials - Schools with trials ending within 7 days, with urgency badges for immediate attention

Stripe Connected Accounts Management

Super admins can now view and delete Stripe Connect accounts directly from the admin dashboard, enabling easier cleanup of test accounts and orphaned connections.

• Account Overview - Summary cards showing total accounts, active charges, pending onboarding, and unlinked accounts
• Account Table - Detailed table with account ID, business name, email, linked school, status badges, and creation date
• Delete via API - Delete connected accounts using the Stripe API with confirmation dialog and automatic cleanup of linked school records
• Quick Links - Direct links to view each account in the Stripe Dashboard

Platform Messaging Write Conflict Fixes

Resolved critical Convex write conflicts in the platform messaging system that were causing mutation failures and excessive retries on the platformConversations table.

• Infinite Loop Fix - Fixed markAdminMessagesRead re-firing on every Convex subscription update due to object reference dependencies in useEffect
• No-Op Write Guards - Added early-exit checks to skip writes when unread count is already zero or typing state is unchanged
• Typing Debounce - Debounced typing indicator mutations to fire only once when typing starts instead of on every keystroke
• Both Sides Fixed - Applied same fixes to both admin-side and user-side messaging components
• Batch Limiting - Limited message read marking to 50 messages per call to reduce transaction conflict window

Mobile App Convex Implementation Guide

Created a comprehensive implementation guide for building the React Native mobile companion app, fully updated for the Convex migration.

• Database Schema - Complete Convex database schema documentation with all 45+ tables, field types, and indexes
• API Route Reference - Full reference covering 160+ REST endpoints organized by feature area
• Authentication Flow - Detailed JWT Bearer token auth documentation for mobile implementation
• Push Notifications - Registration and delivery implementation guide with Expo
• File Uploads - Vercel Blob integration patterns for React Native
• Payments - Stripe Connect payment flow documentation for parent invoice payments
• Multi-Role Support - Implementation details for role-switching between parent and staff views
• Real-Time Data - Polling vs direct Convex React Native subscription options
• Data Flow Diagrams - Visual flows for auth, check-in, and messaging systems
• Migration Notes - All changes documented from Neon/PostgreSQL to Convex

Public API Documentation

Comprehensive public-facing API documentation is now available for developers building integrations with CentreCareOS. The new Developer Portal provides everything needed to get started with our REST API.

• Developer Portal - New /developers page with complete API documentation including authentication, endpoints, scopes, and error handling
• Endpoint Reference - Detailed documentation for Students, Attendance, Billing, Rooms, Staff, and Messages APIs with required scopes and examples
• Footer Links - Quick access to API documentation added to the site footer and API settings page

Super Admin Plan Assignment

Super admins can now assign subscription plans directly to schools from the admin dashboard. This feature enables quick testing of plan benefits and manual plan management for special cases.

• Assign Plan - New menu option in the schools three-dot menu to assign any available plan to a school
• Plan Selection Dialog - User-friendly dialog showing all available plans with pricing for easy selection
• Audit Logging - All plan assignments are logged with details for tracking and accountability

Enterprise API Access

Introducing API access for Enterprise plan subscribers. Schools can now integrate CentreCareOS with their existing systems, build custom integrations, and automate workflows through a secure, rate-limited API.

• API Key Management - School admins can create, revoke, and manage API keys from the dashboard settings with customizable scopes and expiration
• Granular Permission Scopes - 10 permission scopes including students:read/write, attendance:read/write, billing:read, staff:read, rooms:read, reports:read, and messages:read/write
• Rate Limiting - Configurable rate limits per plan (default 1000 requests/minute) to ensure fair usage and platform stability
• Usage Analytics - Real-time API usage statistics including request counts, response times, and top endpoints
• Super Admin Controls - Platform-wide API management dashboard for monitoring all API keys, usage across schools, and ability to revoke access
• Plan-Based Access - API access can be enabled/disabled per subscription plan with configurable rate limits and allowed scopes

SEO Content Pages & Admin Signup Notifications

Added comprehensive SEO-optimized content pages targeting high-value search queries, plus automatic email notifications when new schools sign up for a free trial.

• State Ratio Pages - Dedicated pages for childcare staff-to-child ratios in Pennsylvania, Massachusetts, California, Texas, New York, Florida, Connecticut, New Hampshire, Rhode Island, and Vermont
• Ratios Hub - Central index page linking to all state-specific ratio guides at /resources/ratios
• Software Comparison Guide - Comprehensive childcare software comparison page at /resources/compare
• Attendance Tracking Guide - SEO page for attendance tracking software queries at /resources/attendance-tracking
• Ireland Childcare Page - International SEO page for Irish childcare centers at /resources/ireland
• Signup Notification Emails - Automatic branded email to admin when a new school signs up, including school name, admin details, country, and signup timestamp

Page-Specific Social Media Previews

Added unique Open Graph and Twitter Card metadata to all public pages. Now when you share a link on social media or messaging apps, each page shows its own specific preview with relevant title, description, and image instead of the generic home page preview.

• Pricing Page - Custom preview highlighting transparent pricing and free trial
• Features Page - Preview showcasing complete childcare management capabilities
• Careers & Job Postings - Individual previews for each job listing (e.g., Marketing Lead)
• Contact Page - Preview encouraging visitors to get in touch
• Compare & Resources Pages - Specific previews for software comparisons and guides
• Changelog Page - Preview highlighting latest product updates

Theme Toggle Bug Fixes Across All Public Pages

Fixed the dark mode toggle to work properly on all public-facing pages. Previously, pages like Features, Pricing, Compare, Careers, Resources, and Changelog had hardcoded light colors that ignored the theme toggle. All pages now use semantic design tokens for proper theming.

• Footer Theme Fix - Updated footer to use theme-aware tokens (bg-muted, text-muted-foreground, border-border)
• Features Page Fix - Converted from bg-white/text-neutral-* to bg-background/text-foreground
• Pricing Page Fix - Updated all hardcoded colors to semantic tokens
• Compare Pages Fix - Updated main compare page and all sub-pages (Brightwheel, HiMama, Procare)
• Careers & Resources Pages Fix - Converted to theme-aware styling
• Feature Sub-pages Fix - Updated Attendance and Billing feature pages with proper theming
• Changelog Page Fix - Updated all neutral colors to theme tokens

Public Pages Light Mode with Dark Mode Toggle

Initial implementation of light mode default for public-facing pages with a dark mode toggle in the navigation bar.

• New PublicThemeToggle Component - Theme toggle button in the navigation bar
• Home Page Conversion - Initial conversion to theme-aware styles
• Contact Page Update - Converted to use shared Navbar and Footer components

Staff Room-Based Access Control & Email Dark Mode Fix

Major update implementing room-based access restrictions for staff members. Staff can now only see students, parents, daily reports, photos, and incidents related to their assigned classroom. Also fixed email template visibility in dark mode.

• Email Dark Mode Fix - Updated all email templates with high-contrast colors that remain visible in dark mode email clients
• Room Assignment on Staff Creation - New staff can now be assigned to a room during the invitation process
• Staff Access Restrictions - Staff members can only view students, parents, photos, incidents, daily reports, and attendance from their assigned room
• Read-Only Rooms View - Staff see their assigned room in read-only mode without add/edit/delete buttons
• Hidden Settings - School Settings tab is now hidden from staff members in the sidebar
• Filtered Waitlist - Staff only see waitlist entries for their assigned room
• New StaffRoomProvider - Context provider that manages room-based access throughout the dashboard
• New getStaffAssignedRoomsByUserId Query - Convex query to efficiently fetch a staff member's assigned rooms

Messaging Empty State Layout Fix

Fixed the layout issue where the "Select a conversation" message was offset to the left instead of being centered in the message pane on all messaging interfaces.

• Added flex class to message thread container for proper centering
• Added flex-1 to empty state container to fill available space
• Fixed on both dashboard messaging and admin messages pages

Platform Messaging Read Receipts

Added read receipts (tick marks) to platform messaging between super admins and users. Now all messaging interfaces have consistent read receipt indicators showing single tick for sent and double tick for read.

• Platform Message Thread UI - Added Check and CheckCheck icons to show read status for user messages
• markPlatformMessagesRead Fix - Now marks individual admin messages as read when user views them
• markAdminMessagesRead Fix - Now marks individual user messages as read when super admin views them
• Cleaned up debug logging from messaging system

Staff Messaging Display and Header Fix

Fixed messaging display issues where conversation headers showed "?" and "Conversation" instead of the other participant's name and avatar for staff members. Updated Convex queries to properly compute display information for direct conversations.

• getConversation Fix - Now computes display name and avatar from other participant for DIRECT conversations
• Message Details - Added senderName and senderAvatar to message query results for proper display
• Typing Indicators - Added userName field to participants for typing indicator display

Invitation Accept Flow and Email Matching Fix

Fixed staff invitation flow where accept-clerk API was creating duplicate users instead of linking to pre-created users. Added email normalization throughout the flow and debug logging for troubleshooting.

• Accept-Clerk Fix - API now checks for pre-created user by email before creating new user
• Email Normalization - All email comparisons now use lowercase for consistent matching
• Debug Logging - Added console logs throughout invitation flow for easier troubleshooting
• Clerk Webhook Update - Webhook now normalizes email before user upsert

Staff Invitation Role Assignment Fix

Fixed an issue where invited staff members were being redirected to the school setup flow instead of the staff dashboard. The problem was caused by the Clerk webhook creating users with a default PARENT role before the invitation was accepted.

• User Pre-Creation - Staff invitation now pre-creates user with correct STAFF role before Clerk signup
• Invitation Linking - Users are marked as invited with invitation ID for tracking
• Clerk Webhook Compatibility - upsertFromClerk now finds pre-created user by email and preserves their assigned role

Multi-Role Super Admin Access Fix

Fixed an issue where Super Admin users with multiple roles could not access the admin dashboard when logged in with a different active role. The system now properly checks the roles array in addition to the primary role.

• requireSuperAdmin Fix - Convex helper now checks both role and roles array for SUPER_ADMIN access
• Dashboard Banner Fix - Super Admin banner now shows when SUPER_ADMIN is in the roles array
• Sidebar Button Fix - Super Admin shield button now visible for users with SUPER_ADMIN in roles array

Invitation Management and Acceptance Loop Fix

Added ability to delete and resend pending invitations from the Staff Directory. Fixed an infinite loop issue when accepting invitations after Clerk sign-up, and widened the Clerk SignUp modal for better usability.

• Invitation Management - Added Resend and Cancel buttons to pending invitations in Staff Directory
• Loop Fix - Fixed infinite 400 error loop when accepting invitations by tracking accepted state properly
• Wider SignUp Modal - Increased Clerk SignUp container width from max-w-lg to max-w-xl for better display
• New Convex Mutations - Added deleteInvitation and updateInvitation mutations for invitation management

Staff Invitation Flow and Clerk Integration

Fixed the staff invitation acceptance flow to properly integrate with Clerk authentication. Invited staff members now see pending invitations in the Staff Directory, and accepting invitations properly creates Clerk accounts.

• Clerk Integration - Invitation acceptance now uses Clerk SignUp component instead of custom password handling
• New Accept API - /api/invitations/accept-clerk endpoint properly links Clerk users to Convex records
• Pending Invitations UI - Staff Directory now shows pending invitations with status badges
• getPendingInvitations Query - New Convex query to fetch school invitations that haven't been accepted
• Room Assignments Fix - API now returns empty array instead of 500 error when no assignments exist

Simplified Role Assignment for Existing Users

Admins can now easily add existing users as different roles directly from the Parents and Staff Management pages. A staff member can be added as a parent with just a few clicks, and vice versa - no need to re-enter any information.

• Add Existing Staff as Parent - New dropdown option in Parents page to select any staff member and instantly add them as a parent, with optional student linking
• Add Existing Parent as Staff - New dropdown option in Staff Management to select any parent and add them as a staff member, with optional room assignment
• New API Endpoints - /api/users/add-role for adding roles to existing users, and /api/users/eligible-for-role to get users who can be assigned a specific role
• Smart Filtering - The system automatically filters out users who already have the target role, showing only eligible users in the selection dropdown
• Convex Query - New getByUserAndSchool query in staff module to check for existing staff records when adding roles

Multi-Role Support for Users

Users can now have multiple roles within the system. A staff member can also be a parent of a child at the same school, eliminating the need for separate accounts. The invite system intelligently handles existing users by adding roles instead of creating duplicate accounts.

• Schema Update - Added roles array and activeRole fields to users table while maintaining backward compatibility with existing single-role users
• Role Management Mutations - New addRole, removeRole, and switchActiveRole Convex mutations for managing user roles
• Smart Parent Invite Flow - When inviting a parent who already exists as staff, the system adds the PARENT role to their existing account instead of rejecting the invite
• Role Switcher UI - New sidebar component allows users with multiple roles to switch between their active role (e.g., Staff View vs Parent View)
• Auth Session Updates - Session now includes roles array, activeRole, and hasMultipleRoles flag with helper functions for role checking
• Switch Role API - New /api/auth/switch-role endpoint for changing active role with automatic dashboard redirection
• Migration Support - migrateAllUsersToMultiRole mutation to backfill existing users with roles array from their current single role

Complete Neon to Convex Migration

Final migration phase converting all remaining 27 API routes from Neon PostgreSQL to Convex. The application is now fully migrated to Convex for all data operations, with Clerk handling authentication.

• Billing Routes (7 files) - Settings, overview, student billing, payment processing, reports, and invoice generation now use Convex billing module
• Staff Routes (4 files) - Timecards, training certifications, time-off requests, and staff details migrated to Convex staff module
• Platform Messaging (2 files) - User-to-admin messaging and read receipts migrated to Convex platformMessages module
• Push Notifications (2 files) - Token registration and management migrated to Convex pushTokens module
• Public Chat Widget (3 files) - Visitor chat start, conversations, and messages migrated to Convex publicChat module
• Incident Routes (3 files) - Parent notification, follow-up, and parent incident viewing migrated to Convex incidents module
• Admin Routes (3 files) - School fee management and billing actions migrated to Convex; legacy migration route removed
• Utility Routes (3 files) - Room students, Pusher auth, and debug endpoints updated to use Convex
• Password Management - Updated to use Clerk API instead of custom bcrypt hashing
• Main Dashboard - School Stripe status now fetched from Convex schools module

Convex Schema Expansion - Supporting All Features

Major schema expansion adding all missing tables to Convex to support the remaining 28 API routes. New Convex functions added for push tokens, staff training, platform messaging, and billing settings.

• Push Tokens Table - New pushTokens schema for mobile push notification token management with user, platform, and device tracking
• Chat Visitors Table - chatVisitors schema for public chat widget with session tracking, visitor metadata, and rate limiting support
• Staff Training - staffTraining table for tracking certifications, expiration dates, and compliance with complete CRUD functions
• Platform Messaging - platformConversations and platformMessages tables for super admin to user communication system
• Billing Settings - billingSettings table with auto-billing, reminders, late fees, and payment term configuration per school
• Student Billing Assignments - studentBillingAssignments for assigning plans, custom rates, and discounts to students
• School Platform Fees - schoolPlatformFees table for custom platform fee overrides per school
• Enhanced Schools Schema - Added Stripe charges/payouts enabled fields, custom platform fee percent, and country field
• New Convex Modules - platformMessaging.ts, pushTokens.ts, staffTraining.ts with full query and mutation functions

Convex API Migration - Phase 4 (Support & Dashboard)

Extensive migration phase converting support, admin, messaging, and core API routes from Neon to Convex. 28 routes remain using Neon for specialized features requiring schema expansion.

• Support System - Thread listing, thread details, canned responses, and agent management migrated to Convex support module
• Admin Routes - Platform settings, school details, user management now use Convex admin and schools modules
• Admin Messaging - User list and conversation start routes migrated to Convex admin.getAllUsersForMessaging and admin.startPlatformConversation
• Dashboard Stats API - Uses Convex getDashboardStats query for real-time attendance, revenue, and student counts
• Conversation Features - Mute toggle, public schools list, and unread count all migrated to Convex
• Remaining 28 Routes - Still use Neon for billing, staff timecards, public chat, push tokens, and cron jobs

Convex API Migration - Phase 3 (Major)

Major migration phase converting parent portal, admin messaging, authentication, and conversation APIs from Neon to Convex. This completes migration of critical user-facing features.

• Parent Portal APIs - Dashboard, children, billing, and daily reports routes now use Convex queries
• Admin Messaging APIs - Platform conversations, messages, and user lists migrated to Convex with preserved Pusher real-time updates
• Authentication APIs - User details (/auth/me) and password change routes now use Convex for data storage
• Conversations System - Full migration including contacts, conversations list, and role-based access control
• Convex Modules Added - New admin.ts and parents.ts modules for platform messaging and parent data
• Schema Expansion - Added platformConversations and platformMessages tables to Convex schema

Convex API Migration - Phase 2

Continued migration of critical dashboard APIs to Convex, including waitlist management, incident reports, forms, and staff invitations.

• Waitlist API - New Convex module with room stats, position ordering, and enrollment conversion
• Incident Reports API - New Convex module with student/reporter details and severity tracking
• Forms API - Migrated to Convex with form builder integration and submission management
• Staff API - Migrated to Convex with invitation system and email integration preserved
• Calendar Events API - New Convex module with month filtering and time-off protection
• School Settings API - New Convex module with upsert support for all configuration options
• Invitations System - Added Convex mutations for creating, accepting, and managing staff/parent invitations
• Schema Updates - Added incident reports table and expanded invitations schema with name fields

Convex API Migration - Phase 1

Major migration of school admin dashboard API routes from Neon PostgreSQL to Convex for real-time updates and improved performance.

• Students API - Migrated to Convex with full CRUD operations, room assignments, and parent linking
• Parents API - Migrated to Convex with welcome email flow and student linking preserved
• Rooms API - Migrated to Convex with staff assignments and student capacity tracking
• Attendance API - Migrated to Convex with real-time check-in/check-out functionality
• Daily Reports API - New Convex module with upsert support and student info enrichment
• Lesson Plans API - New Convex module with room and date filtering
• Photos Module - New Convex module for photo management with Vercel Blob integration

Billing Exemption UI Restoration

Restored the billing exemption and trial reset controls to the admin schools page dropdown menu.

• Billing Exemption Toggle - Added back the option to exempt schools from billing directly from the schools table dropdown menu
• Reset Trial - Restored the trial reset functionality with customizable day count
• Exempt Status Badge - Added purple "Exempt" status badge and filter option for exempt schools

Super Admin Settings & Announcements Migration

Completed migration of super admin settings and platform announcements to Convex, ensuring all admin functionality uses the real-time database.

• Platform Announcements - Info box announcements now stored and managed via Convex with full CRUD operations
• Platform Settings - Branding, general settings, and toggles (signups, email verification, maintenance mode) all use Convex
• Logo Upload - Platform branding avatar upload uses Vercel Blob with URL stored in Convex

Stripe Integration & Pricing Convex Migration

Complete migration of all Stripe payment flows and pricing pages to use Convex, ensuring consistent data handling across the platform.

• Pricing Page - Now displays plans from Convex with Professional ($199/mo) and Enterprise ($399/mo) tiers
• Subscription Checkout - Stripe checkout flow now reads plan data from Convex and updates subscription status in real-time
• Stripe Webhook Handler - Fully migrated to update Convex subscriptions and school records on payment events
• Stripe Connect - Create account, onboarding, and dashboard link routes now use Convex for school data
• Billing Dashboard API - Current subscription, portal, and Connect status routes migrated to Convex

Admin Dashboard Convex Migration

Complete migration of the super admin dashboard from Neon PostgreSQL to Convex for real-time data and consistent architecture across the platform.

• Admin Dashboard - Platform analytics, school counts, user stats, revenue, and recent activity now powered by Convex real-time queries
• Schools Management - Create, edit, and delete schools with subscription tracking all stored in Convex with instant UI updates
• Users Management - User CRUD operations with role and school filtering now using Convex mutations and queries
• Plans Management - Subscription plans with features, pricing, and Stripe integration migrated to Convex
• Platform Settings - Global settings including branding, trial days, signup controls, and maintenance mode now in Convex
• Audit Logs - Comprehensive activity tracking with filtering and export functionality using Convex backend

Support Enhancements & Canned Responses

Improved support chat experience with sleeker attachment display, in-app file previews, and a new canned responses system to help support staff respond faster.

• Canned Responses System - Pre-written responses for support agents with categories, shortcuts, and usage tracking. Includes 10 default templates for common scenarios.
• Canned Responses Management - New admin page at /admin/canned-responses for creating, editing, and organizing response templates with search and category filters
• In-App File Preview - Click any attachment to preview PDFs, Word docs, and images in a modal instead of downloading, with option to download or open in new tab
• Sleeker Image Attachments - Removed borders and backgrounds from image attachments in support chat for a cleaner, more modern appearance
• Support Upload Fix - Fixed "Unauthorized" error when visitors uploaded files in the support chat widget by adding the endpoint to public API routes

Convex Database Migration & Real-Time Messaging

Major platform upgrade migrating from Neon PostgreSQL to Convex for real-time database capabilities, along with Clerk authentication integration and a completely rebuilt messaging system.

• Convex Database Migration - Complete migration from Neon PostgreSQL to Convex with 40+ tables, enabling real-time data synchronization across all features
• Clerk Authentication - Replaced custom JWT authentication with Clerk for secure, managed authentication with social login support and enhanced security
• Real-Time Messaging - Completely rebuilt messaging system with instant message delivery, typing indicators, read receipts, and cross-school super admin messaging
• Public Help Desk - Real-time support chat widget for website visitors with instant responses and ticket management for administrators
• School Admin Sign-up - Streamlined onboarding flow with Clerk authentication, automatic school creation, and trial subscription setup
• Streamlined Authentication - Consolidated sign-in/sign-up flows using Clerk with Google OAuth and email/password options, plus automatic post-auth routing to appropriate dashboards

Comprehensive Reports & Billing Enhancements

Major expansion of the Reports section with comprehensive school-wide reports, enhanced billing with Stripe payment method integration, and improved UI consistency across the platform.

• Comprehensive Reports Hub - New Reports section with 9 report categories: Attendance, Students, Financial, Staff, Incidents, Admissions, Activities, and Communications
• Billing Payment Methods - View connected Stripe payment methods per student, including card type (Visa, Mastercard, etc.), last 4 digits, and auto-pay status
• Billing Reports Tab - New reports section within Billing showing overdue balances, deposits, invoice summaries, revenue breakdown, and transaction history
• Attendance Reports UI Fix - Fixed time display to show human-readable format (e.g., 8:30 AM instead of raw timestamps) and removed colored icon backgrounds for cleaner monochrome styling
• Export Functionality - All reports support CSV export for offline analysis and record-keeping

Super Admin Billing Controls

Added new billing management features to the Super Admin dashboard for better control over school subscriptions and test accounts.

• Reset Trial - Super admins can now reset the 14-day trial period for any school, useful for extending evaluations or resolving customer issues
• Billing Exemption - Schools can be marked as exempt from billing, giving them full platform access without payment requirements, perfect for test accounts and demos
• Visual Indicators - Exempt schools display a Test Account badge in the schools list and show Exempt status in their subscription column for easy identification

Pipeline Drag-and-Drop & Waitlist Integration

Enhanced the Admissions Pipeline with drag-and-drop functionality and intelligent integration with the My School Waitlist, creating a seamless workflow from prospect to enrollment.

• Drag-and-Drop Kanban - Cards can now be dragged between pipeline stages with visual feedback, drop zones highlight when hovering, and grip handles indicate draggable items
• Waitlist Integration - Entries from My School Waitlist with status waiting now automatically appear in the Pipeline Waitlist stage, marked with a From Waitlist badge
• Bidirectional Sync - Moving a prospect to Waitlist stage automatically creates a corresponding entry in My School Waitlist for operational management
• Combined Statistics - Waitlist count in pipeline summary now includes both pipeline entries and My School Waitlist entries for accurate totals

Admissions Tab Redesign

Complete redesign of the Admissions section with clearer purpose and separation from the operational Waitlist. The new structure focuses on tracking the full enrollment journey from inquiry to enrollment.

• Pipeline Tab - Visual kanban-style board tracking prospective families through stages: Inquiry, Tour Scheduled, Toured, Applied, Offered, and Enrolled
• Tours Tab - New dedicated tour scheduling system with parent/child info, date/time selection, staff assignment, and outcome tracking (enrolled, waitlisted, declined, no show)
• Enrollment Forms Tab - Renamed from Admissions Packets for clarity, manages digital enrollment forms and documents
• Removed Redundancy - Eliminated duplicate Waitlists tab and confusing Programs tab that was just showing rooms
• Clear Separation - My School Waitlist remains for day-to-day operational management, while Admissions focuses on the marketing/sales pipeline

Staff Management UI Improvements

Refined staff management interface with cleaner summary cards, enhanced time off request form with start and end times, and various mobile messaging improvements.

• Cleaner Summary Cards - Removed colored background circles from icons in staff management summary cards for a cleaner, monochrome look
• Time Off Request Enhancement - Added start and end time fields to the time off request form for more precise scheduling
• Platform Avatar API - Made platform avatar endpoint publicly accessible for mobile app integration
• Unread Message Count API - New dedicated endpoint for retrieving total unread message count for badge display
• Platform Messaging Updates - CentreCareOS support avatar now properly displays in conversation lists and individual messages

Check-In PIN System & Tablet Mode

Enhanced check-in security with PIN verification, redesigned attendance page with unified student view, and new touch-optimized Tablet Mode for streamlined check-in/check-out at childcare facilities.

• PIN Authentication System - Staff, admin, and parents can set 4-6 digit PINs for secure check-in/check-out verification
• PIN + Last Name Verification - Unique identification combining PIN and last name to prevent duplicates
• Attendance Page Redesign - Unified grid view showing all students with color-coded status badges (Not Arrived, Present, Checked Out)
• Clickable Summary Cards - Filter students by status by clicking on summary cards instead of tabs
• Tablet Mode Interface - Touch-optimized full-screen mode with large buttons for use on tablets at facility entrances
• Multi-Child Check-In - Parents can select and check in multiple children at once with individual health screenings
• Staff Room Assignment - Staff see only their assigned rooms in Tablet Mode for streamlined access
• Audit Trail Enhancement - All check-ins/check-outs now log the verified user's name and role for accountability
• Parent Settings Page - New settings page for parents at /parent/settings with pickup PIN management
• Secure Tablet Mode Exit - Only staff/admin can exit Tablet Mode with PIN verification
• Auto-Reset Timer - Success screen automatically returns to main screen after 5 seconds

Mobile App API Documentation & Careers

Comprehensive API documentation for React Native mobile app development, complete careers section with job application system, and enhanced API organization for all user roles.

• Complete Mobile App API Documentation - 140+ documented endpoints with request/response examples
• Screen Design Mapping - Detailed screen layouts and navigation structure for each role (Super Admin, School Admin, Staff, Parent)
• Role-Based API Reference - Organized by user role with permission indicators
• React Native Implementation Guide - Best practices for authentication, file uploads, offline support, and push notifications
• Careers Page - Professional careers landing page with job listings
• Job Application System - Form with file uploads (resume & cover letter) that emails applications with branded HTML emails
• Marketing Lead Job Posting - First role posted with detailed responsibilities and requirements
• Database Schema Reference - Live schema included in documentation for reference

Super Admin Messaging & Platform Enhancements

Platform-level messaging system allowing super admins to communicate directly with any user across all schools, plus configurable platform fees, automatic billing, and email template management.

• Super Admin Messaging - Message any user across all schools as "CentreCareOS Team"
• Email Template Previews - Preview and send test emails for all 9 platform email templates
• Configurable Platform Fees - Set global default and per-school custom platform fee percentages
• Automatic Invoice Generation - Configurable billing cycles with automatic invoice creation
• Invoice Reminders - Automatic reminder and overdue notification emails
• Enhanced Scholarship/Discount UI - Clear discount fields with live preview of effective amounts
• Email From Name - All emails now show sender as "CentreCareOS Team"
• Dark Mode Fixes - Improved dark mode support across super admin dashboard