A full-stack web application for comprehensive school administration. Manages students, staff, academics, finance, communication, library, and transport — built for four user roles across a single integrated platform.

• Overview
• Features
• Tech Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Database Setup
  • Backend Setup
  • Frontend Setup
• Environment Variables
• API Reference
• User Roles
• Modules
• Deployment
• Development Phases
• Team

The School Management System (SMS) is a production-ready web application that consolidates all core school operations into a single platform. It replaces fragmented spreadsheets and manual registers with a unified system accessible to administrators, teachers, students, and parents.

The system was built as a final year project at Medicaps University, Indore, over a ten-month development timeline across five phases.

Live Application: https://sms-client.vercel.app
API Base URL: https://sms-server.onrender.com/api

Authentication and Security

• JWT-based stateless authentication with 7-day token expiry
• BCrypt password hashing (strength factor 10)
• Role-based access control across four user roles
• Protected routes with per-role middleware enforcement

Academic Management

• Drag-and-drop timetable builder with teacher double-booking prevention
• Subject-wise attendance tracking with automatic email alerts to parents
• Exam scheduling with bulk marks entry and absent flag support
• Automated PDF report card generation (percentage, letter grade, GPA, class rank)

Finance Management

• Fee structure definition per class with multiple frequency types
• Payment recording with auto-generated receipt numbers
• Partial payment support with real-time balance tracking
• PDF receipt (A5) and full invoice (A4) generation
• Expense tracking with monthly revenue vs expense reports

Communication

• School-wide and class-specific announcements with priority levels
• Real-time push notifications via Socket.io (room-based)
• Email blast to target audience on announcement creation
• In-app parent-teacher messaging with typing indicators and read receipts
• Event calendar with seven event types and multi-day event support

Add-on Modules

• Library catalog with issue/return tracking and fine calculation
• Transport route, vehicle, and driver management with student allocation
• Analytics dashboard with Recharts visualisations (bar, line, radar, pie)

school-management-system/
├── client/                          # React frontend
│   ├── src/
│   │   ├── api/                     # Axios instance and API call functions
│   │   ├── app/                     # Redux store configuration
│   │   ├── components/              # Shared UI components
│   │   │   ├── DashboardLayout.jsx
│   │   │   ├── Navbar.jsx
│   │   │   ├── NotificationBell.jsx
│   │   │   └── Sidebar.jsx
│   │   ├── context/                 # Socket.io context provider
│   │   ├── features/                # Redux slices
│   │   │   └── auth/
│   │   ├── hooks/                   # Custom hooks (useNotifications)
│   │   ├── pages/
│   │   │   ├── admin/               # Admin-only pages
│   │   │   ├── teacher/             # Teacher-only pages
│   │   │   ├── student/             # Student-only pages
│   │   │   ├── parent/              # Parent-only pages
│   │   │   └── shared/              # Shared pages (messaging, calendar)
│   │   ├── routes/                  # ProtectedRoute component
│   │   └── utils/                   # Helper functions (PDF download)
│   ├── .env.development
│   ├── .env.production
│   └── vercel.json
│
└── server/                          # Node.js backend
    ├── config/
    │   ├── db.js                    # PostgreSQL connection pool
    │   └── cloudinary.js            # Cloudinary configuration
    ├── controllers/                 # Route handler functions
    │   ├── auth.controller.js
    │   ├── student.controller.js
    │   ├── attendance.controller.js
    │   ├── marks.controller.js
    │   ├── feeCollection.controller.js
    │   ├── feeStructure.controller.js
    │   ├── announcement.controller.js
    │   ├── message.controller.js
    │   ├── event.controller.js
    │   ├── library.controller.js
    │   ├── transport.controller.js
    │   ├── analytics.controller.js
    │   └── financialReport.controller.js
    ├── middleware/
    │   ├── auth.middleware.js        # JWT protect + authorizeRoles
    │   └── upload.middleware.js      # Multer + Cloudinary storage
    ├── routes/                      # Express routers
    ├── socket/
    │   └── index.js                 # Socket.io server with JWT auth
    ├── utils/
    │   ├── mailer.js                # Nodemailer helpers
    │   ├── grading.js               # Grade/GPA calculation
    │   ├── receipt.js               # Receipt number generator
    │   ├── receiptPDF.js            # Receipt and invoice PDF
    │   └── reportCard.js            # Report card PDF
    ├── db/
    │   └── schema.sql               # Full PostgreSQL schema
    └── index.js                     # Express app entry point

• Node.js 18 or higher
• PostgreSQL 15 or higher (or a Neon account for managed cloud PostgreSQL)
• A Cloudinary account (free tier)
• A Gmail account with App Password enabled

Option A — Local PostgreSQL

psql -U postgres
CREATE DATABASE sms_db;
\q
psql -U postgres -d sms_db -f server/db/schema.sql

Option B — Neon (recommended for deployment)

1. Create a project at neon.tech
2. Copy the connection string from the dashboard
3. Open the Neon SQL Editor and paste the contents of server/db/schema.sql
4. Run the schema

cd server
npm install
cp .env.example .env
# Fill in all values in .env (see Environment Variables section)
npm run dev

The server starts on http://localhost:5000.

Verify the setup:

curl http://localhost:5000/api/health
# Expected: {"status":"OK","message":"SMS API is running"}

cd client
npm install
# Create .env.development (see Environment Variables section)
npm run dev

The frontend starts on http://localhost:5173.

Default login credentials:

# Server
PORT=5000
NODE_ENV=development

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/sms_db

# Authentication
JWT_SECRET=your_minimum_32_character_random_secret_key
JWT_EXPIRES_IN=7d

# Email (Gmail SMTP)
# Generate App Password at: Google Account > Security > 2-Step Verification > App Passwords
EMAIL_USER=yourgmail@gmail.com
EMAIL_PASS=your_16_character_app_password
EMAIL_FROM=SMS School <yourgmail@gmail.com>

# Cloudinary
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Frontend URL (for CORS)
FRONTEND_URL=http://localhost:5173

VITE_API_URL=http://localhost:5000/api
VITE_SOCKET_URL=http://localhost:5000

VITE_API_URL=https://sms-server.onrender.com/api
VITE_SOCKET_URL=https://sms-server.onrender.com

All endpoints except /api/auth/login require a valid JWT token in the Authorization header:

Authorization: Bearer <token>

Full access to all modules. Can create and manage all user accounts, configure fee structures, publish exam results, view all financial reports, and access the analytics dashboard.

Can mark and view attendance for assigned classes, enter marks for assigned exams, view their own timetable, post class-specific announcements, and communicate with parents via in-app messaging.

Read-only access to own attendance (with shortage warnings), published exam results with downloadable PDF report card, class timetable, fee status, school notices, and event calendar.

View their child's attendance, marks, fee dues, and timetable. Receive automatic email alerts when their child is marked absent. Communicate with teachers via in-app messaging.

The application is deployed on free-tier infrastructure.

1. Connect the client repository to Vercel
2. Set Framework Preset to Vite, Output Directory to dist
3. Add environment variables:
   • VITE_API_URL = https://sms-server.onrender.com/api
   • VITE_SOCKET_URL = https://sms-server.onrender.com
4. Deploy

1. Create a new Web Service on Render, connected to the server repository
2. Set Build Command: npm install, Start Command: npm start
3. Set Runtime to Node, Region to Singapore
4. Add all environment variables from server/.env (production values)
5. Enable WebSocket support in Service Settings
6. Deploy

1. Create a project at neon.tech
2. Copy the connection string (includes ?sslmode=require)
3. Set as DATABASE_URL in Render environment variables
4. Run schema SQL in Neon SQL Editor

Both Vercel and Render watch the connected GitHub repositories. Every push to main triggers an automatic redeploy.

Note: Render free tier spins down after 15 minutes of inactivity. The first request after a sleep period takes approximately 30 seconds to respond. This is acceptable for development and demonstration purposes.

A student is marked FAIL if any subject falls below 40% or if any subject is absent.

Room naming convention:

• user:<id> — Personal notifications
• role:<role> — Role-based broadcasts (e.g., role:teacher)
• role:all — School-wide broadcasts