IRC Employee Management System

A lightweight, role‑based employee management system designed for organizations with a Global Admin and fixed Province Admins.
The system provides a clean separation of access, scoped data visibility, and a simple front‑end flow.

📸 Screenshots

Below are some screenshots of the IRC Employee Management System in action:

Login Page

Global Admin Dashboard

Province List

Province Dashboard

Employee List

Employee Details

Edit Employee Dialog

New Employee Form

Performance Lock Warning

📦 Repository layout

The project is organized as a pnpm workspace with two sub‑projects:

.
├── client/                 # React + Vite front‑end
│   ├── public/
│   ├── src/
│   ├── package.json
│   └── …
├── server/                 # Express + TypeORM back‑end
│   ├── src/
│   ├── jest.config.js
│   └── …
├── PERFORMANCE_LOCK_*.md   # design notes for the performance‑lock feature
├── routing.md              # api routing notes
└── README.md               # you are here

�️ Tech Stack

Backend

Node.js + Express + TypeScript
MongoDB with TypeORM
Session-based authentication
Jest for unit/integration tests

Frontend

React 18 + TypeScript + Vite
Material-UI (MUI) v5
React Router + Axios
ESLint/Prettier configured via eslint.config.js

🔧 Getting started

Prerequisites

Node.js 18+ (or LTS)
pnpm (see https://pnpm.io/)
MongoDB instance (local or remote)

Installation

Clone the repository and install dependencies from the root:

git clone <repo-url>
cd IRC-StaffSystem
pnpm install

This will install packages for both client and server.

Environment

Create a .env file in server/ with at least:

PORT=4000
MONGO_URI=mongodb://localhost:27017/irc-staff
SESSION_SECRET=super-secret

The client does not require environment variables for basic development; see client/vite.config.ts for the few that exist (VITE_API_BASE).

Running the server

cd server
pnpm dev          # ts-node‑dev / nodemon – watches files
# or to build & start
pnpm build
pnpm start

The server listens on http://localhost:4000 by default.

Running the client

cd client
pnpm dev

Open http://localhost:5173 (or the port printed by Vite).

Running both

From the repo root you can run the two concurrently with tools such as concurrently, or use two terminals:

pnpm --filter server dev
pnpm --filter client dev

The client is configured to proxy API requests to the server (/api/*), see vite.config.ts.

�🚀 Overview

The system manages employees across multiple provinces.
There are only two roles:

Global Admin — can view all provinces and browse employees within any province.
Province Admin — can only manage employees within their own province.

Province admins themselves are fixed (not created through the UI or API).

🗂️ Core Features

Secure login (/auth/login)
Global Admin dashboard showing all provinces
Province‑scoped employee management
Create, edit, delete employees (province‑scoped)
Performance record management (add, edit, delete)
Global Performance Lock — Prevent all employees from editing performance records system-wide
Fetch employees belonging to a selected province
Material-UI frontend with custom theme
No generic /employees root — everything is province‑scoped

🧩 API Structure

All employee data is nested under provinces.

Authentication

Method	Endpoint	Description
POST	`/auth/login`	Login as Global Admin or Province Admin

🔹 Provinces

Method	Endpoint	Description
GET	`/provinces`	List all provinces (Global Admin only)
GET	`/provinces/:provinceId`	Get details of a specific province

🔹 Global Settings

Method	Endpoint	Description
GET	`/global-settings`	Get global settings (performance lock status)
POST	`/global-settings/toggle-performance-lock`	Toggle performance editing lock (Global Admin only)

🔹 Employees (Province‑Scoped)

All employee operations must include the province they belong to.

Method	Endpoint	Description
GET	`/provinces/:provinceId/employees`	List all employees of the province
POST	`/provinces/:provinceId/employees`	Create a new employee in the province
GET	`/provinces/:provinceId/employees/:employeeId`	Fetch a single employee
PUT	`/provinces/:provinceId/employees/:employeeId`	Update an employee
DELETE	`/provinces/:provinceId/employees/:employeeId`	Delete an employee

🧭 Front-End Flow

1. Login Page (`/`)

User enters credentials
Sends POST → /auth/login
Redirects based on role

2. Global Admin Flow

GlobalAdminDashboardPage

Displays a list of all provinces (GET /provinces).

User selects a province → redirect to:

/provinces/:provinceId/employees

Which loads the employee list for that province.

3. Province Admin Flow

ProvinceEmployeesPage

Displays all employees of their province:

GET /provinces/:provinceId/employees

Actions:

"Create Employee" → NewEmployeeFormPage
Select employee → EmployeePage (/provinces/:provinceId/employees/:employeeId)
Edit employee → EditEmployeeDialog (modal)
Manage performance → PerformanceManager component

� Performance Lock Feature

The Global Admin can lock/unlock performance editing across the entire system.

How It Works

Locking: Global Admin clicks the lock toggle on the dashboard
- Sets performanceLocked: true in global settings
- All employees receive HTTP 423 (Locked) when attempting to edit performance
UI Feedback:
- Lock toggle button shows current state (🔒 locked / 🔓 unlocked)
- Toast notification displays with distinct messages and colors:
  - Warning (orange): "Performance editing is now LOCKED"
  - Success (green): "Performance editing is now UNLOCKED"
- Employees see alert when locked: "Performance records are currently locked. You cannot make changes at this time."
Reset All button is disabled when lock is active (prevents accidental resets during lock period)

Reset All Performances

Global Admin can reset all employee performance metrics to defaults:

Preserved: Employee status (remains unchanged)
Reset to defaults:
- Daily performance: 0
- Shift count per location: 0
- Shift duration: 8 hours
- Overtime: 0
- Daily leave: 0
- Sick leave: 0
- Absence: 0
- Travel assignment: 0
- Notes: cleared

API Response

{
	"success": true,
	"data": {
		"_id": "...",
		"performanceLocked": true,
		"lastLockedBy": "admin_user_id",
		"lockedAt": "2025-12-28T...",
		"createdAt": "...",
		"updatedAt": "..."
	}
}

�📦 Data Model

User

{
  id: string,
  email: string,
  password: string (hashed),
  role: "global" | "province",
  provinceId?: string
}

Province

{
  id: string,
  name: string
}

Employee

{
  id: string,
  firstName: string,
  lastName: string,
  phone: string,
  nationalId: string,
  provinceId: string
}

Employees always reference the province they belong to.

GlobalSettings

{
  id: string,
  performanceLocked: boolean,
  lastLockedBy: string (user id),
  lockedAt: Date,
  createdAt: Date,
  updatedAt: Date
}

Stores system-wide settings including the performance lock status.

🎯 Design Principles

Minimalistic & strict: no unnecessary endpoints
100% province‑scoped employees
Global admin ≠ province admin list viewer
Predictable URL structure
Easy to port into any client framework

📘 Summary

This system provides:

Clean role‑based structure
Simple routes
Hierarchical API (/provinces → employees)
No redundant admin management
Production‑ready separation of access

Perfect for organizational employee management with fixed province administration.

🛠 Testing & linting

Server tests live in server/src/__tests__; run with:
```
cd server
pnpm test
```
Client currently has no automated tests – end‑to‑end tests may be added in the future.
Linting/formatting (frontend) is enforced by running:
```
cd client
pnpm lint
pnpm format
```

The server project uses TypeScript's strict mode and eslint is enabled via npm run lint inside server.

🧭 Development notes

Routing is defined in server/src/routes; see routing.md for the decision‑making process.
Performance lock logic lives in server/src/controllers/globalSettingsController.ts and is documented in PERFORMANCE_LOCK_FEATURE.md.
Front‑end pages and components reside under client/src/pages and client/src/components; look for GlobalAdminDashboardPage, ProvinceEmployeesPage, etc.

📦 Build for production

Build the server: cd server && pnpm build.
Build the client: cd client && pnpm build.
Serve the client/dist folder with a static server, or configure the Express app to serve it (not implemented out‑of‑the-box).

📖 Additional documentation

routing.md – rationale for API structure.
PERFORMANCE_LOCK_FEATURE.md – deep dive on the lock feature.
client/IMPLEMENTATION.md – frontend implementation notes.
server/TEST_SETUP.md – instructions for test database seeding.

📜 License

This project is licensed under the MIT License.

This README has been updated to reflect the current codebase structure and development workflow.

FilesExpand file tree

README.md

Latest commit

History