{"id":22902536,"url":"https://github.com/tanzeebul-tamim/unimate-ums","last_synced_at":"2026-04-14T19:32:28.880Z","repository":{"id":228459192,"uuid":"769666190","full_name":"Tanzeebul-Tamim/UniMate-UMS","owner":"Tanzeebul-Tamim","description":"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.","archived":false,"fork":false,"pushed_at":"2025-08-13T16:34:47.000Z","size":3553,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-13T18:39:35.395Z","etag":null,"topics":["backend-development","dotenv","expressjs","mondodb","mongoose","mongoose-schema","nodejs","personal-project","restful-api","typescript","web-development"],"latest_commit_sha":null,"homepage":"https://unimate-ums-backend.vercel.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tanzeebul-Tamim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-09T18:02:38.000Z","updated_at":"2025-08-13T16:34:51.000Z","dependencies_parsed_at":"2025-08-01T14:05:58.132Z","dependency_job_id":"0b1c90bf-cd4c-4d9a-b66f-dc6b4b89c034","html_url":"https://github.com/Tanzeebul-Tamim/UniMate-UMS","commit_stats":null,"previous_names":["tanzeebul-tamim/ph-university","tanzeebul-tamim/unimate-ums"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Tanzeebul-Tamim/UniMate-UMS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tanzeebul-Tamim%2FUniMate-UMS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tanzeebul-Tamim%2FUniMate-UMS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tanzeebul-Tamim%2FUniMate-UMS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tanzeebul-Tamim%2FUniMate-UMS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tanzeebul-Tamim","download_url":"https://codeload.github.com/Tanzeebul-Tamim/UniMate-UMS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tanzeebul-Tamim%2FUniMate-UMS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31812968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend-development","dotenv","expressjs","mondodb","mongoose","mongoose-schema","nodejs","personal-project","restful-api","typescript","web-development"],"created_at":"2024-12-14T02:16:05.620Z","updated_at":"2026-04-14T19:32:28.872Z","avatar_url":"https://github.com/Tanzeebul-Tamim.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\r\n    🎓 UniMate\r\n    \u003cbr\u003e\r\n    University Management System (UMS)\r\n\u003c/h1\u003e\r\n\r\n\u003ch5 align=\"center\"\u003e\r\n  \u003cb\u003eRobust, scalable backend for academic and administrative management.\u003cbr\u003eBuilt with TypeScript, Express.js, MongoDB, and modern best practices.\u003c/b\u003e\r\n\u003c/h5\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n\u003cp align=\"center\"\u003e\r\n    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.\r\n\u003c/p\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n## 📚 Table of Contents\r\n\r\n-   [🚀 Features](#-features)\r\n-   [🧰 Technologies Used](#-technologies-used)\r\n-   [📁 Project Structure](#-project-structure)\r\n-   [📋 Requirement Analysis](#-requirement-analysis)\r\n-   [🗂 Database Schema Overview](#-database-schema-overview)\r\n-   [📡 API Endpoints](#-api-endpoints)\r\n-   [🧪 Sample API Testing](#-sample-api-testing)\r\n-   [🔍 Common Advanced Query Features](#-common-advanced-query-features)\r\n-   [📦 Sample Data](#-sample-data)\r\n-   [✅ Prerequisites](#-prerequisites)\r\n-   [🔧 Installation \u0026 Running Locally](#-installation--running-locally)\r\n-   [🌐 Live Deployment](#-live-deployment)\r\n-   [🤝 Contributing](#-contributing)\r\n-   [📄 License](#-license)\r\n\r\n\u003cbr\u003e\r\n\r\n## 🚀 Features\r\n\r\n-   \u003cb\u003eFull CRUD\u003c/b\u003e for students, faculty, and admin profiles\r\n-   \u003cb\u003eDynamic\u003c/b\u003e semester \u0026 department management\r\n-   \u003cb\u003eComprehensive ID validation\u003c/b\u003e and naming conventions\r\n-   \u003cb\u003eMiddleware-driven\u003c/b\u003e error handling \u0026 async wrapper\r\n-   \u003cb\u003eZod-based\u003c/b\u003e schema validation for type-safe API requests\r\n-   \u003cb\u003eGlobal error handler\u003c/b\u003e with specific error mappers (Zod, Mongoose, duplicate, cast)\r\n-   \u003cb\u003eCustom logic\u003c/b\u003e (middle name removal, ID formatting checks)\r\n-   \u003cb\u003eRole-based restrictions\u003c/b\u003e and request validation utilities\r\n-   \u003cb\u003eModular, scalable folder architecture\u003c/b\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n## 🧰 Technologies Used\r\n\r\n\u003cdiv style=\"display: flex; gap: 10px; flex-wrap: wrap;\"\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Node.js-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white\" alt=\"Node.js\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Express.js-000000?style=for-the-badge\u0026logo=express\u0026logoColor=white\" alt=\"Express.js\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/MongoDB-47A248?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white\" alt=\"MongoDB\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Mongoose-880000?style=for-the-badge\u0026logoColor=white\" alt=\"Mongoose\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Zod-3E7CFF?style=for-the-badge\u0026logoColor=white\" alt=\"Zod\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/ESLint-4B32C3?style=for-the-badge\u0026logo=eslint\u0026logoColor=white\" alt=\"ESLint\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Prettier-F7B93E?style=for-the-badge\u0026logo=prettier\u0026logoColor=white\" alt=\"Prettier\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/dotenv-8DD6F9?style=for-the-badge\u0026logoColor=white\" alt=\"dotenv\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/bcrypt-00599C?style=for-the-badge\u0026logoColor=white\" alt=\"bcrypt\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/validator-FF4C4C?style=for-the-badge\u0026logoColor=white\" alt=\"validator\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/CORS-1E90FF?style=for-the-badge\u0026logoColor=white\" alt=\"CORS\" /\u003e\r\n  \u003cimg src=\"https://img.shields.io/badge/Vercel-000000?style=for-the-badge\u0026logo=vercel\u0026logoColor=white\" alt=\"Vercel\" /\u003e\r\n\u003c/div\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n\u003cdetails\u003e\r\n   \u003csummary\u003e\r\n      \u003cstrong\u003e\r\n         Full list of \u003ci\u003ePackages \u0026 Technologies Used\u003c/i\u003e (Click to expand)\r\n      \u003c/strong\u003e\r\n   \u003c/summary\u003e\r\n\r\n-   **Node.js**: JavaScript runtime environment for building scalable server-side applications\r\n-   **Express.js**: Web framework for Node.js to handle routing and middleware\r\n-   **TypeScript** – Strong typing \u0026 clean code structure\r\n-   **MongoDB**: NoSQL database for storing application data\r\n-   **Mongoose** – Schema modeling\r\n-   **Zod** – Runtime validation\r\n-   **ESLint** – Linting\r\n-   **Prettier** – Formatting\r\n-   **dotenv** – Environment variable management\r\n-   **HTTP Status** – Clean status messaging\r\n-   **ts-node-dev** – TypeScript development server\r\n-   **bcrypt** – Password hashing\r\n-   **validator** – Data validation\r\n-   **CORS** – Cross-Origin Resource Sharing\r\n-   **Vercel** – Cloud deployment\r\n\u003c/details\u003e\r\n\r\n\u003cbr\u003e\r\n\r\n## 📁 Project Structure\r\n\r\n```\r\nUniMate-UMS/\r\n├── .gitignore                                      # Specifies files and folders to be ignored by Git\r\n├── LICENSE                                         # Project license information (MIT)\r\n├── README.md                                       # Project documentation (this file)\r\n├── analysis-requirements/\r\n│   ├── UniMate-Course-Syllabus.pdf                 # Project syllabus document\r\n│   ├── UniMate-UMS-Database-Schema.png             # Visual ER diagram showing database collections and relationships\r\n│   └── UniMate-UMS-Requirement-Analysis.pdf        # Documents functional requirements, database models, and API endpoints\r\n└── server/\r\n    ├── sample/                                     # sample request payloads (student.json, faculty.json, admin.json)\r\n    ├── src/\r\n    │   ├── app/\r\n    │   │   ├── builder/                            # QueryBuilder.ts – builds mongoose queries (filter, sort, paginate)\r\n    │   │   ├── config/                             # index.ts – loads environment config\r\n    │   │   ├── constant/                           # common.ts – shared enums and schemas\r\n    │   │   ├── errors/                             # AppError \u0026 handlers for Zod, Mongoose, etc.\r\n    │   │   ├── interface/                          # common.ts, error.ts – TypeScript types/interfaces\r\n    │   │   ├── middlewares/                        # globalErrorHandler.ts, validateRequest.ts, notFound.ts\r\n    │   │   ├── modules/                            # feature modules (academicFaculty, student, semesterRegistration, etc.)\r\n    │   │   │   ├── moduleName/\r\n    │   │   │   │   ├── moduleName.constant.ts      # Module-specific constants (roles, statuses, default values)\r\n    │   │   │   │   ├── moduleName.controller.ts    # Handles HTTP request/response logic\r\n    │   │   │   │   ├── moduleName.interface.ts     # Module-specific TypeScript types and interfaces\r\n    │   │   │   │   ├── moduleName.model.ts         # Mongoose schema/model definition for the module\r\n    │   │   │   │   ├── moduleName.route.ts         # Express route definitions and API endpoints\r\n    │   │   │   │   ├── moduleName.service.ts       # Core business logic, DB interactions\r\n    │   │   │   │   ├── moduleName.utils.ts         # Utility/helper functions for the module (Optional)\r\n    │   │   │   │   └── moduleName.validation.ts    # Zod schema for validating incoming request bodies\r\n    │   │   │   │\r\n    │   │   │   └── ...                             # Other similar module directories\r\n    │   │   │\r\n    │   │   ├── routes/                             # index.ts – central router\r\n    │   │   └── utils/                              # Utilities - catchAsync.ts, sendResponse.ts, idValidator.ts, etc.\r\n    │   ├── app.ts                                  # Express app setup (parsers, routes, error middleware)\r\n    │   └── server.ts                               # Server entry point \u0026 MongoDB connection logic\r\n    ├── .env.example                                # Template Environment variables for local development\r\n    ├── .eslintignore                               # Specifies files and folders to be ignored by ESLint\r\n    ├── .eslintrc.json                              # ESLint configuration for code linting and style enforcement\r\n    ├── .prettierrc.json                            # Prettier configuration for consistent code formatting\r\n    ├── package-lock.json                           # Automatically generated lockfile for reproducible installs\r\n    ├── package.json                                # npm dependencies, devDependencies \u0026 useful scripts\r\n    ├── tsconfig.json                               # TypeScript compiler options and project settings\r\n    └── vercel.json                                 # Vercel deployment configuration\r\n\r\n```\r\n\r\n\u003cbr\u003e\r\n\r\n## 📋 Requirement Analysis\r\n\r\n| Entity                  | Student                                           | Faculty                          | Admin                                       |\r\n| ----------------------- | ------------------------------------------------- | -------------------------------- | ------------------------------------------- |\r\n| **Authentication**      | Login, logout, change password                    | Login, logout, change password   | Login, logout, change password              |\r\n| **Profile Mgmt**        | Edit permitted fields                             | Edit permitted fields            | Edit permitted fields                       |\r\n| **Academic Procedures** | Enroll in courses, view schedule, grades, notices | Manage grades, view student info | Manage semesters, courses, offerings, rooms |\r\n| **User Mgmt**           | —                                                 | —                                | Create/block/unblock users, reset passwords |\r\n\r\n_Full API spec and data structure details provided in the analysis document._\r\n\r\n\u003cbr\u003e\r\n\r\n## 🗂 Database Schema Overview\r\n\r\nA visual representation of the core database models and relationships:\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"./analysis-requirements/UniMate-UMS-Database-Schema.png\" alt=\"Database Schema\" /\u003e\r\n\u003c/p\u003e\r\n\r\n\u003e **Legend:**\r\n\u003e\r\n\u003e -   \u003cstrong\u003e\u003cspan style=\"color:green\"\u003eGREEN\u003c/span\u003e:\u003c/strong\u003e Primary entities (Student, Faculty, Admin)\r\n\u003e -   \u003cstrong\u003e\u003cspan style=\"color:pink\"\u003ePINK\u003c/span\u003e:\u003c/strong\u003e User \u0026 academic structure entities\r\n\u003e -   \u003cstrong\u003e\u003cspan style=\"color:yellow\"\u003eYELLOW\u003c/span\u003e:\u003c/strong\u003e Embedded objects\r\n\u003e -   \u003cstrong\u003e\u003cspan style=\"color:cyan\"\u003eCYAN\u003c/span\u003e:\u003c/strong\u003e Client payloads (Offered Course, Semester Registration)\r\n\r\n\u003e [!IMPORTANT]\r\n\u003e Entities shown under \u003cspan style=\"color:cyan\"\u003e\u003ci\u003e\u003cstrong\u003eCYAN\u003c/strong\u003e\u003c/i\u003e\u003c/span\u003e have the same names as their database counterparts but may differ in structure (client payloads vs. DB models).\r\n\r\n\u003cbr\u003e\r\n\r\n## 📡 API Endpoints\r\n\r\nFor a complete list of API specifications, including all endpoints and HTTP methods, see the [**_Requirement Analysis PDF_**](./analysis-requirements/UniMate-UMS-Requirement-Analysis.pdf).\r\n\r\n**Sample endpoints:**\r\n\r\n```http\r\nPOST    /api/v1/users/create-student\r\nGET     /api/v1/students\r\nGET     /api/v1/students/S-2021010001\r\nPATCH   /api/v1/students/S-2021010001\r\nDELETE  /api/v1/students/S-2021010001\r\n```\r\n\r\n\u003e **Tips:**\r\n\u003e\r\n\u003e -   All endpoints are prefixed with `/api/v1/`\r\n\u003e -   For user operations (admin, faculty, student), use the \u003cb\u003eapplication-generated user ID\u003c/b\u003e (e.g., S-2021010001), not the MongoDB ObjectId.\r\n\u003e -   For other entities (Academic Faculty, Department, etc.), use the MongoDB ObjectId (`_id`).\r\n\r\n\u003cbr\u003e\r\n\r\n## 🧪 Sample API Testing\r\n\r\n-   Use [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/) to test APIs.\r\n-   For POST/PATCH, provide the required JSON body.\r\n-   The server responds with JSON for all endpoints.\r\n\r\n\u003e **Note:**\r\n\u003e\r\n\u003e -   See [Requirement Analysis PDF](./analysis-requirements/UniMate-UMS-Requirement-Analysis.pdf) for full API route details.\r\n\u003e -   Sample payloads are available in [`server/sample`](./server/sample).\r\n\r\n\u003cbr\u003e\r\n\r\n## 🔍 Common Advanced Query Features\r\n\r\nMost GET endpoints (students, faculties, departments, courses, etc.) support:\r\n\r\n-   `searchTerm=\u003ckeyword\u003e` — partial name/code search\r\n-   `limit=\u003cnumber\u003e` — limit results per page\r\n-   `page=\u003cnumber\u003e` — pagination\r\n-   `sort=\u003cfield\u003e` — sorting\r\n-   Field-based filters (e.g., `gender=male\u0026bloodGroup=B+`)\r\n\r\nExample:\r\n\r\n```http\r\nGET   /api/v1/faculties?searchTerm=john\u0026gender=male\u0026page=2\u0026limit=10\u0026sort=name.firstName\r\n```\r\n\r\n\u003cbr\u003e\r\n\r\n## 📦 Sample Data\r\n\r\nSample `.json` data files for Student, Faculty, Admin are available in [`server/sample`](./server/sample) for testing payloads.\r\n\r\n\u003cbr\u003e\r\n\r\n## ✅ Prerequisites\r\n\r\n-   [**Node**.js](https://nodejs.org/) (v18 or higher recommended)\r\n-   [**npm**](https://www.npmjs.com/) (comes with Node.js)\r\n-   [**MongoDB**](https://www.mongodb.com/try/download/community) (local or remote)\r\n-   A [**`.env`**](./server/.env.example) file with required environment variables\r\n\r\n\u003cbr\u003e\r\n\r\n## 🔧 Installation \u0026 Running Locally\r\n\r\n### 1. Clone the repository\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/UniMate-UMS.git\r\ncd UniMate-UMS/server\r\n```\r\n\r\n### 2. Install dependencies\r\n\r\n```bash\r\nnpm install\r\n```\r\n\r\n### 3. Set up environment variables\r\n\r\n-   **Rename [`server/.env.example`](./server/.env.example) to `.env` and fill in your credentials:**\r\n\r\n    ```env\r\n    NODE_ENV=development\r\n    PORT=5000\r\n    DATABASE_URL=yourDatabaseUser\r\n    BCRYPT_SALT_ROUNDS=12\r\n    DEFAULT_PASS=ChangeMeToASecurePassword!\r\n    ```\r\n\r\n-   **Configuration Details:**\r\n\r\n    -   \u003cb\u003eNODE_ENV\u003c/b\u003e: `development` (local) or `production` (deployed)\r\n    -   \u003cb\u003ePORT\u003c/b\u003e: Port your Express app will listen on\r\n    -   \u003cb\u003eDATABASE_URL\u003c/b\u003e: MongoDB connection string (local or Atlas)\r\n    -   \u003cb\u003eBCRYPT_SALT_ROUNDS\u003c/b\u003e: Password hashing complexity (integer ≥ 4)\r\n    -   \u003cb\u003eDEFAULT_PASS\u003c/b\u003e: Default admin password (change after first login)\r\n\r\n\u003e ⚠️ \u003cb\u003eCaution:\u003c/b\u003e \u003cbr\u003e Never commit your `.env` file to version control. Keep it private and add `.env` to your `.gitignore`.\r\n\r\n### 4. Run the development server\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\n### 5. Build for production\r\n\r\n```bash\r\nnpm run build\r\nnpm run prod\r\n```\r\n\r\n\u003cbr\u003e\r\n\r\n## 🌐 Live Deployment\r\n\r\nThe API is deployed on [**_Vercel_**](https://vercel.com/) and is live at [**this following URL**](https://unimate-ums-backend.vercel.app/).\r\n\r\n\u003cbr\u003e\r\n\r\n## 🤝 Contributing\r\n\r\nHave ideas to improve this API? Found a bug? [Open an issue](https://github.com/yourusername/UniMate-UMS/issues) or submit a pull request!\r\n\r\n\u003cbr\u003e\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the \u003cb\u003eMIT License\u003c/b\u003e - see the [LICENSE](LICENSE) file for details.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanzeebul-tamim%2Funimate-ums","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftanzeebul-tamim%2Funimate-ums","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftanzeebul-tamim%2Funimate-ums/lists"}