# PeopleDesk User Guide

Friendly guide for **new users**, **testers**, and **developers**.

PeopleDesk is an Employee Management System for attendance, leave, payroll, performance, and reporting — with role-based access for Admin, HR, and Employee.

---

## 1. Quick start (everyone)

1. Open the app: `http://localhost:5173`
2. Sign in with a demo account (below)
3. Use the left menu (it changes by role)
4. Open **User Guide** inside the app anytime for help

### Demo accounts

| Role | Email | Password | What you can do |
|------|-------|----------|-----------------|
| Admin | `admin@ems.com` | `Admin@123` | Everything, including departments |
| HR | `hr@ems.com` | `Hr@12345` | Employees, leave approvals, payroll, reviews |
| Employee | `john@ems.com` | `Employee@123` | Own attendance, leave, payslips, profile |

---

## 2. Main flow (simple)

```mermaid
flowchart LR
  Login[Login] --> Dashboard[Dashboard]
  Dashboard --> Attendance[Attendance]
  Attendance --> Leaves[Leave_Requests]
  Leaves --> Payroll[Payroll]
  Payroll --> Reports[Reports_and_Notifications]
```

---

## 3. Who should use which path?

```mermaid
flowchart TD
  Start[Open_PeopleDesk] --> Role{Select_role_by_login}
  Role -->|Admin| AdminPath[Manage_Depts_Employees_Approvals_Payroll]
  Role -->|HR| HrPath[Manage_Employees_Approvals_Payroll_Reviews]
  Role -->|Employee| EmpPath[CheckIn_ApplyLeave_ViewPayslip_Profile]
```

### Plain-language permissions

| Feature | Admin | HR | Employee |
|---------|-------|----|----------|
| Dashboard | Yes | Yes | Yes |
| Manage employees | Yes | Yes | Own profile only |
| Manage departments | Yes | View | No |
| Check in / out | Yes | Yes | Yes |
| Apply leave | Yes | Yes | Yes |
| Approve / reject leave | Yes | Yes | No |
| Generate payroll | Yes | Yes | View/download own |
| Performance reviews | Create | Create | View own |

---

## 4. New employee guide

1. Login with your email/password  
2. Go to **Attendance** → **Check in**  
3. At end of day → **Check out**  
4. Need time off → **Leaves** → choose type + dates → Apply  
5. Watch status: Pending → Approved / Rejected  
6. Open **Payroll** to download salary PDF when ready  
7. Update phone in **Profile**

### Attendance diagram

```mermaid
flowchart TD
  A[Check_In_once_per_day] --> B[Work]
  B --> C[Check_Out]
  C --> D[Hours_calculated]
  D --> E{Hours_over_8}
  E -->|Yes| F[Overtime_added]
  E -->|No| G[Normal_hours_only]
```

**Important:** Only one check-in per employee per day. A second check-in shows an expected error.

---

## 5. Leave flow (HR + Employee)

```mermaid
flowchart TD
  Emp[Employee_applies_leave] --> Pending[Status_Pending]
  Pending --> Review{HR_or_Admin_decision}
  Review -->|Approve| Approved[Status_Approved]
  Approved --> BalanceDown[Leave_balance_decreases]
  BalanceDown --> NotifyA[Employee_notification]
  Review -->|Reject| Rejected[Status_Rejected]
  Rejected --> NotifyR[Employee_notification]
  Pending --> Cancel[Employee_can_cancel]
```

Leave types: Casual, Sick, Paid, Unpaid.

---

## 6. Payroll flow

```mermaid
flowchart TD
  Hr[HR_or_Admin_opens_Payroll] --> Fill[Select_employee_month_year]
  Fill --> Calc[System_calculates_net_salary]
  Calc --> Save[Payroll_saved]
  Save --> Pdf[Download_PDF_payslip]
  Save --> Note[Employee_gets_notification]
```

Formula:

`Net = Basic + Allowances + Bonuses - Deductions - Tax`

**Currency:** All money values (salary, budget, payroll, payslips) use **Indian Rupees (INR)** with Indian grouping — e.g. `₹75,000.00` in the UI and `Rs. 75,000.00` on PDF payslips.

---

## 7. Tester checklist

- [ ] Login works for Admin, HR, Employee  
- [ ] Employee cannot manage all employees/departments  
- [ ] Duplicate attendance check-in is blocked  
- [ ] Leave approve reduces balance; reject does not  
- [ ] Payroll PDF downloads  
- [ ] Notifications appear after leave review and payroll generate  
- [ ] Mobile/responsive layout remains usable under 768px  

---

## 8. Developer guide

### Run locally

```bash
# Backend
cd people-desk-be
npm install
npm run seed
npm run dev

# Frontend (new terminal)
cd people-desk-fe
npm install
npm run dev
```

- UI: `http://localhost:5173`
- API: `http://localhost:5000`
- Root `.env` needs `MONGODB_URI`, `JWT_SECRET`, `PORT`, `CLIENT_URL`

### Access My Database (MongoDB Atlas)

PeopleDesk stores data in **MongoDB Atlas** (cloud). Local connection string lives in root `.env` as `MONGODB_URI` (also mirrored in `atlas-credentials.env` — keep both private).

1. Open [MongoDB Atlas](https://cloud.mongodb.com/) and sign in  
2. Choose your project → click the cluster (e.g. `Cluster0`)  
3. Click **Browse Collections** to open **Collections** (this is “My Database” in Atlas)  
4. Select database **`ems`** — you will see collections such as `users`, `employees`, `departments`, `attendances`, `leaverequests`, `payrolls`, `notifications`, etc.  
5. Optional — connect from a GUI:  
   - In Atlas: **Connect** → **Drivers** or **MongoDB Compass**  
   - Copy the URI (same style as `MONGODB_URI` in `.env`)  
   - Open [MongoDB Compass](https://www.mongodb.com/products/compass) → paste URI → Connect → open database **`ems`**

**Tip:** After `npm run seed` in `people-desk-be`, demo users and sample employees appear under `ems`. If the app cannot connect, check Atlas **Network Access** (your IP allowlist) and that `MONGODB_URI` is correct.

### Architecture

```mermaid
flowchart TD
  FE[people-desk-fe_React] -->|JWT_Bearer_API| BE[people-desk-be_Express]
  BE --> MW[Auth_and_RBAC_middleware]
  MW --> CTRL[Controllers]
  CTRL --> DB[(MongoDB_Atlas)]
```

### Useful API routes

- `POST /api/auth/login`
- `GET /api/auth/me`
- `CRUD /api/employees`
- `CRUD /api/departments`
- `POST /api/attendance/check-in` · `POST /api/attendance/check-out`
- `POST /api/leaves` · `PUT /api/leaves/:id/review`
- `POST /api/payroll/generate` · `GET /api/payroll/:id/payslip`
- `GET /api/dashboard/stats`
- `GET /api/notifications`

Use header: `Authorization: Bearer <token>`

---

## 9. Friendly tips

- Menus hide features your role cannot use  
- If a button fails, read the red message — it usually explains the rule (example: already checked in)  
- For demos, start as Employee for self-service, then switch to HR/Admin for approvals  
- Keep `.env` and `atlas-credentials.env` private — never commit secrets  

---

## 10. Need more help?

Inside the app, open **User Guide** from the left menu for the same content in a visual layout.