https://github.com/tanzeebul-tamim/unimate-ums
A MERN-stack MVP project aimed at showcasing the core functionalities of a university management system. Built as a major back-end practice project with focus on writing enterprise-grade backend architecture with scalable and modular design.
https://github.com/tanzeebul-tamim/unimate-ums
backend-development dotenv expressjs mondodb mongoose mongoose-schema nodejs personal-project restful-api typescript web-development
Last synced: 2 months ago
JSON representation
A MERN-stack MVP project aimed at showcasing the core functionalities of a university management system. Built as a major back-end practice project with focus on writing enterprise-grade backend architecture with scalable and modular design.
- Host: GitHub
- URL: https://github.com/tanzeebul-tamim/unimate-ums
- Owner: Tanzeebul-Tamim
- License: mit
- Created: 2024-03-09T18:02:38.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-08-13T16:34:47.000Z (10 months ago)
- Last Synced: 2025-08-13T18:39:35.395Z (10 months ago)
- Topics: backend-development, dotenv, expressjs, mondodb, mongoose, mongoose-schema, nodejs, personal-project, restful-api, typescript, web-development
- Language: TypeScript
- Homepage: https://unimate-ums-backend.vercel.app/
- Size: 3.39 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
🎓 UniMate
University Management System (UMS)
Robust, scalable backend for academic and administrative management.
Built with TypeScript, Express.js, MongoDB, and modern best practices.
UniMate is a robust and scalable university management backend system designed to manage academic and administrative functionalities for students, faculty, and admin users. It is built with TypeScript, Express.js, MongoDB, and other modern tools, featuring proper error handling, validation, and modular architecture.
## 📚 Table of Contents
- [🚀 Features](#-features)
- [🧰 Technologies Used](#-technologies-used)
- [📁 Project Structure](#-project-structure)
- [📋 Requirement Analysis](#-requirement-analysis)
- [🗂 Database Schema Overview](#-database-schema-overview)
- [📡 API Endpoints](#-api-endpoints)
- [🧪 Sample API Testing](#-sample-api-testing)
- [🔍 Common Advanced Query Features](#-common-advanced-query-features)
- [📦 Sample Data](#-sample-data)
- [✅ Prerequisites](#-prerequisites)
- [🔧 Installation & Running Locally](#-installation--running-locally)
- [🌐 Live Deployment](#-live-deployment)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
## 🚀 Features
- Full CRUD for students, faculty, and admin profiles
- Dynamic semester & department management
- Comprehensive ID validation and naming conventions
- Middleware-driven error handling & async wrapper
- Zod-based schema validation for type-safe API requests
- Global error handler with specific error mappers (Zod, Mongoose, duplicate, cast)
- Custom logic (middle name removal, ID formatting checks)
- Role-based restrictions and request validation utilities
- Modular, scalable folder architecture
## 🧰 Technologies Used
Full list of Packages & Technologies Used (Click to expand)
- **Node.js**: JavaScript runtime environment for building scalable server-side applications
- **Express.js**: Web framework for Node.js to handle routing and middleware
- **TypeScript** – Strong typing & clean code structure
- **MongoDB**: NoSQL database for storing application data
- **Mongoose** – Schema modeling
- **Zod** – Runtime validation
- **ESLint** – Linting
- **Prettier** – Formatting
- **dotenv** – Environment variable management
- **HTTP Status** – Clean status messaging
- **ts-node-dev** – TypeScript development server
- **bcrypt** – Password hashing
- **validator** – Data validation
- **CORS** – Cross-Origin Resource Sharing
- **Vercel** – Cloud deployment
## 📁 Project Structure
```
UniMate-UMS/
├── .gitignore # Specifies files and folders to be ignored by Git
├── LICENSE # Project license information (MIT)
├── README.md # Project documentation (this file)
├── analysis-requirements/
│ ├── UniMate-Course-Syllabus.pdf # Project syllabus document
│ ├── UniMate-UMS-Database-Schema.png # Visual ER diagram showing database collections and relationships
│ └── UniMate-UMS-Requirement-Analysis.pdf # Documents functional requirements, database models, and API endpoints
└── server/
├── sample/ # sample request payloads (student.json, faculty.json, admin.json)
├── src/
│ ├── app/
│ │ ├── builder/ # QueryBuilder.ts – builds mongoose queries (filter, sort, paginate)
│ │ ├── config/ # index.ts – loads environment config
│ │ ├── constant/ # common.ts – shared enums and schemas
│ │ ├── errors/ # AppError & handlers for Zod, Mongoose, etc.
│ │ ├── interface/ # common.ts, error.ts – TypeScript types/interfaces
│ │ ├── middlewares/ # globalErrorHandler.ts, validateRequest.ts, notFound.ts
│ │ ├── modules/ # feature modules (academicFaculty, student, semesterRegistration, etc.)
│ │ │ ├── moduleName/
│ │ │ │ ├── moduleName.constant.ts # Module-specific constants (roles, statuses, default values)
│ │ │ │ ├── moduleName.controller.ts # Handles HTTP request/response logic
│ │ │ │ ├── moduleName.interface.ts # Module-specific TypeScript types and interfaces
│ │ │ │ ├── moduleName.model.ts # Mongoose schema/model definition for the module
│ │ │ │ ├── moduleName.route.ts # Express route definitions and API endpoints
│ │ │ │ ├── moduleName.service.ts # Core business logic, DB interactions
│ │ │ │ ├── moduleName.utils.ts # Utility/helper functions for the module (Optional)
│ │ │ │ └── moduleName.validation.ts # Zod schema for validating incoming request bodies
│ │ │ │
│ │ │ └── ... # Other similar module directories
│ │ │
│ │ ├── routes/ # index.ts – central router
│ │ └── utils/ # Utilities - catchAsync.ts, sendResponse.ts, idValidator.ts, etc.
│ ├── app.ts # Express app setup (parsers, routes, error middleware)
│ └── server.ts # Server entry point & MongoDB connection logic
├── .env.example # Template Environment variables for local development
├── .eslintignore # Specifies files and folders to be ignored by ESLint
├── .eslintrc.json # ESLint configuration for code linting and style enforcement
├── .prettierrc.json # Prettier configuration for consistent code formatting
├── package-lock.json # Automatically generated lockfile for reproducible installs
├── package.json # npm dependencies, devDependencies & useful scripts
├── tsconfig.json # TypeScript compiler options and project settings
└── vercel.json # Vercel deployment configuration
```
## 📋 Requirement Analysis
| Entity | Student | Faculty | Admin |
| ----------------------- | ------------------------------------------------- | -------------------------------- | ------------------------------------------- |
| **Authentication** | Login, logout, change password | Login, logout, change password | Login, logout, change password |
| **Profile Mgmt** | Edit permitted fields | Edit permitted fields | Edit permitted fields |
| **Academic Procedures** | Enroll in courses, view schedule, grades, notices | Manage grades, view student info | Manage semesters, courses, offerings, rooms |
| **User Mgmt** | — | — | Create/block/unblock users, reset passwords |
_Full API spec and data structure details provided in the analysis document._
## 🗂 Database Schema Overview
A visual representation of the core database models and relationships:
> **Legend:**
>
> - GREEN: Primary entities (Student, Faculty, Admin)
> - PINK: User & academic structure entities
> - YELLOW: Embedded objects
> - CYAN: Client payloads (Offered Course, Semester Registration)
> [!IMPORTANT]
> Entities shown under CYAN have the same names as their database counterparts but may differ in structure (client payloads vs. DB models).
## 📡 API Endpoints
For a complete list of API specifications, including all endpoints and HTTP methods, see the [**_Requirement Analysis PDF_**](./analysis-requirements/UniMate-UMS-Requirement-Analysis.pdf).
**Sample endpoints:**
```http
POST /api/v1/users/create-student
GET /api/v1/students
GET /api/v1/students/S-2021010001
PATCH /api/v1/students/S-2021010001
DELETE /api/v1/students/S-2021010001
```
> **Tips:**
>
> - All endpoints are prefixed with `/api/v1/`
> - For user operations (admin, faculty, student), use the application-generated user ID (e.g., S-2021010001), not the MongoDB ObjectId.
> - For other entities (Academic Faculty, Department, etc.), use the MongoDB ObjectId (`_id`).
## 🧪 Sample API Testing
- Use [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) to test APIs.
- For POST/PATCH, provide the required JSON body.
- The server responds with JSON for all endpoints.
> **Note:**
>
> - See [Requirement Analysis PDF](./analysis-requirements/UniMate-UMS-Requirement-Analysis.pdf) for full API route details.
> - Sample payloads are available in [`server/sample`](./server/sample).
## 🔍 Common Advanced Query Features
Most GET endpoints (students, faculties, departments, courses, etc.) support:
- `searchTerm=` — partial name/code search
- `limit=` — limit results per page
- `page=` — pagination
- `sort=` — sorting
- Field-based filters (e.g., `gender=male&bloodGroup=B+`)
Example:
```http
GET /api/v1/faculties?searchTerm=john&gender=male&page=2&limit=10&sort=name.firstName
```
## 📦 Sample Data
Sample `.json` data files for Student, Faculty, Admin are available in [`server/sample`](./server/sample) for testing payloads.
## ✅ Prerequisites
- [**Node**.js](https://nodejs.org/) (v18 or higher recommended)
- [**npm**](https://www.npmjs.com/) (comes with Node.js)
- [**MongoDB**](https://www.mongodb.com/try/download/community) (local or remote)
- A [**`.env`**](./server/.env.example) file with required environment variables
## 🔧 Installation & Running Locally
### 1. Clone the repository
```bash
git clone https://github.com/yourusername/UniMate-UMS.git
cd UniMate-UMS/server
```
### 2. Install dependencies
```bash
npm install
```
### 3. Set up environment variables
- **Rename [`server/.env.example`](./server/.env.example) to `.env` and fill in your credentials:**
```env
NODE_ENV=development
PORT=5000
DATABASE_URL=yourDatabaseUser
BCRYPT_SALT_ROUNDS=12
DEFAULT_PASS=ChangeMeToASecurePassword!
```
- **Configuration Details:**
- NODE_ENV: `development` (local) or `production` (deployed)
- PORT: Port your Express app will listen on
- DATABASE_URL: MongoDB connection string (local or Atlas)
- BCRYPT_SALT_ROUNDS: Password hashing complexity (integer ≥ 4)
- DEFAULT_PASS: Default admin password (change after first login)
> ⚠️ Caution:
Never commit your `.env` file to version control. Keep it private and add `.env` to your `.gitignore`.
### 4. Run the development server
```bash
npm run dev
```
### 5. Build for production
```bash
npm run build
npm run prod
```
## 🌐 Live Deployment
The API is deployed on [**_Vercel_**](https://vercel.com/) and is live at [**this following URL**](https://unimate-ums-backend.vercel.app/).
## 🤝 Contributing
Have ideas to improve this API? Found a bug? [Open an issue](https://github.com/yourusername/UniMate-UMS/issues) or submit a pull request!
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.