Secondary School Management System

A modern Secondary School Management System built with React, Node.js, Express, and MongoDB for South Sudan and other African education systems.

Project Overview

The Secondary School Management System is a production-hardened MVP for managing the core operations of a secondary school. Version v1.0.0-rc1 is feature-complete for controlled pilot deployment and focuses on school setup, admissions, attendance, student fees, assessments, result workflows, report cards, promotion, dashboards, reporting, RBAC, audit logging, backup/restore utilities, and operational documentation.

The system is designed for the South Sudan market first, with support for Senior 1 to Senior 4, local school configuration, SSP/USD currency configuration, term-based workflows, receipt numbering, and realistic South Sudan demo data.

Key Features

• School profile setup, receipt settings, report-card settings, academic settings, and feature flags
• Academic years, terms, Senior 1 to Senior 4, classes, streams, subjects, grading scales, and assessment configurations
• Student admissions, student records, guardians, user/staff access, and school-scoped records
• Daily attendance registers, class/stream attendance, corrections, summaries, and attendance percentages
• Fee structures, student fee accounts, ledger-derived balances, payments, discounts, waivers, immutable receipts, and finance reports
• Payment idempotency using Idempotency-Key to prevent duplicate receipts after retries
• Assessment definitions, marks entry, bulk marks, draft/submitted marks, grading snapshots, and correction history
• Result processing, staged approval workflow, released report-card snapshots, academic history, and promotion records
• Executive dashboard, role-aware navigation, reporting center, CSV/Excel-compatible exports, audit search, and platform operations
• Attendance and marks local draft preservation for intermittent connectivity
• Structured startup diagnostics, health/readiness endpoints, backup/restore scripts, and demo-data verification

System Architecture

React + Vite Web App
        |
        | REST / JSON over HTTPS
        v
Express API
        |
        | Controllers, services, validation, RBAC, audit logging
        v
Business Modules
        |
        | Mongoose models and indexes
        v
MongoDB

The repository uses a modular monolith architecture. Backend domains are separated by module while sharing authentication, RBAC, audit logging, environment validation, response envelopes, and database connection utilities.

Technology Stack

Layer	Technology
Frontend	React 19, Vite 8, React Router 8, TanStack Query
Backend	Node.js, Express, Mongoose
Database	MongoDB
Authentication	JWT access tokens, opaque refresh tokens, HTTP-only refresh cookie
Authorization	Role-based access control with shared capabilities
Validation	Zod
Testing	Vitest, Supertest, Testing Library, MongoDB Memory Server
Tooling	npm workspaces, ESLint, Prettier

Screenshots

Screenshots are expected under docs/images/. The paths below are intentionally stable so images can be added later without another README rewrite.

Authentication

Login screen for secure email/password access and session start.

Administration

User management screen for creating users, assigning roles, and maintaining access.

School setup screen for school profile, academic configuration, receipt settings, and report-card settings.

Student admissions workflow for registering learners and linking guardians.

Student profile screen showing learner records, guardian details, class placement, and status.

Settings screen for school-wide configuration, feature flags, and operational defaults.

Academic

Attendance register screen for daily class and stream attendance marking.

Assessments screen for configuring assessment definitions, marks entry, and grading workflows.

Results workflow screen for staged submission, review, approval, and release.

Report-card screen showing student results, attendance summary, comments, and promotion decision.

Academic analytics dashboard for class averages, pass rates, subject performance, and students at risk.

Finance

Fee structure screen for configuring academic year, term, class-specific, optional, and recurring charges.

Payments screen for recording cash, bank, mobile money, scholarship, and adjustment payments.

Finance dashboard showing collections, outstanding balances, students with balances, and payment trends.

Receipt view showing immutable receipt details generated from school receipt settings.

Platform

Executive dashboard showing role-aware KPIs, recent activity, attendance, collections, enrollment, and pass rates.

Reporting center screen for filtered enrollment, attendance, finance, academic, promotion, and audit reports.

Audit logs screen for reviewing user activity, financial actions, academic workflow events, and operational changes.

User Roles

The system includes the following roles:

Role	Typical responsibility
super_admin	Platform-wide administration
school_admin	School configuration, users, operations
headteacher	Result approval, academic oversight, school KPIs
academic_admin	Assessments, marks review, result workflow
registrar	Admissions and student records
bursar	Fee structures, balances, finance reports
cashier	Payment entry and receipts
finance_manager	Finance oversight and reporting
teacher	Attendance and marks entry
class_teacher	Class-level attendance, reports, progression support

Backend middleware is the enforcement source. Frontend visibility is for usability only.

Installation Guide

Prerequisites

• Node.js >=22.22.0
• npm
• MongoDB database

Local Setup

git clone https://github.com/Jur815/School-Management-System.git
cd School-Management-System
npm install
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env
npm run dev

Create Initial Administrator

Set the temporary bootstrap variables in apps/api/.env, then run:

npm run seed:super-admin --workspace apps/api

Remove all BOOTSTRAP_* variables after confirming administrator access.

Seed Demo Data

For staging or demonstrations only:

npm run seed:demo

The demo seed creates a realistic South Sudan school dataset for St. Theresa Secondary School - Juba.

Environment Variables

API variables are documented in docs/ENVIRONMENT_VARIABLES_GUIDE.md.

Core API variables:

• NODE_ENV
• PORT
• MONGODB_URI
• JWT_ACCESS_SECRET
• JWT_REFRESH_SECRET
• CLIENT_URL
• COOKIE_SECURE
• COOKIE_SAME_SITE
• DEFAULT_CURRENCY
• BACKUP_DIR
• LOG_LEVEL
• RELEASE_VERSION

Web variable:

• VITE_API_URL

See .env.example, apps/api/.env.example, and apps/web/.env.example.

Project Structure

.
├── apps
│   ├── api                 # Express API, Mongoose models, services, scripts, tests
│   └── web                 # React + Vite frontend
├── docs                    # Deployment, operations, API, backup/recovery and user guides
├── packages
│   └── shared              # Roles, capabilities, shared validation and response schemas
├── CHANGELOG_v1.0.md
├── package.json
└── README.md

Important docs:

• Deployment Guide
• Backup & Recovery Guide
• Production Operations Guide
• API Reference
• Installation Guide
• Implementation Status

Database Schema Overview

The database is school-scoped and uses Mongoose models with indexes for uniqueness, workflow lookup, and operational reporting.

Major model groups:

• Core: School, User, RefreshToken, AuditLog
• Academics: AcademicYear, Term, ClassLevel, Stream, Subject, GradingScale, AssessmentConfiguration
• People: Student, Guardian
• Attendance: AttendanceRecord
• Finance: FeeStructure, StudentFeeAccount, FeeLedgerEntry, Payment, Receipt
• Assessments: TeachingAssignment, AssessmentDefinition, MarkRecord
• Results: StudentResult, ReportCard, PromotionRecord, EnrollmentRecord, AcademicHistory
• Platform: BackupRecord, OperationalEvent

Important data rules:

• Student admission numbers are unique per school.
• Balances are derived from append-only ledger entries.
• Receipt numbers are immutable and unique per school.
• Raw marks are preserved; grades are reproducible from stored assessment and grading snapshots.
• Released results cannot be edited directly.
• Promotion creates new academic history/enrollment records without overwriting historical results.

Deployment Guide

The recommended production architecture is:

• Static React/Vite web deployment
• Node.js/Express API deployment
• MongoDB Atlas or managed MongoDB database
• Secured backup directory or mounted storage
• External uptime monitoring for health/readiness endpoints

Health endpoints:

• GET /api/v1/health
• GET /api/v1/readiness

Read docs/DEPLOYMENT_GUIDE.md before deploying.

Backup & Restore

Create a backup:

npm run backup:create --workspace apps/api -- --out ./backups/ssms-backup.json

Verify backup mechanics:

npm run backup:verify

Verify restore mechanics:

npm run restore:verify

Production restore requires explicit operator confirmation. See docs/BACKUP_RECOVERY_GUIDE.md.

Testing

Run the full quality gate:

npm install
npx prettier --check . --ignore-path .gitignore
npm run lint
npm run test
npm run build
npm run deploy:verify
npm run backup:verify
npm run restore:verify
npm run seed:demo:verify
npm audit --omit=dev --audit-level=high
npm audit --audit-level=high

Release Candidate 1 status:

• 104 automated tests passing
• Production build verified
• Deployment health/readiness verification passing
• Backup and restore verification passing
• Demo seed verification passing
• Production and full npm audits passing with 0 high/critical vulnerabilities

Roadmap

Version	Planned focus
v1.0.0-rc1	Controlled pilot deployment readiness
v1.0.0	First pilot-approved stable release
v1.1	Parent portal, SMS notifications, online payments, production PDF hardening
v1.2	Mobile/PWA improvements, payroll and staff HR expansion
v1.3	Advanced analytics after data governance and pilot validation

Out of scope for MVP 1: payroll, full accounting, library, hostel, transport, biometric/RFID attendance, e-learning, SMS integration, AI features, and native mobile apps.

Contributing

This project is currently in Release Candidate status. Before contributing:

1. Create a feature branch from main.
2. Keep changes aligned with the frozen v1.0 scope.
3. Run formatting, lint, tests, build, verification scripts, and audits before opening a pull request.
4. Do not change RBAC capabilities, API contracts, or database schema for RC1 unless the change is a critical release fix.

License

No license file has been committed yet. Until a license is added, all rights are reserved by the project owner.

Author

Created for the South Sudan secondary school market by Peter Jur, with implementation support from Codex.

Repository: github.com/Jur815/School-Management-System