School Management System API

A RESTful School Management System API built on the Axion microservice boilerplate. Manages Schools, Classrooms, and Students with JWT-based authentication and role-based access control (RBAC).

Architecture

This project follows Axion's convention-based architecture:

• Managers (managers/entities/) — Business logic for each entity
• Middlewares (mws/) — Authentication and authorization pipeline
• Models (*.mongoModel.js) — Mongoose schemas for MongoDB persistence
• Validators (*.schema.js) — Input validation using qantra-pineapple
• Loaders (loaders/) — Dependency injection and auto-discovery system

Tech Stack

• Runtime: Node.js + Express
• Database: MongoDB (Mongoose ODM)
• Cache/Bus: Redis (ioredis + ion-cortex)
• Auth: JWT (jsonwebtoken) + bcrypt
• Security: helmet, express-rate-limit, CORS
• Validation: qantra-pineapple

Getting Started

Prerequisites

• Node.js >= 14
• MongoDB (local or MongoDB Atlas)
• Redis (local or Redis Cloud)

Installation

# Clone the repository
git clone https://github.com/taiwoak/axion.git
cd axion

# Install dependencies
npm install

# Create environment file
cp .env.example .env
# Edit .env with your MongoDB URI, Redis URI, and secrets

Environment Variables

Variable	Description	Required
MONGO_URI	MongoDB connection string	Yes
REDIS_URI	Redis connection string	Yes
CORTEX_REDIS	Redis for inter-service bus	Yes
CACHE_REDIS	Redis for caching	Yes
LONG_TOKEN_SECRET	JWT secret for long-lived tokens	Yes
SHORT_TOKEN_SECRET	JWT secret for short-lived tokens	Yes
NACL_SECRET	Secret for symmetric encryption	Yes
USER_PORT	HTTP server port (default: 5111)	No

Run the Application

# Start the server
npm start

# The server starts on the configured USER_PORT (default: 5111)

Getting Started with the API

1. Register a superadmin — POST /api/user/register (public, no auth needed)
2. Login — POST /api/user/login → receive a longToken
3. Get a short token — POST /api/token/v1_createShortToken (with longToken in header) → receive shortToken
4. Use the API — include token: <shortToken> in headers for all authenticated endpoints

Run Tests

npm test

API Overview

All API requests go through: POST /api/:moduleName/:fnName

Roles

Role	Permissions
Superadmin	Full system access — manages schools, creates school administrators
School Admin	Manages classrooms and students within their assigned school only

Endpoints

Module	Function	Auth	Description
user	register	Public	Register a new superadmin
user	login	Public	Login (any role)
user	createUser	Superadmin	Create a school administrator
token	v1_createShortToken	Long Token	Exchange long token for short token
school	createSchool	Superadmin	Create a school
school	getSchools	Authenticated	List schools
school	getSchool	Authenticated	Get school by ID
school	updateSchool	Superadmin	Update a school
school	deleteSchool	Superadmin	Delete a school
classroom	createClassroom	Admin+	Create a classroom
classroom	getClassrooms	Authenticated	List classrooms
classroom	getClassroom	Authenticated	Get classroom by ID
classroom	updateClassroom	Admin+	Update a classroom
classroom	deleteClassroom	Admin+	Delete a classroom
student	createStudent	Admin+	Enroll a student
student	getStudents	Authenticated	List students
student	getStudent	Authenticated	Get student by ID
student	updateStudent	Admin+	Update a student profile
student	deleteStudent	Admin+	Remove a student
student	transferStudent	Admin+	Transfer student to different classroom/school

See API_DOCUMENTATION.md for full request/response details.

Database Schema

┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐
│    School     │     │    Classroom     │     │     Student      │
├──────────────┤     ├──────────────────┤     ├──────────────────┤
│ _id          │◄────│ school (FK)      │     │ _id              │
│ name         │     │ _id              │◄────│ classroom (FK)   │
│ address      │     │ name             │     │ school (FK)  ────┤►
│ phone        │     │ capacity         │     │ firstName        │
│ email        │     │ resources[]      │     │ lastName         │
│ createdAt    │     │ createdAt        │     │ email            │
│ updatedAt    │     │ updatedAt        │     │ dateOfBirth      │
└──────────────┘     └──────────────────┘     │ enrollmentDate   │
       ▲                                       │ status           │
       │              ┌──────────────────┐     │ createdAt        │
       └──────────────│ school (FK)      │     │ updatedAt        │
                      │      User        │     └──────────────────┘
                      ├──────────────────┤
                      │ _id              │
                      │ username         │
                      │ email            │
                      │ password (hash)  │
                      │ role             │
                      │ createdAt        │
                      └──────────────────┘

Assumptions

1. Superadmin registration is a public endpoint — any user can register as a superadmin, enabling multiple superadmins to manage the system
2. School administrators are created by superadmins and assigned to a specific school
3. All API endpoints use POST (Axion's convention) — the request body carries all data
4. Student transfer requires specifying both new school and new classroom when moving across schools
5. Classroom capacity is strictly enforced when enrolling or transferring students

Project Structure

axion/
├── index.js                  # Entry point
├── config/                   # Configuration
├── connect/                  # MongoDB connection
├── cache/                    # Redis abstraction
├── loaders/                  # DI system (auto-discovery)
├── managers/
│   ├── api/                  # Request dispatcher
│   ├── http/                 # Express server (rate limiting, helmet)
│   ├── entities/
│   │   ├── user/             # User manager + model + schema
│   │   ├── school/           # School manager + model + schema
│   │   ├── classroom/        # Classroom manager + model + schema
│   │   └── student/          # Student manager + model + schema
│   ├── token/                # JWT token management
│   ├── shark_fin/            # RBAC engine
│   └── ...
├── mws/                      # Middleware (auth, device, etc.)
├── static_arch/              # Permission layers
└── tests/                    # Test suite

License

ISC

Built by

The School Management System was built by Taiwo Akerele