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:

# Server
PORT=5000
FRONTEND_URL=http://localhost:5173
NODE_ENV=development

# Database
MONGO_URI=your_mongodb_uri

# Authentication
JWT_SECRET=your_secret_key
GOOGLE_CLIENT_ID=your_google_id
GOOGLE_CLIENT_SECRET=your_google_secret

# Caching & Background Jobs
REDIS_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.com
EMAIL_PORT=587                       # or 465 for SSL
EMAIL_SECURE=false                   # true for port 465
EMAIL_USER=your_smtp_username        # e.g. your_email@gmail.com
EMAIL_PASS=your_smtp_password        # or app password
EMAIL_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_host
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your_smtp_user
SMTP_PASS=your_smtp_pass

# Logging
LOG_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:5000
VITE_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_key
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
SMTP_SECURE=false
EMAIL_FROM="PaySphere" <no-reply@paysphere.com>

3. Run Development

# Backend
cd backend && npm run dev

# Frontend
cd frontend && npm run dev

4. Testing

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

---

PaySphere — Payroll in seconds, not hours. ⚡