PayFlow (People Pay360) 🚀

An Integrated Human Resource and Payroll Operations Platform

Many basic HR tools store employee details, attendance, leave, and salary data as separate, disconnected records. Real HR and payroll teams need these records to work together seamlessly[cite: 5].

PayFlow (People Pay360) solves this by building an operational flow where the Employee record acts as the central hub[cite: 5]. Related Contracts and Working Schedules provide payroll context, Attendance and Time Off capture day-to-day activity, Salary Structures define computation, and Payruns turn eligible records into validated payslips that can be printed as PDFs and emailed to employees[cite: 5].

---

✨ Key Features & How We Solved Them

1. Unified Employee Master & Access Control

• Role-Based Access Control (RBAC): Built-in roles for Employee, HR Manager, HR Payroll User, HR Payroll Manager, and Admin, restricting views and actions accordingly[cite: 5].
• Central Hub: Employees are managed via unified Kanban or List views, acting as the central hub for all HR interactions[cite: 5]. Smart buttons on the employee profile instantly link to their specific contracts, attendance, and time-off records[cite: 5].

2. Time Off & Allocation Engine

• Allocation Balances: Time Off Allocations manage employee balances, tracking taken, remaining, and validity periods[cite: 5].
• Automated Deduction: When an HR manager approves a Time Off request, the backend automatically validates the duration against the employee's active allocation balance and deducts the days, preventing overdrawing[cite: 5].

3. Dynamic Salary Computation

• Structures & Rules: Salary Structures act as containers for organized collections of Salary Rules (e.g., "Regular Salary")[cite: 5].
• Computation Engine: Salary Rules define how earnings and deductions are calculated using flexible computation methods—including fixed amounts, percentages of other rules, and complex dynamic mathematical formulas[cite: 5].
• Sequential Processing: Rules are processed in a specific sequence to ensure dependencies are respected, allowing complex totals (like Net Salary) to build upon earlier calculations (like Basic + Allowances)[cite: 5].

4. 2-Step Payrun Wizard & Payslip Generation

• Wizard Flow: We implemented a 2-step wizard. Step 1 defines the scope (Salary Structure and Period). Step 2 filters eligible staff for explicit user selection before finalizing the batch creation[cite: 5].
• Period-Specific Context: The computation logic automatically fetches the specific active contract for the selected period[cite: 5], preventing concurrent contract conflicts.
• Delivery: Payslips can be printed as PDF documents for individual employees[cite: 5], or distributed via a bulk email delivery system built directly into the Payrun workflow[cite: 5].

5. Live Payroll Dashboard

• The Payroll Dashboard aggregates real-time data across HR, attendance, and payroll modules[cite: 5].
• Features live KPI cards (Total Net Salary, Average Salary), Charts (Salary Cost by Department, Monthly Net Salary Trends), and operational alerts (missing check-outs, pending leave requests, draft payruns)[cite: 5].

---

🛠 Tech Stack

Our team chose a modern, scalable JavaScript/TypeScript stack to ensure robust data modeling and accurate payroll computation:

• Frontend: Next.js (App Router), React Query, Tailwind CSS, Recharts (for Dashboard).
• Backend: Node.js, Express, Prisma ORM.
• Database: PostgreSQL.
• Authentication: JWT-based stateless authentication with HTTP-only cookies.
• Email & Delivery: Resend / Nodemailer configured with an async in-memory queue.
• PDF Generation: Native HTML/CSS print media queries ensuring zero-dependency, pixel-perfect PDF rendering.

---

🔄 The End-to-End Workflow

To test the application, follow this complete operational lifecycle:

1. Onboarding: Create a new Employee and assign them a Department and Job Title.
2. Contracts: Create an active Contract for the employee, linking them to a Working Schedule and a Salary Structure (e.g., "Standard 5-Day" and "Basic Salary").
3. Time & Attendance: Grant the employee a Time Off Allocation (e.g., 10 days). Create an approved Time Off Request and verify the balance decreases automatically. Mark attendance check-ins/outs.
4. Payroll Configuration: Ensure the Salary Structure has sequential rules (e.g., Sequence 1: BASIC (Fixed), Sequence 2: HRA (Percentage of BASIC), Sequence 3: NET (Formula: BASIC + HRA)).
5. Run Payroll: Navigate to Payroll -> New Payrun. Select your period and structure, pick your employee, and click Create.
6. Validate & Pay: Review the generated Draft payslip. Click Mark Computed to execute the math formulas. Review the exact Gross/Net breakdowns. Validate, then Mark as Paid.
7. Distribute: Click Send Payslips (Email) to bulk-dispatch the payslips, or click Print PDF to save a local copy.
8. Analyze: Open the Dashboard to see your newly processed payroll data reflected in the live charts and departmental breakdowns.

---

🚀 How to Run Locally

Prerequisites

• Node.js (v18+)
• PostgreSQL database

Setup Instructions

1. Clone the repository & install dependencies:

   git clone <repository-url>
   cd payflow
   npm install
   

2. **Configure Environment Varialbes:

   DATABASE_URL="postgresql://user:password@localhost:5432/payflow"
   ACCESS_SECRET="your-access-secret"
   REFRESH_SECRET="your-refresh-secret"
   OTP_VERIFY_SECRET="your-otp-secret"
   

3. **Run Database migrations & Seed Data:

   npx prisma migrate dev
   npm run seed
   

4. **Start the Development Server:

   # Run both frontend and backend concurrently
   npm run dev