PaySphere 💰

Payroll in seconds, not hours.
A lightweight payroll management system built for small businesses in India.

Figma Design • Live Project • Postman Documentation • Backend API • YouTube Demo

---

❗ Problem Statement

Small businesses employing fewer than 10 workers spend hours every month manually calculating salaries factoring in paid leave, unpaid absences, overtime hours, and festival bonuses.

Most payroll software is built for large enterprises, making them:

• Too complex for tiny teams.
• Expensive and over-engineered.
• Not optimized for the fast-paced "Digital Ledger" style of Bharat.

👉 Result: Wasted time, calculation errors, and frustration.

---

💡 Solution

PaySphere simplifies payroll into a 3-step workflow:

1. 👥 Add Employees: Quickly onboard your team with base salary and overtime rates.
2. 💬 Log Updates: Add leaves, overtime, and bonuses through a clean, intuitive interface.
3. ⚡ Run Payroll: Generate professional payslips and finalize payouts in one click.

---

🎯 Features

Feature	Description
🔐 Google Authentication	Secure Login & Signup with Google One-Tap integration.
🛡️ Role-Based Access Control (RBAC)	Granular permissions with Admin, Manager, and Viewer roles for team collaboration.
👥 Employee Management	Dashboard view with status, role, and salary at a glance.
📥 Bulk Employee Import (CSV)	Onboard entire teams in seconds by uploading a CSV file with row-level validation & duplicate detection.
💬 Activity Tracking	Log leave, overtime, bonuses, and deductions per employee.
⚡ Instant Payroll	Automated calculation of Net Salary based on monthly activity.
📄 Professional Payslips	Download detailed PDF breakdowns for each payout.
📧 Bulk Payslip Emailing	One-click or auto-scheduled (via cron) email dispatch of payslips to all employees.
📊 Advanced Reporting & Analytics	Interactive dashboard with payroll trends, department/role breakdowns, and overtime analysis.
📑 XLSX Payroll Summaries	Export formatted Excel spreadsheets with totals and per-employee breakdowns.
📦 ZIP Payslip Export	Download a single ZIP archive containing all employee payslip PDFs for a given month.
📋 Audit Logging	Event bus tracking for all mutations (payroll runs, employee CRUD, imports, emails, reports) with IP & user agent.
📱 Responsive Design	Fully optimized for Mobile, Tablet, and Desktop.

---

🛠️ Tech Stack

Layer	Technologies
Frontend	React.js (v19), Vite, Tailwind CSS v4, MUI (Material UI), Redux Toolkit, Recharts, React Router
Backend	Node.js, Express.js (v5), MongoDB, Mongoose, Redis (Caching layer), BullMQ (Background Jobs)
Deployment	Vercel (Frontend), Render (Backend)
Tools & Libraries	ExcelJS (XLSX exports), Archiver (ZIP archives), Nodemailer (SMTP emails), PDFKit, Multer, csv-parse, node-cron, Winston, Helmet, Jest (Testing)

---

📁 Project Structure

paysphere/
├── backend/
│ ├── src/
│ │ ├── config/ # Database connection & environment config
│ │ ├── controllers/ # Business logic (employees, payroll, reports, users)
│ │ │ └── __tests__/ # Controller unit tests (Jest + Supertest)
│ │ ├── jobs/ # Scheduled cron jobs (monthly payslip emails)
│ │ ├── middlewares/ # Auth, error handling, rate limiting, file upload
│ │ │ └── __tests__/ # Middleware tests
│ │ ├── models/ # Mongoose schemas (User, Employee, Payroll, AuditLog, CronLock)
│ │ ├── routes/ # API endpoint definitions
│ │ ├── seeds/ # Database seed scripts
│ │ ├── services/ # Cross-cutting services (audit logging, email dispatch)
│ │ │ └── __tests__/ # Service tests
│ │ ├── utils/ # Helpers: salary calculator, CSV export, logger, validators, email
│ │ │ └── __tests__/ # Utility unit tests
│ │ ├── workers/ # Background worker threads (PDF generation)
│ │ ├── app.js # Express app setup & middleware chain
│ │ └── index.js # Server entry point & cron job bootstrap
├── frontend/
│ ├── src/
│ │ ├── assets/ # Images and local files
│ │ ├── components/ # Reusable UI Components
│ │ │ ├── common/ # Button, Input, Modal, Skeleton, EmptyState, etc.
│ │ │ └── reports/ # Charts & tables: PayrollTrend, SalaryDistribution, etc.
│ │ ├── features/ # Feature-based slices (Auth, UI, User) + Redux hooks & services
│ │ ├── hooks/ # Global reusable React hooks (e.g., useLocalStorage)
│ │ ├── pages/ # Main route views (Landing, Dashboard, Reports, Settings, etc.)
│ │ ├── services/ # API services (axios config + request helpers)
│ │ ├── store/ # Redux store configuration
│ │ ├── utils/ # Helper functions and constants
│ │ ├── App.jsx # Route definitions & global providers
│ │ ├── main.jsx # React root & app bootstrap
│ │ └── index.css # Global styles + Tailwind directives

---

📸 Screenshots

Dashboard Overview

---

🚀 Installation & Setup

1. Backend Configuration

Copy the .env.example file to create a .env file in backend/:

cp .env.example .env

Update the variables with your own values:

# ServerPORT=5000FRONTEND_URL=http://localhost:5173NODE_ENV=development# DatabaseMONGO_URI=your_mongodb_uri# AuthenticationJWT_SECRET=your_secret_keyGOOGLE_CLIENT_ID=your_google_idGOOGLE_CLIENT_SECRET=your_google_secret# Caching & Background JobsREDIS_URI=your_redis_connection_uri# Email (SMTP)# Backend sends payslips & notifications directly via SMTP. If SMTP is# not configured, it falls back to the Vercel proxy at FRONTEND_URL/api/send-email,# then to console logging.EMAIL_HOST=your_smtp_host# e.g. smtp.gmail.comEMAIL_PORT=587# or 465 for SSLEMAIL_SECURE=false# true for port 465EMAIL_USER=your_smtp_username# e.g. your_email@gmail.comEMAIL_PASS=your_smtp_password# or app passwordEMAIL_FROM="PaySphere <no-reply@paysphere.com>"EMAIL_PROXY_SECRET=your_email_proxy_secret_key# Aliases (used by SMTP transport — populate both pairs for compatibility)SMTP_HOST=your_smtp_hostSMTP_PORT=587SMTP_SECURE=falseSMTP_USER=your_smtp_userSMTP_PASS=your_smtp_pass# LoggingLOG_LEVEL=info

2. Frontend Configuration

Copy the .env.example file to create a .env file in frontend/:

cp .env.example .env

Update the variables with your own values:

VITE_API_URL=http://localhost:5000VITE_GOOGLE_CLIENT_ID=your_google_id# Email Proxy SMTP (used by Vercel Serverless Function at /api/send-email)EMAIL_PROXY_SECRET=your_email_proxy_secret_keySMTP_HOST=smtp.gmail.comSMTP_PORT=587SMTP_USER=your_email@gmail.comSMTP_PASS=your_app_passwordSMTP_SECURE=falseEMAIL_FROM="PaySphere" <no-reply@paysphere.com>

3. Run Development

# Backendcd backend && npm run dev
# Frontendcd frontend && npm run dev

4. Run with Docker (Recommended)

The entire stack (MongoDB + backend + frontend) can be started with a single command using Docker Compose. Hot-reloading is enabled for both the backend (nodemon) and the frontend (Vite HMR).

Prerequisites: Docker with Docker Compose v2.

# From the repo root
docker compose up --build

This starts:

• MongoDB at localhost:27017
• Backend API at http://localhost:5000
• Frontend at http://localhost:5173

All services work out of the box with sensible defaults. To override secrets and Google/SMTP settings, copy the root .env.example to .env and edit it:

cp .env.example .env

Then restart the stack for changes to take effect:

docker compose up -d
docker compose restart backend

Useful commands:

# Build/start all services in the background
docker compose up --build -d
# Stream logs from all services (or one: docker compose logs backend)
docker compose logs -f
# Stop the stack (keeps the MongoDB volume)
docker compose down
# Stop and delete the MongoDB data volume
docker compose down -v

Note: Redis is optional. Without a REDIS_URL, caching falls back to an in-memory store and background payslip email jobs remain available in a degraded mode.

5. Testing

# Run backend test suite (Jest + Supertest)cd backend && npm test

---

PaySphere — Payroll in seconds, not hours. ⚡