Payroll Check System

A comprehensive payroll management system similar to Gusto, built with Java and Spring Boot. This system provides complete payroll processing, tax calculations, employee management, and payment history tracking.

Features

Core Functionality

• Company Management

  • Create and manage multiple companies
  • Track company information (EIN, address, contact details)
  • Active/inactive company status management

• Employee Management

  • Complete employee lifecycle management (hire, update, terminate)
  • Support for multiple employment types (Full-time, Part-time, Contractor, Temporary, Intern)
  • Flexible pay frequencies (Weekly, Bi-weekly, Semi-monthly, Monthly)
  • Department and job title tracking
  • Tax withholding configuration (federal and state allowances)

• Payroll Processing

  • Automated payroll creation for pay periods
  • Support for salary-based and hourly employees
  • Overtime calculation (1.5x rate)
  • Bonus and commission handling
  • Comprehensive tax calculations:
    • Federal income tax (2024 tax brackets)
    • State income tax (state-specific rates)
    • FICA taxes (Social Security and Medicare)
    • Additional Medicare tax for high earners
  • Year-to-date tracking for gross pay and taxes
  • Payroll status workflow (Draft → Pending → Processing → Processed → Completed)

• Deductions Management

  • Health insurance deductions
  • 401(k) retirement contributions
  • Custom deductions

• Reporting & Analytics

  • Employee payroll history
  • Year-to-date totals
  • Payroll summaries by period
  • Tax withholding reports

Technology Stack

• Java 17 - Programming language
• Spring Boot 3.2.0 - Application framework
• Spring Data JPA - Data persistence
• H2 Database - In-memory database (development)
• PostgreSQL - Production database (configurable)
• Spring Security - Authentication and authorization
• Maven - Dependency management
• Lombok - Boilerplate reduction
• ModelMapper - DTO mapping
• OpenAPI/Swagger - API documentation

Project Structure

src/
├── main/
│   ├── java/com/payrollcheck/
│   │   ├── config/              # Configuration classes
│   │   │   ├── ModelMapperConfig.java
│   │   │   ├── OpenApiConfig.java
│   │   │   └── SecurityConfig.java
│   │   ├── controller/          # REST API controllers
│   │   │   ├── CompanyController.java
│   │   │   ├── EmployeeController.java
│   │   │   ├── PayrollController.java
│   │   │   └── PayrollItemController.java
│   │   ├── dto/                 # Data Transfer Objects
│   │   │   ├── CompanyDTO.java
│   │   │   ├── EmployeeDTO.java
│   │   │   ├── PayrollDTO.java
│   │   │   ├── PayrollItemDTO.java
│   │   │   ├── CreatePayrollRequest.java
│   │   │   └── UpdatePayrollItemRequest.java
│   │   ├── exception/           # Exception handling
│   │   │   ├── BusinessException.java
│   │   │   ├── DuplicateResourceException.java
│   │   │   ├── ResourceNotFoundException.java
│   │   │   ├── GlobalExceptionHandler.java
│   │   │   ├── ErrorResponse.java
│   │   │   └── ValidationErrorResponse.java
│   │   ├── model/               # Domain entities
│   │   │   ├── BaseEntity.java
│   │   │   ├── Company.java
│   │   │   ├── Employee.java
│   │   │   ├── Payroll.java
│   │   │   ├── PayrollItem.java
│   │   │   └── enums/
│   │   │       ├── EmploymentType.java
│   │   │       ├── PayFrequency.java
│   │   │       └── PayrollStatus.java
│   │   ├── repository/          # Data access layer
│   │   │   ├── CompanyRepository.java
│   │   │   ├── EmployeeRepository.java
│   │   │   ├── PayrollRepository.java
│   │   │   └── PayrollItemRepository.java
│   │   ├── service/             # Business logic layer
│   │   │   ├── CompanyService.java
│   │   │   ├── EmployeeService.java
│   │   │   ├── PayrollService.java
│   │   │   └── TaxCalculationService.java
│   │   └── PayrollCheckApplication.java
│   └── resources/
│       ├── application.yml
│       └── application-prod.yml
└── test/

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher
• PostgreSQL (for production) - optional

Installation

1. Clone the repository:

git clone <repository-url>
cd Payroll-Check

2. Build the project:

mvn clean install

3. Run the application:

mvn spring-boot:run

The application will start on http://localhost:8080

Database Configuration

Development (H2 In-Memory Database)

The application uses H2 database by default. Access the H2 console at:

• URL: http://localhost:8080/h2-console
• JDBC URL: jdbc:h2:mem:payrolldb
• Username: sa
• Password: (leave blank)

Production (PostgreSQL)

To use PostgreSQL in production:

1. Create a PostgreSQL database:

CREATE DATABASE payrolldb;

2. Run with production profile:

mvn spring-boot:run -Dspring-boot.run.profiles=prod

3. Set environment variables:

export DB_USERNAME=your_username
export DB_PASSWORD=your_password
export SERVER_PORT=8080

API Documentation

Swagger UI

Access the interactive API documentation at:

http://localhost:8080/swagger-ui.html

Authentication

The API uses Basic Authentication. Default credentials:

• Username: admin
• Password: admin123

API Endpoints

Company Management

Method	Endpoint	Description
POST	/api/companies	Create a new company
GET	/api/companies/{id}	Get company by ID
GET	/api/companies/ein/{ein}	Get company by EIN
GET	/api/companies	Get all companies
GET	/api/companies/active	Get active companies
GET	/api/companies/search?name={name}	Search companies by name
PUT	/api/companies/{id}	Update company
PATCH	/api/companies/{id}/deactivate	Deactivate company
PATCH	/api/companies/{id}/activate	Activate company
DELETE	/api/companies/{id}	Delete company

Employee Management

Method	Endpoint	Description
POST	/api/companies/{companyId}/employees	Create a new employee
GET	/api/companies/{companyId}/employees/{id}	Get employee by ID
GET	/api/companies/{companyId}/employees	Get all employees
GET	/api/companies/{companyId}/employees/active	Get active employees
GET	/api/companies/{companyId}/employees/type/{type}	Get employees by type
GET	/api/companies/{companyId}/employees/department/{dept}	Get employees by department
GET	/api/companies/{companyId}/employees/search?name={name}	Search employees
PUT	/api/companies/{companyId}/employees/{id}	Update employee
PATCH	/api/companies/{companyId}/employees/{id}/terminate	Terminate employee
PATCH	/api/companies/{companyId}/employees/{id}/reactivate	Reactivate employee
DELETE	/api/companies/{companyId}/employees/{id}	Delete employee

Payroll Management

Method	Endpoint	Description
POST	/api/companies/{companyId}/payrolls	Create a new payroll
POST	/api/companies/{companyId}/payrolls/{id}/generate-items	Generate payroll items
GET	/api/companies/{companyId}/payrolls/{id}	Get payroll by ID
GET	/api/companies/{companyId}/payrolls	Get all payrolls
GET	/api/companies/{companyId}/payrolls/date-range	Get payrolls by date range
POST	/api/companies/{companyId}/payrolls/{id}/process	Process payroll
DELETE	/api/companies/{companyId}/payrolls/{id}	Delete draft payroll

Payroll Items

Method	Endpoint	Description
PUT	/api/payroll-items/{id}	Update payroll item
GET	/api/payroll-items/employee/{employeeId}	Get payroll items by employee

Usage Examples

1. Create a Company

curl -X POST http://localhost:8080/api/companies \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "ein": "12-3456789",
    "address": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94105",
    "email": "[email protected]",
    "phone": "4155551234"
  }'

2. Create an Employee

curl -X POST http://localhost:8080/api/companies/1/employees \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "ssn": "123-45-6789",
    "email": "[email protected]",
    "phone": "4155555678",
    "address": "456 Oak Avenue",
    "city": "San Francisco",
    "state": "CA",
    "zipCode": "94102",
    "dateOfBirth": "1990-05-15",
    "hireDate": "2024-01-01",
    "employmentType": "FULL_TIME",
    "jobTitle": "Software Engineer",
    "department": "Engineering",
    "payFrequency": "BI_WEEKLY",
    "salary": 120000,
    "federalAllowances": 2,
    "stateAllowances": 2,
    "additionalFederalWithholding": 0,
    "additionalStateWithholding": 0
  }'

3. Create a Payroll

curl -X POST http://localhost:8080/api/companies/1/payrolls \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "periodStartDate": "2024-01-01",
    "periodEndDate": "2024-01-15",
    "payDate": "2024-01-19",
    "notes": "First payroll of 2024"
  }'

4. Generate Payroll Items

curl -X POST http://localhost:8080/api/companies/1/payrolls/1/generate-items \
  -u admin:admin123

5. Update a Payroll Item (Add Bonus)

curl -X PUT http://localhost:8080/api/payroll-items/1 \
  -u admin:admin123 \
  -H "Content-Type: application/json" \
  -d '{
    "bonus": 1000,
    "healthInsurance": 200,
    "retirement401k": 500
  }'

6. Process Payroll

curl -X POST 'http://localhost:8080/api/companies/1/payrolls/1/process?processedBy=admin' \
  -u admin:admin123

Tax Calculation Details

Federal Income Tax

• Uses 2024 federal tax brackets for single filers
• Supports standard deduction ($13,850 for 2024)
• Accounts for federal allowances
• Supports additional withholding

FICA Taxes

Social Security

• Rate: 6.2%
• Wage base limit: $160,200 (2024)
• Automatically stops withholding when limit is reached

Medicare

• Regular rate: 1.45%
• Additional Medicare tax: 0.9% on earnings over $200,000
• No wage base limit

State Income Tax

• Configurable state-specific rates
• Pre-configured rates for major states (CA, NY, TX, FL, etc.)
• Supports state allowances
• Supports additional withholding

Data Models

Company

• Basic information (name, EIN, address)
• Contact details
• Active/inactive status
• One-to-many relationship with employees and payrolls

Employee

• Personal information (name, SSN, contact)
• Employment details (hire date, job title, department)
• Compensation (salary, hourly rate, pay frequency)
• Tax withholding preferences
• One-to-many relationship with payroll items

Payroll

• Pay period dates
• Payment date
• Status tracking
• Totals (gross pay, net pay, taxes, deductions)
• Processing information
• One-to-many relationship with payroll items

PayrollItem

• Individual employee payment record
• Hours worked (regular and overtime)
• Additional compensation (bonus, commission)
• Tax withholdings
• Deductions
• Year-to-date tracking

Best Practices

1. Always use the termination endpoint instead of deleting employees to maintain payroll history
2. Generate payroll items immediately after creating a payroll to see calculated amounts
3. Review payroll items before processing to ensure accuracy
4. Process payrolls on or before the pay date to ensure timely payments
5. Track year-to-date totals for tax reporting and compliance
6. Use appropriate pay frequencies that match your company's payroll schedule
7. Update tax allowances when employees submit new W-4 forms

Security Considerations

• Change default credentials in production
• Use HTTPS in production environments
• Implement proper authentication (JWT or OAuth2) for production
• Secure sensitive data (SSN, salary information)
• Implement role-based access control (RBAC)
• Regular security audits and updates

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

For issues, questions, or contributions, please open an issue in the GitHub repository.

Roadmap

Future enhancements:

• Direct deposit integration
• W-2 form generation
• 1099 form generation for contractors
• Benefits management
• Time tracking integration
• Multi-currency support
• Advanced reporting and analytics
• Mobile application
• Email notifications
• Audit trail and compliance reporting

---

Built with Java and Spring Boot | Version 1.0.0