🎓 UniSense - University Management System

A comprehensive, AI-powered university management platform designed to streamline administrative operations and improve student outcomes.

📋 Table of Contents

Overview
Features
Architecture
Tech Stack
Getting Started
Configuration
API Documentation
Testing
Deployment
Contributing
License

🌟 Overview

UniSense is a modern, microservices-based university management system that combines essential administrative functions with AI-powered analytics. Built with scalability and multi-tenancy in mind, it provides universities with the tools they need to manage students, courses, grades, fees, and more—all while gaining actionable insights through machine learning.

Key Highlights

Multi-tenant Architecture - Complete data isolation for multiple universities
AI-Powered Insights - Predictive analytics for student success and risk detection
Progressive Web App - Works offline with automatic sync when online
Role-Based Access Control - Granular permissions for Admin, Dean, Lecturer, Student, and Finance roles
Real-time Notifications - WhatsApp, Email, and SMS integration
RESTful APIs - Well-documented APIs with Swagger/OpenAPI
Property-Based Testing - Rigorous testing for correctness guarantees

✨ Features

Core Modules

👥 User Management

Multi-role support (Admin, Dean, Lecturer, Student, Finance)
JWT-based authentication
University-scoped access control
Profile management

📚 Student Information System (SIS)

Student registration and enrollment
Bulk CSV import/export
Academic records management
Student profile with photo support

📖 Course Management

Course catalog and scheduling
Course registration workflow
Credit hour tracking
Prerequisite management

📊 Grading System

Flexible grading scales
GPA and CGPA calculation
Semester results tracking
Grade distribution analytics

💰 Fee Management

Fee structure configuration
Invoice generation
Payment tracking
Outstanding balance reports
Export to Excel/PDF

📢 Announcements & Notifications

Role-targeted announcements
Multi-channel delivery (WhatsApp, Email, SMS)
Notification preferences
Read/unread tracking

AI-Powered Features

🎯 At-Risk Student Detection

Identifies students at risk of academic failure based on:

GPA trends and patterns
Attendance records
Fee payment status
Historical performance data

📈 GPA Prediction

Predicts end-of-semester GPA using:

Current academic performance
Course difficulty metrics
Historical student data
Workload analysis

👨‍🏫 Lecturer Workload Analytics

Analyzes teaching loads to:

Identify overloaded faculty
Balance course assignments
Optimize resource allocation
Prevent burnout

📊 Administrative Insights

Provides actionable insights on:

Enrollment trends
Course performance heatmaps
Department analytics
Resource utilization

🏗️ Architecture

UniSense follows a microservices architecture with four main services:

┌─────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js)                   │
│                    Progressive Web App (PWA)                 │
└────────────────────────┬────────────────────────────────────┘
                         │
                         │ HTTPS/REST
                         │
┌────────────────────────┴────────────────────────────────────┐
│                    Core Backend (NestJS)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │     Auth     │  │   Business   │  │   Database   │     │
│  │   & RBAC     │  │    Logic     │  │    Layer     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────┬────────────────────┬────────────────────┬─────────┘
         │                    │                    │
         │                    │                    │
    ┌────┴─────┐      ┌──────┴──────┐      ┌─────┴──────┐
    │   AI     │      │  WhatsApp   │      │ PostgreSQL │
    │ Service  │      │   Service   │      │   + Redis  │
    │ (Python) │      │  (Python)   │      │            │
    └──────────┘      └─────────────┘      └────────────┘

Service Responsibilities

Service	Technology	Purpose
Core Backend	NestJS + TypeORM	Authentication, business logic, data persistence
Frontend	Next.js + React	User interface, PWA capabilities, offline support
AI Service	Python + FastAPI	Machine learning models, predictive analytics
WhatsApp Service	Python + FastAPI	Asynchronous message delivery, notification queue

🛠️ Tech Stack

Backend

Framework: NestJS 10.x
Language: TypeScript 5.x
ORM: TypeORM
Database: PostgreSQL 15+
Cache: Redis 7+
Authentication: JWT + Passport
Validation: class-validator
Testing: Jest + fast-check (property-based testing)

Frontend

Framework: Next.js 14.x
Language: TypeScript 5.x
UI Library: React 18.x
Styling: Tailwind CSS
PWA: next-pwa
HTTP Client: Axios
Charts: Recharts
Testing: Jest + React Testing Library + fast-check

AI Service

Framework: FastAPI
Language: Python 3.11+
ML Libraries: scikit-learn, pandas, numpy
Database: PostgreSQL (read-only)
Testing: pytest + Hypothesis (property-based testing)

WhatsApp Service

Framework: FastAPI
Language: Python 3.11+
Queue: Redis
API: WhatsApp Business API
Testing: pytest + Hypothesis

Infrastructure

Containerization: Docker + Docker Compose
Reverse Proxy: Nginx (production)
CI/CD: GitHub Actions
Monitoring: Prometheus + Grafana (optional)

🚀 Getting Started

Prerequisites

Docker 24.0+ and Docker Compose 2.20+
Node.js 20+ (for local development)
Python 3.11+ (for local development)
PostgreSQL 15+ (if not using Docker)
Redis 7+ (if not using Docker)

Quick Start (Docker)

Clone the repository

git clone https://github.com/Emart29/unisense.git
cd unisense

Set up environment variables

cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
cp ai-service/.env.example ai-service/.env
cp whatsapp-service/.env.example whatsapp-service/.env

Configure your environment

Edit the .env files with your configuration. At minimum, update:
- Database credentials
- JWT secret
- Redis URL
- API keys (optional for MVP)
Start all services
```
docker-compose up -d
```

Run database migrations

docker-compose exec backend npm run migration:run

Access the application
- Frontend: http://localhost:3000
- Backend API: http://localhost:3001
- API Documentation: http://localhost:3001/api
- AI Service: http://localhost:8001
- WhatsApp Service: http://localhost:8002

Quick Start (Windows - Manual Setup)

For Windows users without Docker/WSL2:

Install dependencies
- PostgreSQL 15+ (Download)
- Redis (Memurai for Windows: choco install memurai)
- Node.js 20+ (Download)
- Python 3.11+ (Download)
Set up database
```
.\setup-database.ps1
```
Seed test data
```
.\seed-data.ps1
```
Start all services
```
.\start-services.ps1
```
Stop all services
```
.\stop-services.ps1
```

Test Credentials

After seeding the database, you can login with:

Email	Password	Role
admin@test.edu	password123	Admin
dean@test.edu	password123	Dean
lecturer@test.edu	password123	Lecturer
student@test.edu	password123	Student
finance@test.edu	password123	Finance

All test users belong to "Test University" (TEST_UNI).

⚙️ Configuration

Environment Variables

Core Backend (`backend/.env`)

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_NAME=unisense

# JWT
JWT_SECRET=your-secret-key-min-32-chars

# Redis
REDIS_URL=redis://localhost:6379

# AI Service
AI_SERVICE_URL=http://localhost:8001

# Application
NODE_ENV=development
PORT=3001

Frontend (`frontend/.env.local`)

NEXT_PUBLIC_API_URL=http://localhost:3001

AI Service (`ai-service/.env`)

DATABASE_URL=postgresql://postgres:password@localhost:5432/unisense
MODEL_PATH=./models

WhatsApp Service (`whatsapp-service/.env`)

DATABASE_URL=postgresql://postgres:password@localhost:5432/unisense
REDIS_URL=redis://localhost:6379
WHATSAPP_API_URL=https://graph.facebook.com/v18.0
WHATSAPP_API_TOKEN=your_token
WEBHOOK_SECRET=your_secret

Multi-Tenancy

UniSense implements row-level multi-tenancy:

All tables include a university_id column
Middleware automatically scopes queries to the authenticated user's university
Complete data isolation between universities

📚 API Documentation

Once the backend is running, access the interactive API documentation:

Swagger UI: http://localhost:3001/api

Key Endpoints

Authentication

POST /auth/login - User login
GET /auth/profile - Get current user profile

Students

GET /students - List all students
POST /students - Create new student
POST /students/import - Bulk import from CSV
GET /students/:id - Get student details

Courses

GET /courses - List all courses
POST /courses - Create new course
POST /course-registrations - Register student for course

Grades

POST /grades - Submit grade
GET /grades/student/:id - Get student grades
GET /semester-results/:id - Get semester results with GPA

Fees

GET /invoices - List invoices
POST /invoices - Create invoice
GET /invoices/export - Export invoices to Excel

AI Analytics

GET /ai/at-risk-students - Get at-risk students
GET /ai/enrollment-trends - Get enrollment trends
GET /ai/department-performance - Get department analytics

🧪 Testing

Running Tests

Backend Tests

cd backend
npm run test              # Run all tests
npm run test:watch        # Watch mode
npm run test:cov          # With coverage
npm run test:e2e          # Integration tests

Frontend Tests

cd frontend
npm run test              # Run all tests
npm run test:watch        # Watch mode

AI Service Tests

cd ai-service
pytest                    # Run all tests
pytest -v                 # Verbose output
pytest --cov              # With coverage

WhatsApp Service Tests

cd whatsapp-service
pytest                    # Run all tests
pytest -v                 # Verbose output

Property-Based Testing

UniSense uses property-based testing to ensure correctness:

Backend (fast-check):

// Feature: unisense-mvp, Property 14: GPA calculation correctness
test('GPA equals weighted average of grade points', () => {
  fc.assert(
    fc.property(
      fc.array(courseGradeGenerator(), { minLength: 1 }),
      (grades) => {
        const gpa = calculateGPA(grades);
        const expected = weightedAverage(grades);
        expect(gpa).toBeCloseTo(expected, 2);
      }
    ),
    { numRuns: 100 }
  );
});

Python Services (Hypothesis):

@given(st.lists(student_generator(), min_size=1))
def test_risk_score_range(students):
    """Risk scores should always be between 0 and 1"""
    for student in students:
        score = calculate_risk_score(student)
        assert 0 <= score <= 1

🚢 Deployment

Production Deployment

Update environment variables for production

cp .env.example .env
# Edit with production values

Build and start services

docker-compose -f docker-compose.prod.yml up -d --build

Run migrations

docker-compose -f docker-compose.prod.yml exec backend npm run migration:run

Set up SSL/TLS with Let's Encrypt or your certificate provider
Configure reverse proxy (Nginx recommended)

For detailed deployment instructions, see DEPLOYMENT.md.

Scaling

UniSense is designed to scale horizontally:

Backend: Multiple instances behind load balancer
Database: Read replicas + connection pooling (PgBouncer)
Redis: Redis Cluster for high availability
AI Service: Multiple workers for parallel processing

📖 Documentation

SETUP.md - Detailed setup instructions
DEPLOYMENT.md - Production deployment guide
CONTRIBUTING.md - Contribution guidelines
API Documentation - Interactive API docs (when running)

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

Code of conduct
Development workflow
Coding standards
Testing requirements
Pull request process

Quick Contribution Guide

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (npm run test)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with NestJS, Next.js, and FastAPI
Property-based testing powered by fast-check and Hypothesis
Icons and UI components from various open-source projects

📞 Support

Documentation: docs.unisense.com (coming soon)
Issues: GitHub Issues
Discussions: GitHub Discussions

🗺️ Roadmap

Phase 1 (Current - MVP)

✅ Core modules (Users, Students, Courses, Grades, Fees)
✅ AI-powered analytics
✅ Multi-tenancy
✅ PWA support
✅ Property-based testing

Phase 2 (Q1-Q2 2026)

Online payment integration (Paystack/Flutterwave)
Student self-service portal
Timetable automation
Enhanced AI models
Mobile apps (iOS/Android)

Phase 3 (Q3-Q4 2026)

👨‍💻 Author

Emmanuel Nwanguma

GitHub: @Emart29
LinkedIn: Emmanuel Nwanguma

Made with ❤️ for universities across Africa and beyond

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
ai-service		ai-service
backend		backend
docs		docs
frontend		frontend
scripts		scripts
whatsapp-service		whatsapp-service
.env.example		.env.example
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
Makefile		Makefile
README.md		README.md
SETUP.md		SETUP.md
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.test.yml		docker-compose.test.yml
docker-compose.yml		docker-compose.yml
seed-data.ps1		seed-data.ps1
setup-database.ps1		setup-database.ps1
start-services.ps1		start-services.ps1
stop-services.ps1		stop-services.ps1

Emart29/unisense

Folders and files

Latest commit

History

Repository files navigation