QUICKSTART.md

Quick Start Guide

Get the Payroll Check System up and running in 5 minutes!

Prerequisites

• Java 17+ installed
• Maven 3.6+ installed

Steps

1. Build the Project

mvn clean package

2. Run the Application

mvn spring-boot:run

The application will start on port 8080.

3. Access the Application

Open your browser and navigate to:

• Swagger UI (API Documentation): http://localhost:8080/swagger-ui.html
• H2 Database Console: http://localhost:8080/h2-console

4. Login Credentials

API Authentication:

• Username: admin
• Password: admin123

H2 Console:

• JDBC URL: jdbc:h2:mem:payrolldb
• Username: sa
• Password: (leave blank)

Sample Data

The application comes pre-loaded with sample data:

Companies

1. Acme Corporation (ID: 1)

   • EIN: 12-3456789
   • Location: San Francisco, CA
   • 3 employees

2. TechStart Inc (ID: 2)

   • EIN: 98-7654321
   • Location: New York, NY
   • 1 employee

Employees

• John Doe - Software Engineer ($120,000/year)
• Jane Smith - Senior Product Manager ($145,000/year)
• Mike Johnson - Marketing Specialist ($75,000/year)
• Sarah Williams - Data Scientist ($135,000/year)

Try It Out!

Example 1: View All Employees

Using curl:

curl -u admin:admin123 http://localhost:8080/api/companies/1/employees

Or use Swagger UI for an interactive experience!

Example 2: Create a Payroll

1. Go to Swagger UI
2. Navigate to "Payroll Management"
3. Click on "POST /api/companies/{companyId}/payrolls"
4. Click "Try it out"
5. Enter:
   • companyId: 1
   • Request body:

   {
     "periodStartDate": "2024-01-01",
     "periodEndDate": "2024-01-15",
     "payDate": "2024-01-19"
   }

6. Click "Execute"

Example 3: Generate Payroll Items

After creating a payroll (let's say it got ID 1):

1. Find "POST /api/companies/{companyId}/payrolls/{payrollId}/generate-items"
2. Click "Try it out"
3. Enter:
   • companyId: 1
   • payrollId: 1
4. Click "Execute"

You'll see calculated payroll items with taxes automatically computed!

Example 4: View Payroll Details

1. Find "GET /api/companies/{companyId}/payrolls/{payrollId}"
2. Enter:
   • companyId: 1
   • payrollId: 1
3. Click "Execute"

You'll see the complete payroll with all items, taxes, and totals!

What's Next?

• Explore the full README for detailed documentation
• Try different API endpoints in Swagger UI
• Create your own companies and employees
• Process a complete payroll from start to finish
• Check out the tax calculations in the payroll items

Common Tasks

Create a New Company

POST /api/companies

Add an Employee

POST /api/companies/{companyId}/employees

Run Payroll

1. POST /api/companies/{companyId}/payrolls - Create payroll
2. POST /api/companies/{companyId}/payrolls/{payrollId}/generate-items - Generate items
3. PUT /api/payroll-items/{itemId} - Update items (optional)
4. POST /api/companies/{companyId}/payrolls/{payrollId}/process - Process payroll

View Employee Payment History

GET /api/payroll-items/employee/{employeeId}

Troubleshooting

Port 8080 already in use?

Change the port in src/main/resources/application.yml:

server:
  port: 8081

Build fails?

Make sure you have Java 17+ and Maven 3.6+:

java -version
mvn -version

Support

For issues or questions, check the main README or open an issue on GitHub.

---

Happy payroll processing!