System Architecture
The Institution Management System is built as a modern, microservices-inspired architecture with distinct frontend, backend, and AI services.
Technology Stack
Backend Technologies
- NestJS 11 (TypeScript 5.7+)
- Prisma 6.x ORM
- MariaDB 11
- Passport + JWT authentication
- Swagger/OpenAPI documentation
Frontend Technologies
- Next.js 16 (App Router)
- React 19
- TypeScript 5.9+
- TailwindCSS v4 + Radix UI + shadcn/ui
- Zustand (state management)
- React Hook Form + Zod (forms & validation)
Additional Services
- FastAPI (Python) — AI service
- Nginx — reverse proxy (production)
- AWS S3 — file storage (multer-s3)
- Puppeteer — PDF generation
- Resend / Nodemailer — email delivery
- PisoPay — payment gateway (Philippines)
NestJS Structure
The backend is built with NestJS using a modular architecture. Each module (Education, CRM, LMS, ERP) is organized with controllers, services, and entities following domain-driven design principles.
Database Schema
MariaDB 11 database with Prisma 6.x ORM managing 151 models and 106 enums across all modules. The schema supports complex relationships between students, courses, enrollments, financial transactions, notifications, audit logs, and more.
API Design
RESTful API following consistent patterns across all modules. Supports pagination, filtering, sorting, and includes comprehensive error handling with standardized response formats.
Authentication
JWT-based authentication with role-based access control (RBAC). Tokens are stored as HTTP cookies on the frontend. Configurable expiry (default: 7 days). Global JWT guard protects all routes except those marked with @Public().
Roles & Permissions
The system implements 23 predefined roles with granular permissions using a permission matrix (format: module:entity:action). Multi-role support allows assigning multiple roles per user with CRUD-level permission overrides. Three global guards enforce access: JwtAuthGuard → RolesGuard → PermissionsGuard.
Route-Level Access Control
Frontend middleware enforces role-based route protection via a ROUTE_ROLE_MAP that maps URL prefixes to allowed roles. Unauthorized access redirects users to their appropriate dashboard. The command search palette also filters results based on the same role map.
Student Isolation
Students are restricted to /portal/* routes only and cannot access admin pages (/lms/*, /education/*, /crm/*, /erp/*). Student-facing features use dedicated student-portal API endpoints (/my/*) secured by @RequireStudentStatus guards, separate from admin LMS permissions.
Audit Logging & Exception Handling
Comprehensive audit trail tracking all critical operations including create, update, and delete actions across all modules with user attribution and timestamps.
Structured Logging
All backend services use the NestJS built-in Logger with zero console.log calls. Logging covers authentication events, financial transactions, business operations, and LMS activities.
Global Exception Filter
A centralized AllExceptionsFilter catches all unhandled errors. Server errors (5xx) are logged with full stack traces, client errors (4xx) are logged as warnings, and all responses follow a standardized format with statusCode, message, timestamp, and path.
Security Logging
JWT authentication rejections and permission denials are logged with userId, HTTP method, URL, and the specific reason for denial, enabling security monitoring and incident response.
Next.js Structure
Built with Next.js 16 App Router using server and client components. Organized by feature modules with shared components, hooks, and utilities for consistent user experience.
State Management
Zustand stores for global state management. React Hook Form with Zod validation for forms. API calls managed through service modules with proper error handling.
UI Components
Component library built with Radix UI primitives (shadcn/ui) and styled with TailwindCSS v4. Includes reusable components for forms, data tables (@tanstack/react-table), dialogs, charts (Recharts), drag-and-drop (dnd-kit), and a Monaco code editor.
Module Integration
Seamless integration between Education, CRM, LMS, and ERP modules. Student records from Education link to LMS enrollments, fee management connects to ERP accounting, and more.
AI Service
A FastAPI (Python) microservice running on port 8000 with a health check endpoint. Designed as an extensibility point for future AI-powered features such as automated grading, content recommendations, and intelligent analytics.