HR Management System

A Comprehensive Human Resources Management System

Built with NestJS, MongoDB, and TypeScript

---

📋 Table of Contents

1. Project Overview
2. System Architecture
3. Team Modules
4. Technology Stack
5. Quick Start
6. Module Documentation
7. API Documentation
8. Development
9. Testing
10. Deployment
11. Contributing Teams

---

🎯 Project Overview

This is a comprehensive HR Management System designed to handle all aspects of human resources management in a modern organization. The system is built as a modular, scalable application using NestJS framework with MongoDB as the database.

Key Features

• Employee Profile Management - Complete employee data repository with change request workflows
• Organization Structure - Department and position hierarchy management
• Performance Management - Appraisal cycles, evaluations, and dispute resolution
• Time Management - Attendance tracking, shift management, and overtime handling
• Leave Management - Comprehensive leave policies, requests, and approvals
• Integration-Ready - RESTful APIs for seamless integration with payroll, recruitment, and other systems

Project Statistics

• 33+ Database Schemas - Well-designed data models with proper relationships
• 173+ API Endpoints - Comprehensive REST API coverage
• 18+ Integration Endpoints - Cross-module communication support
• 5 Core Modules - Modular architecture for maintainability
• Zero Compilation Errors - Production-ready codebase

---

🏗️ System Architecture

The HR Management System follows a modular monolith architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                     COMMON MODULE                            │
│         (Authentication, Authorization, Notifications)       │
└──────────────┬───────────────────────────────────────────────┘
               │
       ┌───────┴────────┬──────────┬───────────┬──────────┐
       │                │          │           │          │
┌──────▼──────┐  ┌─────▼─────┐ ┌─▼──────┐ ┌──▼────┐ ┌──▼────┐
│  EMPLOYEE   │  │    ORG    │ │ PERF   │ │  TIME │ │ LEAVE │
│  PROFILE    │◄─┤ STRUCTURE │ │  MGMT  │ │  MGMT │ │  MGMT │
└──┬──────┬───┘  └─┬──────┬──┘ └─┬──────┘ └───┬───┘ └───┬───┘
   │      │        │      │      │            │         │
   │      └────────┴──────┴──────┘            │         │
   │                                           │         │
   └───────────────────────────────────────────┴─────────┘
                          │
                 ┌────────▼─────────┐
                 │  EXTERNAL SYSTEMS │
                 │  (Payroll, etc.)  │
                 └───────────────────┘

Design Principles

• Modular Design - Each module is self-contained with clear boundaries
• API-First - RESTful APIs for all operations
• Data Integrity - Mongoose schemas with validation
• Audit Trail - Complete tracking of all changes
• Role-Based Access - Granular permissions control
• Integration-Ready - Designed for easy integration with other systems

---

👥 Team Modules

This project is developed by multiple teams, each responsible for specific modules:

Team Software404 ✅ MILESTONE 2 COMPLETE

Modules: Employee Profile, Organization Structure, Performance Management

📖 View Detailed Documentation →

Status: 100% Complete - Production Ready

Statistics:

• 11 Database Schemas - Fully implemented and tested
• 60+ API Endpoints - All functional with Swagger documentation
• 3 Core Modules - Fully integrated
• Zero Critical Issues - All bugs resolved

Completed Features:

1️⃣ Employee Profile Module

• ✅ Complete employee lifecycle management (CRUD)
• ✅ Self-service portal (profile viewing, contact updates, biography, photo upload)
• ✅ Change request workflow (Submit → Approve/Reject)
• ✅ Manager dashboard (team overview, statistics)
• ✅ Qualifications management (education, certifications)
• ✅ System roles and permissions
• ✅ Candidate management and conversion to employee

2️⃣ Organization Structure Module

• ✅ Department hierarchy management (CRUD)
• ✅ Position management with automatic reporting relationships
• ✅ Change request system for structural changes
• ✅ Circular dependency prevention
• ✅ Integration with Employee Profile

3️⃣ Performance Management Module

• ✅ Customizable appraisal templates with rating scales
• ✅ Cycle management (Annual, Semi-annual, Probationary, Project-based)
• ✅ Appraisal assignment and tracking
• ✅ Weighted scoring system with automatic calculation
• ✅ Dispute submission and resolution workflow
• ✅ Auto-update employee profiles with appraisal scores

Technical Achievements:

• Clean architecture (Controller → Service → Model)
• Comprehensive DTO validation with class-validator
• Full Swagger/OpenAPI documentation
• Standardized error handling
• Production-ready code quality
• All integration points functional

Key Endpoints:

Employee Profile:     /api/employee-profile/*
Organization:         /api/organization-structure/*
Performance:          /api/performance/*

Swagger Documentation: http://localhost:3000/api

---

Team D.F.J

Module: Time Management

📖 View Detailed Documentation →

• 8 Database Schemas
• 40+ API Endpoints
• 5 Implementation Phases

Key Features:

• Shift configuration and assignment
• Attendance recording (clock-in/out)
• Policy enforcement (overtime, lateness)
• Exception handling and approvals
• Payroll integration

---

Team J.M.F

Module: Leave Management

📖 View Detailed Documentation →

• 14 Database Schemas
• 75+ API Endpoints
• 3 Implementation Phases

Key Features:

• Leave policy configuration
• Vacation packages and entitlements
• Leave request workflows
• Automatic accrual and carry-forward
• Final settlement processing
• Cumulative tracking (BR 41)

---

Team git blame all.ts

Module: Payroll Configuration & Policy Setup

📖 View Detailed Documentation →

• Core payroll configuration schemas (pay grades, pay types, allowances, tax rules, insurance brackets, severance rules, company settings)
• Integration-first dummy responses unblock payroll execution, tracking, and finance teams
• Approval workflows ensure every configuration change is auditable

Key Features:

• Salary structure templates aligned with organizational grades and contract types
• Legal and insurance rule modeling that matches milestone scope
• Company-wide payroll settings plus signing bonus and severance configurations

---

Team Dynamic Trio

Module: Payroll Processing & Execution

📖 View Detailed Documentation →

• Manages payroll runs from initiation through draft generation, approvals, freeze, and payment tracking
• Stores detailed payroll employee records (earnings, deductions, benefits, overtime, exception logs)
• Provides the run/record APIs that downstream systems call during payroll cycles

Key Features:

• Supports regular, off-cycle, and refund payroll runs
• Exception workflows for missing data, salary spikes, and bank issues
• State-machine style status progression (Draft → Paid) with audit history

---

Team SMH

Module: Payroll Tracking, Transparency & Self-Service

📖 View Detailed Documentation →

• 30+ endpoints across payslips, payroll disputes, reimbursements, refunds, and reporting
• Five submodules (Payslips, Expense Claims, Disputes, Refunds, Reports) powering employee self-service
• Dummy datasets keep integrations with payroll execution, leave, and time-management modules unblocked

Key Features:

• Employee-facing payroll visibility with filtering and export-friendly payloads
• Claim/dispute workflows capturing action history for specialists, managers, and finance
• Departmental and finance reporting APIs for month-end and year-end reviews

---

Team L.Y.M

Modules: Recruitment, Onboarding & Offboarding

📖 View Detailed Documentation →

• 27 schemas and 60+ endpoints covering requisitions, candidates, onboarding tasks, clearances, and final settlements
• Integrations trigger onboarding after offer acceptance and finalize settlements during offboarding
• Sub-readmes document recruitment analytics, onboarding checklists, and clearance/final-pay flows

Key Features:

• Recruitment pipelines with templates, interviews, offers, and GDPR-compliant consent tracking
• Onboarding orchestration for tasks, documents, access provisioning, and payroll initiation
• Offboarding workflows handling notices, asset returns, department clearances, and final settlements

---

💻 Technology Stack

Backend

• Framework: NestJS 11.x
• Runtime: Node.js 18+
• Language: TypeScript 5.7
• Database: MongoDB 5.x with Mongoose ODM

Core Libraries

• Validation: class-validator, class-transformer
• Authentication: JWT (Passport.js)
• Configuration: @nestjs/config (dotenv)
• API Documentation: Swagger/OpenAPI (planned)

Development Tools

• Linting: ESLint with TypeScript support
• Formatting: Prettier
• Testing: Jest (unit & e2e)
• Build: NestJS CLI

---

🚀 Quick Start

Prerequisites

• Node.js v18 or higher
• MongoDB v5 or higher
• npm or yarn package manager

Installation

# Clone the repository
git clone <repository-url>
cd HR_Main

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env
# Edit .env with your configuration

# Start MongoDB (if running locally)
mongod --dbpath /path/to/data

# Run the application
npm run start:dev

Verify Installation

# Check if server is running
curl http://localhost:3000

# Should return: "Hello World!"

---

📚 Module Documentation

Each module has comprehensive documentation covering schemas, endpoints, business rules, and integration points:

Module	Team	Documentation	Status
Common Module	All Teams	README-Software404.md	✅ Complete
Employee Profile	Software404	README-Software404.md	✅ Complete
Organization Structure	Software404	README-Software404.md	✅ Complete
Performance Management	Software404	README-Software404.md	✅ Complete
Time Management	D.F.J	README-DFJ.md	✅ Complete
Leave Management	J.M.F	README-JMF.md	✅ Complete
Payroll Configuration	git blame all.ts	README-git blame all.ts.md	✅ Complete
Payroll Processing	Dynamic Trio	README-dynaic-trio.md	✅ Complete
Payroll Tracking & Self-Service	SMH	README-SMH.md	✅ Complete
Recruitment Lifecycle	L.Y.M	README-LYM.md	✅ Complete

---

🔌 API Documentation

Base URL

http://localhost:3000

Module Endpoints

Module	Base Path	Endpoints	Integration Endpoints
Employee Profile	/employee-profile	20	4
Organization Structure	/org-structure	17	5
Performance	/performance	21	4
Time Management	/time-management	40+	3+
Leave Management	/leave-management	75+	4

Quick API Test

# Test Employee Profile integration
curl http://localhost:3000/employee-profile/EMP001/appraisals

# Test Organization Structure integration
curl http://localhost:3000/org-structure/integration/pay-grades

# Test Performance integration
curl http://localhost:3000/performance/integration/final-appraisal/EMP001

# Test Time Management integration
curl "http://localhost:3000/time-management/integration/payroll/EMP001?startDate=2024-12-01&endDate=2024-12-31"

# Test Leave Management integration
curl http://localhost:3000/leave-management/integration/payroll/EMP001

---

🛠️ Development

Available Scripts

# Development
npm run start          # Start the application
npm run start:dev      # Start with hot-reload (watch mode)
npm run start:debug    # Start in debug mode

# Build
npm run build          # Build for production

# Testing
npm run test           # Run unit tests
npm run test:watch     # Run tests in watch mode
npm run test:cov       # Run tests with coverage
npm run test:e2e       # Run end-to-end tests

# Linting & Formatting
npm run lint           # Run ESLint
npm run format         # Format code with Prettier

Project Structure

src/
├── common/                 # Shared resources
│   ├── decorators/        # Custom decorators (roles, etc.)
│   ├── guards/            # Auth guards (JWT, roles)
│   └── schemas/           # Common schemas (User, Notification)
│
├── modules/               # Feature modules
│   ├── employee-profile/  # Employee data management
│   ├── org-structure/     # Organization hierarchy
│   ├── performance/       # Performance appraisals
│   ├── time-management/   # Attendance & shifts
│   └── leave-management/  # Leave policies & requests
│
├── app.module.ts          # Root module
└── main.ts                # Application entry point

---

🧪 Testing

Test Coverage

Each module includes:

• Unit Tests - Service and controller testing
• Integration Tests - Cross-module communication
• E2E Tests - Full API workflow testing

Running Tests

# Run all unit tests
npm run test

# Run specific module tests
npm run test -- employee-profile

# Run with coverage
npm run test:cov

# Run e2e tests
npm run test:e2e

---

🚀 Deployment

Environment Configuration

Create a .env file in the root directory:

# Application
NODE_ENV=production
PORT=3000

# Database
MONGODB_URI=mongodb://localhost:27017/hr_system

# JWT Configuration
JWT_SECRET=your-secret-key
JWT_EXPIRATION=7d

# CORS
CORS_ORIGIN=https://your-frontend-domain.com

Production Build

# Build the application
npm run build

# Start production server
npm run start:prod

---

📝 License

This project is developed as part of an academic initiative.

---

🔗 Additional Resources

• Requirements Documentation: See /docs folder for detailed CSV requirements
• API Testing: Use Postman or similar tools with the endpoint examples above
• MongoDB Compass: Use for database visualization and queries
• NestJS Documentation: https://docs.nestjs.com

---

📞 Support

For questions, issues, or feature requests:

1. Check the module-specific documentation first
2. Review the requirements in /docs folder
3. Contact the responsible team (see Contributing Teams section)

---

Built with ❤️ using NestJS