Tech Stack

Project Structure

src/
├── config/
│   ├── db.ts                        # MongoDB connection
│   └── env.ts                       # Environment variables
├── controllers/
│   ├── user.controller.ts           # Auth: register, profile
│   ├── session.controller.ts        # Auth: login
│   ├── logout.controller.ts         # Auth: logout
│   ├── refresh.controller.ts        # Auth: token refresh
│   ├── student.controller.ts
│   ├── teacher.controller.ts
│   ├── class.controller.ts
│   ├── attendance.controller.ts
│   ├── exam.controller.ts
│   ├── grade.controller.ts
│   ├── timetable.controller.ts
│   ├── fee.controller.ts
│   ├── announcement.controller.ts
│   ├── message.controller.ts
│   ├── library.controller.ts
│   └── hr.controller.ts
├── middlewares/
│   ├── auth.middleware.ts           # JWT verification
│   ├── adminOnly.middleware.ts      # Admin role guard
│   ├── role.middleware.ts           # Role-based guard
│   ├── validate.middleware.ts       # Zod request validation
│   ├── error.middleware.ts          # Global error handler
│   └── rateLimit.middleware.ts      # Rate limiting
├── models/
│   ├── User.model.ts
│   ├── Session.model.ts
│   ├── Student.model.ts
│   ├── Teacher.model.ts
│   ├── Class.model.ts
│   ├── Attendance.model.ts
│   ├── Exam.model.ts
│   ├── Grade.model.ts
│   ├── Timetable.model.ts
│   ├── Fee.model.ts
│   ├── Announcement.model.ts
│   ├── Message.model.ts
│   ├── Book.model.ts
│   ├── BookBorrow.model.ts
│   └── Staff.model.ts
├── routes/
│   ├── index.ts                     # Route aggregator
│   ├── user.routes.ts
│   ├── session.routes.ts
│   ├── logout.routes.ts
│   ├── refresh.routes.ts
│   ├── student.routes.ts
│   ├── teacher.routes.ts
│   ├── class.routes.ts
│   ├── attendance.routes.ts
│   ├── exam.routes.ts
│   ├── grade.routes.ts
│   ├── timetable.routes.ts
│   ├── fee.routes.ts
│   ├── announcement.routes.ts
│   ├── message.routes.ts
│   ├── library.routes.ts
│   └── hr.routes.ts
├── services/
│   ├── user.service.ts
│   ├── session.service.ts
│   ├── refresh.service.ts
│   ├── student.service.ts
│   ├── teacher.service.ts
│   ├── class.service.ts
│   ├── attendance.service.ts
│   ├── exam.service.ts
│   ├── grade.service.ts
│   ├── timetable.service.ts
│   ├── fee.service.ts
│   ├── announcement.service.ts
│   ├── message.service.ts
│   ├── library.service.ts
│   └── hr.service.ts
├── types/
│   └── express.d.ts                 # Express type extensions
├── utils/
│   ├── ApiError.ts                  # Custom error class
│   └── jwt.ts                       # JWT helpers
├── validators/
│   ├── user.validator.ts
│   ├── session.validator.ts
│   ├── student.validator.ts
│   ├── teacher.validator.ts
│   ├── class.validator.ts
│   ├── attendance.validator.ts
│   ├── exam.validator.ts
│   ├── grade.validator.ts
│   ├── timetable.validator.ts
│   ├── fee.validator.ts
│   ├── announcement.validator.ts
│   ├── message.validator.ts
│   ├── library.validator.ts
│   └── hr.validator.ts
├── app.ts                           # Express app setup
└── server.ts                        # Server entry point

Getting Started

Prerequisites

• Node.js v18+
• MongoDB (local or Atlas)
• npm or yarn

Installation

1. Clone the repository

git clone https://github.com/hamidukarimi/SchoolOS-backend.git
cd SchoolOS-backend

2. Install dependencies

npm install

3. Set up environment variables

cp .env.example .env

Fill in your values in the .env file (see Environment Variables).

4. Build the project

npm run build

5. Start the server

# Development
npm run dev

# Production
npm start

The server will start on the port defined in your .env file (default: 5000).

First Admin User

After starting the server, register a user via the API and then manually update their role to admin in MongoDB:

db.users.updateOne(
  { email: "your@email.com" },
  { $set: { role: "admin" } }
)

Environment Variables

Create a .env file in the root directory with the following variables:

# Server
PORT=5000
NODE_ENV=development

# Database
MONGO_URI=mongodb://localhost:27017/schoolos

# JWT
JWT_ACCESS_SECRET=your_access_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
JWT_ACCESS_EXPIRES_IN=1d
JWT_REFRESH_EXPIRES_IN=7d

API Reference

All endpoints are prefixed with /api.

Authentication

Students

Query Parameters (GET /api/students)

Teachers

Classes

Timetable

Attendance

Exams

Grades

Grade Scale

Fees

Announcements