I Built an Open-Source School Management System API — SchoolOS

#node #webdev #opensource #typescript

What is SchoolOS?

SchoolOS is a fully production-ready School Management Information System (MIS) REST API built with Node.js, Express, TypeScript, and MongoDB. It covers everything a school needs to manage its operations through a clean, well-structured API.

The project is fully open-source under the MIT license, anyone can use it, extend it, or contribute to it.

Tech Stack

Runtime: Node.js
Framework: Express.js
Language: TypeScript
Database: MongoDB + Mongoose
Validation: Zod
Authentication: JWT (Access + Refresh tokens with session management)

What's included?

SchoolOS ships with 12 fully tested modules:

Students — CRUD, filtering, search, pagination
Teachers — CRUD with subject and qualification tracking
Classes — Class creation, student enrollment, capacity management
Timetable — Weekly scheduling with teacher conflict detection
Attendance — Single and bulk recording, student summary reports
Exams — Exam scheduling with status tracking
Grades — Auto grade calculation (A+/A/B/C/D/F), bulk entry, summaries
Fees — Payment recording, overdue tracking, student summaries
Announcements — Audience-targeted (all, teachers, students, parents)
Messages — Inbox, sent, unread count, read receipts
Library — Book catalog, borrow/return with availability control
HR — Staff management, contracts, salary summaries

Architecture

The project follows a clean flat layered architecture. Every feature is spread across exactly 5 files:

models/       → Mongoose schema and TypeScript interface
validators/   → Zod schemas for request validation
services/     → Business logic (database operations)
controllers/  → HTTP handlers (thin, no business logic)
routes/       → Express router with middleware applied

The single rule: controllers stay thin. All database queries and business logic belong in services.

Authentication

Authentication is powered by a custom JWT system with:

Access token (short-lived, sent in Authorization header)
Refresh token (long-lived, stored in httpOnly cookie)
Session management with device tracking
Role-based access control (admin, teacher, student, parent)

Response Format

All endpoints follow a consistent response structure:

{
  "success": true,
  "data": {},
  "message": "Operation successful"
}

Getting Started

git clone https://github.com/hamidukarimi/SchoolOS-backend.git
cd SchoolOS-backend
npm install
cp .env.example .env
npm run dev

What's next?

The frontend is currently in development — a React + TypeScript + Tailwind CSS web app that consumes this API. It will be open-source as well.

DEV Community