Add README.md

2026-08-14 07:07:23 +00:00 · 2026-08-14 07:07:23 +00:00 · 32666386fb
commit 32666386fb
parent d7e319c5f5
1 changed files with 112 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,112 @@
+# PeopleDesk
+
+PeopleDesk is a full-stack Employee Management System built with React, Express, MongoDB Atlas, JWT auth, and role-based access (Admin / HR / Employee).
+
+For step-by-step help with diagrams (new users, testers, developers), see [USER_GUIDE.md](USER_GUIDE.md) or open **User Guide** in the app menu.
+
+## Features
+
+- Authentication with JWT + bcrypt
+- Role-based access control
+- Employee and department management
+- Attendance check-in/out with duplicate prevention and monthly reports
+- Leave apply / cancel / approve / reject with balances
+- Payroll generation and downloadable PDF payslips
+- Performance reviews
+- Dashboard analytics and in-app notifications
+
+## Project structure
+
+```
+people-desk/
+├── people-desk-fe/   # Vite + React frontend
+├── people-desk-be/   # Express + MongoDB API
+├── .env              # secrets (gitignored)
+└── README.md
+```
+
+## Setup
+
+### 1. Environment
+
+Copy Atlas credentials into root `.env` (already prepared if you used `atlas-credentials.env`):
+
+```
+PORT=5000
+JWT_SECRET=your_secret
+MONGODB_URI=mongodb+srv://USER:PASS@cluster0.xxx.mongodb.net/ems?retryWrites=true&w=majority
+CLIENT_URL=http://localhost:5173
+```
+
+### 2. Install dependencies
+
+```bash
+cd people-desk-be
+npm install
+
+cd ../people-desk-fe
+npm install
+```
+
+### 3. Seed demo data
+
+```bash
+cd people-desk-be
+npm run seed
+```
+
+Demo accounts:
+
+| Role     | Email           | Password      |
+|----------|-----------------|---------------|
+| Admin    | admin@ems.com   | Admin@123     |
+| HR       | hr@ems.com      | Hr@12345      |
+| Employee | john@ems.com    | Employee@123  |
+
+### 4. Run
+
+Terminal 1 — API:
+
+```bash
+cd people-desk-be
+npm run dev
+```
+
+Terminal 2 — UI:
+
+```bash
+cd people-desk-fe
+npm run dev
+```
+
+Open http://localhost:5173
+
+The Vite dev server proxies `/api` to http://localhost:5000.
+
+## Main API routes
+
+- `POST /api/auth/register`
+- `POST /api/auth/login`
+- `GET /api/auth/me`
+- `CRUD /api/employees`
+- `CRUD /api/departments`
+- `POST /api/attendance/check-in|check-out`
+- `GET /api/attendance` · `GET /api/attendance/report/monthly`
+- `POST /api/leaves` · `PUT /api/leaves/:id/cancel` · `PUT /api/leaves/:id/review`
+- `POST /api/payroll/generate` · `GET /api/payroll/:id/payslip`
+- `CRUD /api/performance`
+- `GET /api/dashboard/stats`
+- `GET /api/notifications`
+
+## Roles
+
+- **Admin** — full access including departments
+- **HR** — employees, leave approvals, payroll, performance
+- **Employee** — self attendance, leave, payroll view, profile
+
+## Notes
+
+- Never commit `.env` or `atlas-credentials.env`
+- Payroll net salary = basic + allowances + bonuses − deductions − tax
+- One attendance record per employee per day
+- On some Windows networks, MongoDB SRV DNS can fail; the backend forces Google/Cloudflare DNS resolvers before connecting