A robust, extensible, and modular backend base project built with Java 21, Spring Boot 4, and MongoDB. This project serves as a foundational blueprint for developing customized electronic school portals (ePortals) specifically tailored to Nigerian educational institutions (Crèche, Nursery, Primary, Junior Secondary (JSS), and Senior Secondary (SSS)).
- Overview
- Key Features
- Domain Structure & Classifications
- Tech Stack
- Getting Started & Setup
- Environment Configuration
- Authentication & Security
- API Documentation
- 1. User Sign-In (Authentication)
- 2. Parent Registration
- 3. Pre-Registration via Excel Upload
- 4. Account Activation
- 5. Get User Profile
- 6. Upload School Fees Configuration Spreadsheet
- 7. Initiate School Fees Payment
- 8. Paystack Payment Webhook
- 9. Verify School Fees Payment Eligibility
- 10. Get School Fees Details & Breakdown
- Global Exception & Error Responses
- Customization Guide for Schools
The ePortal Base simplifies the deployment of school management systems in Nigeria. It addresses common local requirements such as bulk student/teacher onboarding from Excel spreadsheets, strict grade-level structures (Nursery 1-2, Primary 1-6, JSS 1-3, SS 1-3), senior secondary department branching (Science, Art, Commercial), parent-student linkages, account activation workflows, and fee payment processing (Paystack integration).
- Bulk Pre-Registration: Easily parse and validate Excel (
.xlsx) files containing rosters of students and teachers using Apache POI. - Account Activation Workflow: Students and staff receive pre-assigned School IDs and activate their accounts by verifying their Date of Birth and establishing a secure password.
- Parent Portal Linkage: Parents register by validating their ward's School ID and Date of Birth to auto-link parent-child profiles.
- Role-Based Security: Access controls configured for
ADMIN,PRINCIPAL,TEACHER,STUDENT,PARENT, andACCOUNTANT. - JWT Authentication: Stateless token generation with strict claim validation and account status checks (
ACTIVE,INACTIVE,BANNED). - Paystack Integration Ready: Models and configuration ready for processing tuition and administrative fees.
Designed around the standard Nigerian educational framework:
| Category | Values |
|---|---|
| Roles | ADMIN, PRINCIPAL, TEACHER, STUDENT, PARENT, ACCOUNTANT |
| Grades | CRECHE, PLAYGROUND, KG1, KG2, NURSERY_1, NURSERY_2, PRIMARY_1 to PRIMARY_6, JSS1 to JSS3, SS1 to SS3 |
| Departments | SCIENCE, ART, COMMERCIAL, NONE |
| Divisions | A, B, NONE |
| Account Status | ACTIVE, INACTIVE, BANNED |
- Language: Java 21
- Framework: Spring Boot 4.1.0 (Spring WebMVC, Spring Security, Spring Validation, Actuator)
- Database: MongoDB (via Spring Data MongoDB & Docker Compose)
- Security & Tokens: Auth0
java-jwt(v4.5.0) - Excel Parsing: Apache POI (v5.4.1) & Apache Tika (v3.2.3)
- Payment Gateway: Paystack integration configuration
- Build Tool: Maven
- Java 21 JDK
- Docker & Docker Compose
- Maven 3.8+ (or use the provided
./mvnwwrapper)
-
Clone the Repository:
git clone https://github.com/TheDurodola/ePortal.git cd ePortal -
Configure Environment Variables: Copy
.env.exampleto.envand populate the required parameters:cp .env.example .env
-
Start MongoDB via Docker:
docker-compose up -d
Mongo Express will be available at
http://localhost:8081(Credentials:guest/guest). -
Build and Run the Application:
./mvnw clean spring-boot:run
Refer to .env.example for required configuration keys:
MONGODB_URI=mongodb://admin:admin@localhost:27017/eportal_db?authSource=admin
JWT_SIGNING_KEY=your_secure_secret_key_here
REFRESH_TOKEN_SIGNING_KEY=your_secure_refresh_key_here
JWT_DURATION=86400
PAYSTACK_SECRET_KEY=<SECRET_KEY>
SERVER_PORT=8080- Public Endpoints: Sign-in, parent registration, and account activation do not require an authorization header.
- Secured Endpoints: Require a valid JWT passed in the HTTP
Authorizationheader:Authorization: Bearer <your_jwt_token> - Permission Requirements:
POST /api/v1/preregistration/excelrequiresPRINCIPALorADMINauthority.- Profile retrieval requires an account with an
ACTIVEstatus.
To test these endpoints directly, view the interactive Postman Documentation. It includes complete request schemas, headers, and pre-configured environment examples.
Authenticates users and returns a signed JWT token upon successful credential verification.
- Endpoint:
POST /api/v1/auth/signin - Access: Public
- Content-Type:
application/json
{
"username": "STU/2026/001",
"password": "mySecurePassword123"
}{
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}401 Unauthorized(Invalid credentials):{ "error": "Bad credentials", "message": "Invalid Username or Password" }500 Internal Server Error(System error during authentication):{ "error": "Database connectivity failed", "message": "Something went wrong..." }
Registers a parent user account and automatically links the parent to their child's profile using the child's pre-registered School ID and Date of Birth.
- Endpoint:
POST /api/v1/auth/registration - Access: Public
- Content-Type:
application/json
{
"username": "parent.adebayo@example.com",
"firstName": "Bamidele",
"lastName": "Adebayo",
"dateOfBirth": "1980-05-14",
"childSchoolId": "STU/2026/001",
"childDateOfBirth": "2010-08-22",
"password": "ParentPassword123!"
}{
"parentFirstName": "Bamidele",
"childFirstName": "Tunde"
}400 Bad Request(Validation failed):{ "type": "about:blank", "title": "Validation Failed", "status": 400, "detail": "One or more fields are invalid", "instance": "/api/v1/auth/registration", "errors": { "username": "Must be a valid Email Address", "childSchoolId": "Lastname cannot be blank" } }404 Not Found(Child record not found or date of birth mismatch):{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Child account with specified School ID and Date of Birth does not exist" }
Enables Administrators or Principals to upload structured Excel spreadsheets (.xlsx) to pre-register students and teachers into the database.
- Endpoint:
POST /api/v1/preregistration/excel - Access: Secured (
ADMIN,PRINCIPAL) - Content-Type:
multipart/form-data
file(binary): The.xlsxfile containing student and teacher rosters. The spreadsheet file needs to contain TWO sheets.- Sheet 1 for the Teacher
| FIRSTNAME | LASTNAME | DATE OF BIRTH | GRADE | DIVISION |
|---|---|---|---|---|
| John | Doe | 02/01/1980 | JSS1 | A |
| Kodak | Black | 03/11/1992 |
- Sheet 2 for the students
| FIRSTNAME | LASTNAME | DATE OF BIRTH | GRADE | DIVISION | DEPARTMENT |
|---|---|---|---|---|---|
| Nicki | Minaj | 02/11/2001 | CRECHE | A | NONE |
| Jermaine | Cole | 01/01/2009 | JSS1 | B | NONE |
| Kendrick | Lamar | 01/09/2005 | SS2 | A | SCIENCE |
{
"students": [
{
"firstName": "Chidi",
"lastName": "Okonkwo",
"schoolId": "STU/2026/012",
"role": "STUDENT",
"grade": "SS1",
"division": "A",
"department": "SCIENCE"
}
],
"teachers": [
{
"username": "tch_funke@school.edu.ng",
"firstName": "Funke",
"lastName": "Akindele",
"role": "TEACHER",
"grade": "SS1",
"division": "A"
}
]
}400 Bad Request(Invalid file format, empty cells, or bad data structure):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Invalid Excel file format or unparseable columns at row 5" }401 Unauthorized/403 Forbidden(Missing token or insufficient role privileges):{ "error": "Invalid JWT" }
Activates a pre-registered student or teacher account by confirming their pre-assigned School ID/Username, verifying their Date of Birth, and setting their password.
- Endpoint:
PATCH /api/v1/preregistration/activation - Access: Public
- Content-Type:
application/json
{
"username": "STU/2026/012",
"dateOfBirth": "2011-03-15",
"password": "NewStudentPassword123!"
}{
"firstName": "Chidi"
}400 Bad Request(Account already active, inactive, or invalid Date of Birth):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Account status is already ACTIVE or Date of Birth does not match pre-registered records" }404 Not Found(School ID / Username not found):{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Account not found for username: STU/2026/012" }
Fetches profile information for the logged-in user based on the JWT token provided in the request headers.
- Endpoint:
GET /api/v1/profile - Access: Secured (Requires
ACTIVEstatus) - Headers:
Authorization: Bearer <jwt_token>
None
{
"profile": {
"firstName": "Bamidele",
"lastName": "Adebayo",
"username": "parent.adebayo@example.com",
"role": "PARENT",
"dateOfBirth": "1980-05-14",
"students": [
{
"id": "STU/2026/001",
"firstName": "Tunde",
"lastName": "Adebayo",
"grade": "JSS2",
"division": "B",
"department": "NONE"
}
],
"teachers": []
}
}401 Unauthorized(Invalid, missing, or expired JWT):{ "error": "Invalid JWT" }403 Forbidden(Account inactive or suspended):{ "type": "about:blank", "title": "Forbidden", "status": 403, "detail": "Account status INACTIVE is not allowed to access this resource" }
Enables Administrators or Principals to upload structured Excel spreadsheets (.xlsx) containing school fee breakdowns (tuition, total fees, and term minimum percentages) across grades and senior secondary departments.
- Endpoint:
POST /api/v1/schoolfee/excel - Access: Secured (
ACTIVE,ADMIN,PRINCIPAL) - Content-Type:
multipart/form-data
-
file(binary): The.xlsxworkbook specifying fees configuration per grade/department. -
Sheet name should be the session - 2019/2020, 2020/2021 etc.
| DEPARTMENT | GRADE | TUITION | FIRST TERM MIN PERCENTAGE | SECOND TERM MIN PERCENTAGE |
|---|---|---|---|---|
| NONE | CRECHE | 400000 | 30 | 60 |
| ART | SS2 | 500000 | 30 | 75 |
| NONE | JSS1 | 350000 | 25 | 50 |
{
"count": 1,
"data": [
{
"session": "2026/2027",
"department": "SCIENCE",
"grade": "SS1",
"tuition": 150000.0,
"total": 220000.0,
"firstTermMinPercentage": 0.5,
"secondTermMinPercentage": 0.8,
"thirdTermMinPercentage": 1.0
}
]
}400 Bad Request(Invalid percentage order, percentage > 100%, or bad Excel structure):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Row: 2 First term minimum percentage can't be greater than the Second term minimum percentage" }401 Unauthorized/403 Forbidden(Missing or insufficient permissions):{ "error": "Invalid JWT" }
Initiates a Paystack checkout transaction for a parent paying fees on behalf of their ward.
- Endpoint:
POST /api/v1/schoolfee/payment - Access: Secured (
ACTIVE,PARENT) - Headers:
Authorization: Bearer <jwt_token> - Content-Type:
application/json
{
"studentId": "STU/2026/001",
"amount": 100000.0
}{
"redirectUrl": "https://checkout.paystack.com/0123456789abcdef"
}400 Bad Request(Payment exceeds total outstanding amount or prior fees unpaid):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Exceeded total amount" }401 Unauthorized/403 Forbidden:{ "error": "Invalid JWT" }
Processes asynchronous transaction lifecycle events from Paystack, verifies HMAC signature, and updates fee transaction and ledger status.
- Endpoint:
POST /api/v1/schoolfee/webhook - Access: Public
- Content-Type:
application/json
{
"signature": "a1b2c3d4e5f6...",
"rawPayload": "{\"event\":\"charge.success\",\"data\":{\"reference\":\"TX-123456\",\"status\":\"success\"}}"
}Empty Body
400 Bad Request(Invalid signature or malformed payload):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Invalid Webhook Signature" }409 Conflict(Duplicate transaction reference):{ "type": "about:blank", "title": "Conflict", "status": 409, "detail": "Transaction already processed" }
Verifies whether a student has met the required percentage thresholds to qualify for school term activities (such as examinations or registration) for a specific academic session.
- Endpoint:
GET /api/v1/schoolfee/verification - Access: Authenticated
- Content-Type:
application/json
{
"studentID": "STU/2026/001",
"session": "2026/2027"
}{
"studentFirstName": "Tunde",
"studentLastName": "Adebayo",
"qualifiedForFirstTerm": true,
"qualifiedForSecondTerm": true,
"qualifiedForThirdTerm": false
}400 Bad Request(Invalid session format or student ID):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "Input Session could not be parsed into Session Object" }404 Not Found(Fee ledger or classroom not found):{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Fee Ledger does not exist for the student in this session" }
Fetches comprehensive school fee details, tuition amount, total charges, and payment progress for all wards linked to the logged-in parent.
- Endpoint:
GET /api/v1/schoolfee - Access: Secured (
ACTIVE,PARENT) - Headers:
Authorization: Bearer <jwt_token>
None
{
"data": [
{
"session": "2026/2027",
"studentID": "STU/2026/001",
"studentFirstName": "Tunde",
"studentLastName": "Adebayo",
"grade": "JSS2",
"department": "NONE",
"tuition": 150000.0,
"total": 220000.0,
"totalPaid": 120000.0
}
]
}400 Bad Request(Parent has no linked child):{ "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "This parent currently has no child assigned" }401 Unauthorized/403 Forbidden:{ "error": "Invalid JWT" }
The system uses a centralized @RestControllerAdvice exception handler (GlobalExceptionHandler). All exceptions are formatted and returned as standard RFC 7807 ProblemDetail objects.
Returned for custom application business exceptions (e.g. InactiveAccountStatusException, InvalidPasswordException, AccountNotFoundException, InvalidClassroomException, ExcelParserException).
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Error description message explaining the precise failure"
}| Exception Class | Status | Description / Trigger Condition |
|---|---|---|
InactiveAccountStatusException |
400 BAD REQUEST |
Attempting actions on a child or user account that has not yet been activated |
InvalidPasswordException |
400 BAD REQUEST |
Password change failed due to incorrect old password |
InvalidAccountStatusException |
400 BAD REQUEST |
Account is already active or invalid status transition attempted |
InvalidAmountException |
400 BAD REQUEST |
Payment amount is invalid or exceeds total required fees |
InvalidBulkRegistration |
400 BAD REQUEST |
Bulk user onboarding failure due to duplicate usernames |
InvalidCellValueException |
400 BAD REQUEST |
Excel cell value formatting error or missing mandatory cell |
InvalidClassroomException |
400 BAD REQUEST |
Grade and division combination does not exist |
InvalidDateOfBirthException |
400 BAD REQUEST |
Date of birth validation failure against registered records |
InvalidFileTypeException |
400 BAD REQUEST |
Uploaded document is not a valid Microsoft Excel file |
InvalidPercentageException |
400 BAD REQUEST |
Term fees percentage breakdown exceeds 100% or fails order checks |
InvalidPreRegistrationException |
400 BAD REQUEST |
Excel sheet contains empty student/teacher rosters |
InvalidRoleException |
400 BAD REQUEST |
Operation not applicable to the specified user role |
InvalidSchoolSessionException |
400 BAD REQUEST |
Invalid school session year format |
InvalidSessionException |
400 BAD REQUEST |
Academic session could not be parsed into a valid Session object |
InvalidUserException |
400 BAD REQUEST |
User reference is invalid |
InvalidUsernameException |
400 BAD REQUEST |
Username or email address already registered |
InvalidWebhookSignature |
400 BAD REQUEST |
Paystack webhook verification failure |
OutstandingSchoolFeesException |
400 BAD REQUEST |
Student has uncleared prior term or session fees |
ParentChildRelationshipException |
400 BAD REQUEST |
Parent account has no linked child or invalid ward relationship |
ParsingException |
400 BAD REQUEST |
Payload or payload structure parsing error |
SchoolFeesException |
400 BAD REQUEST |
School fees configuration error |
ValidatorException |
400 BAD REQUEST |
General validation error |
UserNotFoundException |
401 UNAUTHORIZED |
User not found in authentication context |
AuthenticationNotSupportedException |
401 UNAUTHORIZED |
Authentication mechanism not supported |
AcademicSessionDoesntExistException |
404 NOT FOUND |
Academic session does not exist |
AccountNotFoundException |
404 NOT FOUND |
Account record does not exist |
FeeLedgerDoesntExistException |
404 NOT FOUND |
Fee ledger for student/session does not exist |
FeeTransactionDoesntExistException |
404 NOT FOUND |
Fee transaction record does not exist |
NoSuchClassroomException |
404 NOT FOUND |
Classroom does not exist |
TransactionAlreadyExistsException |
409 CONFLICT |
Duplicate transaction reference detected |
Returned when request body validation fails (MethodArgumentNotValidException). Includes a key-value mapping of field validation errors under the errors property.
{
"type": "about:blank",
"title": "Validation Failed",
"status": 400,
"detail": "One or more fields are invalid",
"instance": "/api/v1/auth/registration",
"errors": {
"username": "Must be a valid Email Address",
"password": "Password must be at least 8 characters"
}
}When deploying a new customized ePortal instance for a specific Nigerian school:
- Branding & Configuration: Update application properties and JWT issuer string in
CustomAuthenticationFilter.java. - Class & Grade Extensions: Modify
Grade.javaandDepartment.javaif the school uses custom arm names (e.g. Gold, Diamond instead of A, B). - Paystack Credentials: Set
PAYSTACK_SECRET_KEYin environment variables for school fees transactions. - Excel Template: Ensure school administrators upload spreadsheets matching expected column headers for student and teacher pre-registration.