Software404 Team - Core HR Modules

Team: Software404
Modules: Employee Profile, Organization Structure, Performance Management
Status: ✅ COMPLETE - Production Ready
Last Updated: November 29, 2025

Overview
Team Members
Module 1: Employee Profile
Module 2: Organization Structure
Module 3: Performance Management
Integration Architecture
Testing Guide
Deployment

Overview

The Software404 team has delivered the core foundation of the HR Management System, providing essential functionality for employee management, organizational hierarchy, and performance evaluation. These three modules form the backbone of the entire HR system and are tightly integrated to provide a seamless experience.

System Architecture

┌─────────────────────────────────────────────────────────┐
│                  HR System Gateway                       │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌──────▼───────┐  ┌────────▼────────┐
│   Employee     │  │ Organization │  │  Performance    │
│    Profile     │◄─┤  Structure   │◄─┤   Management    │
│   (Seif)       │  │  (Marwan)    │  │   (Sherif)      │
└────────────────┘  └──────────────┘  └─────────────────┘

Key Statistics

Module	Schemas	Endpoints	DTOs	Features
Employee Profile	6	30+	13	Employee lifecycle, self-service, change requests
Organization Structure	6	15+	7	Departments, positions, hierarchy, change tracking
Performance Management	5	17+	6	Templates, cycles, appraisals, disputes
Total	17	62+	26	Complete Core HR System

Team Members

Member	Module	Primary Responsibilities
Seif	Employee Profile	Employee CRUD, self-service portal, candidate management, change requests
Marwan	Organization Structure	Department hierarchy, position management, reporting relationships
Sherif	Performance Management	Appraisal templates, cycles, scoring, dispute resolution

Module 1: Employee Profile

Developer: Seif
Base URL: /api/employee-profile

Overview

The Employee Profile module manages the complete employee lifecycle from candidate to active employee to termination. It provides self-service capabilities, change request workflows, and integration points for all other HR modules.

Database Schemas (6 Schemas)

1. Employee Profile Schema

File: models/employee-profile.schema.ts

Core employee information extending the base user profile.

Key Fields:

employeeNumber - Unique employee identifier (required, unique)
dateOfHire - Employment start date
workEmail - Corporate email address
biography - Employee bio/description
contractStartDate, contractEndDate - Contract period
contractType - Full-Time, Part-Time, Contract, Intern
workType - On-Site, Remote, Hybrid
status - Active, On Leave, Suspended, Terminated
statusEffectiveFrom - Status change date
primaryPositionId - Reference to Position
primaryDepartmentId - Reference to Department
supervisorPositionId - Manager's position
payGradeId - Salary grade reference
Performance Integration:
- lastAppraisalRecordId - Latest appraisal
- lastAppraisalCycleId - Latest cycle
- lastAppraisalTemplateId - Template used
- lastAppraisalDate - When evaluated
- lastAppraisalScore - Numeric score
- lastAppraisalRatingLabel - Rating text
- lastAppraisalScaleType - Scale type used
- lastDevelopmentPlanSummary - Development notes

Business Rules:

Employee number must be unique
Status defaults to Active
Automatically integrates with performance appraisals
Linked to organizational structure

2. User Profile Base Schema

File: models/user-schema.ts

Base profile shared by employees and candidates.

Key Fields:

firstName, middleName, lastName - Name fields
nationalId - Government ID (unique)
dateOfBirth - Birth date
phoneNumber - Contact number
email - Email address
address - Physical address
photoUrl - Profile picture

Business Rules:

National ID must be unique across system
Used as base class for Employee and Candidate

3. Candidate Schema

File: models/candidate.schema.ts

Job applicants in recruitment pipeline.

Key Fields:

candidateNumber - Unique candidate identifier
departmentId - Applied department
positionId - Applied position
applicationDate - Application submission date
status - Applied, Screening, Interview, Offer, Hired, Rejected
resumeUrl - Resume document link
notes - Recruitment notes

Business Rules:

Can be converted to employee upon hiring
Inherits from UserProfileBase
Status tracks recruitment pipeline stage

4. Employee System Role Schema

File: models/employee-system-role.schema.ts

Role-based access control assignments.

Key Fields:

employeeId - Employee reference
role - System role (HR Manager, Department Manager, etc.)
assignedBy - Who granted the role
assignedAt - When granted
effectiveFrom, effectiveTo - Role validity period
isActive - Active status

Business Rules:

Multiple roles can be assigned to one employee
Time-bound role assignments supported
Tracks role assignment history

5. Change Request Schema

File: models/ep-change-request.schema.ts

Workflow for employee data changes.

Key Fields:

requestNumber - Unique request ID (auto-generated)
employeeId - Employee requesting change
requestedBy - Who submitted (employee or HR)
changeType - Personal Info, Contact, Employment, Position
currentData - Current values
requestedData - Proposed changes
reason - Justification
status - Pending, Approved, Rejected, Cancelled
reviewedBy - Approver
reviewedAt - Approval date
reviewNotes - Approval comments

Business Rules:

Critical data changes require approval
Audit trail maintained
Can be cancelled before review

6. Qualification Schema

File: models/qualification.schema.ts

Education and certifications.

Key Fields:

employeeId - Employee reference
type - Degree, Certificate, License
institution - Issuing organization
fieldOfStudy - Subject area
level - Bachelors, Masters, PhD, etc.
dateObtained - Completion date
expiryDate - For licenses/certifications
verificationStatus - Pending, Verified, Rejected

Business Rules:

Multiple qualifications per employee
Expiry tracking for certifications
Verification workflow

API Endpoints (30+ Endpoints)

Self-Service Portal

Method	Endpoint	Description	Roles
GET	`/me/profile`	Get own profile	All Authenticated
PATCH	`/me/contact`	Update contact info	Department Employee
PATCH	`/me/biography`	Update biography	Department Employee
POST	`/me/photo`	Upload profile photo	Department Employee

Change Request Management

Method	Endpoint	Description	Roles
POST	`/change-requests`	Create change request	Department Employee, HR Employee
GET	`/change-requests`	List all requests	HR Manager, HR Employee
GET	`/change-requests/:id`	Get request details	HR Manager, HR Employee, Request Owner
PATCH	`/change-requests/:id/approve`	Approve request	HR Manager
PATCH	`/change-requests/:id/reject`	Reject request	HR Manager
PATCH	`/change-requests/:id/cancel`	Cancel request	Request Owner

Team Management

Method	Endpoint	Description	Roles
GET	`/team/members`	List team members	Department Manager
GET	`/team/statistics`	Team statistics	Department Manager

Candidate Management

Method	Endpoint	Description	Roles
POST	`/candidates`	Create candidate	HR Manager, HR Employee, Recruiter
GET	`/candidates`	List all candidates	HR Manager, HR Employee, Recruiter
PATCH	`/candidates/:id/status`	Update candidate status	HR Manager, HR Employee, Recruiter
POST	`/candidates/:id/convert`	Convert to employee	HR Manager

Employee Management

Method	Endpoint	Description	Roles
POST	`/search`	Search employees	HR Manager, HR Employee, Department Manager
POST	`/`	Create employee	HR Manager
GET	`/`	List all employees	HR Manager, HR Employee
GET	`/:id`	Get employee by ID	HR Manager, HR Employee, Department Manager
PATCH	`/:id`	Update employee	HR Manager
PATCH	`/:id/deactivate`	Deactivate employee	HR Manager

Qualification Management

Method	Endpoint	Description	Roles
POST	`/qualifications`	Add qualification	Department Employee, HR Employee
GET	`/qualifications`	List qualifications	Department Employee, HR Employee
PATCH	`/qualifications/:id`	Update qualification	HR Manager, HR Employee
DELETE	`/qualifications/:id`	Remove qualification	HR Manager

System Role Management

Method	Endpoint	Description	Roles
POST	`/:id/roles`	Assign system role	HR Manager, System Admin
DELETE	`/:id/roles/:roleId`	Remove system role	HR Manager, System Admin

Business Rules Implementation

✅ BR 1: Employee number must be unique and auto-generated
✅ BR 2: National ID must be unique across employees and candidates
✅ BR 3: Self-service updates allowed for non-critical fields
✅ BR 4: Critical changes require HR approval via change requests
✅ BR 5: Profile photo upload with validation
✅ BR 6: Manager can view team members and statistics
✅ BR 7: Candidate to employee conversion preserves data
✅ BR 8: Qualifications support expiry tracking
✅ BR 9: System roles support time-bound assignments
✅ BR 10: Employee status change tracking with effective dates
✅ BR 11: Integration with performance appraisals (auto-update scores)
✅ BR 12: Integration with organization structure (position/department links)

Module 2: Organization Structure

Developer: Marwan
Base URL: /api/organization-structure

Overview

The Organization Structure module manages the company's hierarchical structure, including departments, positions, and reporting relationships. It provides automatic resolution of reporting lines and change tracking for structural modifications.

Database Schemas (6 Schemas)

1. Department Schema

File: models/department.schema.ts

Organizational departments.

Key Fields:

code - Unique department code (required, unique)
name - Department name
description - Purpose/description
headPositionId - Department head position
isActive - Active status

Business Rules:

Department code must be unique
Can have one designated head position
Used for organizational hierarchy

2. Position Schema

File: models/position.schema.ts

Job positions within departments.

Key Fields:

code - Unique position code (required, unique)
title - Position title
description - Role description
departmentId - Parent department (required)
reportsToPositionId - Manager position (auto-resolved)
isActive - Active status

Business Rules:

Position code must be unique
Must belong to a department
Automatic Reporting: reportsToPositionId automatically set to department head
Pre-save and pre-update hooks handle automatic resolution
Prevents circular reporting relationships

Technical Highlights:

Mongoose pre-save hooks for automatic field population
Intelligent department head resolution
Workaround for _id generation timing issues

3. Position Assignment Schema

File: models/position-assignment.schema.ts

Employee position assignments (history).

Key Fields:

employeeId - Employee reference
positionId - Position reference
startDate - Assignment start
endDate - Assignment end (optional)
isPrimary - Primary position flag
notes - Assignment notes

Business Rules:

Tracks position history
Supports multiple concurrent positions
One primary position per employee

4. Structure Change Request Schema

File: models/structure-change-request.schema.ts

Workflow for organizational changes.

Key Fields:

requestNumber - Unique request ID (auto-generated)
requestedBy - Requester employee ID
changeType - Create Department, Update Department, Create Position, etc.
entityType - Department or Position
entityId - Affected entity (for updates)
currentData - Current state
proposedData - Proposed changes
justification - Change reason
status - Pending, Approved, Rejected
reviewedBy - Approver
reviewedAt - Review date
implementedAt - Implementation date

Business Rules:

All structural changes require approval
Complete audit trail
Changes implemented only after approval

5. Structure Approval Schema

File: models/structure-approval.schema.ts

Multi-level approval workflow.

Key Fields:

changeRequestId - Related change request
approverPositionId - Approver's position
level - Approval level (1, 2, 3...)
status - Pending, Approved, Rejected
comments - Approval notes
decidedAt - Decision date

Business Rules:

Supports multi-level approval chains
Each level must approve before implementation
Tracks approval hierarchy

6. Structure Change Log Schema

File: models/structure-change-log.schema.ts

Immutable audit trail of changes.

Key Fields:

changeRequestId - Related request
entityType - Department or Position
entityId - Affected entity
changeType - Create, Update, Delete
previousData - Before state
newData - After state
changedBy - Who made change
changedAt - When changed

Business Rules:

Immutable log entries
Complete history of structural changes
Used for auditing and reporting

API Endpoints (15+ Endpoints)

Department Management

Method	Endpoint	Description	Roles
POST	`/departments`	Create department	HR Manager, System Admin
GET	`/departments`	List all departments	HR Manager, HR Employee, Department Manager
GET	`/departments/:id`	Get department by ID	HR Manager, HR Employee, Department Manager
PATCH	`/departments/:id`	Update department	HR Manager, System Admin
DELETE	`/departments/:id`	Delete department	System Admin
GET	`/departments/:id/positions`	Get department positions	HR Manager, HR Employee, Department Manager

Position Management

Method	Endpoint	Description	Roles
POST	`/positions`	Create position	HR Manager, System Admin
GET	`/positions`	List all positions	HR Manager, HR Employee, Department Manager
GET	`/positions/:id`	Get position by ID	HR Manager, HR Employee, Department Manager
PATCH	`/positions/:id`	Update position	HR Manager, System Admin
DELETE	`/positions/:id`	Delete position	System Admin

Change Request Management

Method	Endpoint	Description	Roles
POST	`/change-requests`	Create change request	HR Employee, Department Manager
GET	`/change-requests`	List all requests	HR Manager, HR Employee
PATCH	`/change-requests/:id/approve`	Approve request	HR Manager, System Admin
PATCH	`/change-requests/:id/reject`	Reject request	HR Manager, System Admin

Business Rules Implementation

✅ BR 1: Department code must be unique
✅ BR 2: Position code must be unique
✅ BR 3: Position must belong to a department
✅ BR 4: Automatic reporting relationship resolution
✅ BR 5: reportsToPositionId set to department head automatically
✅ BR 6: Circular reporting relationship prevention
✅ BR 7: All structural changes require approval
✅ BR 8: Complete change audit trail
✅ BR 9: Multi-level approval workflow supported
✅ BR 10: Position assignment history tracking
✅ BR 11: Department head can be designated
✅ BR 12: Integration with employee profile for assignments

Module 3: Performance Management

Developer: Sherif
Base URL: /api/performance

Overview

The Performance Management module provides comprehensive employee appraisal functionality, including customizable templates, appraisal cycles, weighted scoring, and dispute resolution. It automatically integrates with the Employee Profile module to update appraisal scores.

Database Schemas (5 Schemas)

1. Appraisal Template Schema

File: models/appraisal-template.schema.ts

Reusable appraisal templates with criteria and rating scales.

Key Fields:

name - Template name (unique)
description - Template purpose
templateType - Annual, Semi-Annual, Probationary, Project-Based, Ad-Hoc
ratingScale - Rating scale definition
- type - THREE_POINT, FIVE_POINT, TEN_POINT
- min, max - Score range
- step - Increment
- labels - Rating labels (e.g., ["Poor", "Fair", "Good", "Excellent"])
criteria - Array of evaluation criteria
- key - Unique criterion identifier
- title - Criterion name
- details - Description
- weight - Weight percentage (0-100)
- maxScore - Maximum score
- required - Required field flag
instructions - Evaluation instructions
applicableDepartmentIds - Applicable departments
applicablePositionIds - Applicable positions
isActive - Active status

Business Rules:

Template names must be unique
Criteria weights should sum to 100%
Supports multiple rating scale types
Can be department or position-specific

2. Appraisal Cycle Schema

File: models/appraisal-cycle.schema.ts

Appraisal periods and schedules.

Key Fields:

name - Cycle name (unique, e.g., "2025 Annual Review")
description - Cycle description
cycleType - Annual, Semi-Annual, Probationary, Project-Based, Ad-Hoc
startDate - Cycle start
endDate - Cycle end
managerDueDate - Manager review deadline
employeeAcknowledgementDueDate - Employee acknowledgement deadline
templateAssignments - Array of template assignments
- templateId - Template reference
- departmentIds - Applicable departments
status - Planned, Active, Closed, Archived
publishedAt - When cycle published
closedAt - When cycle closed
archivedAt - When cycle archived

Business Rules:

Cycle name must be unique
Templates assigned to specific departments
Status workflow: Planned → Active → Closed → Archived
Deadlines enforced for managers and employees

3. Appraisal Assignment Schema

File: models/appraisal-assignment.schema.ts

Links employees to templates and cycles.

Key Fields:

employeeId - Employee being evaluated
managerId - Evaluating manager
cycleId - Appraisal cycle
templateId - Template used
assignedAt - Assignment date
dueDate - Completion deadline
status - Not Started, In Progress, Completed

Business Rules:

One assignment per employee per cycle
Manager must be assigned
Status tracks progress

4. Appraisal Record Schema

File: models/appraisal-record.schema.ts

Completed appraisals with scores.

Key Fields:

assignmentId - Related assignment
employeeId - Employee evaluated
managerId - Evaluating manager
cycleId - Appraisal cycle
templateId - Template used
criteriaScores - Array of criterion scores
- criterionKey - Criterion identifier
- score - Score given
- comments - Evaluator comments
totalScore - Calculated weighted total
ratingLabel - Final rating label
managerComments - Overall manager feedback
employeeComments - Employee response
developmentPlan - Development recommendations
status - Draft, Submitted, Acknowledged, Disputed
submittedAt - Submission date
acknowledgedAt - Employee acknowledgement date

Business Rules:

Total score calculated from weighted criteria
Employee must acknowledge review
Can be disputed by employee
Auto-updates Employee Profile with appraisal scores

5. Appraisal Dispute Schema

File: models/appraisal-dispute.schema.ts

Employee disputes of appraisal results.

Key Fields:

appraisalRecordId - Disputed appraisal
employeeId - Employee disputing
reason - Dispute reason
details - Detailed explanation
raisedAt - When raised
status - Pending, Under Review, Resolved, Rejected
reviewedBy - HR reviewer
resolution - Resolution details
resolvedAt - Resolution date

Business Rules:

Can only dispute acknowledged appraisals
HR reviews and resolves
Resolution tracked with comments

API Endpoints (17+ Endpoints)

Template Management

Method	Endpoint	Description	Roles
POST	`/templates`	Create template	HR Manager, System Admin
GET	`/templates`	List all templates	HR Manager, HR Employee
GET	`/templates/:id`	Get template by ID	HR Manager, HR Employee
PATCH	`/templates/:id`	Update template	HR Manager, System Admin
DELETE	`/templates/:id`	Delete template	System Admin

Cycle Management

Method	Endpoint	Description	Roles
POST	`/cycles`	Create cycle	HR Manager, System Admin
GET	`/cycles`	List all cycles	HR Manager, HR Employee, Department Manager
GET	`/cycles/:id`	Get cycle by ID	HR Manager, HR Employee, Department Manager
PATCH	`/cycles/:id`	Update cycle	HR Manager, System Admin

Appraisal Management

Method	Endpoint	Description	Roles
POST	`/appraisals`	Create/assign appraisal	HR Manager, Department Manager
GET	`/appraisals/my-appraisals`	Get own appraisals	Department Employee
GET	`/appraisals/:id`	Get appraisal by ID	HR Manager, HR Employee, Appraisee, Manager
POST	`/appraisals/:id/feedback`	Submit manager feedback	Department Manager
POST	`/appraisals/:id/self-assessment`	Submit self-assessment	Department Employee
PATCH	`/appraisals/:id/finalize`	Finalize appraisal	Department Manager

Dispute Management

Method	Endpoint	Description	Roles
POST	`/appraisals/:id/dispute`	Raise dispute	Department Employee
PATCH	`/disputes/:id/resolve`	Resolve dispute	HR Manager

Business Rules Implementation

✅ BR 1: Template names must be unique
✅ BR 2: Criteria weights sum to 100%
✅ BR 3: Multiple rating scale types supported
✅ BR 4: Cycle names must be unique
✅ BR 5: Templates assigned to departments within cycles
✅ BR 6: Status workflow enforced (Planned → Active → Closed → Archived)
✅ BR 7: One assignment per employee per cycle
✅ BR 8: Total score calculated from weighted criteria
✅ BR 9: Employee must acknowledge appraisal
✅ BR 10: Auto-update Employee Profile with scores
✅ BR 11: Disputes can only be raised on acknowledged appraisals
✅ BR 12: HR reviews and resolves disputes
✅ BR 13: Manager feedback required before finalization
✅ BR 14: Self-assessment optional
✅ BR 15: Development plan creation supported

Integration Architecture

Cross-Module Dependencies

┌────────────────────────────────────────────────────────┐
│                  Employee Profile                       │
│  - Employee data                                        │
│  - Candidate records                                    │
│  - System roles                                         │
└──────────┬──────────────────────────────┬──────────────┘
           │                              │
           │ References                   │ Updates
           ▼                              ▼
┌──────────────────────┐     ┌───────────────────────────┐
│ Organization         │     │   Performance             │
│ Structure            │     │   Management              │
│ - Departments        │────►│ - Templates               │
│ - Positions          │     │ - Cycles                  │
│ - Reporting lines    │     │ - Appraisals              │
└──────────────────────┘     └───────────────────────────┘

Integration Points

Employee Profile → Organization Structure

Employee references primaryDepartmentId and primaryPositionId
Position assignments tracked in PositionAssignment
Manager hierarchy through supervisorPositionId

Employee Profile → Performance Management

Appraisal records reference employeeId and managerId
Employee Profile auto-updated with:
- lastAppraisalScore
- lastAppraisalRatingLabel
- lastAppraisalDate
- lastAppraisalCycleId
- lastAppraisalTemplateId
- lastAppraisalScaleType

Organization Structure → Performance Management

Templates can be department-specific (applicableDepartmentIds)
Templates can be position-specific (applicablePositionIds)
Cycles assign templates to departments (templateAssignments)

Testing Guide

Setup Test Environment

# Install dependencies
npm install

# Start MongoDB
# Ensure MongoDB is running on localhost:27017

# Start application in development mode
npm run start:dev

Testing Workflow

1. Organization Structure Setup

Step 1.1: Create Department

POST http://localhost:3000/api/organization-structure/departments
{
  "code": "ENG",
  "name": "Engineering",
  "description": "Software Engineering Department"
}

Step 1.2: Create Position

POST http://localhost:3000/api/organization-structure/positions
{
  "code": "ENG-MGR",
  "title": "Engineering Manager",
  "departmentId": "<department_id>"
}

Step 1.3: Update Department Head

PATCH http://localhost:3000/api/organization-structure/departments/<department_id>
{
  "headPositionId": "<position_id>"
}

2. Employee Creation

Step 2.1: Create Manager Employee

POST http://localhost:3000/api/employee-profile
{
  "firstName": "John",
  "lastName": "Smith",
  "nationalId": "12345678901234",
  "email": "john.smith@company.com",
  "employeeNumber": "EMP001",
  "dateOfHire": "2025-01-01",
  "primaryDepartmentId": "<department_id>",
  "primaryPositionId": "<manager_position_id>"
}

Step 2.2: Create Team Member Employee

POST http://localhost:3000/api/employee-profile
{
  "firstName": "Jane",
  "lastName": "Doe",
  "nationalId": "12345678901235",
  "email": "jane.doe@company.com",
  "employeeNumber": "EMP002",
  "dateOfHire": "2025-01-15",
  "primaryDepartmentId": "<department_id>",
  "primaryPositionId": "<team_member_position_id>",
  "supervisorPositionId": "<manager_position_id>"
}

3. Performance Appraisal Flow

Step 3.1: Create Template

POST http://localhost:3000/api/performance/templates
{
  "name": "Annual Review 2025",
  "templateType": "ANNUAL",
  "ratingScale": {
    "type": "FIVE_POINT",
    "min": 1,
    "max": 5,
    "step": 1,
    "labels": ["Poor", "Below Average", "Average", "Good", "Excellent"]
  },
  "criteria": [
    {
      "key": "job_knowledge",
      "title": "Job Knowledge",
      "details": "Understanding of role and responsibilities",
      "weight": 30,
      "maxScore": 5,
      "required": true
    },
    {
      "key": "quality_of_work",
      "title": "Quality of Work",
      "details": "Accuracy and thoroughness",
      "weight": 40,
      "maxScore": 5,
      "required": true
    },
    {
      "key": "teamwork",
      "title": "Teamwork",
      "details": "Collaboration and communication",
      "weight": 30,
      "maxScore": 5,
      "required": true
    }
  ],
  "applicableDepartmentIds": ["<department_id>"]
}

Step 3.2: Create Cycle

POST http://localhost:3000/api/performance/cycles
{
  "name": "2025 Annual Performance Review",
  "cycleType": "ANNUAL",
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "managerDueDate": "2025-12-15",
  "employeeAcknowledgementDueDate": "2025-12-31",
  "templateAssignments": [
    {
      "templateId": "<template_id>",
      "departmentIds": ["<department_id>"]
    }
  ],
  "status": "ACTIVE"
}

Step 3.3: Assign Appraisal

POST http://localhost:3000/api/performance/appraisals
{
  "employeeId": "<employee_id>",
  "managerId": "<manager_id>",
  "cycleId": "<cycle_id>",
  "templateId": "<template_id>",
  "dueDate": "2025-12-15"
}

Step 3.4: Submit Manager Feedback

POST http://localhost:3000/api/performance/appraisals/<appraisal_id>/feedback
{
  "criteriaScores": [
    {
      "criterionKey": "job_knowledge",
      "score": 4,
      "comments": "Strong understanding of responsibilities"
    },
    {
      "criterionKey": "quality_of_work",
      "score": 5,
      "comments": "Consistently delivers high-quality work"
    },
    {
      "criterionKey": "teamwork",
      "score": 4,
      "comments": "Great team player"
    }
  ],
  "managerComments": "Excellent performance this year",
  "developmentPlan": "Continue to develop leadership skills"
}

Step 3.5: Finalize Appraisal

PATCH http://localhost:3000/api/performance/appraisals/<appraisal_id>/finalize

Step 3.6: Verify Employee Profile Update

GET http://localhost:3000/api/employee-profile/<employee_id>
# Check lastAppraisalScore, lastAppraisalRatingLabel, etc.

4. Self-Service Testing

Step 4.1: View Own Profile

GET http://localhost:3000/api/employee-profile/me/profile
# Requires authentication JWT token

Step 4.2: Update Contact Info

PATCH http://localhost:3000/api/employee-profile/me/contact
{
  "phoneNumber": "+20123456789",
  "email": "new.email@company.com"
}

Step 4.3: Create Change Request

POST http://localhost:3000/api/employee-profile/change-requests
{
  "changeType": "PERSONAL_INFO",
  "requestedData": {
    "address": "123 New Street, Cairo, Egypt"
  },
  "reason": "Moved to new residence"
}

Deployment

Environment Configuration

Required Environment Variables:

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

# Server
PORT=3000
NODE_ENV=production

# JWT (if authentication is enabled)
JWT_SECRET=your-secret-key
JWT_EXPIRATION=1d

# File Upload (if using file storage)
UPLOAD_PATH=/uploads
MAX_FILE_SIZE=5242880

Production Build

# Build the application
npm run build

# Run production server
npm run start:prod

Docker Deployment

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist

EXPOSE 3000

CMD ["node", "dist/main"]

Health Check

# System health endpoint
GET http://localhost:3000/

Response:
{
  "message": "HR System API",
  "version": "1.0.0",
  "status": "ok",
  "modules": {
    "employeeProfile": "/api/employee-profile",
    "organizationStructure": "/api/organization-structure",
    "performance": "/api/performance",
    ...
  }
}

API Documentation

Swagger UI: http://localhost:3000/api

All endpoints are documented with:

Request/response schemas
Role-based access indicators
Example payloads
Error responses

Statistics Summary

Metric	Count
Total Schemas	17
Total Endpoints	62+
Total DTOs	26+
Supported Roles	8 (System Admin, HR Manager, HR Employee, Department Manager, Department Employee, Recruiter, Job Candidate, Payroll Admin)
Business Rules	38+
Integration Points	10+

Team Contact

Team: Software404
Status: Production Ready ✅
Completion Date: November 24, 2025

Team Members

Seif - Employee Profile Module
Marwan - Organization Structure Module
Sherif - Performance Management Module

Last Updated: November 29, 2025
Version: 2.0 (Updated Structure Documentation)

FilesExpand file tree

README-Software404.md

Latest commit

History

README-Software404.md

File metadata and controls

Software404 Team - Core HR Modules

Table of Contents

Overview

System Architecture

Key Statistics

Team Members

Module 1: Employee Profile

Overview

Database Schemas (6 Schemas)

1. Employee Profile Schema

2. User Profile Base Schema

3. Candidate Schema

4. Employee System Role Schema

5. Change Request Schema

6. Qualification Schema

API Endpoints (30+ Endpoints)

Self-Service Portal

Change Request Management

Team Management

Candidate Management

Employee Management

Qualification Management

System Role Management

Business Rules Implementation

Module 2: Organization Structure

Overview

Database Schemas (6 Schemas)

1. Department Schema

2. Position Schema

3. Position Assignment Schema

4. Structure Change Request Schema

5. Structure Approval Schema

6. Structure Change Log Schema

API Endpoints (15+ Endpoints)

Department Management

Position Management

Change Request Management

Business Rules Implementation

Module 3: Performance Management

Overview

Database Schemas (5 Schemas)

1. Appraisal Template Schema

2. Appraisal Cycle Schema

3. Appraisal Assignment Schema

4. Appraisal Record Schema

5. Appraisal Dispute Schema

API Endpoints (17+ Endpoints)

Template Management

Cycle Management

Appraisal Management

Dispute Management

Business Rules Implementation

Integration Architecture

Cross-Module Dependencies

Integration Points

Employee Profile → Organization Structure

Employee Profile → Performance Management

Organization Structure → Performance Management

Testing Guide

Setup Test Environment

Testing Workflow

1. Organization Structure Setup

2. Employee Creation

3. Performance Appraisal Flow

4. Self-Service Testing

Deployment

Environment Configuration

Production Build

Docker Deployment

Health Check

API Documentation

Statistics Summary

Team Contact

Team Members