School Management System

Project Name: School Management System Type: Multi-Tenant, Multi-Branch School ERP (Web Application) Status: Feature-complete prototype with external messaging microservice

📸 Screenshots

Replace the dummy links below with actual screenshot URLs.

Section	Preview
Login / Role Selection
Owner Dashboard
Executive Principal Portal
Principal Dashboard
Teacher Portal
Student Portal
Parent Portal
Branch Management
User Management
Fee Management
Payroll
Expenses
Marks Entry
Report Cards
Attendance
Homework
Timetable
Document Editor
Academic Documents
Excel/CSV Import Wizard
WhatsApp Sessions Panel
AI Assistant
Analytics
Finance Overview
Audit Logs
Reports Module
Settings

🎯 Problem Statement

1. Data silos between branches, making owner-level oversight nearly impossible.
2. No clear role hierarchy — staff often access data they shouldn't, while parents lack visibility into their own children's progress.
3. Manual fee collection with no automated reminders, leading to revenue leakage.
4. Slow report-card generation that consumes weeks of teacher effort each term.
5. Unreliable parent communication scattered across personal WhatsApp accounts.
6. No audit trail of who changed what, when, or why.
7. Bulk data entry pain when onboarding hundreds of students/staff at the start of a session.

✅ Solution

Owner → Executive Principal → Principal → Teacher → Student / Parent

🧑‍💼 Role Hierarchy & Permissions

🚀 Core Features

1. Multi-Branch Management

• Create and configure unlimited school branches.
• Per-branch KPIs: enrollment, revenue, attendance %, staff count.
• Branch performance comparison chart for the Owner.

2. User Management

• Unified directory across all roles: students, parents, teachers, principals, EPs.
• Country-code-validated phone numbers (Zod).
• Salary structure on staff records (base, allowances, deductions).
• Block / disable users with cascading parent-disable when all linked students are removed.

3. Dynamic Subordinate Portals

• Owner/EP/Principal can select any subordinate and view that user's exact portal (read & act).
• Sidebar dynamically rebuilds based on the impersonated role.
• Parent-student linkage automatically resolves both directions.

4. Fee Management & Collection

• Per-student fee ledger (Tuition / Transport / Library / Exam / Other).
• Auto-flips
  past the due date.
• One-click Mark Paid with auto-generated receipt PDF.
• Defaulters tab with sortable outstanding dues.
• Bulk WhatsApp reminders with built-in 1.5s gap & 5-message confirm batches to avoid browser popup blocking.
• Monthly collection summary chart.

5. Payroll

• Monthly payslip generation per staff member.
• Bulk Process Month action with status badges (draft / processed / paid).
• Payslip PDF with earnings, deductions, net pay in words.

6. Expense Management

• Categorized expense tracking (Utilities / Maintenance / Supplies / Salaries / Transport / Other).
• Vendor, payment mode, attachments.
• Pie chart (category breakdown) + monthly trend line.
• CSV export of filtered rows.

7. Marks Entry & Report Cards

• Spreadsheet-style marks grid: pick Class + Subject + Term → enter marks for all students at once.
• Auto-grading via configurable thresholds (A+ / A / B / C / D / F).
• Individual or Bulk Report Card PDFs (one multi-page PDF for an entire class).
• Includes student info, subjects table, totals, percentage, attendance %, teacher remarks, principal signature line, and an AI-assisted teacher note.

8. Attendance

• Teacher-side daily marking grid.
• Student & Parent attendance views with month calendar heatmap.
• Auto-WhatsApp absence alerts to parents.

9. Homework Module

• Teachers assign homework per class/subject with due dates.
• Students view pending/completed homework.
• Reminder popovers with in-app + WhatsApp send options.

10. Timetables

• Lecture schedule editor for Principals.
• Class-wise and teacher-wise timetable views.

11. Academic Documents (Notion-style Editor)

• Rich text editor built with
  (never TipTap or BlockNote — those caused build failures).
• Notion-like slash command menu, embedded images, headings, lists, tables.
• One-click PDF export of any document (HTML-to-PDF via jsPDF).
• Document library with cards & list views.

12. WhatsApp Notifications (Two-Tier)

• helper opens pre-filled chats in a new tab.
• Templates:
  ,
  ,
  ,
  ,
  .
• Green WhatsApp buttons across Fees, Attendance, Homework, and Report Cards.

• Standalone Node.js service in
  using
  + BullMQ (Redis).
• Multi-tenant
  — each branch scans QR once, session stored in
  .
• BullMQ queue (
  ) with 5 retries + exponential backoff + 2-second rate-limit gap (≤30 msgs/min) to prevent bans.
• Job types:
  ,
  ,
  (downloads PDF via axios → sends as
  ).
• Auto re-initialization on
  /
  .
• Express API (
  ,
  ,
  ) authenticated via
  .
• WhatsApp Sessions dashboard inside the ERP: live status per branch (
  ), KPIs (queued / failed / sent 24h), and controls (Show QR, Trigger re-scan, Force disconnect).

13. AI Assistant for Admins

• Floating chat bubble (Owner/EP/Principal only) on every dashboard page.
• Drawer chat UI (shadcn Sheet) with
  rendering.
• Pattern-matches keywords (fees, attendance, defaulters, top performer, expenses) → returns real, data-driven sentences queried from the relevant React Contexts.
• Conversation persists in
  per user.

14. AI-Generated Student Reports

• composes a natural paragraph from real data: attendance %, average grade, subject strengths/weaknesses, homework completion.
• Embedded in both the student profile and the Report Card PDF as a "Teacher's AI-assisted note".

15. Excel / CSV Bulk Import Wizard

• Tabs for Students, Staff, Parents, Fees.
• Powered by
  — parses
  and
  .
• Flow: Upload → Preview 10 rows → Map columns → Zod validate → Show row errors → Import valid rows.
• Downloadable
  templates per tab.
• Failures exportable as an error CSV for offline correction.

16. Reports & Audit Module

• Modular directory:
  with reusable
  ,
  ,
  ,
  .
• Centralized PDF generators (
  ,
  ,
  ,
  ,
  ).
• Audit Logs page — chronological trail of admin actions (who, what, when).
• CSV export across all report types.

17. Analytics & Finance Overview

• Recharts-powered dashboards: revenue trends, branch performance, enrollment growth.
• Live KPIs pulled directly from
  ,
  ,
  (no hardcoded numbers).

18. Quality-of-Life

• Global Error Boundary + global error handlers.
• Offline banner for disconnected states.
• wrapper around
  (handles quota / private-mode failures).
• Page-title hook, notification dropdown, teacher inbox, student notifications.

🏗️ Tech Stack

Frontend

WhatsApp Microservice (

)

Notable Architectural Decisions

• No backend in the React app — entirely client-side prototype using Context +
  , intentionally avoiding Lovable Cloud / Supabase per project scope.
• WhatsApp microservice is fully decoupled so it can be deployed externally without coupling to the frontend's build pipeline.
• Role checks at the top of every page — unauthorized roles redirect to
  .
• All colors live in
  +
  as HSL semantic tokens — components never hardcode colors.

🧩 Problem → Solution Map

WhatsApp Microservice (optional, deploy externally)

Mount

as a persistent volume in production (Render disk, Fly volume, Docker named volume) so QR re-scans aren't needed after restarts.

📜 License